Tovább a tartalomhoz
Tudástár

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.

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.


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.


Ú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 }


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
}

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
}

Ú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.


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": []
}

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": []
}

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 }


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"}

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.

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

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:

  1. Ha a require_email be van állítva, kizárja az e-mail-cím nélküli válaszadókat
  2. Kizárja az exclude_respondent_ids listában szereplő válaszadókat
  3. 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.