ส่วนนี้จะอธิบายรูปแบบของเพย์โหลด JSON เมื่อ Actions on Google เรียกใช้ การดำเนินการผ่าน Actions SDK
เมื่อการสนทนาเริ่มขึ้นแล้ว ระบบจะระบุการสนทนานั้นด้วย conversationId ที่ไม่ซ้ำกัน สำหรับผู้ใช้แต่ละคนที่ตามมา
Assistant จะถือว่าการดำเนินการตามคำสั่งซื้อได้รับความตั้งใจที่
เว็บฮุคจะต้องประมวลผลและตอบกลับ จะมีconversationIdข้อมูลนี้อยู่ในทุกคำขอและ
คู่คำตอบจนกว่าการสนทนาจะสิ้นสุด
เนื้อหาของคำขอ
เมื่อผู้ใช้ทำการค้นหาเบื้องต้นหรือป้อนข้อมูลในภายหลัง Assistant จะส่งคำขอ ได้ตามคำสั่งซื้อ คำขอเว็บฮุคของการสนทนา จาก Assistant ประกอบด้วยข้อมูล เช่น ความตั้งใจที่ถูกเรียกให้แสดง ข้อความดิบของผู้ใช้ และความสามารถในการแสดงผลของอุปกรณ์ของผู้ใช้
ช่องคีย์สําหรับคําขอในรูปแบบเว็บฮุคของการสนทนาจะสรุปได้ดังนี้
| ช่อง | คำอธิบาย |
|---|---|
isInSandbox |
ตัวแปรบูลีนนี้ใช้สำหรับ เป็นหลัก
ธุรกรรม เพื่อระบุว่าเว็บฮุคควรจัดการคำขอนี้ในแซนด์บ็อกซ์หรือไม่
ในโหมดแซนด์บ็อกซ์ เว็บฮุคของคุณไม่ควรเรียกเก็บเงินหรือดำเนินการตามใบสั่งซื้อจากผู้ใช้
ระบบจะตั้งค่าเป็น "true" โดยค่าเริ่มต้น |
surface |
ข้อมูลเกี่ยวกับ Assistant จะแสดงการโต้ตอบกับผู้ใช้และความสามารถต่างๆ ของผู้ใช้ |
Inputs |
ข้อมูลเกี่ยวกับคำขอเรียกใช้ สำหรับการเรียกใช้ทริกเกอร์ เงื่อนไขนี้รวมถึง intent ที่แมปกับการดำเนินการ สำหรับตอนถัดไป ในการสนทนา ออบเจ็กต์นี้อาจมีอาร์กิวเมนต์ที่สอดคล้องกับ ข้อมูลที่คาดว่าจะได้รับซึ่งระบุโดยการดำเนินการของคุณ |
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 จากปลายทางของการดำเนินการตามคำสั่งซื้อ
Assistant ต้องเป็น application/json
การตอบกลับใน รูปแบบเว็บฮุคของการสนทนาจะประกอบด้วยข้อมูล เช่น UI จริงเพื่อแสดง ผู้ใช้ (รวมถึงองค์ประกอบเสียงและภาพ) และความตั้งใจที่สามารถ ทริกเกอร์ในคำขอที่ตามมา (เรียกว่า Intent ที่คาดการณ์) ผลลัพธ์ที่คาดไว้ Intent อาจเป็น Intent ใดก็ได้ที่ Assistant เข้าใจตามที่อธิบายไว้ ในข้อมูลอ้างอิง API ของ Intent
หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดรูปแบบอินเทอร์เฟซผู้ใช้สําหรับคําตอบ ที่แสดงใน 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 ที่เป็นตัวช่วยในการสนทนา
รูปแบบเว็บฮุค ในตัวอย่างนี้ เว็บฮุคกำลังใช้เมธอด
ความตั้งใจของตัวช่วย 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 โปรดดู การออกจากการสนทนา