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

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

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

أداة إنشاء الإجراءات حزمة تطوير البرامج (SDK) الخاصة بـ "الإجراءات"

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

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

مهم: إذا كنت بصدد إنشاء باستخدام محرِّر دوال Cloud Functions المضمّنة، يجب ربط حساب فوترة لمشروعك في Google Cloud. يأخذ هذا المطلب اعتبارًا من 17 آب (أغسطس) 2020. للحصول على تعليمات حول ربط حساب الفوترة لمشروعك في Google Cloud، يُرجى الاطّلاع على تعديل إعدادات الفوترة للمشروع عرض الحصص الأسعار لمزيد من الخيارات المعلومات. ننصحك بشدة بربط حساب الفوترة في أقرب وقت ممكن. منع انقطاع الخدمة.

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

1. أنشئ الملف sdk/webhooks/ActionsOnGoogleFulfillment.yaml، وتحديد معالجات الإجراء ودالة السحابة الإلكترونية المضمّنة المستخدمة لتنفيذه.

   handlers:
   - name: questionOnEnterFunc
   - name: fruitSlotValidationFunc
   inlineCloudFunction:
     executeFunction: ActionsOnGoogleFulfillment
       

2. أنشئ المجلد 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 خارجية

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

مهم: إذا كنت تنشئ ونشر التنفيذ باستخدام دوال Cloud على Firebase، يجب ربط حساب فوترة بمشروعك في Google Cloud. هذا النمط اعتبارًا من 17 آب (أغسطس) 2020. للحصول على تعليمات حول الربط حساب فوترة لمشروعك في Google Cloud، راجِع تعديل إعدادات الفوترة للمشروع عرض الحصص الأسعار لمزيد من الخيارات المعلومات. ننصحك بشدة بربط حساب الفوترة في أقرب وقت ممكن. لتجنُّب انقطاع الخدمة.

إعداد البيئة

ننصح باستخدام بنية المشروع التالية عند استخدام دوال Cloud Firebase كخدمة تنفيذ الطلبات:

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

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

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 بمشروع "المهام" من خلال اختيارها باستخدام مفاتيح الأسهم للتنقّل في قائمة المشاريع:

   ملاحظة: يمكنك تخطي هذه الخطوة من خلال اختيار [يُرجى عدم إعداد مشروع تلقائي]، وبعد ذلك عليك إجراء ذلك لاحقًا باستخدام الأمر firebase use PROJECT_ID.

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 الخاص بطريقة التنفيذ لاستخدامه في القسم التالي.

تسجيل معالِج الرد التلقائي على الويب

1. إنشاء الملف sdk/webhooks/ActionsOnGoogleFulfillment.yaml، وتحديد معالِجات الإجراء وعنوان URL لطلبات الردّ التلقائي على الويب.

   httpsEndpoint:
     baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
     endpointApiVersion: 2
   handlers:
   - name: questionOnEnterFunc
   - name: fruitSlotValidationFunc