สร้าง Fulfillment ด้วยไลบรารีของไคลเอ็นต์ Actions on Google Node.js (Dialogflow)

ไลบรารีไคลเอ็นต์ 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 จัดการด้วยความช่วยเหลือของไลบรารีไคลเอ็นต์สรุปไว้คร่าวๆ ได้ด้านล่างนี้

รูปที่ 1 สถาปัตยกรรมระดับสูงของไลบรารีของไคลเอ็นต์ Node.js
  1. การรับคำขอของผู้ใช้: เมื่อผู้ใช้ทำการค้นหาไปยัง Google Assistant แพลตฟอร์ม Actions on Google จะส่งคำขอ HTTP ไปยังเว็บฮุค Fulfillment คำขอจะมีเพย์โหลด JSON ที่มี Intent และข้อมูลอื่นๆ เช่น ข้อความดิบของอินพุตจากผู้ใช้ และความสามารถในแพลตฟอร์มของอุปกรณ์ของผู้ใช้ ดูตัวอย่างเพิ่มเติมของเนื้อหาเพย์โหลด JSON ได้ที่คู่มือรูปแบบเว็บฮุคของ Dialogflow และรูปแบบเว็บฮุคสำหรับการสนทนา
  2. การตรวจหารูปแบบการโทรของเฟรมเวิร์ก: สำหรับเฟรมเวิร์กที่รองรับ ไลบรารีของไคลเอ็นต์จะตรวจหารูปแบบการเรียกของเฟรมเวิร์กโดยอัตโนมัติ (เช่น หากคำขอมาจากเว็บเฟรมเวิร์กของ Express หรือจาก AWS Lambda) และรู้วิธีจัดการกับการสื่อสารกับแพลตฟอร์ม Actions on Google ได้อย่างราบรื่น
  3. การประมวลผลตัวแฮนเดิลบริการ: ไลบรารีของไคลเอ็นต์จะแสดงการสนทนาของ API เว็บฮุค HTTP/JSON สำหรับ Dialogflow และ Actions SDK ในฐานะฟังก์ชันบริการ เว็บฮุค Fulfillment จะใช้บริการที่เหมาะสมในการสร้างอินสแตนซ์ app ส่วนกลาง อินสแตนซ์ app ทำหน้าที่เป็นเครื่องจัดการคำขอ HTTP และเข้าใจโปรโตคอลที่เฉพาะเจาะจงของบริการ
  4. การประมวลผลการสนทนา: ไลบรารีของไคลเอ็นต์จะแสดงข้อมูลต่อการสนทนาเป็นออบเจ็กต์ Conversation ที่แนบกับอินสแตนซ์ app เว็บฮุค Fulfillment ของคุณอาจใช้ออบเจ็กต์ Conversation เพื่อเรียกดูข้อมูลหรือข้อมูลสถานะที่จัดเก็บข้ามการสนทนา ส่งคำตอบไปยังผู้ใช้ หรือปิดไมโครโฟน
  5. การประมวลผลมิดเดิลแวร์: ไลบรารีของไคลเอ็นต์ให้คุณสร้างมิดเดิลแวร์บริการการสนทนาของคุณเอง ซึ่งประกอบด้วยฟังก์ชันอย่างน้อย 1 รายการที่คุณกำหนดว่าไลบรารีของไคลเอ็นต์จะทำงานโดยอัตโนมัติก่อนเรียกใช้เครื่องจัดการ Intent เว็บฮุค Fulfillment จะใช้มิดเดิลแวร์เพื่อเพิ่มพร็อพเพอร์ตี้หรือคลาสตัวช่วยไปยังออบเจ็กต์ Conversation ได้
  6. การประมวลผลตัวแฮนเดิล Intent: ไลบรารีของไคลเอ็นต์ให้คุณกำหนดแฮนเดิลสำหรับ Intent ที่เว็บฮุคสำหรับดำเนินการตามคำสั่งซื้อเข้าใจ สำหรับ Dialogflow ไลบรารีไคลเอ็นต์จะกำหนดเส้นทางคำขอไปยังเครื่องจัดการ Intent ที่ถูกต้องโดยการแมปกับสตริงที่ตรงกับชื่อ Intent ที่ระบุไว้ในคอนโซล Dialogflow สำหรับ Actions SDK ระบบจะกำหนดเส้นทางโดยอิงตามพร็อพเพอร์ตี้ intent ที่ส่งจาก Actions on Google
  7. การส่งคำตอบไปยังผู้ใช้: หากต้องการสร้างคำตอบ เว็บฮุค 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 ให้ทำตามขั้นตอนต่อไปนี้

  1. เรียกใช้ฟังก์ชัน 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 ที่คุณต้องการใช้ได้ หากต้องการดูรายการคลาสที่ถูกต้องทั้งหมดที่คุณดาวน์โหลดได้ โปรดดูเอกสารอ้างอิงสำหรับโมดูลการตอบกลับการสนทนาและความตั้งใจของผู้ช่วยเหลือ

  2. สร้างอินสแตนซ์ app โดยเรียกใช้บริการที่คุณโหลด ตัวอย่างเช่น 

    const app = dialogflow();

  3. หากต้องการกำหนดค่าอินสแตนซ์ 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 ในเครื่องจัดการเพื่อส่งคำตอบไปยังผู้ใช้

นอกจากนี้ คำค้นหาของผู้ใช้อาจมีพารามิเตอร์ที่การดำเนินการของคุณดึงข้อมูลและใช้เพื่อปรับแต่งคำตอบได้

ตั้งค่าเครื่องจัดการสำหรับ 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;