W tej sekcji opisano format danych JSON, gdy Actions on Google wywołuje Twoją realizację za pomocą pakietu SDK Actions.
Po rozpoczęciu rozmowy jest identyfikowany przez unikalny conversationId. Dla każdego kolejnego użytkownika
do Asystenta, Twoja realizacja otrzyma zamiar, który
webhook musi przetworzyć dane i na nie zareagować. Ten plik conversationIdjest utrwalony w każdym żądaniu,
do zakończenia rozmowy.
Treść żądania
Gdy użytkownik sformułuje pierwsze zapytanie lub wpisze jakieś kolejne zapytanie, Asystent wyśle prośbę o połączenie. do realizacji transakcji. Żądania webhooka rozmowy z Asystenta zawierają dane takie jak wywołana intencja czy nieprzetworzony tekst użytkownika i możliwości, jakie daje urządzenie użytkownika.
Podsumowanie najważniejszych pól żądania w formacie webhooka rozmowy:
| Pole | Opis |
|---|---|
isInSandbox |
Ta zmienna logiczna jest używana głównie do
transakcji, aby wskazać, czy webhook powinien obsługiwać to żądanie w trybie piaskownicy
i trybu uzyskiwania zgody. W trybie piaskownicy Twój webhook nie powinien obciążać użytkowników ani realizować żadnych zamówień zakupu.
Domyślna wartość to „true”. |
surface |
Informacje o platformie Asystenta, z którą użytkownik wchodzi w interakcję, oraz o jej możliwościach. |
Inputs |
Informacje o żądaniu wywołania. W przypadku wywołania wyzwalającego obejmuje to element intent, który odzwierciedla działanie. Kolejne żądań w wątku, ten obiekt może również zawierać argumenty odpowiadające argumentowi oczekiwane dane wejściowe określone w realizacji. |
User |
Informacje o użytkowniku, który wysłał żądanie. Te informacje obejmują uprawnienia zgodnie z ustawieniami regionalnymi użytkownika i jego ustawieniami regionalnymi. |
Conversation |
Informacje o kontekście rozmowy, w tym identyfikator rozmowy, jej typ (np. czy żądanie inicjuje nową rozmowę) i token rozmowy, służący do przechowywania trwałych danych przez cały czas trwania rozmowy. |
availableSurfaces |
Te informacje są używane do: do prowadzenia rozmów z różnymi platformami. |
Przykład prostego żądania wywołania
Fragment kodu poniżej zawiera przykład żądania wywołania w formacie webhooka rozmowy.
{
"user": {
"userId": "ABwppHEF...",
"locale": "en-US",
"lastSeen": "2018-03-21T17:59:52Z",
"userStorage": "{\"data\":{}}"
},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {
"conversationId": "1521784527171",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.MAIN",
"rawInputs": [
{
"inputType": "VOICE",
"query": "Talk to my test app"
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
Przykład prostej prośby o rozmowę
Poniższy fragment kodu zawiera przykład żądania konwersacyjnego w formacie webhooka rozmowy: gdzie dane wejściowe użytkownika są ciągiem tekstowym (np. „Moja szczęśliwa liczba to 88”):
{
"user": {
"userId": "ABwppHEF...",
"locale": "en-US",
"lastSeen": "2018-03-21T17:59:52Z",
"userStorage": "{\"data\":{}}"
},
"device": {},
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
},
"conversation": {
"conversationId": "1521784527171",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.TEXT",
"rawInputs": [
{
"inputType": "VOICE",
"query": "My lucky number is 88."
}
]
}
],
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
},
{
"name": "actions.capability.WEB_BROWSER"
}
]
}
]
}
Treść odpowiedzi
Content-Type w nagłówku postów HTTP z punktu końcowego realizacji
do Asystenta musi mieć wartość application/json.
Odpowiedź w formacie webhooka konwersacji zawiera dane takie jak rzeczywisty interfejs użytkownika (w tym komponenty audio i wizualne) oraz intencję, która może zostać wywołana w kolejnych żądaniach (nazywana oczekiwaną intencją). Oczekiwany intencją mogą być dowolne intencje rozumiene przez Asystenta, zgodnie z opisem w dokumentacji interfejsu API Intents.
Aby dowiedzieć się więcej o formatowaniu interfejsu użytkownika, gdy: wyświetlane w Asystencie, zobacz Odpowiedzi.
Przykład prostej odpowiedzi
Fragment poniżej zawiera przykładową prostą odpowiedź w rozmowie webhooka.
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.TEXT"
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
}
}
]
}
}
}
]
}
Przykład Asystenta
Fragment kodu poniżej pokazuje przykład użycia intencji pomocniczej w rozmowie
webhooka. W tym przykładzie webhook używa funkcji
actions.intent.OPTIONS ma zamiar poinstruować Asystenta, że ma uzyskać
do wyboru wielu opcji.
Aby dowiedzieć się więcej o korzystaniu z intencji pomocniczych, przeczytaj Przewodnik dla Pomocników.
{
"expectUserResponse": true,
"expectedInputs": [
{
"possibleIntents": [
{
"intent": "actions.intent.OPTION",
"inputValueData": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"carouselSelect": {
"items": [
{
"optionInfo": {
"key": "one",
"synonyms": [
"synonym of KEY_ONE 1",
"synonym of KEY_ONE 2"
]
},
"description": "Description of number one",
"title": "Number one"
},
{
"optionInfo": {
"key": "two",
"synonyms": [
"synonym of KEY_TWO 1",
"synonym of KEY_TWO 2"
]
},
"description": "Description of number two",
"title": "Number two"
}
]
}
}
}
],
"inputPrompt": {
"richInitialPrompt": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this shows an example of a carousel"
}
}
],
"suggestions": [
{
"title": "1"
},
{
"title": "2"
}
]
}
}
}
]
}
Przykład strony kończenia rozmowy
Fragment kodu poniżej to przykład prostej odpowiedzi na zakończenie rozmowy .
expectedUserResponse
wartość false w wiadomości z odpowiedzią informuje Asystenta, że nie będzie już
dane wejściowe są prawidłowe i powinny zakończyć bieżący wątek.
finalResponse
wskazuje, co Asystent powinien wyświetlić lub wyświetlić użytkownikowi przed
rozmowa dobiegnie końca.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Informacje o zastępowaniu domyślnego działania, gdy użytkownicy wywołują standardowe działanie aby zakończyć rozmowę z Asystentem, zobacz Wyjścia rozmów.