Az egyéni API-integrációk (Custom API integrations) lehetővé teszik, hogy a chatbot élő adatokat kérdezzen le az Ön ERP-, raktárkezelő-, CRM- vagy egyéb rendszeréből. Módosításokat is végezhetnek, például létrehozhatnak egy időpontot. Egy integráció tárolja az alap URL-címet; az egyes műveletek pedig egy-egy hívható kérést határoznak meg. A kiválasztott műveleteket ezután AI actions (AI-műveletek) formájában csatolhatja a chatbothoz.
Mielőtt hozzáfogna
Ellenőrizze, hogy a csomagja tartalmazza-e a Custom API integrations funkciót. Szüksége lesz a végpont URL-címére, a HTTP-metódusra, a paraméterek nevére és típusára, a hitelesítési követelményekre, valamint egy mintaválaszra. A végpontnak elérhetőnek kell lennie a ChatLab szervereiről; a számítógépén futó localhost nem éles végpont.
A beállításhoz használjon HTTPS-t, valamint egy tesztkörnyezetet vagy tesztrekordokat. A tesztkérés valóban meghívja a végpontot, így egy POST, PATCH vagy DELETE kérés módosíthatja a külső adatokat. Ahol csak lehetséges, alakítsa úgy a műveleteket, hogy biztonságosan megismételhetők legyenek.
1. Integráció létrehozása
- Nyissa meg a Custom Integrations (Egyéni integrációk) menüpontot a fő navigációban.
- Kattintson a + Define API Integration (+ API-integráció definiálása) gombra.
- Adja meg az API name (API neve) és az API Base URL (API alap URL-címe) értékét, például
https://api.example.com. - Kattintson a Create API Integration (API-integráció létrehozása) gombra.
- A listában megjelenő elemnél kattintson a View (Megtekintés), majd a + Define API Operation (+ API-művelet definiálása) lehetőségre.
2. A művelet definiálása
Adjon a műveletnek egy jól felismerhető címkét és egy géppel olvasható Operation name (Művelet neve) értéket, például getProductDetails. A művelet nevében csak betűket és számokat használjon, szóközöket vagy aláhúzásjeleket ne. Írja le, mit csinál a művelet, és mikor kell a chatbotnak használnia azt.
Adja meg a relatív URI-t, például /v1/products/@productId@. Az alap URL-cím és az URI együtt alkotja a kérés címét.
Néhány meglévő képernyőképen régebbi példanevek vagy kapcsos zárójeles helyőrzők láthatók. Kövesse az alábbi aktuális szintaxist: használjon olyan műveletneveket, mint a getProductDetails, és @ jelekkel körülvett paraméter-helyőrzőket.
Útvonal- és lekérdezési paraméterek (Path and Query Parameters)
Kattintson az Add path variable (Útvonalváltozó hozzáadása) gombra a productId definiálásához. Állítsa be az adattípusát és az érték forrását, majd illessze be a @productId@ kódot az URI-ba. Az útvonalváltozók kitöltése kötelező, és a mentés vagy a tesztelés előtt minden definiált útvonalváltozónak szerepelnie kell az URI-ban.
Használja az Add query parameter (Lekérdezési paraméter hozzáadása) gombot az olyan paraméterekhez, mint a limit vagy a language, amelyek az URL-ben a kérdőjel után következnek. Adja meg az API által elvárt nevet, a típust, a leírást és az érték forrását.
A választható értékforrások:
- Provided by user or chatbot (Felhasználó vagy chatbot által megadott): a modell a beszélgetésből biztosítja az értéket. Magyarázza el az elvárt formátumot, és jelölje meg megfelelően a kötelező értékeket.
- Constant (Állandó): a műveletben konfigurált fix érték, például egy rögzített fiókazonosító vagy korlátozott jogosultságú API-hitelesítési adat.
- Random value (Véletlenszerű érték): automatikusan generált érték.
- Client context (Klienskontextus): a gazdawebhely által átadott érték, amennyiben ez elérhető az Ön fiókjában. Lásd: Chat API.
A skaláris típusok közé tartozik a string, az integer, a double és a boolean. A törzsparaméterek (Body parameters) a string és integer tömböket is támogatják.
3. A metódus és a törzs konfigurálása
Válassza a GET, POST, PUT, PATCH vagy DELETE lehetőséget a végpontjának megfelelően. A GET-től eltérő metódusok esetén a szerkesztő raw (nyers) vagy form-data kéréstartalmat kínál fel.
Nyers JSON-törzs esetén definiálja a törzsparamétereket, és illessze be a @name@ helyőrzőiket a sablonba. Adja hozzá a végpont által elvárt megfelelő Content-Type fejlécet. Például egy string típusú name és egy string-tömb típusú tags paraméter esetén:
{
"name": "@name@",
"tags": @tags@
}
Ez egy sablon, és a behelyettesítésig nem minősül érvényes JSON-nak. A tömbök helyőrzőit tilos idézőjelek közé tenni. A nyers törzsszerkesztő használatakor minden definiált törzsparaméternek szerepelnie kell a sablonban. A tesztelés során ellenőrizze a legenerált kérést, beleértve az idézőjeleket vagy speciális karaktereket tartalmazó szövegeket is.
4. Hitelesítési fejlécek hozzáadása
Használja az Add header (Fejléc hozzáadása) gombot az API által elvárt fejlécek definiálásához. Bearer-token esetén használja az Authorization fejlécnevet, a Constant értékforrást és a Bearer YOUR_RESTRICTED_TOKEN értéket.
Ne tartson titkos adatokat a promptokban és az URL-címekben. Kerülje az olyan műveleteket, amelyek bejelentkezési tokeneket adnak vissza a modellnek, és az utasításokra bízzák azok elrejtését. Előnyben részesítendő egy olyan szerveroldali integrációs végpont, amely saját maga kezeli a hitelesítést, és kizárólag az engedélyezett műveletet teszi elérhetővé.
5. A kérés mentése és tesztelése
- Kattintson a Save changes (Módosítások mentése) gombra a műveletszerkesztőben. A normál chatbot Settings (Beállítások) menüvel ellentétben ez a szerkesztő külön mentés gombbal rendelkezik.
- Kattintson a Test API Operation (API-művelet tesztelése) gombra. Ez a gomb mindaddig inaktív, amíg mentetlen módosításai vannak.
- Adjon meg reprezentatív paraméterértékeket. Tömb típusú tesztbemeneteknél használjon vesszővel elválasztott értékeket.
- Csak olyan adatokon futtassa a tesztet, amelyek olvasására vagy módosítására jogosult.
- Vizsgálja meg az állaporkódot, a választörzset, a kérés URL-jét, a fejléceket, a törzset és az eredményeknél megjelenő esetleges figyelmeztetéseket.
- Javítsa a hibákat, mentse a változtatásokat, és szükség szerint ismételje meg a folyamatot.
Ne osszon meg hitelesítési adatokat tartalmazó tesztkimeneteket. Lehetőség szerint célzott, lapozható adatokat adjon vissza: a nagy válaszok csonkolódhatnak, mielőtt elérnék a modellt.
6. A művelet csatolása a chatbothoz
Nyissa meg a chatbotot, majd válassza a Settings > Actions (Beállítások > Műveletek) lehetőséget. A plusz gombbal adjon hozzá egy műveletet, keresse meg a saját műveletét az egyéni API-k alatt, és csatolja vagy engedélyezze azt. Egy fiókszintű integráció létrehozása önmagában még nem tesz minden műveletet elérhetővé minden chatbot számára.
Tekintse át a művelet utasításait és az elérhető biztonsági beállításokat, majd várja meg a mentett állapotot. A műveletszerkesztővel kapcsolatban lásd: AI actions.
7. A használat feltételeinek ismertetése
Nyissa meg a Settings > Role & Behavior (Beállítások > Szerepkör és viselkedés) menüpontot.
Ha egyéni szerepkör-utasításokat használ, válassza a Custom Role Definition (Egyéni szerepkör-meghatározás) lehetőséget, és adjon meg egy pontos szabályt, például: "Amikor a látogató megkérdezi, hogy egy termék raktáron van-e, hívd meg a getProductDetails műveletet a termékazonosítóval. Közöld a visszaadott elérhetőséget. Ha a lekérdezés sikertelen, magyarázd el, hogy az elérhetőséget nem sikerült ellenőrizni."
Őrizze meg a chatbot többi hasznos utasítását. Várja meg a mentett állapotot, majd az Overview (Áttekintés) előnézetében teszteljen valósághű kérdéseket, hiányzó paramétereket, hibákat és jogosulatlan kéréseket. Az előnézeti beszélgetések valódi műveleteket hívhatnak meg.
Az AI általi meghívás nem garantált, és nem feltétlenül egyszeri. Teszteljen a chatbothoz kiválasztott modellel; ne feltételezze, hogy a modell neve önmagában garantálja a helyes eszközhasználatot.
Biztonság és hibaelhárítás
A végpontnak hitelesítenie kell a kéréseket, és ellenőriznie kell az egyes felhasználók hozzáférési jogosultságát, mielőtt bizalmas információkat adna vissza vagy módosítást hajtana végre. A böngésző által megadott ügyfél-azonosító, e-mail-cím, rendelési szám vagy kontextusmező nem elegendő a személyazonosság igazolására. Ha a klienskontextuson keresztül felhasználónkénti tokent ad át, a szervernek érvényesítenie kell azt.
Csak azokat a mezőket adja vissza, amelyekre a chatbotnak szüksége van, például a teljes ügyfélprofil helyett csak a rendelés állapotát. A promptban megadott utasítások irányíthatják a megfogalmazást, de nem garantálhatják, hogy a modellnek visszaadott bizalmas adatok rejtve maradnak.
Ha a kérés a tesztszerkesztőben sikeres, de egy beszélgetésben nem, ellenőrizze a csatolt műveletet, annak engedélyezett állapotát, az utasításokat, a kötelező paramétereket és az elérhető kontextust. Ha mindkettő meghiúsul, vizsgálja meg az URL-t, a HTTP-metódust, a hitelesítést, a legenerált törzset és a végpont naplófájljait. Kerülje az írási műveletek ismételt újrapróbálását mindaddig, amíg nem biztos abban, hogy az előző kérés sikeres volt-e.