Válaszadóikör-eszközök – MCP-eszközreferencia
A válaszadóikör-eszközök a kampányokhoz újra felhasználható válaszadói csoportokat kezelik. A válaszadói körök kézzel hozhatók létre, vagy reprezentatív mintákhoz egy mintavételi stratégiából állíthatók elő. A stratégiából előállított válaszadói körök nyomon követik a minőségi pontszámukat, rögzítik azokat a mintahúzási beállításokat, amelyekkel előállították őket (kért méret, túlmintavételezési szorzó, kiválasztási algoritmus, e-mail-cím megkövetelése, kizárások), és a válaszadói állomány változásával ugyanezekkel a beállításokkal frissíthetők. Maga a stratégia nem hordoz mintahúzási beállításokat, így egyetlen stratégia különböző méretű válaszadói köröket is táplálhat.
list_respondent_pools
Szekció neve “list_respondent_pools”Az összes válaszadói kör listázása, opcionálisan projekt vagy név szerint szűrve.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
project_id |
string |
Nem | — | Szűrés projektazonosító szerint |
name |
string |
Nem | — | Kis- és nagybetűt nem megkülönböztető részszöveg-szűrő |
limit |
integer |
Nem | 100 |
A visszaadott találatok legnagyobb száma |
Visszatérési érték: { data: [...], count, limit }. Minden elem tartalmazza a source_type, source_strategy_id, respondent_count, quality_score mezőt és az öt mintahúzási beállítást (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids) – rögzített mintahúzás nélküli válaszadói körnél (kézi, egyesített vagy szétválasztott) mindegyik null.
get_respondent_pool
Szekció neve “get_respondent_pool”Válaszadói kör lekérdezése azonosító alapján, a teljes válaszadói listával és a minőségi részletekkel együtt.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
pool_id |
string |
Igen | — | A válaszadói kör UUID-ja |
Visszatérési érték: a teljes válaszadóikör-objektum a következő mezőkkel: id, name, description, project_id, source_type, source_strategy_id, respondent_ids, respondent_count, az öt mintahúzási beállítás (requested_size, oversample_factor, selection_algorithm, require_email, exclude_respondent_ids; null, ha nincs rögzített mintahúzás), quality_score, quality_details, generated_at.
A requested_size az, amit a mintahúzás kért; a respondent_count az, ahány tagja a válaszadói körnek ténylegesen van. Jogosan eltérhetnek – a túlmintavételezés, a jogosult válaszadók hiánya vagy későbbi kézi módosítások miatt.
create_respondent_pool
Szekció neve “create_respondent_pool”Új válaszadói kör létrehozása (kézi forrástípussal).
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Igen | — | A válaszadói kör neve |
description |
string |
Nem | — | A válaszadói kör leírása |
project_id |
string |
Nem | — | A rendszerezéshez használt projekt |
respondent_ids |
string[] |
Nem | — | A kezdeti válaszadók azonosítói |
Visszatérési érték: { id, name, description, project_id, respondent_count }
add_respondents_to_pool
Szekció neve “add_respondents_to_pool”Válaszadók hozzáadása egy meglévő válaszadói körhöz. Az ismétlődéseket a rendszer csendben kihagyja.
Egy válaszadói kör csak a saját projektjének válaszadóit tartalmazza, így mindenki, aki olvashatja a válaszadói kört, minden tagját is olvashatja. Egy másik projekt válaszadóját a rendszer elutasítja, akkor is, ha Ön olvashatja őt. A válaszadói panelját megosztó szervezetben, valamint projekt nélküli válaszadói kör esetén a szervezet bármely válaszadója hozzáadható.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
pool_id |
string |
Igen | — | A válaszadói kör UUID-ja |
respondent_ids |
string[] |
Igen | — | A hozzáadandó válaszadók azonosítói |
Visszatérési érték:
{ "pool_id": "...", "added": 8, "duplicates_skipped": 2, "new_total": 50}remove_respondents_from_pool
Szekció neve “remove_respondents_from_pool”Válaszadók eltávolítása egy válaszadói körből.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
pool_id |
string |
Igen | — | A válaszadói kör UUID-ja |
respondent_ids |
string[] |
Igen | — | Az eltávolítandó válaszadók azonosítói |
Visszatérési érték:
{ "pool_id": "...", "removed": 3, "not_found": 1, "new_total": 47}generate_pool_from_strategy
Szekció neve “generate_pool_from_strategy”Új válaszadói kör húzása egy mintavételi stratégiából. A kiválasztási algoritmus a stratégia demográfiai céleloszlásainak megfelelő válaszadókat választja ki. A mintahúzási beállítások itt bemenetek, nem a stratégia tulajdonságai, és az új válaszadói kör eltárolja őket, így minden frissítés ugyanúgy húz újra.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
strategy_id |
string |
Igen | — | A mintavételi stratégia UUID-ja |
pool_name |
string |
Igen | — | Az új válaszadói kör neve |
description |
string |
Nem | — | A válaszadói kör leírása |
project_id |
string |
Nem | — | Projektazonosító. Alapértelmezés: a stratégia projektje |
requested_size |
integer |
Igen | — | Hány válaszadóra szól ez a mintahúzás, a túlmintavételezés előtt (> 0) |
oversample_factor |
float |
Nem | 1.0 |
Tartalék a nemválaszolás ellen a requested_size értékére (≥ 1; pl. 1.2 = 20% többlet) |
selection_algorithm |
string |
Nem | "greedy" |
"greedy" vagy "random_constrained" |
require_email |
boolean |
Nem | false |
Csak az e-mail-címmel rendelkező válaszadók jogosultak |
exclude_respondent_ids |
string[] |
Nem | [] |
Azoknak a válaszadóknak az UUID-jai, akik ebben a mintahúzásban soha nem jogosultak (pl. egy korábbi hullám) |
Az érvénytelen beállításokat (0-s méret, 1 alatti túlmintavételezés, ismeretlen algoritmus, nem válaszadói UUID-t tartalmazó kizárás) a rendszer még azelőtt elutasítja, hogy bármely válaszadót kiolvasna.
A mintahúzás csak annak a projektnek a válaszadóit veszi figyelembe, amelyhez az új válaszadói kör tartozik, így egy válaszadói körbe soha nem kerülnek olyan válaszadók, akiket a projekt többi tulajdonosa nem lát. Ugyanez érvényes a válaszadói kör frissítésekor is, bárki frissíti is azt. A válaszadói panelját megosztó szervezetben, valamint projekt nélküli válaszadói kör esetén a mintahúzás a teljes panelt figyelembe veszi.
Példa:
{ "strategy_id": "...", "pool_name": "Urban Millennials — main wave", "requested_size": 200, "oversample_factor": 1.2}Visszatérési érték:
{ "pool_id": "...", "pool_name": "Urban Millennials — main wave", "strategy_id": "...", "respondent_count": 240, "requested_size": 200, "effective_size": 240, "quality_score": 0.94, "quality_details": { }, "computation_time_ms": 145, "warnings": []}Az effective_size értéke requested_size × oversample_factor (lefelé kerekítve), vagyis az a létszám, amelyre a mintahúzás törekszik. Ha túl kevés válaszadó jogosult, a válaszadói kör kevesebb tagot kap, a warnings pedig mindkét méretet megnevező hiányüzenetet tartalmaz, például: Could not fill the draw: 90 of 120 drawn (requested 100 x oversample 1.2); only 90 candidates eligible.
A létrehozott válaszadói kör source_type: "strategy" értékű, és a későbbi frissítéshez eltárolja a source_strategy_id értéket és a mintahúzási beállításokat. Ha más méretben szeretne húzni, állítson elő egy másik válaszadói kört ugyanabból a stratégiából.
preview_pool_generation
Szekció neve “preview_pool_generation”A válaszadói kör előállításának előnézete, a válaszadói kör létrehozása nélkül. Ugyanazt a mintahúzást futtatja, mint a generate_pool_from_strategy, és minőségi mutatókat ad vissza.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
strategy_id |
string |
Igen | — | A mintavételi stratégia UUID-ja |
project_id |
string |
Nem | — | Az a projekt, amelyhez a válaszadói kör tartozna, ugyanúgy, mint a generate_pool_from_strategy esetén. Alapértelmezés: a stratégia projektje |
max_preview |
integer |
Nem | 100 |
Az előnézetbe felvett válaszadói azonosítók legnagyobb száma |
Ugyanazokat a mintahúzási beállításokat is fogadja, mint a generate_pool_from_strategy: requested_size (kötelező), oversample_factor, selection_algorithm, require_email, exclude_respondent_ids.
Visszatérési érték:
{ "eligible_count": 500, "requested_size": 200, "effective_size": 200, "selected_count": 200, "quality_score": 0.94, "quality_details": { }, "sample_respondent_ids": ["..."], "computation_time_ms": 130, "warnings": []}refresh_pool_from_strategy
Szekció neve “refresh_pool_from_strategy”Egy stratégiából előállított válaszadói kör újrahúzása helyben, az aktuális válaszadói állományból. Csak source_type: "strategy" értékű válaszadói köröknél működik. A frissítés nem fogad mintahúzási beállításokat: azzal a kért mérettel, túlmintavételezési szorzóval, algoritmussal, e-mail-követelménnyel és kizárásokkal húz újra, amelyeket a válaszadói kör az előállításakor eltárolt, a stratégia aktuális tényezői alapján. A méret módosításához állítson elő egy új válaszadói kört, és rendelje hozzá a kampányhoz.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
pool_id |
string |
Igen | — | A válaszadói kör UUID-ja (stratégiából előállítottnak kell lennie) |
Visszatérési érték:
{ "pool_id": "...", "previous_size": 195, "new_size": 200, "added": 10, "removed": 5, "requested_size": 200, "effective_size": 200, "quality_score": 0.96, "quality_details": { }, "warnings": []}delete_respondent_pool
Szekció neve “delete_respondent_pool”Válaszadói kör törlése.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
pool_id |
string |
Igen | — | A válaszadói kör UUID-ja |
Visszatérési érték: { pool_id, deleted }
Hibakezelés
Szekció neve “Hibakezelés”Gyakori hibák
Szekció neve “Gyakori hibák”| Helyzet | Válasz |
|---|---|
| A válaszadói kör nem található | {"error": "Pool {id} not found"} |
| A stratégia nem található, vagy olyan projektben van, amelyet a hívó nem olvashat (előállítás, előnézet) | {"error": "Strategy {id} not found"} |
| Nincsenek jogosult válaszadók | {"error": "No eligible respondents available for this strategy"} |
| Nem stratégiából előállított | {"error": "Pool was not generated from a strategy — cannot refresh"} |
| A forrásstratégiát törölték, vagy olyan projektben van, amelyet a hívó nem olvashat (frissítés) | {"error": "Source strategy {id} not found"} |
| Stratégiaalapú válaszadói kör rögzített mintahúzás nélkül (frissítés) | Ütközés: a válaszadói kör nem rögzít mintahúzási beállításokat, ezért nem frissíthető. Helyette állítson elő egy új válaszadói kört a stratégiából a kívánt méretben, és rendelje hozzá a kampányhoz. |
| Nem tulajdonosa a válaszadói kör projektjének | {"error": "forbidden", "detail": "caller is not an owner of this project and lacks an admin role"} |
Ismétlődések kezelése
Szekció neve “Ismétlődések kezelése”Az add_respondents_to_pool halmazműveletekkel ismeri fel az ismétlődéseket. Az ismétlődéseket a rendszer csendben kihagyja, és a duplicates_skipped darabszámban jelenti – hibát nem jelez.
A forrástípus nyomon követése
Szekció neve “A forrástípus nyomon követése”| Forrástípus | Létrehozó eszköz | Frissíthető |
|---|---|---|
"manual" |
create_respondent_pool |
Nem |
"strategy" |
generate_pool_from_strategy |
Igen, a válaszadói kör eltárolt mintahúzási beállításaival |
Jogosultsági szűrés
Szekció neve “Jogosultsági szűrés”Minden mintahúzás (előállítás, előnézet, frissítés) azokból a válaszadókból indul, akiket Ön láthat: privát szervezetben vagy adminisztrátorként a teljes panelből, egyébként az Ön tulajdonában lévő projektek válaszadóiból. Ez a szervezet alapértelmezett stratégiájára is érvényes, így egy mintahúzás soha nem nevez meg olyan válaszadót, akit a list_respondents nem mutatna meg Önnek.
Ezután a kiválasztás előtt a mintahúzás beállításai alapján szűri őket:
- Ha a
require_emailbe van állítva, kizárja az e-mail-cím nélküli válaszadókat - Kizárja az
exclude_respondent_idslistában szereplő válaszadókat - Ha nem marad jogosult válaszadó, az előállítás és a frissítés hibát ad vissza (a frissítés soha nem üríti ki a válaszadói kört); az előnézet
eligible_count: 0értéket ad vissza
A válaszadói körből kézzel eltávolított tag nem kerül be az exclude_respondent_ids listába, így a következő frissítés újra kihúzhatja.