ส่วนนี้จะอธิบายรูปแบบของเพย์โหลด JSON เมื่อ Actions on Google เรียกใช้ Fulfillment ของคุณผ่าน Actions SDK
เมื่อการสนทนาเริ่มขึ้น ระบบจะระบุการสนทนานั้นด้วย conversationId ที่ไม่ซ้ำกัน สำหรับการค้นหา Assistant ที่ตามมาจากผู้ใช้แต่ละครั้ง Fulfillment ของคุณจะได้รับ Intent ซึ่งเว็บฮุคต้องประมวลผลและตอบสนอง conversationIdนี้จะคงอยู่ในคู่คำขอและการตอบกลับทั้งหมดจนกว่าการสนทนาจะสิ้นสุดลง
เนื้อหาของคำขอ
เมื่อผู้ใช้ทำการค้นหาครั้งแรกหรือป้อนข้อมูลภายหลัง Assistant จะส่งคำขอไปยัง Fulfillment ของคุณ คำขอเว็บฮุคการสนทนาจาก Assistant ประกอบด้วยข้อมูล เช่น ความตั้งใจที่มีการทริกเกอร์ ข้อความดิบจากผู้ใช้ และความสามารถในแพลตฟอร์มของอุปกรณ์ของผู้ใช้
ช่องสำคัญของคำขอในรูปแบบเว็บฮุคการสนทนาสรุปได้ดังนี้
| ฟิลด์ | คำอธิบาย |
|---|---|
isInSandbox |
ตัวแปรบูลีนนี้มีจุดประสงค์หลักสำหรับฟีเจอร์
ธุรกรรมเพื่อระบุว่าเว็บฮุคควรจัดการคำขอนี้ในโหมดแซนด์บ็อกซ์หรือไม่ ในโหมดแซนด์บ็อกซ์ เว็บฮุคไม่ควรเรียกเก็บเงินหรือดำเนินการตามใบสั่งซื้อของผู้ใช้
ระบบจะตั้งค่าเป็น "true" โดยค่าเริ่มต้น |
surface |
ข้อมูลเกี่ยวกับ Assistant ที่แสดงที่ผู้ใช้โต้ตอบและความสามารถของ Assistant |
Inputs |
ข้อมูลเกี่ยวกับคำขอเรียกใช้ สำหรับการทริกเกอร์ การทริกเกอร์นี้จะรวม Intent ที่แมปกับการดำเนินการ สำหรับคำขอในลำดับต่อมาในการสนทนา ออบเจ็กต์นี้อาจมีอาร์กิวเมนต์ที่สอดคล้องกับอินพุตที่ Fulfillment ของคุณระบุไว้ด้วย |
User |
ข้อมูลเกี่ยวกับผู้ใช้ที่ส่งคำขอ ข้อมูลนี้จะรวมถึงสิทธิ์ที่ผู้ใช้ให้ไว้และภาษาของผู้ใช้ |
Conversation |
ข้อมูลเกี่ยวกับบริบทการสนทนา ซึ่งรวมถึงรหัสการสนทนา ประเภท (เช่น คำขอนี้เริ่มต้นการสนทนาใหม่หรือไม่) และโทเค็นการสนทนาเพื่อจัดเก็บข้อมูลถาวรตลอดอายุการสนทนา |
availableSurfaces |
ข้อมูลนี้จะใช้สำหรับ การสนทนาแบบหลายแพลตฟอร์ม |
ตัวอย่างคำขอการเรียกใช้อย่างง่าย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคําขอคําขอในรูปแบบเว็บฮุคการสนทนา
{
"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"
}
]
}
]
}
ตัวอย่างคำขอการสนทนาอย่างง่าย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำขอแบบบทสนทนาในรูปแบบเว็บฮุคสำหรับการสนทนา ซึ่งอินพุตของผู้ใช้เป็นสตริงข้อความ (เช่น "เลขนำโชคของฉันคือ 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"
}
]
}
]
}
เนื้อหาการตอบกลับ
Content-Type ในส่วนหัวของโพสต์ HTTP จากปลายทาง Fulfillment ไปยัง Assistant ต้องเป็น application/json
การตอบสนองในรูปแบบเว็บฮุคสำหรับการสนทนาจะมีข้อมูล เช่น UI จริงที่จะแสดงให้ผู้ใช้เห็น (รวมถึงคอมโพเนนต์เสียงและภาพ) และความตั้งใจที่จะทริกเกอร์ในคำขอที่ตามมา (เรียกว่า ความตั้งใจที่คาดไว้) Intent ที่คาดไว้อาจเป็น Intent ใดก็ได้ที่ Assistant เข้าใจ ตามที่อธิบายไว้ในการอ้างอิง Intent API
หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดรูปแบบอินเทอร์เฟซผู้ใช้สำหรับคำตอบของคุณเมื่อคำตอบแสดงใน Assistant โปรดดูเอกสารการตอบกลับ
ตัวอย่างคำตอบอย่างง่าย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำตอบง่ายๆ ในรูปแบบเว็บฮุคของการสนทนา
{
"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?"
}
}
]
}
}
}
]
}
ตัวอย่างตัวช่วย
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างการใช้ Intent ของตัวช่วยในรูปแบบเว็บฮุคของการสนทนา ในตัวอย่างนี้ เว็บฮุคใช้ Intent ของผู้ช่วยเหลือ actions.intent.OPTIONS เพื่อสั่งให้ Assistant รับการเลือกจากผู้ใช้ระหว่างตัวเลือกหลายรายการ
หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ Intent ผู้ช่วยเหลือ โปรดดูคู่มือผู้ช่วยเหลือ
{
"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"
}
]
}
}
}
]
}
ตัวอย่างสิ้นสุดการสนทนา
ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำตอบง่ายๆ เพื่อสิ้นสุดเซสชันการสนทนาในรูปแบบการตอบสนองเว็บฮุคการสนทนา
ค่า expectedUserResponse
false ในข้อความตอบกลับจะส่งสัญญาณบอก Assistant ว่าไม่ต้องการอินพุตเพิ่มเติมจากผู้ใช้และควรสิ้นสุดการสนทนาปัจจุบัน ค่า finalResponse จะระบุสิ่งที่ Assistant ควรแสดงหรือแสดงต่อผู้ใช้ก่อนที่การสนทนาจะสิ้นสุดลง
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
ดูวิธีลบล้างการทำงานเริ่มต้นเมื่อผู้ใช้เรียกใช้วลีมาตรฐานเพื่อจบการสนทนากับ Assistant ได้ที่การออกจากการสนทนา