کنش‌های مکالمه در 13 ژوئن 2023 منسوخ شد. برای اطلاعات بیشتر، غروب کنش‌های مکالمه را ببینید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

وب هوک ها

برای اینکه در ساخت Actions انعطاف‌پذیری بیشتری داشته باشید، می‌توانید منطق را به خدمات وب HTTPS (تکمیل) واگذار کنید. Actions شما می‌تواند وب هوک‌هایی را راه‌اندازی کند که به یک نقطه پایانی HTTPS درخواست می‌دهند. برخی از نمونه‌هایی از کارهایی که می‌توانید انجام دهید عبارتند از:

ایجاد یک اعلان پویا بر اساس اطلاعات ارائه شده توسط کاربر.
ثبت سفارش در یک سیستم خارجی و تایید موفقیت.
اعتبار سنجی اسلات ها با داده های باطن.

**شکل 1.** مقاصد و صحنه های فراخوانی می توانند وب هوک ها را تحریک کنند.

محرک ها و کنترل کننده های Webhook

کنش‌های شما می‌توانند یک وبکهک را در داخل مقاصد یا صحنه‌های فراخوانی راه‌اندازی کنند که درخواستی را به نقطه پایانی شما ارسال می‌کند. تکمیل شما حاوی کنترل‌کننده‌های وب هوک است که بار JSON را در درخواست پردازش می‌کنند. در شرایط زیر می توانید وب هوک ها را فعال کنید:

پس از یک تطابق قصد فراخوانی
در طول یک صحنه روی صحنه
بعد از اینکه یک شرط در مرحله شرایط صحنه به درستی ارزیابی می شود
در طول مرحله پر کردن شکاف صحنه
پس از اینکه یک تطابق قصد در مرحله ورودی صحنه رخ می دهد

هنگامی که یک هوک را در Actions خود راه‌اندازی می‌کنید، Google Assistant درخواستی را با یک بار JSON به انجام شما ارسال می‌کند که حاوی نام کنترل‌کننده برای استفاده برای پردازش رویداد است. نقطه پایانی شما می‌تواند رویداد را به سمت کنترل‌کننده مناسب هدایت کند تا منطق را انجام دهد و پاسخ مربوطه را با یک بار 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"
    }
  }
}

تعاملات زمان اجرا

بخش‌های زیر وظایف رایجی را که می‌توانید در کنترل‌کننده‌های وب هوک خود انجام دهید، شرح می‌دهند.

درخواست ها را ارسال کنید

می‌توانید با متن ساده، متن غنی، کارت‌ها و حتی درخواست‌های HTML کامل که توسط یک برنامه وب با 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": ""
    }
  }
}

پارامترهای هدف را بخوانید

وقتی زمان اجرا 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 مراجعه کنید.

نوع زمان اجرا لغو می شود

انواع زمان اجرا به شما امکان می دهد مشخصات نوع را در زمان اجرا تغییر دهید. می توانید از این ویژگی برای بارگیری داده ها از منابع دیگر برای پر کردن مقادیر معتبر یک نوع استفاده کنید. به عنوان مثال، می‌توانید از بازنویسی‌های نوع زمان اجرا برای افزودن گزینه‌های پویا به سؤال نظرسنجی یا افزودن یک آیتم روزانه به منو استفاده کنید.

برای استفاده از انواع زمان اجرا، یک وب هوکی از Action خود راه اندازی می کنید که یک کنترل کننده را در انجام شما فرا می خواند. از آنجا، می توانید پارامتر session.typeOverrides در پاسخی به Action خود پر کنید. حالت‌های موجود عبارتند از 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 برای بهبود تطابق قصد مشخص کنید. شما می توانید تا 1000 ورودی را مشخص کنید.

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"
    }
  }
}

اسلات صحنه را بخوانید

در حین پر کردن شکاف، می توانید از تکمیل برای تأیید اعتبار شکاف یا بررسی وضعیت پر شدن شکاف ( 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 مستقیماً در کنسول بسازید و مستقر کنید. همچنین می‌توانید تکمیل‌سازی را در میزبان انتخابی خود بسازید و مستقر کنید و نقطه پایانی تکمیل HTTPS خود را به‌عنوان کنترل‌کننده وب هوک خود ثبت کنید.

ویرایشگر درون خطی

مهم : اگر با ویرایشگر توابع Cloud درون خطی در حال ساخت و استقرار اجرای آن هستید، باید یک حساب صورت‌حساب را به پروژه خود در Google Cloud پیوند دهید. این الزام از 17 اوت 2020 اعمال می‌شود. برای دستورالعمل‌های مرتبط کردن حساب صورت‌حساب به پروژه خود در Google Cloud، به اصلاح تنظیمات صورت‌حساب پروژه مراجعه کنید. برای اطلاعات بیشتر به سهمیه ها و قیمت ها مراجعه کنید. ما شدیداً توصیه می‌کنیم در اسرع وقت یک حساب صورت‌حساب را برای جلوگیری از قطع شدن خدمات مرتبط کنید.

برای توسعه با ویرایشگر Cloud Functions:

فایل sdk/webhooks/ActionsOnGoogleFulfillment.yaml را ایجاد کنید و کنترل‌کننده‌های Action خود و تابع ابر درون خطی مورد استفاده برای انجام را تعریف کنید.
```
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment
    
```

پوشه sdk/webhooks/ActionsOnGoogleFulfillment را ایجاد کنید و یک فایل index.js که کنترل کننده های قبلاً تعریف شده را پیاده سازی می کند و یک فایل package.json که الزامات npm را برای کد شما تعریف می کند، اضافه کنید.

// index.js
const {conversation} = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('questionOnEnterFunc', conv => {
  conv.add('questionOnEnterFunc triggered on webhook');
});

app.handle('fruitSlotValidationFunc', conv => {
  conv.add('fruitSlotValidationFunc triggered on webhook');
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

// package.json
{
  "name": "ActionsOnGoogleFulfillment",
  "version": "0.1.0",
  "description": "Actions on Google fulfillment",
  "main": "index.js",
  "dependencies": {
    "@assistant/conversation": "^3.0.0",
    "firebase-admin": "^5.4.3",
    "firebase-functions": "^0.7.1"
  }
}

نقطه پایانی HTTPS خارجی

این بخش نحوه راه اندازی Cloud Functions برای Firebase را به عنوان یک سرویس تکمیلی برای کنش مکالمه خود توضیح می دهد. با این حال، شما می توانید تکمیل را به یک سرویس میزبانی انتخابی خود مستقر کنید.

تنظیم محیط

هنگامی که از توابع Cloud برای Firebase به عنوان یک سرویس تکمیل استفاده می کنید، ساختار پروژه زیر را توصیه می کنیم:

ProjectFolder        - Root folder for the project
  sdk                - Actions project configuration files
  functions          - Cloud functions for Firebase files

برای تنظیم محیط خود، این مراحل را دنبال کنید:

Node.js را دانلود و نصب کنید .
Firebase CLI را تنظیم و مقداردهی اولیه کنید. اگر دستور زیر با خطای EACCES ناموفق بود، ممکن است لازم باشد مجوزهای npm را تغییر دهید .
```
npm install -g firebase-tools
```
ابزار Firebase را با حساب Google خود تأیید اعتبار کنید:
```
firebase login
```
دایرکتوری پروژه را که در آن پروژه Actions خود را ذخیره کرده اید شروع کنید. از شما خواسته می شود ویژگی های Firebase CLI را که می خواهید برای پروژه Actions خود تنظیم کنید، انتخاب کنید. Functions و سایر ویژگی‌هایی را که ممکن است بخواهید استفاده کنید، مانند Firestore را انتخاب کنید، سپس Enter را برای تأیید و ادامه فشار دهید:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
ابزار Firebase را با استفاده از کلیدهای جهت‌نما برای پیمایش در فهرست پروژه‌ها، با پروژه Actions خود مرتبط کنید:
توجه: می‌توانید با انتخاب [پروژه پیش‌فرض را تنظیم نکنید] از این مرحله رد شوید، اما بعداً باید این ارتباط را با استفاده از دستور firebase use PROJECT_ID انجام دهید.
پس از انتخاب پروژه، ابزار Firebase تنظیمات Functions را شروع می کند و از شما می پرسد که از چه زبانی می خواهید استفاده کنید. با استفاده از کلیدهای جهت دار انتخاب کنید و برای ادامه 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
```
انتخاب کنید که آیا می‌خواهید از ESLint برای شناسایی اشکالات احتمالی و اعمال سبک با تایپ Y یا N استفاده کنید:
```
? 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 به 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 تکمیل را برای استفاده در بخش بعدی کپی کنید.

ثبت نام کنترل کننده وب هوک

فایل sdk/webhooks/ActionsOnGoogleFulfillment.yaml را ایجاد کنید و کنترل‌کننده‌ها را برای Action خود و URL را برای درخواست‌های webhook تعریف کنید.
```
httpsEndpoint:
  baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
  endpointApiVersion: 2
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc
    
```