برای اینکه در ساخت Actionها انعطافپذیری بیشتری داشته باشید، میتوانید منطق را به سرویسهای وب HTTPS (اجرای درخواست) واگذار کنید. Actionهای شما میتوانند Webhookهایی را فعال کنند که درخواستها را به یک نقطه پایانی HTTPS ارسال میکنند. برخی از نمونههایی از کارهایی که میتوانید در بخش اجرا انجام دهید عبارتند از:
- تولید یک اعلان پویا بر اساس اطلاعات ارائه شده توسط کاربر.
- ثبت سفارش در یک سیستم خارجی و تأیید موفقیتآمیز بودن آن.
- اعتبارسنجی اسلاتها با دادههای بکاند.
تریگرها و هندلرهای وبهوک
اقدامات شما میتوانند یک وبهوک را در داخل Intentها یا Sceneهای فراخوانی فعال کنند، که درخواستی را به Endpoint تکمیل درخواست شما ارسال میکند. تکمیل درخواست شما شامل کنترلکنندههای وبهوک است که JSON payload موجود در درخواست را پردازش میکنند. میتوانید وبهوکها را در موقعیتهای زیر فعال کنید:
- پس از تطبیق قصد فراخوانی
- در طول یک صحنه، وارد صحنه میشویم
- پس از اینکه یک شرط در مرحلهی وضعیت صحنه درست (true) ارزیابی شود
- در طول مرحله پر کردن جای خالی صحنه
- پس از وقوع تطابق هدف در مرحله ورودی صحنه
وقتی در Actions خود یک webhook را فعال میکنید، دستیار گوگل درخواستی با یک payload از نوع JSON به سرویس تکمیل درخواست شما ارسال میکند که شامل نام هندلری است که باید برای پردازش رویداد استفاده شود. نقطه پایانی تکمیل درخواست شما میتواند رویداد را به هندلر مناسب هدایت کند تا منطق را اجرا کند و پاسخ مربوطه را با یک payload از نوع JSON برگرداند.
بارهای مفید
قطعه کدهای زیر نمونه درخواستهایی را نشان میدهند که بخش Actions شما برای انجام کار ارسال میکند و پاسخی که بخش انجام کار شما برمیگرداند. برای اطلاعات بیشتر به مستندات مرجع مراجعه کنید.
درخواست نمونه
{
"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"
}
}
}
تعاملات زمان اجرا
بخشهای زیر وظایف رایجی را که میتوانید در webhook handlerهای خود انجام دهید، شرح میدهند.
ارسال پیامهای فوری
شما میتوانید با استفاده از Interactive Canvas و یک برنامه وب، اعلانهایی با متن ساده، متن غنی، کارتها و حتی اعلانهای HTML کامل ایجاد کنید. مستندات اعلانها اطلاعات کاملی در مورد نحوه ایجاد یک اعلان هنگام مدیریت یک رویداد وبهوک ارائه میدهد. قطعه کدهای زیر یک اعلان کارتی را نشان میدهند:
نود جی اس
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": ""
}
}
}
پارامترهای هدف را بخوانید
وقتی که زمان اجرای Assistant با یک intent مطابقت پیدا میکند، هر پارامتر تعریفشدهای را استخراج میکند. ویژگی اصلی چیزی بود که کاربر به عنوان ورودی ارائه میداد و ویژگی حلشده چیزی است که NLU ورودی را بر اساس مشخصات نوع به آن حل کرده است.
نود جی اس
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"
]
}
}
خواندن زبان کاربر
این مقدار مربوط به تنظیمات زبان کاربر برای دستیار گوگل است.
نود جی اس
conv.user.locale
جیسون
{
"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"
]
}
}
خواندن و نوشتن فضای ذخیرهسازی
برای اطلاعات کامل در مورد نحوه استفاده از ویژگیهای مختلف ذخیرهسازی، به مستندات ذخیرهسازی مراجعه کنید.
نود جی اس
//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"
}
}
}
بررسی قابلیتهای دستگاه
شما میتوانید قابلیتهای یک دستگاه را برای ارائه تجربیات یا جریانهای مکالمه مختلف بررسی کنید.
نود جی اس
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 مراجعه کنید.
نوع زمان اجرا لغو میشود
انواع داده در زمان اجرا به شما امکان میدهند مشخصات نوع داده را در زمان اجرا تغییر دهید. میتوانید از این ویژگی برای بارگذاری دادهها از منابع دیگر برای پر کردن مقادیر معتبر یک نوع داده استفاده کنید. به عنوان مثال، میتوانید از لغو نوع داده در زمان اجرا برای اضافه کردن گزینههای پویا به یک سوال نظرسنجی یا اضافه کردن یک مورد روزانه به یک منو استفاده کنید.
برای استفاده از انواع زمان اجرا، شما یک وبهوک را از اکشن خود فعال میکنید که یک هندلر را در تکمیل درخواست شما فراخوانی میکند. از آنجا، میتوانید پارامتر session.typeOverrides را در پاسخ به اکشن خود پر کنید. حالتهای موجود شامل TYPE_MERGE برای حفظ ورودیهای نوع موجود یا TYPE_REPLACE برای جایگزینی ورودیهای موجود با overrideها است.
نود جی اس
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 راهنماییهایی (نکات) مشخص کنید. میتوانید تا ۱۰۰۰ ورودی را مشخص کنید.
نود جی اس
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، میتوانید باعث شوید که انتقالهای صحنه در زمان اجرا رخ دهند.
نود جی اس
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"
}
}
}
اسلاتهای صحنه را بخوانید
در حین پر کردن اسلات، میتوانید از تکمیل سفارش برای اعتبارسنجی اسلات یا بررسی وضعیت پر شدن اسلات ( SlotFillingStatus ) استفاده کنید.
نود جی اس
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"
]
}
}
نامعتبر کردن جایگاههای صحنه
شما میتوانید اسلاتها را نامعتبر کنید و از کاربر بخواهید مقدار جدیدی ارائه دهد.
نود جی اس
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 را مستقیماً در کنسول بسازید و مستقر کنید. همچنین میتوانید تکمیل سفارش را در هاستینگ مورد نظر خود بسازید و مستقر کنید و نقطه پایانی تکمیل سفارش HTTPS خود را به عنوان کنترلکننده وبهوک خود ثبت کنید.
ویرایشگر درون خطی
برای توسعه با ویرایشگر توابع ابری:
- پروژه Actions خود را باز کنید و به تب Develop > Webhook > Change completion method بروید. پنجره Fulfillment methods ظاهر میشود.
- توابع ابری درونخطی را انتخاب کنید و روی تأیید کلیک کنید.
نقطه پایانی HTTPS خارجی
این بخش نحوه تنظیم توابع ابری برای فایربیس به عنوان یک سرویس تکمیل سفارش برای اقدام محاورهای شما را شرح میدهد. با این حال، میتوانید تکمیل سفارش را در یک سرویس میزبانی دلخواه خود مستقر کنید.
محیط را تنظیم کنید
برای تنظیم محیط خود، مراحل زیر را دنبال کنید:
- Node.js را دانلود و نصب کنید .
رابط خط فرمان فایربیس (Firebase CLI) را راهاندازی و مقداردهی اولیه کنید. اگر دستور زیر با خطای
EACCESمواجه شد، ممکن است لازم باشد مجوزهای npm را تغییر دهید .npm install -g firebase-toolsابزار فایربیس را با حساب گوگل خود تأیید کنید:
firebase loginپوشه پروژه را که پروژه Actions خود را در آن ذخیره کردهاید، باز کنید. از شما خواسته میشود که ویژگیهای Firebase CLI مورد نظر خود را برای پروژه Actions خود انتخاب کنید.
Functionsو سایر ویژگیهایی را که ممکن است بخواهید از آنها استفاده کنید، مانند Firestore، انتخاب کنید، سپس Enter را برای تأیید و ادامه فشار دهید:$ cd <ACTIONS_PROJECT_DIRECTORY> $ firebase initبا انتخاب ابزار Firebase با استفاده از کلیدهای جهتنما برای پیمایش در لیست پروژهها، آن را به پروژه Actions خود مرتبط کنید:
پس از انتخاب پروژه، ابزار 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
با تایپ Y یا N، انتخاب کنید که آیا میخواهید از ESLint برای شناسایی اشکالات احتمالی و اعمال سبک استفاده کنید یا خیر:
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
با تایپ کردن Y در خط فرمان، وابستگیهای پروژه را دریافت کنید:
? Do you want to install dependencies with npm now? (Y/n)
پس از اتمام تنظیمات، خروجی مشابه زیر را مشاهده خواهید کرد:
✔ Firebase initialization complete!وابستگی @assistant/conversation را نصب کنید:
$ cd <ACTIONS_PROJECT_DIRECTORY>/functions $ npm install @assistant/conversation --saveوابستگیهای مربوط به تکمیل سفارش را دریافت کرده و تابع تکمیل سفارش را مستقر کنید:
$ npm install $ firebase deploy --only functionsاستقرار چند دقیقه طول میکشد. پس از اتمام، خروجی مشابه زیر را مشاهده خواهید کرد. برای وارد کردن در Dialogflow به آدرس تابع (Function URL) نیاز دارید.
✔ 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>آدرس اینترنتی (URL) مربوط به تکمیل سفارش را کپی کنید تا در بخش بعدی از آن استفاده کنید.
ثبت نام کنترل کننده وب هوک
برای ثبت نقطه پایانی عملکرد ابری خود به عنوان یک کنترل کننده وب هوک:
- در کنسول Actions، روی Develop > Webhook کلیک کنید.
- روی «تغییر روش انجام سفارش» کلیک کنید. پنجره « روشهای انجام سفارش» ظاهر میشود.
- وبهوک را انتخاب کنید و روی تأیید کلیک کنید.
- آدرس وب سرویس خود را در فیلد Webhook وارد کنید.
- روی ذخیره کلیک کنید.