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

لمنحك المزيد من المرونة في إنشاء الإجراءات، يمكنك تفويض المنطق لخدمات الويب التي تستخدم بروتوكول 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"
    }
  }
}

تفاعلات وقت التشغيل

توضِّح الأقسام التالية المهام الشائعة التي يمكنك تنفيذها في معالِجات الردّ التلقائي على الويب.

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

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

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

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

يتيح لك انحياز الكلام تحديد تلميحات إلى 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"
  }
}

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

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

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

خيارات التطوير

توفّر "أداة إنشاء الإجراءات" محرِّرًا مضمّنًا يُعرف باسم محرِّر وظائف السحابة الإلكترونية، الذي يتيح لك إنشاء دالة السحابة الإلكترونية لبرنامج Firebase ونشرها مباشرةً في وحدة التحكّم. يمكنك أيضًا إنشاء وتنفيذ عملية التنفيذ للاستضافة التي تختارها، وتسجيل نقطة نهاية تنفيذ HTTPS كمعالج الرد التلقائي على الويب.

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

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

  1. افتح مشروع "المهام" وانتقِل إلى علامة التبويب "التطوير" > الردّ التلقائي على الويب > تغيير طريقة التنفيذ. ستظهر نافذة طرق التنفيذ.
  2. اختَر دوال السحابة الإلكترونية المضمّنة وانقر على تأكيد.

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

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

إعداد البيئة

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

  1. نزِّل Node.js وثبِّتها.

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

    npm install -g firebase-tools

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

    firebase login

  4. ابدأ دليل المشروع الذي حفظت فيه مشروع الإجراءات. سيُطلب منك تحديد ميزات واجهة سطر الأوامر في Firebase التي تريد إعدادها لمشروع الإجراءات. اختر "Functions" والميزات الأخرى التي قد تريد استخدامها، مثل Firestore، ثم اضغط على Enter للتأكيد والمتابعة:

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. اربط أداة Firebase بمشروع "المهام" من خلال اختياره باستخدام مفاتيح الأسهم للتنقّل في قائمة المشاريع:

  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 كمعالج ردّ تلقائي على الويب:

  1. في وحدة تحكّم الإجراءات، انقر على التطوير > الردّ التلقائي على الويب.
  2. انقر على تغيير طريقة تنفيذ الطلب. ستظهر نافذة طرق التنفيذ.
  3. اختَر الردّ التلقائي على الويب وانقر على تأكيد.
  4. الصِق عنوان URL لخدمة الويب في حقل الردّ التلقائي على الويب.
  5. انقر على حفظ.