ส่วนนี้จะอธิบายรูปแบบของเพย์โหลด 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 ได้ที่การออกจากการสนทนา