Webhook na matukio

Toleo la API 2026-10-affable-towhee

Lingara hurekodi kama matukio kinachotokea kwa mipango ya masomo na matumizi ya akaunti yako, na hupokea matukio kutoka kwa mchezo au programu yako. Kila tukio, kwa njia yoyote linayosafiri, lina bahasha ileile, na orodha ya matukio inayaorodhesha yote.

Bahasha

Kila tukio hubeba sehemu sita. id huanza na lgr_evt_, ni ya kipekee, na ndiyo ufunguo wa kuondoa nakala. type hutaja tukio. created_at ni wakati lilipotokea. api_version ni toleo ambalo data imeundwa kwalo: toleo ambalo mteja wako amefungwa, au, kwenye mlisho na mtiririko, toleo ambalo ombi lako lilitaja katika Lingara-Version. subject huanza na lgr_sub_ na husema tukio linamhusu nani: halibadiliki kwa mteja wako lakini ni tofauti kwa kila mteja, na kamwe si barua pepe, jina wala kitambulisho cha akaunti. data ni ndogo na hutaja rasilimali badala ya kuzinakili: pata rasilimali kwa wigo inaouhitaji.

Aina mbili zinahitaji sentensi moja kila moja. lesson_plan.ready inaweza kufika mara mbili kwa mpango mmoja, kwanza ikiwa na data.status partial na kisha complete: chukua hatua kwa la kwanza ili kupata mpango unaoweza kutumika, au subiri complete ili kupata kila seti. usage.threshold_reached hutumwa tu kwa akaunti na wateja wanaotozwa kulingana na matumizi, na kuruka viwango kadhaa kwa mara moja huripoti kiwango cha juu zaidi kilichovukwa pekee, kwa hivyo usitarajie tukio moja kwa kila kiwango.

Kumbukumbu moja, njia tatu za kuisikia

Webhook zinafaa seva yenye kituo cha umma cha HTTPS. Mlisho na mtiririko vinafaa programu isiyo na kituo hicho, kama mchezo kwenye mashine ya mchezaji. Bahasha ni ileile kwenye kila njia, kwa hivyo programu inaweza kuanza na mlisho na kuhamia webhook baadaye bila kubadilisha jinsi inavyosoma tukio. Njia za matukio hujibu programu asilia. Mchezo unaoendeshwa kwenye kivinjari hauwezi kuziita bado, kwa sababu /v1/ haijibu ukaguzi wowote wa awali wa cross-origin.

Nani husikia tukio

Mteja husikia tukio anaposhikilia events:read na wigo mahususi wa aina ya tukio, ambao orodha inautaja, na tukio linapomhusu mmiliki wa mteja. Kwenye mlisho na mtiririko, wigo wa tokeni ya ufikiaji hupunguza hili zaidi, na types hulipunguza hadi aina unazotaja. webhook.test huenda tu kwenye kituo lilichotumwa, kamwe si kwenye mlisho, na huwezi kujisajili kulipokea. app.installed na app.uninstalled huenda tu kwa mteja mahususi wa programu, kamwe si kwa mteja mwingine wa akaunti ileile.

Sajili kituo

Sajili kituo kwenye ukurasa wa Webhook wa programu ya wavuti ya Lingara, katika app.getlingara.com/admin/webhooks, ukichagua mteja kwanza. URL yake lazima itumie https kwenye mlango 443, na seva pangishi yake lazima itatuliwe kwa anwani za umma pekee. Chagua “Matukio ya kutuma”: aina ambazo wigo wa mteja unaruhusu pekee ndizo zinazotolewa. URL na matukio haviwezi kuhaririwa baadaye: ongeza kituo kipya na ufute cha zamani. Siri ya kutia sahihi huanza na lgr_whsec_ na huonyeshwa mara moja tu.

Thibitisha uwasilishaji

Kila uwasilishaji ni POST yenye vichwa vitatu, kwa kufuata vipimo vya Standard Webhooks: webhook-id (id ya tukio), webhook-timestamp na webhook-signature. Ufunguo wa HMAC ni sehemu ya siri iliyo baada ya lgr_whsec_, iliyosimbuliwa kutoka base64, kamwe si siri kama mfuatano wa herufi. Thibitisha kabla ya kuchanganua mwili, juu ya baiti zake ghafi, kama ilivyo hapa chini. Kataa uwasilishaji ambao muhuri wake wa wakati uko zaidi ya dakika tano kutoka sasa, chaguo-msingi la maktaba za Standard Webhooks: hilo huzuia uwasilishaji ulionaswa usirudiwe.

signed   = webhook-id + "." + webhook-timestamp + "." + raw request body
key      = base64_decode(the secret after its prefix)
expected = "v1," + base64(hmac_sha256(key, signed))
accept   if |now - webhook-timestamp| <= 5 minutes
         and some entry of webhook-signature (space-separated) equals expected
             (compare in constant time)

Standard Webhooks huchapisha vithibitishaji kwa lugha nyingi. Vinatarajia siri iliyoandikwa kama whsec_ ikifuatwa na base64, au kama base64 tupu, kwa hivyo vipe sehemu ya siri ya Lingara iliyo baada ya lgr_whsec_. Maktaba za Lingara zenyewe hukubali siri nzima.

Jibu haraka, tarajia majaribio upya

Jibu kwa 2xx yoyote ndani ya sekunde 10, na ufanye kazi baadaye. Kitu kingine chochote, ikiwemo muda kuisha au 3xx (uelekezaji upya haufuatwi), hujaribiwa tena kwa vipindi vinavyoongezeka kwa takriban siku moja. 410 ikiwa jibu kwa uwasilishaji wa kiotomatiki huzima kituo mara moja; 410 ikiwa jibu kwa jaribio au uwasilishaji upya haikizimi. Baada ya siku tano za uwasilishaji ulioshindwa, kituo huzimwa pia. Kwa njia yoyote ile, mmiliki wake hutumiwa barua pepe. Hitilafu upande wa Lingara haihesabiwi kamwe katika kuzima kituo. Kwenye ukurasa wa Webhook unaweza kubofya “Tuma jaribio”, au “Wasilisha tena” kwa uwasilishaji wowote wa siku 30 zilizopita. Kila moja ni jaribio moja, halirudiwi kamwe, na hutumwa hata kwa kituo kilichozimwa.

Uwasilishaji hufanyika angalau mara moja na bila mpangilio. Tukio lilelile linaweza kufika mara mbili, na jaribio upya linaweza kufika baada ya tukio la baadaye. webhook-id ni ileile kwenye kila jaribio upya, na kwenye uwasilishaji upya hadi siku 30 baadaye. Rekodi kila id uliyoshughulikia kwa siku 30, na upuuze marudio. Panga kwa created_at ikiwa mpangilio ni muhimu.

Zungusha siri ya kutia sahihi

Kituo kinaweza kuwa na siri mbili za kutia sahihi kwa wakati mmoja. Zote mbili zikiwa zinatumika, webhook-signature hubeba maingizo mawili ya v1,, na mpokeaji anayekubali yoyote kati yake huendelea kufanya kazi. Ongeza siri mpya kwenye seva yako, isambaze, kisha ubatilishe ile ya zamani.

Mlisho

GET /v1/events kwa tokeni ya ufikiaji ya mteja hurudisha items (bahasha), next_cursor na has_more. Tokeni inahitaji events:read na wigo wa kila aina unayotaka kusikia: ikiwa na events:read pekee, mlisho ni mtupu. Huanza kuanzia sasa. Pitisha start=oldest ili kupata matukio ya takriban siku 30 zilizopita. Hauhitaji kituo cha umma wala siri ya kutia sahihi: tokeni ya ufikiaji huthibitisha nani anauliza. Ubadilishaji ulio hapa chini unaomba wigo yote miwili ambayo matukio ya mpango wa somo yanahitaji.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=events:read lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

next_cursor huwepo kila wakati: ihifadhi na uirudishe kama cursor. Ni ishara isiyo wazi: usiichambue. has_more ikiwa true inamaanisha uite tena sasa, na false inamaanisha umefikia ya hivi punde: uliza tena baadaye, au fungua mtiririko. Kiashiria cha zamani zaidi ya siku 30 hukataliwa kwa 410 na cursor_expired. Bila kiashiria, mlisho huanza kuanzia sasa, na matukio ya katikati yanarukwa. Ili kuyarejesha, ita kwa start=oldest, inayofikia nyuma kadiri matukio yanavyohifadhiwa, na uruke thamani za id ambazo tayari umezishughulikia.

Mtiririko

GET /v1/events/stream hubeba matukio yaleyale kama server-sent events. data ya kila fremu ya event ni bahasha moja, na id: ya kila fremu ni kiashiria, ishara ileile kama next_cursor, kwa hivyo unaweza kubadilisha kati ya mlisho na mtiririko bila pengo. Baada ya muunganisho kukatika, fremu ya done (mtiririko hujimaliza wenyewe mara kwa mara) au fremu ya error, unganisha tena ukiweka Last-Event-ID kuwa id: ya mwisho uliyopokea. Wateja wengi wa SSE hukufanyia hivi, na vivyo hivyo tailEvents katika maktaba za Lingara (streamEvents humo ni muunganisho mmoja tu). Ni kiashiria, si id ya tukio. Mtiririko hutuma mapigo ya moyo, kwa hivyo muunganisho uliokimya ni muunganisho uliokufa.

curl -N "https://api.getlingara.com/v1/events/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Tuma tukio kwa Lingara

POST /v1/events ikiwa na events:write hutuma tukio kwa Lingara kama {type, data}: world.context_changed (scene, source_lang, target_lang, level, na kwa hiari npc yenye name na persona, na tags) au world.practice_requested (topic na lugha na kiwango vilevile). Idempotency-Key inahitajika: hadi herufi 255 za ASCII zinazoonekana, kama UUID. Bila hiyo, jibu ni 400 na idempotency_key_required. Iweke mara moja kwa kila tukio, na utume ufunguo uleule kwenye jaribio upya. Ufunguo mmoja ni tukio moja: ndani ya siku moja, ombi la pili lenye ufunguo uleule hupata jibu la kwanza (sawa kama JSON, si baiti kwa baiti), hata kama mwili wake ni tofauti, na baada ya hapo hupata tukio lilelile, kama ilivyo hapa chini. Matukio yanayoingia hayatiwi sahihi: tokeni yako ya ufikiaji ndiyo uthibitisho. Eleza ulimwengu, kamwe si mchezaji: hakuna majina wala gumzo katika scene, npc, topic au tags.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=events:write lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

Kila sehemu ya maandishi ni mstari mmoja wa herufi zinazoonekana, zinazohesabiwa baada ya kuondoa nafasi za pembeni: scene na topic hadi 160, npc.name hadi 32, na npc.persona hadi 120. Mivunjiko ya mstari, vichupo na herufi nyingine za udhibiti hukataliwa, na vilevile herufi zisizoonekana na za uumbizaji: ubatilishaji wa mwelekeo, herufi zisizo na upana isipokuwa viunganishi ambavyo baadhi ya hati na emoji vinahitaji, kizuizi cha tag na herufi za matumizi ya faragha. tags hushikilia hadi tokeni 8 za mashine kwa herufi ndogo, kila moja hadi herufi 24, na hazifiki kamwe kwenye mpango wa somo. level ni 1 hadi 9, na lugha hizo mbili lazima ziwe tofauti. Ombi lililo nje ya mipaka hii hukataliwa kwa 400 na halirekodi tukio lolote.

Ukiwa na "generate": true (chaguo-msingi kwa world.practice_requested), tokeni inahitaji pia lesson_plans:write. Bila hiyo, ombi hukataliwa kwa 403 na hakuna tukio linalorekodiwa. Ikiwa nayo, Lingara huanzisha mpango wa somo, kwa ukaguzi uleule na gharama ileile kama kuuunda moja kwa moja, na reaction ya jibu la 202 husema kilichotokea. Kwa started na plan_status generating, hufuata lesson_plan.ready au lesson_plan.failed ambayo data.plan_id yake ni plan_id ya jibu, kwenye kila njia unayotumia. Kwa partial au complete, mpango ulitoka kwenye maktaba na unaweza kusomwa sasa, na hakuna tukio linaloahidiwa: huenda bado likafika, kwa hivyo generating pekee ndiyo inayostahili kusubiriwa. Kwa refused au failed, tukio bado linasimama. Halijaribiwi tena chini ya ufunguo uleule, kwa hivyo tuma tukio jipya ili kujaribu tena.

Jaribio upya ndani ya siku moja hupata jibu la kwanza. Jaribio upya baada ya hapo hujengwa upya kutoka kwa tukio lililohifadhiwa, ambalo huhifadhi mpango lililouanzisha lakini si sababu ya mwitikio kukataliwa. Kwa hivyo jaribio upya la kuchelewa linaweza kujibu kwa reaction failed na internal: hiyo inamaanisha matokeo ya kwanza hayakurekodiwa, si kwamba hakuna mpango. Soma mpango kwa plan_id yake ikiwa uliihifadhi, au tuma tukio jipya.

Tidewater Games: mchezo bila seva

Tidewater Games, studio ya kubuni, inaunda mchezo wa Godot ambamo mchezaji anachunguza soko la usiku. Msanidi wake huendesha mchezo kwenye mashine yake mwenyewe, kwa mteja wake mwenyewe.

Mchezaji anaingia kwenye kibanda cha tambi. Mchezo hutuma world.context_changed ukiwa na "generate": true, amri iliyo katika sehemu ya matukio yanayoingia hapo juu, na huhifadhi plan_id kutoka kwenye jibu.

Ikiwa plan_status ni generating, mchezo husoma mtiririko, au huuliza mlisho mara kwa mara, hadi lesson_plan.ready yenye plan_id hiyo ifike. Kisha husoma mpango kwa lesson_plans:read, kama ilivyo hapa chini. Ikiwa mpango tayari ulikuwa complete, huusoma mara moja.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/lesson-plans/$ID" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Baadaye studio inaongeza seva ndogo yenye kituo cha HTTPS na kukisajili kwa lesson_plan.ready. Tukio lilelile hufika hapo, likiwa na id ileile, na msimbo wa mchezo wa kulisoma haubadiliki.

Siri ya mteja haipaswi kamwe kusafirishwa ndani ya muundo wa mchezo, kwa sababu chochote kilicho kwenye kifaa cha mchezaji kinaweza kusomwa. Hadi Lingara itakapowezesha kuingia kwa niaba ya mchezaji, mchezo ulio kwenye mashine za wachezaji huwasiliana na seva yake yenyewe, na nakala ya msanidi mwenyewe pekee ndiyo huwasiliana na Lingara moja kwa moja.

Gharama ya matukio

Matumizi ya mteja wako huhesabu kila tukio linaloingia lililokubaliwa, kila ombi la mlisho na kila mtiririko uliofunguliwa, kama yanavyohesabu kila ombi la /v1/. Tukio lililotumwa likiwa na "generate": true huhesabiwa pia kama mpango wa somo. Kila uwasilishaji wa webhook huhesabiwa mara moja kwa kila tukio kwa kila kituo, kwenye 2xx yake ya kwanza, vyovyote vile jaribio hilo ni la ngapi. Hauhesabiwi tena kamwe, na jaribio halihesabiwi kamwe. GET /v1/usage huonyesha mwezi hadi sasa.

Ikiwa tafsiri na marejeleo ya Kiingereza yanatofautiana, marejeleo ya Kiingereza ndiyo sahihi.