تم إيقاف إجراءات المحادثات نهائيًا في 13 حزيران (يونيو) 2023. لمزيد من المعلومات، يُرجى الاطّلاع على إنهاء إجراءات المحادثة.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Switch to English

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

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

قراءة معلمات intent

عندما يطابق وقت تشغيل "مساعد 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 لتحسين مطابقة الأهداف. يمكنك تحديد ما يصل إلى 1,000 إدخال.

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

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

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

محرّر مضمّن

للتطوير باستخدام محرّر وظائف السحابة الإلكترونية:

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

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

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

إعداد البيئة

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

نزِّل Node.js وثبِّتها.
إعداد واجهة سطر الأوامر الخاصة بإصدار Firebase وإعدادها إذا تعذّر تنفيذ الأمر التالي مع ظهور خطأ EACCES، قد تحتاج إلى تغيير أذونات npm.
```
npm install -g firebase-tools
```
مصادقة أداة Firebase باستخدام حسابك على Google:
```
firebase login
```
ابدأ دليل المشروع الذي حفظت فيه مشروع المهام. سيُطلب منك اختيار ميزات واجهة سطر الأوامر في Firebase التي تريد إعدادها لمشروع المهام. اختر Functions والميزات الأخرى التي قد تريد استخدامها، مثل Firestore، ثم اضغط على Enter للتأكيد والمتابعة:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
يمكنك ربط أداة Firebase بمشروع "المهام" من خلال اختياره باستخدام مفاتيح الأسهم للتنقّل في قائمة المشاريع:

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

بعد اختيار المشروع، تبدأ أداة 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

اختَر ما إذا كنت تريد استخدام 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
```
تستغرق عملية النشر بضع دقائق. بعد اكتمال عملية النقل، سترى نتائج مماثلة لما يلي. ستحتاج إلى عنوان 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>
```
انسخ عنوان URL لتنفيذ الطلب لاستخدامه في القسم التالي.

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

لتسجيل نقطة نهاية دالة Cloud كمعالج للردّ التلقائي على الويب:

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