الردّ التلقائي على الويب

لمنحك المزيد من المرونة في إنشاء الإجراءات، يمكنك تفويض منطق إلى خدمات الويب HTTPS (التنفيذ). يمكن أن تؤدي إجراءاتك إلى تفعيل ويب هوك يرسل طلبات إلى نقطة نهاية HTTPS. في ما يلي بعض الأمثلة على الإجراءات التي يمكنك اتّخاذها في عملية التنفيذ:

  • إنشاء طلب ديناميكي استنادًا إلى المعلومات التي يقدّمها المستخدم
  • تقديم طلب في نظام خارجي وتأكيد نجاحه
  • التحقّق من صحة الفتحات باستخدام بيانات الخلفية
الشكل 1. يمكن أن تؤدي نوايا الاستدعاء والمشاهد إلى تشغيل خطافات الويب.

مشغّلات الويب هوك ومعالجاتها

يمكن أن تؤدي "الإجراءات" إلى تشغيل ويب هوك ضمن نوايا الاستدعاء أو المشاهد، ما يؤدي إلى إرسال طلب إلى نقطة نهاية التنفيذ. يتضمّن التنفيذ معالِجات لخطاف الويب تعالج حِمل JSON في الطلب. يمكنك تشغيل خطافات الويب في الحالات التالية:

  • بعد مطابقة هدف طلب التفعيل
  • خلال مرحلة "عند الدخول" في مشهد
  • بعد أن يتم تقييم شرط على أنّه صحيح في مرحلة الشرط في أحد المشاهد
  • أثناء مرحلة ملء الخانات في مشهد
  • بعد حدوث تطابق بين النية في مرحلة إدخال المشهد

عندما تشغّل خطاف ويب في "الإجراءات"، يرسل "مساعد Google" طلبًا يتضمّن حمولة بتنسيق JSON إلى خدمة التنفيذ، ويحتوي هذا الطلب على اسم معالج سيتم استخدامه لمعالجة الحدث. يمكن لنقطة نهاية التنفيذ توجيه الحدث إلى المعالج المناسب لتنفيذ المنطق وعرض استجابة بحِمل JSON مطابق.

الحمولات

تعرض المقتطفات التالية أمثلة على الطلبات التي ترسلها "الإجراءات" إلى خدمة التنفيذ وردًّا ترسله خدمة التنفيذ. يمكنك الاطّلاع على المستندات المرجعية للحصول على مزيد من المعلومات.

مثال على الطلب

{
  "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.

إرسال الطلبات

يمكنك إنشاء طلبات باستخدام نص بسيط، ونص منسّق، وبطاقات، وحتى طلبات HTML كاملة مدعومة بتطبيق ويب مع Interactive Canvas. يتضمّن مستند الطلبات معلومات كاملة حول كيفية إنشاء طلب عند معالجة حدث webhook. تعرض المقتطفات التالية طلبًا لإنشاء بطاقة:

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

قراءة مَعلمات القصد

عندما يطابق وقت تشغيل "مساعد Google" غرضًا، يستخرج أي معلَمات محدّدة. الخاصية الأصلية هي ما قدّمه المستخدم كإدخال، أما الخاصية التي تم تحليلها فهي ما حلّله نظام فهم اللغة الطبيعية (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".

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.

إلغاء نوع بيئة التشغيل

تتيح لك أنواع وقت التشغيل تعديل مواصفات الأنواع في وقت التشغيل. يمكنك استخدام هذه الميزة لتحميل البيانات من مصادر أخرى لملء القيم الصالحة لنوع معيّن. على سبيل المثال، يمكنك استخدام عمليات إلغاء نوع وقت التشغيل لإضافة خيارات ديناميكية إلى سؤال في استطلاع أو لإضافة عنصر يومي إلى قائمة.

لاستخدام أنواع وقت التشغيل، عليك تفعيل خطاف ويب من "الإجراء" الخاص بك يستدعي معالجًا في عملية التنفيذ. يمكنك بعد ذلك ملء المَعلمة 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."
    }
  }
}

توفير تحيّز الكلام

تتيح لك ميزة "تحسين التعرّف على الكلام" تحديد تلميحات لمعالجة اللغة الطبيعية من أجل تحسين مطابقة النية. يمكنك تحديد 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"
  }
}

المشاهد الانتقالية

بالإضافة إلى تحديد عمليات الانتقال الثابتة في مشروع "الإجراءات"، يمكنك تفعيل عمليات انتقال المشاهد أثناء وقت التشغيل.

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 محرّرًا مضمّنًا يُعرف باسم محرّر "وظائف السحابة الإلكترونية"، يتيح لك إنشاء وظيفة سحابية لبرنامج Firebase ونشرها مباشرةً في وحدة التحكّم. يمكنك أيضًا إنشاء عملية التنفيذ ونشرها في خدمة الاستضافة التي تختارها وتسجيل نقطة نهاية التنفيذ عبر HTTPS كمعالج لخطاف الويب.

المحرّر المضمّن

للتطوير باستخدام محرِّر Cloud Functions، اتّبِع الخطوات التالية:

  1. افتح مشروع "الإجراءات على Google" وانتقِل إلى علامة التبويب "تطوير" > "خطاف الويب" > "تغيير طريقة التنفيذ". تظهر نافذة طرق التنفيذ.
  2. اختَر Inline Cloud Functions وانقر على تأكيد.

نقطة نهاية HTTPS خارجية

يوضّح هذا القسم كيفية إعداد &quot;وظائف Firebase السحابية&quot; كخدمة تنفيذ لـ &quot;الإجراء الحواري&quot;. ومع ذلك، يمكنك نشر عملية التنفيذ إلى خدمة استضافة من اختيارك.

إعداد البيئة

لإعداد بيئتك، اتّبِع الخطوات التالية:

  1. تنزيل Node.js وتثبيته

  2. إعداد Firebase CLI وتهيئة إعداداته في حال تعذُّر تنفيذ الأمر التالي بسبب ظهور الخطأ EACCES، قد تحتاج إلى تغيير أذونات npm.

    npm install -g firebase-tools

  3. يجب مصادقة أداة Firebase باستخدام حسابك على Google باتّباع الخطوات التالية:

    firebase login

  4. ابدأ دليل المشروع الذي حفظت فيه مشروع "إجراءات Google". سيُطلب منك اختيار ميزات واجهة Firebase CLI التي تريد إعدادها لمشروعك على "إجراءات Google". اختَر 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. احصل على تبعيات المشروع من خلال كتابة 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. احصل على تبعيات التنفيذ ونفِّذ وظيفة التنفيذ:

    $ npm install
$ firebase deploy --only functions

    تستغرق عملية النشر بضع دقائق. بعد اكتمال العملية، ستظهر لك نتيجة مشابهة لما يلي. ستحتاج إلى عنوان 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. في "وحدة تحكّم الإجراءات"، انقر على تطوير > Webhook.
  2. انقر على تغيير طريقة التنفيذ. تظهر نافذة طرق التنفيذ.
  3. اختَر Webhook وانقر على تأكيد.
  4. ألصِق عنوان URL لخدمة الويب في حقل Webhook.
  5. انقر على حفظ.