Bu bölümde, Actions on Google'ın Dialogflow v2 aracılığıyla karşılamanızı çağırdığı durumlarda JSON yükünün biçimi açıklanmaktadır.
Actions on Actions oluşturmak için Dialogflow'u kullanıyorsanız istek karşılama mantığınız, Actions on Google sohbet webhook'u biçimi yerine kendi standart webhook biçimi üzerinden Dialogflow ile iletişim kurar. Dialogflow webhook biçimi, görüşme webhook'u biçimine ilişkin tüm bilgilerin yanı sıra bağlamlar ve parametreler hakkındaki bilgiler gibi Dialogflow'a özgü ek verileri içerir.
Dialogflow webhook'larıyla ilgili JSON mesajlarıyla ilgili daha fazla örnek görmek için bu GitHub projesine bakabilirsiniz.
İstek içeriği
Dialogflowflow'dan gelen request mesajı, Dialogflow webhook biçiminde veriler içerir. Bu nesne, aşağıda özetlendiği gibi Actions on Google'a özgü bilgileri içerir:
originalDetectIntentRequest.source
değeri "google"dır.originalDetectIntentRequest.version
, isteğin Actions on Google sürümünü gösterir.originalDetectIntentRequest.payload
, Asistan'dan gelen istek JSON'si de dahil olmak üzere Actions on Google'a özel önemli bilgileri içerir.Conversation.conversationToken
alanı, Dialogflow webhook istekleri tarafından desteklenmiyor. Bunun yerine, karşılamanız gereken verileri görüşme ömrü boyunca korumak için bir Dialogflow bağımı kullanabilirsiniz.
Basit çağrı isteği örneği
Aşağıdaki snippet'te Dialogflow webhook biçiminde bir çağrı isteği örneği gösterilmektedir.
{
"responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
"queryResult": {
"queryText": "GOOGLE_ASSISTANT_WELCOME",
"action": "input.welcome",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
"displayName": "Default Welcome Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "Talk to my test app",
"inputType": "VOICE"
}
],
"intent": "actions.intent.MAIN"
}
],
"user": {
"lastSeen": "2018-03-16T22:08:48Z",
"permissions": [
"UPDATE"
],
"locale": "en-US",
"userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
},
"conversation": {
"conversationId": "${SESSIONID}",
"type": "NEW"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
Basit sohbet isteği örneği
Aşağıdaki snippet'te Dialogflow webhook biçiminde bir sohbet isteği örneği gösterilmektedir. Bu örnekte, kullanıcı girişi metin dizesidir.
{
"responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
"queryResult": {
"queryText": "query from the user",
"action": "action.name.of.matched.dialogflow.intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
},
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
"displayName": "Name of Dialogflow Intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
},
{
"name": "actions.capability.WEB_BROWSER"
},
{
"name": "actions.capability.MEDIA_RESPONSE_AUDIO"
}
]
},
"inputs": [
{
"rawInputs": [
{
"query": "query from the user",
"inputType": "KEYBOARD"
}
],
"arguments": [
{
"rawText": "query from the user",
"textValue": "query from the user",
"name": "text"
}
],
"intent": "actions.intent.TEXT"
}
],
"user": {
"lastSeen": "2017-10-06T01:06:56Z",
"locale": "en-US",
"userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
},
"conversation": {
"conversationId": "1522951193000",
"type": "ACTIVE",
"conversationToken": "[]"
},
"availableSurfaces": [
{
"capabilities": [
{
"name": "actions.capability.SCREEN_OUTPUT"
},
{
"name": "actions.capability.AUDIO_OUTPUT"
}
]
}
]
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
Yardımcı sonuç örneği
Aşağıdaki snippet, Dialogflow webhook biçimindeki bir yardımcı sonuç örneğini gösterir. Bu örnekte, webhook, Asistan'a kullanıcının onayını alması gerektiğini bildirdikten sonra kullanıcının verdiği yanıt gösterilmektedir.
{
"responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
"queryResult": {
"queryText": "actions_intent_CONFIRMATION",
"action": "Dialogflow action name of matched intent",
"parameters": {},
"allRequiredParamsPresent": true,
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
"parameters": {
"CONFIRMATION": true
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow action name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {},
"inputs": [
{
"rawInputs": [
{
"query": "yes",
"inputType": "VOICE"
}
],
"arguments": [
{
"name": "CONFIRMATION",
"boolValue": true
}
],
"intent": "actions.intent.CONFIRMATION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
Yanıt gövdesi
Karşılama uç noktanızdan Asistan'a giden HTTP yayınlarının başlığındaki Content-Type
, application/json
olmalıdır.
Karşılamanızın Dialogflow'a gönderdiği yanıt mesajı, Dialogflow webhook biçiminde olmalıdır.
Asistan'la iletişim kurarken yanıtınız genellikle "google
" nesnesini içine alan bir payload
nesnesi içerir. "google
" yük nesnesi, Actions on Google'a özel bilgileri içerir. En az bir expectUserResponse
alanı ve richResponse
veya systemIntent
alanı içermelidir.
"google
" yük nesnesi için önemli alanlar aşağıda özetlenmiştir:
Alan | Açıklama |
---|---|
expectUserResponse |
Sipariş karşılamanızın bir kullanıcıdan yanıt bekleyip beklemediğini belirtir. Görüşmenin devam edeceği zaman için değeri true , görüşmeyi sonlandırmak için ise false olarak ayarlayın. |
userStorage |
Belirli bir kullanıcıya bağlı kalıcı verileri depolar. Toplam depolama alanı miktarı 10.000 bayttır. |
richResponse |
Bu alan, Asistan'ın oluşturması için ses, metin, kart, öneri veya yapılandırılmış veri içerir. Actions on Google için zengin yanıtlar kullanma hakkında daha fazla bilgi edinmek isterseniz Zengin yanıtlar konusuna bakın. |
systemIntent |
Bu alan, ExpectedInput.possibleIntents ile aynı yapıya sahiptir. Sipariş karşılama işleminiz yardımcı amaç kullanıyorsa yanıtınız genellikle bir systemIntent içerir. systemIntent öğesindeki possibleIntents alanı, inputValueData alan adı data olarak değiştirilmek üzere ExpectedIntent
nesnesine ayarlanmalıdır.
|
ExpectedIntent
nesnesinin içinde şu değerleri belirtirsiniz:
- niyet: Yardımcı için, kullanıcının sağlamasını istediğiniz bilgi türünü belirten bir amaç adı ve
- data: Asistan'ın yardımcıyı yürütmesi için gerekli olan verileri açıklayan bir dize olan değer spesifikasyonu.
Örneğin, kullanıcının iznini istiyorsanız intent
öğesini actions.intent.PERMISSSION
olarak, data
öğesini de bu türe ait alanlarla birlikte değer spesifikasyonunu "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
olarak ayarlayın.
Aşağıdaki listede, Dialogflow webhook yanıtı için systemIntent
içinde ayarlayabileceğiniz yardımcılara yönelik değer spesifikasyonu dizeleri özetlenmektedir. Konuşma kontrolüyle ilgili Actions on Google amaçlarının tam listesi için Intents referansına bakın.
Amaç Adı | Dialogflow Etkinlik Adı | Değer Spesifikasyonu | Açıklama |
---|---|---|---|
actions.intent.CONFIRMATION
|
actions_intent_CONFIRMATION |
"@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec"
|
Kullanıcıdan onay alır (örneğin, evet-hayır sorusuna yanıt). |
actions.intent.DATETIME
|
actions_intent_DATETIME |
"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"
|
Kullanıcıdan tarih ve saat girişi alır. |
actions.intent.DELIVERY_ADDRESS
|
actions_intent_DELIVERY_ADDRESS |
"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"
|
Kullanıcıdan teslimat adresi girişi alır. |
actions.intent.LINK
|
actions_intent_LINK |
"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"
|
Bir Android uygulamasına derin bağlantı akışı ister. |
actions.intent.OPTION
|
actions_intent_OPTION |
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec"
|
Seçilen öğeyi bir listeden veya bant kullanıcı arayüzünden elde eder. |
actions.intent.PERMISSION
|
actions_intent_PERMISSION |
"@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec"
|
Tam ad, yaklaşık konum veya tam konum dahil olmak üzere kullanıcının bilgilerini elde eder. |
actions.intent.SIGN_IN
|
actions_intent_SIGN_IN |
"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"
|
Bir kullanıcının hesabını bağlamak için hesap bağlama akışı ister. |
Basit yanıt örneği
Aşağıdaki snippet'te Dialogflow webhook biçiminde basit bir yanıt örneği gösterilmektedir.
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a simple response"
}
}
]
}
}
}
}
Yardımcı örneği
Aşağıdaki snippet'te Dialogflow webhook biçiminde yardımcı intent kullanmaya dair bir örnek gösterilmektedir. Bu örnekte, webhook'unuz actions.intent.OPTIONS
yardımcı niyetini kullanarak Asistan'a iki seçenek arasından bir kullanıcı seçimi alma talimatı verir.
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Choose a item"
}
}
]
},
"systemIntent": {
"intent": "actions.intent.OPTION",
"data": {
"@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
"listSelect": {
"title": "Hello",
"items": [
{
"optionInfo": {
"key": "first title key"
},
"description": "first description",
"image": {
"url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
"accessibilityText": "first alt"
},
"title": "first title"
},
{
"optionInfo": {
"key": "second"
},
"description": "second description",
"image": {
"url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
"accessibilityText": "second alt"
},
"title": "second title"
}
]
}
}
}
}
}
}
Önceki örnekte verilen mesajı aldığında Asistan geçici olarak sohbeti devralır ve kullanıcıdan sunulan seçeneklere göre bir seçim yapmasını ister. Asistan, gerekli tüm kullanıcı girişlerini topladıktan sonra bu yardımcı sonucu Dialogflow webhook isteğindeki karşılamanıza gönderir.
Aşağıdaki snippet'te kullanıcı seçimiyle birlikte yardımcı sonucun bir örneği gösterilmektedir.
{
"responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
"queryResult": {
"queryText": "actions_intent_OPTION",
"action": "",
"parameters": {},
"allRequiredParamsPresent": true,
"fulfillmentText": "",
"fulfillmentMessages": [],
"outputContexts": [
{
"name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
"parameters": {
"OPTION": "key of selected item"
}
}
],
"intent": {
"name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
"displayName": "Dialogflow intent name of matched intent"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en-us"
},
"originalDetectIntentRequest": {
"source": "google",
"version": "2",
"payload": {
"isInSandbox": true,
"surface": {
"capabilities": []
},
"inputs": [
{
"rawInputs": [
{
"query": "Title of selected item",
"inputType": "TOUCH"
}
],
"arguments": [
{
"textValue": "Key of selected item",
"name": "OPTION"
}
],
"intent": "actions.intent.OPTION"
}
],
"user": {},
"conversation": {},
"availableSurfaces": []
}
},
"session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}
Görüşmeyi sonlandırma örneği
Aşağıdaki snippet'te, Dialogflow webhook biçiminde bir görüşme oturumunu sonlandırmaya yönelik basit bir yanıt örneği gösterilmektedir. Yanıt mesajındaki expectUserResponse
false
değeri, Asistan'a başka kullanıcı girişi beklenmediğini ve
mevcut görüşmeyi sonlandırması gerektiğini söyler.
{
"payload": {
"google": {
"expectUserResponse": false,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Goodbye!"
}
}
]
}
}
}
}
Kullanıcılar Asistan'la görüşmeyi sonlandırmak için standart bir ifade çağırdığında varsayılan davranışı nasıl geçersiz kılacağınızı öğrenmek için görüşme çıkışları kılavuzuna bakın.