ไลบรารีไคลเอ็นต์ Actions on Google Node.js เป็นวิธีที่แนะนำสำหรับการเข้าถึงและโต้ตอบกับแพลตฟอร์ม Actions on Google หากคุณกำลังสร้างเว็บฮุค Fulfillment ใน JavaScript
เกริ่นนำ
ไลบรารีของไคลเอ็นต์ Node.js คือไลบรารี Fulfillment สำหรับ Actions on Google ที่มีฟีเจอร์ต่อไปนี้
- รองรับฟีเจอร์ Actions on Google ทั้งหมด รวมถึงการตอบกลับแบบข้อความและมัลติมีเดีย การลงชื่อเข้าใช้บัญชี พื้นที่เก็บข้อมูล ธุรกรรม และอื่นๆ
- มีชั้น Abstraction ที่เป็นสำนวนโวหารใน JavaScript ซึ่งรวม API เว็บฮุค HTTP/JSON สำหรับการสนทนา
- จัดการรายละเอียดระดับต่ำของการสื่อสารระหว่างการดำเนินการของคุณและแพลตฟอร์ม Actions on Google
- ติดตั้งได้โดยใช้เครื่องมือการจัดการแพ็กเกจที่คุ้นเคย เช่น
npm
หรือyarn
- ช่วยให้คุณทำให้เว็บฮุคสำหรับ Fulfillment ใช้งานได้ในแพลตฟอร์มการประมวลผลแบบ Serverless ได้อย่างง่ายดาย เช่น Cloud Functions for Firebase หรือ AWS Lambda นอกจากนี้ คุณยังโฮสต์เว็บฮุค Fulfillment ของผู้ให้บริการระบบคลาวด์หรือในสภาพแวดล้อมที่โฮสต์เองและจัดการเองได้ด้วย
- เข้ากันได้กับ Node.js v6.0.0 ขึ้นไป
คุณสามารถใช้ไลบรารีของไคลเอ็นต์ร่วมกับการผสานรวม Dialogflow สำหรับ Actions on Google หรือกับ Actions SDK ได้
หากต้องการดูตัวอย่างโค้ดแบบเต็มสำหรับการใช้ไลบรารีของไคลเอ็นต์ โปรดไปที่หน้าตัวอย่าง
ดูเอกสารอ้างอิง API
เอกสารอ้างอิง API จะโฮสต์ในหน้าไลบรารีของไคลเอ็นต์ Actions on Google Node.js ใน GitHub
นอกจากนี้ คุณยังสร้างสำเนาการอ้างอิงในเครื่องได้โดยเรียกใช้คำสั่งต่อไปนี้จากไดเรกทอรีที่คุณดาวน์โหลดโค้ดไลบรารีไคลเอ็นต์
yarn docs
เอกสารที่สร้างขึ้นจะอยู่ในโฟลเดอร์ docs
ของไดเรกทอรีที่คุณดาวน์โหลดโค้ดไลบรารีของไคลเอ็นต์
ทำความเข้าใจวิธีการทำงาน
ก่อนใช้ไลบรารีไคลเอ็นต์ คุณควรทำความเข้าใจว่าเว็บฮุคสำหรับดำเนินการตามคำสั่งซื้อใช้ไลบรารีไคลเอ็นต์ในการประมวลผลคำขอของผู้ใช้ที่ Actions on Google ส่งไปยัง Fulfillment ของคุณได้อย่างไร
เมื่อสร้างเว็บฮุค Fulfillment ใน JavaScript แล้ว คุณจะทำให้โค้ดใช้งานได้และโฮสต์โค้ดในสภาพแวดล้อมการประมวลผลแบบ Serverless ได้ เช่น Cloud Functions for Firebase ของ Google หรือ AWS Lambda นอกจากนี้ คุณยังโฮสต์โค้ดเองได้โดยไม่ต้องดำเนินการเพิ่มเติมโดยใช้เว็บเฟรมเวิร์ก Express
ภายในสภาพแวดล้อมรันไทม์ เว็บฮุค Fulfillment จะเรียกใช้ฟังก์ชันในไลบรารีไคลเอ็นต์เพื่อประมวลผลคำขอของผู้ใช้และส่งการตอบกลับกลับไปยัง Actions on Google เพื่อแสดงผลเป็นเอาต์พุตผู้ใช้ได้
งานสำคัญที่เว็บฮุค Fulfillment จัดการด้วยความช่วยเหลือของไลบรารีไคลเอ็นต์สรุปไว้คร่าวๆ ได้ด้านล่างนี้
- การรับคำขอของผู้ใช้: เมื่อผู้ใช้ทำการค้นหาไปยัง Google Assistant แพลตฟอร์ม Actions on Google จะส่งคำขอ HTTP ไปยังเว็บฮุค Fulfillment คำขอจะมีเพย์โหลด JSON ที่มี Intent และข้อมูลอื่นๆ เช่น ข้อความดิบของอินพุตจากผู้ใช้ และความสามารถในแพลตฟอร์มของอุปกรณ์ของผู้ใช้ ดูตัวอย่างเพิ่มเติมของเนื้อหาเพย์โหลด JSON ได้ที่คู่มือรูปแบบเว็บฮุคของ Dialogflow และรูปแบบเว็บฮุคสำหรับการสนทนา
- การตรวจหารูปแบบการโทรของเฟรมเวิร์ก: สำหรับเฟรมเวิร์กที่รองรับ ไลบรารีของไคลเอ็นต์จะตรวจหารูปแบบการเรียกของเฟรมเวิร์กโดยอัตโนมัติ (เช่น หากคำขอมาจากเว็บเฟรมเวิร์กของ Express หรือจาก AWS Lambda) และรู้วิธีจัดการกับการสื่อสารกับแพลตฟอร์ม Actions on Google ได้อย่างราบรื่น
- การประมวลผลตัวแฮนเดิลบริการ: ไลบรารีของไคลเอ็นต์จะแสดงการสนทนาของ API เว็บฮุค HTTP/JSON สำหรับ Dialogflow และ Actions SDK ในฐานะฟังก์ชันบริการ เว็บฮุค Fulfillment จะใช้บริการที่เหมาะสมในการสร้างอินสแตนซ์
app
ส่วนกลาง อินสแตนซ์app
ทำหน้าที่เป็นเครื่องจัดการคำขอ HTTP และเข้าใจโปรโตคอลที่เฉพาะเจาะจงของบริการ - การประมวลผลการสนทนา: ไลบรารีของไคลเอ็นต์จะแสดงข้อมูลต่อการสนทนาเป็นออบเจ็กต์
Conversation
ที่แนบกับอินสแตนซ์app
เว็บฮุค Fulfillment ของคุณอาจใช้ออบเจ็กต์Conversation
เพื่อเรียกดูข้อมูลหรือข้อมูลสถานะที่จัดเก็บข้ามการสนทนา ส่งคำตอบไปยังผู้ใช้ หรือปิดไมโครโฟน - การประมวลผลมิดเดิลแวร์: ไลบรารีของไคลเอ็นต์ให้คุณสร้างมิดเดิลแวร์บริการการสนทนาของคุณเอง ซึ่งประกอบด้วยฟังก์ชันอย่างน้อย 1 รายการที่คุณกำหนดว่าไลบรารีของไคลเอ็นต์จะทำงานโดยอัตโนมัติก่อนเรียกใช้เครื่องจัดการ Intent เว็บฮุค Fulfillment จะใช้มิดเดิลแวร์เพื่อเพิ่มพร็อพเพอร์ตี้หรือคลาสตัวช่วยไปยังออบเจ็กต์
Conversation
ได้ - การประมวลผลตัวแฮนเดิล Intent: ไลบรารีของไคลเอ็นต์ให้คุณกำหนดแฮนเดิลสำหรับ Intent ที่เว็บฮุคสำหรับดำเนินการตามคำสั่งซื้อเข้าใจ สำหรับ Dialogflow ไลบรารีไคลเอ็นต์จะกำหนดเส้นทางคำขอไปยังเครื่องจัดการ Intent ที่ถูกต้องโดยการแมปกับสตริงที่ตรงกับชื่อ Intent ที่ระบุไว้ในคอนโซล Dialogflow สำหรับ Actions SDK ระบบจะกำหนดเส้นทางโดยอิงตามพร็อพเพอร์ตี้
intent
ที่ส่งจาก Actions on Google - การส่งคำตอบไปยังผู้ใช้: หากต้องการสร้างคำตอบ เว็บฮุค Fulfillment จะเรียกใช้ฟังก์ชัน
Conversation#ask()
คุณสามารถเรียกใช้ฟังก์ชันask()
ได้หลายครั้งเพื่อสร้างการตอบสนองแบบค่อยเป็นค่อยไป ไลบรารีของไคลเอ็นต์จะทำให้การตอบกลับคำขอ HTTP เป็นอนุกรมที่มีเพย์โหลด JSON และส่งไปยัง Actions on Google ฟังก์ชันclose()
มีลักษณะการทำงานที่คล้ายกับask()
แต่ปิดการสนทนา
ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์ภายใน
อย่าลืมติดตั้งไลบรารีไคลเอ็นต์ก่อนใช้เว็บฮุค Fulfillment
ติดตั้งไลบรารีของไคลเอ็นต์
วิธีที่ง่ายที่สุดในการติดตั้งไลบรารีของไคลเอ็นต์ในสภาพแวดล้อมการพัฒนาในเครื่องคือการใช้ตัวจัดการแพ็กเกจ เช่น npm
หรือ yarn
หากต้องการติดตั้ง ให้เรียกใช้คำสั่งต่อไปนี้จากเทอร์มินัล
- หากใช้ npm:
npm install actions-on-google
- หากใช้ไหมพรม:
yarn add actions-on-google
ตั้งค่าโฟลเดอร์โปรเจ็กต์
คุณอาจต้องสร้างโครงสร้างโฟลเดอร์โปรเจ็กต์เฉพาะเพื่อบันทึกไฟล์ ทั้งนี้ขึ้นอยู่กับว่าคุณวางแผนทำให้เว็บฮุค Fulfillment ใช้งานได้ (Cloud Functions ของ Google สำหรับ Firebase, AWS Lambda หรือ Express ที่โฮสต์ด้วยตนเอง) อยู่ที่ใด
เช่น หากใช้ฟังก์ชัน Cloud สำหรับ Firebase คุณสามารถตั้งค่าโฟลเดอร์โปรเจ็กต์ที่จำเป็นโดยทำตามขั้นตอนที่อธิบายไว้ในตั้งค่า Node.js และ Firebase CLI และเริ่มต้น Firebase สำหรับ Cloud Functions สำหรับ Cloud Functions for Firebase โดยทั่วไปแล้วคุณจะเขียนเว็บฮุคสำหรับการดำเนินการในไฟล์ /functions/index.js
สร้างอินสแตนซ์แอป
Actions on Google ใช้รูปแบบการส่งข้อความที่เฉพาะเจาะจงในการแลกเปลี่ยนคำขอและการตอบกลับกับเว็บฮุค Fulfillment โดยขึ้นอยู่กับว่าคุณกำลังสร้างการดำเนินการแบบบทสนทนาโดยใช้ Dialogflow หรือ Actions SDK หรือสร้างการดำเนินการสำหรับสมาร์ทโฮม
ในการแสดงถึงโปรโตคอลคำขอและการตอบกลับต่างๆ เหล่านี้ ไลบรารีของไคลเอ็นต์จะมีฟังก์ชันของบริการ 3 อย่างดังนี้
ทั้งบริการแบบสนทนา (Dialogflow และ Actions SDK) ใช้โปรโตคอลเว็บฮุคการสนทนา แต่แต่ละบริการจะตัดข้อความที่แตกต่างกัน
คุณใช้บริการเพื่อสร้างอินสแตนซ์ app
อินสแตนซ์ app
สรุปตรรกะสถานะส่วนกลางและ Fulfillment สำหรับเว็บฮุคของคุณและจัดการการสื่อสารระหว่าง Actions on Google กับ Fulfillment โดยใช้โปรโตคอลเฉพาะบริการ
คุณกำหนดค่าพร็อพเพอร์ตี้ของอินสแตนซ์ app
และเรียกใช้เมธอดของอินสแตนซ์เพื่อกำหนดลักษณะการทำงานของเว็บฮุค Fulfillment ได้ นอกจากนี้ คุณยังเสียบอินสแตนซ์ app
เข้ากับสภาพแวดล้อมการประมวลผลแบบ Serverless ได้อย่างง่ายดาย เช่น Cloud Functions for Firebase ซึ่งยอมรับฟังก์ชัน JavaScript เป็นตัวแฮนเดิลสำหรับคำขอ HTTP
หากต้องการสร้างอินสแตนซ์ app
ในเว็บฮุค Fulfillment ให้ทำตามขั้นตอนต่อไปนี้
เรียกใช้ฟังก์ชัน
require()
เพื่อนำเข้าโมดูล "actions-on-google" และโหลดบริการที่คุณต้องการ เช่น ข้อมูลโค้ดต่อไปนี้แสดงวิธีโหลดบริการdialogflow
และองค์ประกอบบางอย่างที่ใช้สร้างคำตอบ รวมทั้งกำหนดให้กับค่าคงที่ชื่อdialogflow
// Import the service function and various response classes const { dialogflow, actionssdk, Image, Table, Carousel, } = require('actions-on-google');
ในที่นี้
actions-on-google
หมายถึงการอ้างอิงที่ระบุไว้ในไฟล์package.json
ในโฟลเดอร์โปรเจ็กต์ (คุณดูตัวอย่างจากไฟล์package.json
ตัวอย่างนี้ได้)เมื่อได้รับอินสแตนซ์
app
คุณจะเลือกระบุคลาสที่แสดงการตอบกลับที่สมบูรณ์, Intent ของผู้ช่วยเหลือ และฟังก์ชันการทำงานอื่นๆ ของ Actions on Google ที่คุณต้องการใช้ได้ หากต้องการดูรายการคลาสที่ถูกต้องทั้งหมดที่คุณดาวน์โหลดได้ โปรดดูเอกสารอ้างอิงสำหรับโมดูลการตอบกลับการสนทนาและความตั้งใจของผู้ช่วยเหลือสร้างอินสแตนซ์
app
โดยเรียกใช้บริการที่คุณโหลด ตัวอย่างเช่นconst app = dialogflow();
หากต้องการกำหนดค่าอินสแตนซ์
app
ขณะเริ่มต้น คุณจะระบุออบเจ็กต์options
เป็นอาร์กิวเมนต์แรกเมื่อเรียกใช้บริการได้ (ดูรายละเอียดเพิ่มเติมได้ที่DialogflowOptions
) ตัวอย่างเช่น ข้อมูลโค้ดต่อไปนี้แสดงวิธีบันทึกเพย์โหลด JSON แบบข้อมูลดิบจากคำขอของผู้ใช้หรือการตอบกลับโดยการตั้งค่าแฟล็ก{ debug: true }
const app = dialogflow({ debug: true });
ตั้งค่าเครื่องจัดการสำหรับเหตุการณ์
หากต้องการประมวลผลเหตุการณ์ที่เกี่ยวข้องกับ Actions on Google ซึ่งสร้างขึ้นโดยไลบรารีของไคลเอ็นต์ในระหว่างวงจรการโต้ตอบของผู้ใช้กับการดำเนินการของคุณ คุณจะใช้ไลบรารีของไคลเอ็นต์เพื่อสร้างตัวแฮนเดิลเพื่อประมวลผลคำขอของผู้ใช้และส่งการตอบกลับกลับมา
คุณสามารถสร้างฟังก์ชันที่ทำหน้าที่เป็นตัวแฮนเดิลสำหรับเหตุการณ์ประเภทหลักต่อไปนี้ที่ไลบรารีของไคลเอ็นต์รู้จัก
- เหตุการณ์ Intent: Intent คือตัวระบุที่ไม่ซ้ำกันซึ่ง Actions on Google ส่งไปยัง Fulfillment ของคุณเมื่อใดก็ตามที่ผู้ใช้ขอฟังก์ชันการทำงานที่เจาะจง หากคุณใช้ Dialogflow อยู่ ส่วนนี้จะสอดคล้องกับ Dialogflow ที่ตรงกับคำค้นหาของผู้ใช้กับความตั้งใจใน Agent ของ Dialogflow
- เหตุการณ์ข้อผิดพลาด: เมื่อ JavaScript หรือไลบรารีของไคลเอ็นต์เกิดข้อผิดพลาด คุณสามารถใช้ฟังก์ชัน
catch
ของอินสแตนซ์app
เพื่อประมวลผลข้อยกเว้นข้อผิดพลาดอย่างเหมาะสม คุณควรใช้ฟังก์ชันcatch
เดียวเพื่อจัดการข้อผิดพลาดทั้งหมดที่ Fulfillment ของคุณให้ความสำคัญ - เหตุการณ์สำรอง: เหตุการณ์สำรองจะเกิดขึ้นเมื่อผู้ใช้ส่งคำค้นหาที่ Actions on Google ไม่รู้จัก คุณใช้ฟังก์ชัน
fallback
ของอินสแตนซ์app
เพื่อลงทะเบียนเครื่องจัดการสำรองทั่วไปได้ ซึ่งระบบจะทริกเกอร์หากไม่มีการจับคู่เครื่องจัดการ Intent สำหรับคำขอการดำเนินการที่เข้ามาใหม่ คุณควรใช้ฟังก์ชันfallback
เดียวเพื่อจัดการเหตุการณ์สำรองทั้งหมด หากคุณใช้ Dialogflow อยู่ Dialogflow จะทริกเกอร์ Intent สำรองที่เฉพาะเจาะจงได้เมื่อไม่มีการจับคู่ Intent อื่นที่ตรงกัน คุณควรสร้างเครื่องจัดการ Intent ที่สอดคล้องกันสำหรับ Intent สำรองนั้น
เมื่อใดก็ตามที่ผู้ใช้ส่งคำขอไปยังการดำเนินการของคุณ อินสแตนซ์ app
จะสร้างออบเจ็กต์ Conversation
ที่แสดงถึงเซสชันการสนทนานั้น ออบเจ็กต์นี้เข้าถึงผ่านทางชื่อตัวแปร conv
ที่ส่งผ่านในฟังก์ชันเครื่องจัดการ Intent เป็นอาร์กิวเมนต์ฟังก์ชันแรก โดยปกติแล้ว คุณจะใช้ออบเจ็กต์ conv
ในเครื่องจัดการเพื่อส่งคำตอบไปยังผู้ใช้
นอกจากนี้ คำค้นหาของผู้ใช้อาจมีพารามิเตอร์ที่การดำเนินการของคุณดึงข้อมูลและใช้เพื่อปรับแต่งคำตอบได้
- หากใช้ Actions SDK ให้กําหนดพารามิเตอร์ในแพ็กเกจการดําเนินการ ดูตัวอย่างวิธีแยกพารามิเตอร์จาก Intent ได้ที่ตัวอย่างโค้ด Eliza
- หากใช้ Dialogflow คุณจะเข้าถึงค่าพารามิเตอร์ได้ผ่านทางตัวแปร
params
หากต้องการดูตัวอย่างการจัดการ Intent ด้วยพารามิเตอร์ใน Dialogflow โปรดดูพารามิเตอร์และบริบทการเข้าถึง
ตั้งค่าเครื่องจัดการสำหรับ Intent
หากต้องการตั้งค่าเครื่องจัดการสำหรับ Intent ให้เรียกใช้ฟังก์ชัน intent()
ของอินสแตนซ์ app
เช่น หากคุณใช้ Dialogflow นี่คือฟังก์ชัน DialogflowApp#intent()
ระบุชื่อ Intent ในอาร์กิวเมนต์และระบุฟังก์ชันเครื่องจัดการ
หากคุณใช้ Dialogflow คุณไม่จำเป็นต้องตั้งค่าเครื่องจัดการสำหรับ Intent ทุกๆ ตัวใน Agent คุณสามารถใช้ประโยชน์จากแฮนเดิลการตอบสนองในตัวของ Dialogflow แทน เพื่อจัดการ Intent โดยอัตโนมัติได้โดยไม่ต้องใช้ฟังก์ชันตัวแฮนเดิลของคุณเอง ตัวอย่างเช่น เจตนาต้อนรับเริ่มต้นสามารถมอบอำนาจให้กับ Dialogflow ได้ในลักษณะนี้
ตัวอย่างต่อไปนี้แสดงเครื่องจัดการ Intent สำหรับ Intent "greeting" และ "bye" ฟังก์ชันเครื่องจัดการแบบไม่ระบุตัวตนจะใช้อาร์กิวเมนต์ conv
และส่งการตอบกลับสตริงง่ายๆ กลับไปให้ผู้ใช้ผ่านฟังก์ชัน conv.ask()
ดังนี้
app.intent('Default Welcome Intent', (conv) => { conv.ask('How are you?'); }); app.intent('bye', (conv) => { conv.close('See you later!'); });
โปรดทราบว่าฟังก์ชัน close()
คล้ายกับ ask()
เว้นแต่ว่าจะเป็นการปิดไมโครโฟนและการสนทนาจะสิ้นสุดลง
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีสร้างเครื่องจัดการสำหรับ Intent ได้ที่สร้างเครื่องจัดการ Intent
ตั้งค่าเครื่องจัดการสำหรับเหตุการณ์ข้อผิดพลาด
หากต้องการตั้งค่าเครื่องจัดการสำหรับข้อผิดพลาด ให้เรียกใช้ฟังก์ชัน catch()
ของอินสแตนซ์ app
(เช่น หากคุณใช้ Dialogflow ก็คือฟังก์ชัน DialogflowApp#catch()
)
ตัวอย่างต่อไปนี้แสดงเครื่องจัดการข้อผิดพลาดการตรวจจับแบบง่ายที่ส่งข้อผิดพลาดไปยังเอาต์พุตของคอนโซลและส่งการตอบกลับสตริงง่ายๆ กลับไปเพื่อแจ้งให้ผู้ใช้ผ่านฟังก์ชัน conv.ask()
app.catch((conv, error) => { console.error(error); conv.ask('I encountered a glitch. Can you say that again?'); });
ตั้งค่าเครื่องจัดการสำหรับเหตุการณ์สำรอง
หากต้องการตั้งค่าเครื่องจัดการสำรองทั่วไปเมื่อไม่มี Intent ที่ตรงกับคำขอขาเข้าสำหรับการดำเนินการตามคำสั่งซื้อ ให้เรียกใช้ฟังก์ชัน fallback()
ของอินสแตนซ์ app
(เช่น หากคุณใช้ Dialogflow ก็คือฟังก์ชัน DialogflowApp#fallback()
)
ตัวอย่างต่อไปนี้แสดงตัวแฮนเดิลสำรองแบบง่ายที่ส่งการตอบสนองด้วยสตริงแบบง่ายกลับมาเพื่อแจ้งให้ผู้ใช้ผ่านฟังก์ชัน conv.ask()
app.fallback((conv) => { conv.ask(`I couldn't understand. Can you say that again?`); });
สร้างเครื่องจัดการ Intent
ส่วนนี้จะอธิบาย Use Case ที่พบบ่อยเมื่อคุณใช้ตัวแฮนเดิล Intent กับไลบรารีของไคลเอ็นต์ หากต้องการดูว่าไลบรารีของไคลเอ็นต์ตรงกับ Intent อย่างไร โปรดดูที่ส่วน "การประมวลผลของตัวแฮนเดิล Intent" ในทำความเข้าใจวิธีการทำงาน
พารามิเตอร์และบริบทการเข้าถึง
หากใช้ Dialogflow คุณสามารถกำหนดพารามิเตอร์และบริบทใน Agent ของ Dialogflow เพื่อเก็บรักษาข้อมูลสถานะและควบคุมโฟลว์การสนทนาได้
พารามิเตอร์มีประโยชน์ในการบันทึกคำ วลี หรือค่าที่สำคัญในการค้นหาของผู้ใช้ Dialogflow จะดึงข้อมูลพารามิเตอร์ที่เกี่ยวข้องจากการค้นหาของผู้ใช้ขณะรันไทม์ และคุณสามารถประมวลผลค่าพารามิเตอร์เหล่านี้ในเว็บฮุค Fulfillment เพื่อระบุวิธีตอบกลับผู้ใช้ได้
เมื่อใดก็ตามที่ผู้ใช้ส่งคำขอไปยังการดำเนินการของคุณ อินสแตนซ์ DialogflowApp
จะสร้างออบเจ็กต์ parameters
ที่แสดงค่าพารามิเตอร์ที่ Dialogflow ดึงข้อมูลจากคำขอนั้น ออบเจ็กต์นี้เข้าถึงผ่านชื่อตัวแปร params
ข้อมูลโค้ดต่อไปนี้แสดงวิธีเข้าถึงพร็อพเพอร์ตี้ name
จากออบเจ็กต์ params
เมื่อผู้ใช้ส่งคำขอ
app.intent('Default Welcome Intent', (conv, params) => { conv.ask(`How are you, ${params.name}?`); });
นี่คือข้อมูลโค้ดสำรองที่สามารถทำได้เหมือนกัน วงเล็บปีกกา ({}
) จะดำเนินการทำลาย JavaScript เพื่อนำพร็อพเพอร์ตี้ name
จากออบเจ็กต์ parameters
และใช้เป็นตัวแปรภายใน ดังนี้
app.intent('Default Welcome Intent', (conv, {name}) => { conv.ask(`How are you, ${name}?`); });
ในข้อมูลโค้ดต่อไปนี้ ชื่อพารามิเตอร์คือ full-name
แต่ถูกยกเลิกโครงสร้างและกำหนดให้กับตัวแปรภายในชื่อ name
app.intent('Default Welcome Intent', (conv, {'full-name': name}) => { conv.ask(`How are you, ${name}?`); });
บริบทเป็นฟีเจอร์ขั้นสูงของ Dialogflow คุณจะใช้บริบทเพื่อจัดการสถานะการสนทนา โฟลว์ และการขยายหัวข้อได้ ไลบรารีของไคลเอ็นต์ให้สิทธิ์เข้าถึงบริบทผ่านออบเจ็กต์ DialogflowConversation#contexts
ข้อมูลโค้ดต่อไปนี้แสดงวิธีตั้งค่าบริบทแบบเป็นโปรแกรมในเว็บฮุค Fulfillment และวิธีเรียกข้อมูลออบเจ็กต์บริบท
app.intent('intent1', (conv) => { const lifespan = 5; const contextParameters = { color: 'red', }; conv.contexts.set('context1', lifespan, contextParameters); // ... conv.ask('...'); }); app.intent('intent2', (conv) => { const context1 = conv.contexts.get('context1'); const contextParameters = context1.parameters; // ... conv.ask('...'); }); app.intent('intent3', (conv) => { conv.contexts.delete('context1'); // ... conv.ask('...'); });
เข้าถึงผลลัพธ์ของ Intent ของตัวช่วย
เพื่อความสะดวก ไลบรารีของไคลเอ็นต์จะมีคลาส Intent ของตัวช่วย ซึ่งรวบรวมข้อมูลผู้ใช้ประเภททั่วไปที่ Actions ขอบ่อยครั้ง ซึ่งรวมถึงคลาสที่แสดงผลลัพธ์ของความตั้งใจช่วยเหลือของ Actions on Google ที่หลากหลาย คุณจะใช้ Intent ของผู้ช่วยเหลือเมื่อต้องการให้ Google Assistant จัดการส่วนต่างๆ ของการสนทนาซึ่งผู้ใช้ต้องระบุข้อมูลเพื่อสนทนาต่อ
ตัวอย่าง: ผลลัพธ์ของตัวช่วยการยืนยัน
เจตนารมณ์ของตัวช่วยการยืนยันให้คุณขอคำยืนยัน "ใช่/ไม่ใช่" จากผู้ใช้และรับคำตอบได้
ข้อมูลโค้ดต่อไปนี้จะแสดงวิธีที่เว็บฮุคสามารถปรับแต่งการตอบสนองตามผลลัพธ์ที่ส่งคืนโดย Intent ของตัวช่วยการยืนยัน ดูตัวอย่างที่สมบูรณ์มากขึ้นได้ในเอกสารอ้างอิงของชั้นเรียน Confirmation
// Create Dialogflow intent with `actions_intent_CONFIRMATION` event app.intent('get_confirmation', (conv, input, confirmation) => { if (confirmation) { conv.close(`Great! I'm glad you want to do it!`); } else { conv.close(`That's okay. Let's not do it now.`); } });
ตัวอย่าง: ผลการค้นหาที่เป็นภาพสไลด์
ข้อมูลโค้ดต่อไปนี้จะแสดงวิธีที่เว็บฮุค Fulfillment สามารถปรับแต่งการตอบสนองตามอินพุตของผู้ใช้สำหรับภาพสไลด์ คอมโพเนนต์ภาพหมุนช่วยให้การดำเนินการแสดงตัวเลือกให้ผู้ใช้เลือก โปรดดูตัวอย่างที่สมบูรณ์กว่านี้ได้ในเอกสารอ้างอิงชั้นเรียน Carousel
app.intent('carousel', (conv) => { conv.ask('Which of these looks good?'); conv.ask(new Carousel({ items: { car: { title: 'Car', description: 'A four wheel vehicle', synonyms: ['automobile', 'vehicle'], }, plane: { title: 'Plane', description: 'A flying machine', synonyms: ['aeroplane', 'jet'], } } })); }); // Create Dialogflow intent with `actions_intent_OPTION` event app.intent('get_carousel_option', (conv, input, option) => { if (option === 'one') { conv.close(`Number one is a great choice!`); } else { conv.close(`Number ${option} is a great choice!`); } });
กำหนดค่าออบเจ็กต์การตอบกลับการสนทนา
ไลบรารีของไคลเอ็นต์มีคลาสการตอบกลับของการสนทนาที่แสดงการตอบกลับที่หลากหลายหรือองค์ประกอบมัลติมีเดียที่การดำเนินการของคุณส่งได้ โดยทั่วไป คุณจะส่งคำตอบหรือองค์ประกอบเหล่านี้เมื่อผู้ใช้ไม่จำเป็นต้องให้ข้อมูลใดๆ เพื่อสนทนาต่อ
ตัวอย่าง: รูปภาพ
ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่เว็บฮุค Fulfillment สามารถส่ง Image
ในการตอบกลับซึ่งไลบรารีจะแนบไปกับการตอบกลับ BasicCard
โดยอัตโนมัติ
app.intent('Default Welcome Intent', (conv) => { conv.ask('Hi, how is it going?'); conv.ask(`Here's a picture of a cat`); conv.ask(new Image({ url: '/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg', alt: 'A cat', })); });
เรียกใช้ฟังก์ชันแบบไม่พร้อมกัน
ไลบรารีไคลเอ็นต์ Node.js ของ Actions on Google ได้รับการออกแบบมาสำหรับการเขียนโปรแกรมแบบอะซิงโครนัส ตัวแฮนเดิล Intent สามารถแสดงการรับประกันที่ได้รับการแก้ไขเมื่อเว็บฮุค Fulfillment สร้างการตอบสนองเสร็จสิ้น
ข้อมูลโค้ดต่อไปนี้แสดงวิธีเรียกใช้ฟังก์ชันแบบไม่พร้อมกันเพื่อแสดงผลออบเจ็กต์ที่มีสัญญา และตอบกลับด้วยข้อความหากเว็บฮุค Fulfillment ได้รับ Intent "คำทักทาย" ในข้อมูลโค้ดนี้ สัญญาที่สัญญาว่าจะช่วยให้มั่นใจว่าเว็บฮุคสำหรับ Fulfillment จะส่งข้อความตอบกลับการสนทนาเฉพาะหลังจากที่คำสัญญาสำหรับการเรียก API ภายนอกได้รับการแก้ไขแล้วเท่านั้น
ในตัวอย่างนี้ เราใช้ API ปลอมเพื่อรับข้อมูลสภาพอากาศ
/** * Make an external API call to get weather data. * @return {Promise<string>} */ const forecast = () => { // ... }; app.intent('Default Welcome Intent', (conv) => { return forecast().then((weather) => { conv.ask('How are you?'); conv.ask(`Today's weather is ${weather}.`); }); });
ข้อมูลโค้ดที่ปรับปรุงใหม่ต่อไปนี้ให้ผลเหมือนกัน แต่ใช้ฟีเจอร์ async
await
ที่เปิดตัวใน ECMA 2017 (Node.js เวอร์ชัน 8) หากต้องการใช้โค้ดนี้กับ Cloud Functions for Firebase โปรดตรวจสอบว่าคุณกำลังใช้Firebase-tools เวอร์ชันที่ถูกต้องและมีการกำหนดค่าที่ถูกต้อง
app.intent('Default Welcome Intent', async (conv) => { const weather = await forecast(); conv.ask('How are you?'); conv.ask(`Today's weather is ${weather}.`); });
จัดเก็บข้อมูลการสนทนา
ไลบรารีของไคลเอ็นต์ช่วยให้เว็บฮุค Fulfillment สามารถบันทึกข้อมูลในการสนทนาไว้ใช้ในอนาคตได้ ออบเจ็กต์หลักที่คุณใช้เป็นพื้นที่เก็บข้อมูลได้มีดังนี้
DialogflowConversation#data
หรือActionsSdkConversation#data
: บันทึกข้อมูลในรูปแบบ JSON ตลอดระยะเวลาของเซสชันการสนทนาเดียวระหว่างผู้ใช้และการดำเนินการConversation#user.storage
: บันทึกข้อมูลในรูปแบบ JSON ในเซสชันการสนทนาหลายเซสชัน
ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่เว็บฮุค Fulfillment สามารถจัดเก็บข้อมูลในพร็อพเพอร์ตี้ที่กำหนดเองที่คุณกำหนด (someProperty
) และแนบไว้กับออบเจ็กต์ Conversation#user.storage
โปรดดูตัวอย่างที่สมบูรณ์กว่านี้ได้ในเอกสารอ้างอิงของชั้นเรียน Conversation#user.storage
app.intent('Default Welcome Intent', (conv) => { conv.user.storage.someProperty = 'someValue'; conv.ask('...'); });
คุณสามารถใช้ออบเจ็กต์ Conversation#user
เพื่อรับข้อมูลเกี่ยวกับผู้ใช้ รวมถึงตัวระบุสตริงและข้อมูลส่วนบุคคล บางช่อง เช่น conv.user.name.display
และ conv.user.email
ต้องมีการส่งคำขอ conv.ask(new Permission)
สำหรับ NAME และ conv.ask(new SignIn)
สำหรับ Google Sign-In ตามลำดับ
const {Permission} = require('actions-on-google'); app.intent('Default Welcome Intent', (conv) => { if (conv.user.last.seen) { conv.ask('Welcome back! How are you?'); } else { conv.ask('Nice to meet you! How are you doing?'); } }); app.intent('permission', (conv) => { conv.ask(new Permission({ context: 'To greet you personally', permissions: 'NAME', })); }); // Create Dialogflow intent with `actions_intent_PERMISSION` event app.intent('get_permission', (conv, input, granted) => { if (granted) { conv.close(`Hi ${conv.user.name.display}!`); } else { // User did not grant permission conv.close(`Hello!`); } });
การปรับขนาดด้วยมิดเดิลแวร์
คุณสามารถขยายไลบรารีของไคลเอ็นต์ผ่านมิดเดิลแวร์ได้
เลเยอร์มิดเดิลแวร์ประกอบด้วยฟังก์ชันที่คุณกำหนดอย่างน้อย 1 ฟังก์ชัน ซึ่งไลบรารีของไคลเอ็นต์จะเรียกใช้โดยอัตโนมัติก่อนเรียกเครื่องจัดการ Intent การใช้เลเยอร์มิดเดิลแวร์จะช่วยให้คุณแก้ไขอินสแตนซ์ Conversation
และเพิ่มฟังก์ชันการทำงานได้
บริการ Dialogflow และ Actions SDK แสดงฟังก์ชัน app.middleware()
ที่ช่วยให้คุณเพิ่มพร็อพเพอร์ตี้หรือคลาสตัวช่วยลงในอินสแตนซ์ Conversation
ได้
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างวิธีที่คุณอาจใช้มิดเดิลแวร์
class Helper { constructor(conv) { this.conv = conv; } func1() { this.conv.ask(`What's up?`); } } app.middleware((conv) => { conv.helper = new Helper(conv); }); app.intent('Default Welcome Intent', (conv) => { conv.helper.func1(); });
ส่งออกแอป
หากต้องการแสดงเว็บฮุค Fulfillment สำหรับเฟรมเวิร์กเว็บหรือแพลตฟอร์มการประมวลผลแบบ Serverless คุณต้องส่งออกออบเจ็กต์ app
เป็นเว็บฮุคที่เข้าถึงได้แบบสาธารณะ ไลบรารีของไคลเอ็นต์สนับสนุนการติดตั้งใช้งานในสภาพแวดล้อมที่หลากหลายตั้งแต่แกะกล่อง
ข้อมูลโค้ดต่อไปนี้แสดงวิธีส่งออก app
ภายในรันไทม์ต่างๆ
ตัวอย่าง: Cloud Function สำหรับ Firebase
const functions = require('firebase-functions'); // ... app code here exports.fulfillment = functions.https.onRequest(app);
ตัวอย่าง: เครื่องมือแก้ไขในบรรทัดของ Dialogflow
const functions = require('firebase-functions'); // ... app code here // Exported function name must be 'dialogflowFirebaseFulfillment' exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);
ตัวอย่าง: เซิร์ฟเวอร์ Express แบบโฮสต์ด้วยตนเอง (แบบง่าย)
const express = require('express'); const bodyParser = require('body-parser'); // ... app code here express().use(bodyParser.json(), app).listen(3000);
ตัวอย่าง: เซิร์ฟเวอร์ Express แบบโฮสต์ด้วยตนเอง (หลายเส้นทาง)
const express = require('express'); const bodyParser = require('body-parser'); // ... app code here const expressApp = express().use(bodyParser.json()); expressApp.post('/fulfillment', app); expressApp.listen(3000);
ตัวอย่าง: เกตเวย์ AWS Lambda API
// ... app code here exports.fulfillment = app;