เว็บฮุค

เพื่อให้คุณมีความยืดหยุ่นมากขึ้นในการสร้างการดำเนินการ คุณสามารถมอบสิทธิ์ตรรกะ ไปยังบริการเว็บ HTTPS (Fulfillment) การดำเนินการสามารถทริกเกอร์เว็บฮุคที่ ส่งคำขอไปยังปลายทาง HTTPS ตัวอย่างสิ่งที่คุณทำได้ใน การดำเนินการตามคำสั่งซื้อมีดังนี้

  • สร้างข้อความแจ้งแบบไดนามิกตามข้อมูลที่ผู้ใช้ให้ไว้
  • สั่งซื้อในระบบภายนอกและยืนยันความสำเร็จ
  • กำลังตรวจสอบสล็อตด้วยข้อมูลแบ็กเอนด์
รูปที่ 1 Intent การเรียกใช้และฉากจะทริกเกอร์ได้ เว็บฮุค

ทริกเกอร์และเครื่องจัดการเว็บฮุค

การดำเนินการจะทริกเกอร์เว็บฮุคภายใน Intent การเรียกใช้หรือฉาก ซึ่ง ส่งคำขอไปยังปลายทางการดำเนินการตามคำสั่งซื้อ การดำเนินการตามคำสั่งซื้อของคุณมีเว็บฮุค เครื่องจัดการที่ประมวลผลเพย์โหลด JSON ในคำขอ คุณทริกเกอร์เว็บฮุคได้ ในสถานการณ์ต่อไปนี้

  • หลังจากจับคู่ Intent การเรียกใช้แล้ว
  • ระหว่างฉากในเวที
  • หลังจากที่เงื่อนไขประเมินเป็น true แล้วในขั้นตอนเงื่อนไขของฉาก
  • ระหว่างระยะเติมช่องของฉาก
  • หลังจากเกิดการจับคู่ Intent ในขั้นตอนการป้อนข้อมูลของฉาก

เมื่อเรียกใช้เว็บฮุคในการดำเนินการต่างๆ Google Assistant จะส่งคำขอ ด้วยเพย์โหลด JSON ไปยังการดำเนินการตามคำสั่งซื้อ ซึ่งมีส่วน ของเครื่องจัดการที่จะใช้ในการประมวลผลเหตุการณ์ ปลายทางของการดำเนินการตามคำสั่งซื้อจะ กำหนดเส้นทางเหตุการณ์ไปยังตัวแฮนเดิลที่เหมาะสมเพื่อดำเนินการตรรกะและแสดงผล การตอบสนองด้วยเพย์โหลด JSON ที่สอดคล้องกัน

เพย์โหลด

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างคำขอที่การดำเนินการของคุณส่งไปให้ Fulfillment และการตอบกลับที่ Fulfillment ส่งกลับมา โปรดดู เอกสารอ้างอิงเพิ่มเติม

ตัวอย่างคำขอ

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

ตัวอย่างการตอบกลับ

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

การโต้ตอบรันไทม์

ส่วนต่อไปนี้จะอธิบายงานทั่วไปที่คุณสามารถดำเนินการได้ เครื่องจัดการเว็บฮุค

ส่งข้อความแจ้ง

คุณสามารถสร้างพรอมต์ด้วยข้อความธรรมดา ข้อความที่มีการจัดรูปแบบ การ์ด และแม้กระทั่งข้อความ พรอมต์ HTML ที่มาจากเว็บแอปที่ใช้ Interactive Canvas เอกสารประกอบเกี่ยวกับข้อความแจ้งมี ข้อมูลทั้งหมดเกี่ยวกับวิธีสร้างข้อความแจ้งเมื่อจัดการเหตุการณ์เว็บฮุค ข้อมูลโค้ดต่อไปนี้จะแสดงข้อความแจ้งของการ์ด

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

JSON ของการตอบกลับ

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

อ่านพารามิเตอร์ Intent

เมื่อรันไทม์ของ Assistant ตรงกับ Intent จะดึงข้อมูล พารามิเตอร์ พร็อพเพอร์ตี้เดิมคือสิ่งที่ผู้ใช้ระบุไว้เป็นอินพุตและ พร็อพเพอร์ตี้ที่ได้รับการแก้ไขคือสิ่งที่ NLU วิเคราะห์อินพุตโดยอิงตามประเภท

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

ขอ JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

อ่านภาษาของผู้ใช้

ค่านี้สอดคล้องกับการตั้งค่าภาษาของผู้ใช้สำหรับ Google Assistant

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

พื้นที่เก็บข้อมูลอ่านและเขียน

ดูเอกสารเกี่ยวกับพื้นที่เก็บข้อมูลเพื่อดูข้อมูลทั้งหมดเกี่ยวกับวิธีดำเนินการ ใช้ฟีเจอร์พื้นที่เก็บข้อมูลที่หลากหลาย

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

ขอ JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

JSON ของการตอบกลับ

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

ตรวจสอบความสามารถของอุปกรณ์

คุณสามารถตรวจสอบความสามารถของอุปกรณ์เพื่อมอบประสบการณ์ที่แตกต่างกัน หรือ ของการสนทนา

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

ขอ JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

ดูรายการความสามารถทั้งหมดของแพลตฟอร์มได้ที่ Capability ข้อมูลอ้างอิง

การลบล้างประเภทรันไทม์

ประเภทรันไทม์ช่วยให้คุณแก้ไขข้อกำหนดประเภทขณะรันไทม์ได้ คุณใช้ เพื่อโหลดข้อมูลจากแหล่งที่มาอื่นๆ เพื่อเติมค่าที่ถูกต้องของประเภท สำหรับ เช่น คุณสามารถใช้การลบล้างประเภทรันไทม์เพื่อเพิ่มตัวเลือกแบบไดนามิกไปยังแบบสำรวจ คำถามหรือการเพิ่มรายการประจำวันลงในเมนู

ในการใช้ประเภทรันไทม์ คุณจะทริกเกอร์เว็บฮุคจากการดำเนินการที่เรียกใช้ ใน Fulfillment จากตรงนั้น คุณจะป้อนข้อมูล session.typeOverrides ในการตอบกลับการดำเนินการของคุณ พร้อมใช้งาน โหมดรวม TYPE_MERGE เพื่อเก็บรักษารายการประเภทที่มีอยู่หรือ TYPE_REPLACE เพื่อแทนที่รายการที่มีอยู่ด้วยการลบล้าง

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

JSON ของการตอบกลับ

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

ให้ข้อมูลการให้น้ำหนักพิเศษกับคำพูด

การให้น้ำหนักคำพูดช่วยให้คุณระบุคำแนะนำให้กับ NLU เพื่อปรับปรุงการจับคู่ Intent ได้ คุณ สามารถระบุได้สูงสุด 1,000 รายการ

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

JSON ของการตอบกลับ

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

ฉากทรานซิชัน

นอกจากการกำหนดการเปลี่ยนแบบคงที่ในโปรเจ็กต์ Actions แล้ว คุณยังสามารถ ทำให้การเปลี่ยนฉากเกิดขึ้นขณะรันไทม์

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

JSON ของการตอบกลับ

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

อ่านช่วงฉาก

ในระหว่างการเติมช่อง คุณสามารถใช้ Fulfillment เพื่อตรวจสอบช่องหรือตรวจสอบ สถานะของการเติมช่อง (SlotFillingStatus)

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

ตัวอย่างเช่น สมมติว่าคุณต้องการแยกเขตเวลาจากคำตอบ ใน ในตัวอย่างนี้ ชื่อสล็อตคือ datetime1 หากต้องการดูเขตเวลา คุณต้อง ใช้:

conv.scene.slots['datetime1'].value.time_zone.id

ขอ JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

ทำให้สล็อตโหมดไม่ถูกต้อง

คุณสามารถยกเลิกช่องโฆษณาและกำหนดให้ผู้ใช้ระบุค่าใหม่ได้

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

JSON ของการตอบกลับ

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

ตัวเลือกการพัฒนาซอฟต์แวร์

Actions Builder มีเครื่องมือแก้ไขในบรรทัดชื่อเครื่องมือแก้ไข Cloud Functions ซึ่งช่วยให้คุณสร้างและทำให้ Cloud Function สำหรับ Firebase ใช้งานได้โดยตรงใน คอนโซลผู้ดูแลระบบ นอกจากนี้ คุณยังสร้างและติดตั้งใช้งาน Fulfillment ไปยังโฮสติ้งที่ต้องการได้ด้วย และลงทะเบียนปลายทางการดำเนินการตาม HTTPS เป็นเครื่องจัดการเว็บฮุค

ตัวแก้ไขอินไลน์

หากต้องการพัฒนาด้วยเครื่องมือแก้ไข Cloud Functions ให้ทำดังนี้

  1. เปิดโปรเจ็กต์ Actions และไปที่แท็บพัฒนา > เว็บฮุค > เปลี่ยน การดำเนินการตามคำสั่งซื้อ หน้าต่างวิธีการดำเนินการตามคำสั่งซื้อจะปรากฏขึ้น
  2. เลือกฟังก์ชันระบบคลาวด์ในบรรทัด แล้วคลิกยืนยัน

ปลายทาง HTTPS ภายนอก

ส่วนนี้จะอธิบายวิธีตั้งค่าฟังก์ชันระบบคลาวด์สำหรับ Firebase เป็น บริการดำเนินการตามคำสั่งซื้อสำหรับการดำเนินการแบบการสนทนา แต่คุณสามารถทำให้ บริการโฮสติ้งที่คุณเลือก

ตั้งค่าสภาพแวดล้อม

หากต้องการตั้งค่าสภาพแวดล้อม ให้ทำตามขั้นตอนต่อไปนี้

  1. ดาวน์โหลดและติดตั้ง Node.js

  2. ตั้งค่าและเริ่มต้น Firebase CLI หากคำสั่งต่อไปนี้ล้มเหลวกับ ข้อผิดพลาด EACCES คุณอาจต้องเปลี่ยนสิทธิ์ npm

    npm install -g firebase-tools

  3. ตรวจสอบสิทธิ์เครื่องมือ Firebase ด้วยบัญชี Google

    firebase login

  4. เริ่มต้นไดเรกทอรีโปรเจ็กต์ที่คุณบันทึกโปรเจ็กต์ Actions ไว้ ระบบจะขอให้คุณเลือกฟีเจอร์ Firebase CLI ที่ต้องการตั้งค่า โปรเจ็กต์ Actions เลือก Functions และฟีเจอร์อื่นๆ ที่คุณอาจต้องการ ใช้ เช่น Firestore แล้วกด Enter เพื่อยืนยันและดำเนินการต่อ

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. เชื่อมโยงเครื่องมือ Firebase กับโปรเจ็กต์ Actions โดยเลือกโดยใช้ ปุ่มลูกศรเพื่อไปยังส่วนต่างๆ ของรายการโปรเจ็กต์

  6. หลังจากเลือกโปรเจ็กต์แล้ว เครื่องมือ Firebase จะเริ่มฟังก์ชัน ตั้งค่าและถามว่าคุณต้องการใช้ภาษาใด เลือกโดยใช้ปุ่มลูกศร แล้วกด Enter เพื่อดำเนินการต่อ

    === Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

  7. เลือกว่าคุณต้องการใช้ ESLint ในการดักจับข้อบกพร่องที่เป็นไปได้และบังคับใช้การจัดรูปแบบโดยพิมพ์ Y หรือ N ดังนี้

    ? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)

  8. รับทรัพยากร Dependency ของโปรเจ็กต์โดยพิมพ์ Y ลงในข้อความแจ้ง

    ? Do you want to install dependencies with npm now? (Y/n)

    เมื่อตั้งค่าเสร็จแล้ว คุณจะเห็นผลลัพธ์ที่คล้ายกับข้อความต่อไปนี้

    ✔  Firebase initialization complete!

  9. ติดตั้งการอ้างอิง @assistant/conversation ดังนี้

    $ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

  10. รับทรัพยากร Dependency ของ Fulfillment และจะทำให้ฟังก์ชัน Fulfillment ใช้งานได้ด้วยคำสั่งต่อไปนี้

    $ npm install
$ firebase deploy --only functions

    การทำให้ใช้งานได้จะใช้เวลาไม่กี่นาที เมื่อเสร็จแล้ว คุณจะเห็นเอาต์พุต ดังต่อไปนี้ คุณจะต้องมี Function URL จึงจะป้อนใน Dialogflow ได้

    ✔  Deploy complete!
    
Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>

  11. คัดลอก URL การดำเนินการตามคำสั่งซื้อเพื่อใช้ในส่วนถัดไป

ลงทะเบียนเครื่องจัดการเว็บฮุค

วิธีลงทะเบียนปลายทาง Cloud Function เป็นเครื่องจัดการเว็บฮุค

  1. ในคอนโซล Actions ให้คลิก Develop > เว็บฮุค
  2. คลิกเปลี่ยนวิธีดำเนินการตามคำสั่งซื้อ หน้าต่างวิธีการดำเนินการตามคำสั่งซื้อ จะปรากฏขึ้น
  3. เลือกเว็บฮุค แล้วคลิกยืนยัน
  4. วาง URL ของบริการเว็บลงในช่อง Webhook
  5. คลิกบันทึก