Individualios API integracijos leidžia Jūsų pokalbių robotui užklausti tiesioginės informacijos iš Jūsų ERP, sandėlio, CRM ar kitos sistemos. Jos taip pat gali atlikti pakeitimus, pavyzdžiui, užregistruoti vizitą. Integracija saugo bazinį URL adresą, o kiekviena operacija apibrėžia vieną iškviečiamą užklausą. Vėliau pasirinktas operacijas priskiriate pokalbių robotui kaip AI veiksmus.
Prieš pradedant
Patikrinkite, ar Jūsų plane yra numatytos individualios API integracijos. Jums reikės galinio taško (angl. endpoint) URL adreso, HTTP metodo, parametrų pavadinimų bei tipų, autentifikavimo reikalavimų ir pavyzdinio atsakymo. Galinis taškas privalo būti pasiekiamas iš ChatLab serverių; localhost Jūsų kompiuteryje nėra gamybinis galinis taškas.
Konfigūruodami naudokite HTTPS ir bandomąją paslaugą arba bandomuosius įrašus. Bandomoji užklausa realiai iškviečia galinį tašką, todėl POST, PATCH arba DELETE užklausos gali pakeisti išorinius duomenis. Jei įmanoma, užtikrinkite, kad operacijas būtų saugu kartoti.
1. Sukurkite integraciją
- Pagrindiniame meniu atidarykite Custom Integrations (Individualios integracijos).
- Spustelėkite + Define API Integration (Apibrėžti API integraciją).
- Įveskite API name (API pavadinimas) ir API Base URL (API bazinis URL), pavyzdžiui,
https://api.example.com. - Spustelėkite Create API Integration (Sukurti API integraciją).
- Jos sąrašo įraše spustelėkite View (Peržiūrėti), tada + Define API Operation (Apibrėžti API operaciją).
2. Apibrėžkite operaciją
Suteikite operacijai aiškią etiketę ir mašininiu būdu skaitomą Operation name (Operacijos pavadinimas), pavyzdžiui, getProductDetails. Operacijos pavadinimui naudokite tik raides ir skaičius, nenaudokite tarpų ar pabraukimo brūkšnių. Aprašykite, ką operacija atlieka ir kada pokalbių robotas turėtų ją naudoti.
Įveskite santykinį URI adresą, pavyzdžiui, /v1/products/@productId@. Bazinis URL ir URI sudaro visą užklausos adresą.
Kai kuriose senesnėse ekrano kopijose rodomi ankstesni pavyzdiniai pavadinimai arba riestiniai skliaustai vietoj vietosžymų. Vadovaukitės dabartine sintakse: naudokite operacijų pavadinimus, tokius kaip getProductDetails, ir parametrų vietosžymas, apsuptas @ simboliais.
Kelio ir užklausos parametrai
Spustelėkite Add path variable (Pridėti kelio kintamąjį), kad apibrėžtumėte productId. Nustatykite jo duomenų tipą bei reikšmės šaltinį, tada įterpkite @productId@ į URI adresą. Kelio kintamieji yra privalomi, ir kiekvienas apibrėžtas kelio kintamasis turi atsirasti URI adrese prieš išsaugant ar atliekant testavimą.
Naudokite Add query parameter (Pridėti užklausos parametrą) parametrams, tokiems kaip limit arba language, kurie rašomi po URL klaustuko. Įveskite parametrą, kurio tikisi Jūsų API, jo tipą, aprašymą ir reikšmės šaltinį.
Galimi reikšmių šaltiniai:
- Provided by user or chatbot (Pateikta naudotojo arba pokalbių roboto): modelis pateikia reikšmę iš pokalbio. Paaiškinkite pageidaujamą formatą ir tinkamai pažymėkite privalomas reikšmes.
- Constant (Konstanta): reikšmė, sukonfigūruota pačioje operacijoje, pavyzdžiui, fiksuotas paskyros identifikatorius arba ribotos prieigos API prisijungimo duomenys.
- Random value (Atsitiktinė reikšmė): automatiškai sugeneruota reikšmė.
- Client context (Kliento kontekstas): reikšmė, perduodama iš pagrindinės svetainės, jei ši funkcija pasiekiama Jūsų paskyroje. Žr. Chat API.
Skaliariniai tipai apima eilutę (angl. string), sveikąjį skaičių (angl. integer), dešimtainį skaičių (angl. double) ir loginę reikšmę (angl. boolean). Užklausos turinio (angl. body) parametrai taip pat palaiko eilučių ir sveikųjų skaičių masyvus.
3. Sukonfigūruokite metodą ir užklausos turinį
Pasirinkite GET, POST, PUT, PATCH arba DELETE, atsižvelgdami į savo galinį tašką. Kitiems nei GET metodams redaktorius siūlo raw (neapdorotą) arba form-data užklausos turinį.
Neapdorotam JSON turiniui apibrėžkite užklausos turinio parametrus ir įterpkite jų @name@ vietosžymas į šabloną. Pridėkite atitinkamą Content-Type antraštę, kurios reikalauja Jūsų galinis taškas. Pavyzdžiui, naudojant eilutės parametrą name ir eilučių masyvo parametrą tags:
{
"name": "@name@",
"tags": @tags@
}
Tai yra šablonas, o ne tiesioginis JSON, kol neatliktas reikšmių pakeitimas. Masyvų vietosžymos neturi būti apsuptos kabutėmis. Kiekvienas apibrėžtas užklausos turinio parametras privalo būti panaudotas šablone, kai taikomas neapdoroto turinio redaktorius. Testavimo metu patikrinkite sugeneruotą užklausą, įskaitant tekstą su kabutėmis ar specialiaisiais simboliais.
4. Pridėkite autentifikavimo antraštes
Naudokite Add header (Pridėti antraštę), kad apibrėžtumėte antraštes, kurių tikisi API. Nešėjo prieigos raktui (angl. bearer token) naudokite antraštės pavadinimą Authorization, reikšmės šaltinį Constant ir reikšmę Bearer JŪSŲ_APRIBOTAS_RAKTAS.
Saugokite slaptus duomenis ir nekelkite jų į raginimus ar URL adresus. Venkite operacijų, kurios grąžina prisijungimo raktus modeliui ir pasikliauja instrukcijomis jiems paslėpti. Geriau naudokite serverio integracijos galinį tašką, kuris pats tvarko autentifikavimą ir pateikia tik leidžiamą operaciją.
5. Išsaugokite ir ištestuokite užklausą
- Operacijų redaktoriuje spustelėkite Save changes (Išsaugoti pakeitimus). Skirtingai nei įprasti pokalbių roboto Settings, šis redaktorius turi aiškų išsaugojimo mygtuką.
- Spustelėkite Test API Operation (Išbandyti API operaciją). Šis mygtukas yra neaktyvus, kol pakeitimai nėra išsaugoti.
- Įveskite reprezentatyvias parametrų reikšmes. Masyvų bandomosioms įvestims naudokite kableliais atskirtas reikšmes.
- Testuokite tik su tais duomenimis, kuriuos turite teisę skaityti ar keisti.
- Peržiūrėkite būsenos kodą, atsakymo turinį, užklausos URL, antraštes, turinį ir bet kokį rezultatų lauke rodomą įspėjimą.
- Ištaisykite klaidas, išsaugokite ir prireikus pakartokite.
Nesidalykite testavimo rezultatais, kuriuose yra prisijungimo duomenų. Jei įmanoma, grąžinkite konkrečius, puslapiais suskirstytus duomenis: didelės apimties atsakai gali būti sutrumpinti dar prieš pasiekiant modelį.
6. Priskirkite operaciją pokalbių robotui
Atidarykite savo pokalbių robotą, tada eikite į Settings > Actions (Nustatymai > Veiksmai). Naudodami pliuso mygtuką pridėkite veiksmą, suraskite savo operaciją ties individualiomis API ir ją priskirkite arba įjunkite. Vien tik paskyros lygio integracijos sukūrimas nepadaro kiekvienos operacijos pasiekiamos kiekvienam pokalbių robotui.
Peržiūrėkite veiksmo instrukcijas ir galimus saugumo nustatymus, tada palaukite, kol pasirodys išsaugojimo būsena. Apie veiksmų redaktorių skaitykite skiltyje AI veiksmai.
7. Paaiškinkite, kada ją naudoti
Atidarykite Settings > Role & Behavior (Nustatymai > Vaidmuo ir elgsena).
Jei naudojate individualias vaidmens instrukcijas, pasirinkite Custom Role Definition (Individualus vaidmens apibrėžimas) ir pridėkite tikslią taisyklę, pavyzdžiui: „Kai lankytojas paklausia, ar prekė yra sandėlyje, iškvieskite getProductDetails nurodydami jos prekės ID. Praneškite apie gautą likutį. Jei paieška nepavyksta, paaiškinkite, kad likučio patikrinti nepavyko.“
Išsaugokite kitas naudingas pokalbių roboto instrukcijas. Palaukite, kol pasirodys išsaugojimo būsena, tada naudokite Overview (Apžvalga) peržiūrą, kad patikrintumėte realius klausimus, trūkstamus parametrus, klaidas ir neleistinas užklausas. Peržiūros pokalbiai gali iškviesti realias operacijas.
AI iškvietimas nėra garantuotas ir nebūtinai vykdomas tik vieną kartą. Testuokite naudodami modelį, parinktą Jūsų pokalbių robotui; nepasikliaukite vien modelio pavadinimu manydami, kad jis užtikrins teisingą įrankių naudojimą.
Saugumas ir trikčių šalinimas
Prieš grąžindamas slaptą informaciją arba atlikdamas pakeitimą, Jūsų galinis taškas privalo autentifikuoti užklausas ir autorizuoti kiekvieno naudotojo prieigą. Naršyklės pateiktas kliento ID, el. paštas, užsakymo numeris ar konteksto laukas nėra pakankamas tapatybės įrodymas. Jei per kliento kontekstą perduodate konkretaus naudotojo prieigos raktą, Jūsų serveris privalo jį patvirtinti.
Grąžinkite tik tuos laukus, kurių pokalbių robotui tikrai reikia, pavyzdžiui, užsakymo būseną vietoj viso kliento profilio. Raginimo instrukcijos gali padėti parinkti formuluotę, tačiau negali garantuoti, kad modeliui perduoti konfidencialūs duomenys liks neatskleisti.
Jei užklausa sėkmingai atliekama testavimo redaktoriuje, tačiau nepavyksta pokalbio metu, patikrinkite priskirtą veiksmą, jo įjungimo būseną, instrukcijas, privalomus parametrus ir pasiekiamą kontekstą. Jei nepavyksta abu variantai, patikrinkite URL, HTTP metodą, autentifikavimą, sugeneruotą turinį ir savo galinio taško žurnalus. Venkite pakartotinai bandyti vykdyti įrašymo operaciją, kol nežinote, ar ankstesnė užklausa buvo sėkminga.