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

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

تنفيذ عملية التنفيذ باستخدام مكتبة عملاء Node.js في "المهام مع مساعد Google" (Dialogflow)

إنّ مكتبة عملاء Node.js في "المهام مع مساعد Google" هي الطريقة المقترَحة للوصول إلى منصة "المهام مع مساعد Google" والتفاعل معها في حال إنشاء ردّ تلقائي على الويب لتنفيذ الطلب في JavaScript.

مقدمة

مكتبة عملاء Node.js هي مكتبة تنفيذ لـ "المهام مع مساعد Google" توفّر الميزات التالية:

يتوافق التطبيق مع جميع ميزات "المهام مع مساعد Google"، بما في ذلك الردود النصية وردود الوسائط المتعددة التفاعلية، وتسجيل الدخول إلى الحساب، وتخزين البيانات، والمعاملات، والمزيد.
توفر طبقة اصطلاحية من التجريد في JavaScript التي تضم واجهة برمجة تطبيقات HTTP/JSON للردّ التلقائي على الويب.
تتعامل مع التفاصيل المنخفضة المستوى للاتصال بين تنفيذك ومنصة "المهام مع مساعد Google".
يمكن تثبيت هذه الإضافة باستخدام أدوات معروفة لإدارة الحزم، مثل npm أو yarn.
تتيح لك هذه الميزة نشر الرد التلقائي على الويب الخاص بالتنفيذ بسهولة على الأنظمة الأساسية للحوسبة بدون خادم، مثل وظائف السحابة الإلكترونية لبرنامج Firebase أو AWS Lambda. يمكنك أيضًا استضافة الرد التلقائي على الويب الخاص بالتنفيذ على مقدّم خدمة سحابية أو على بيئة ذاتية الاستضافة أو مُدارة ذاتيًا.
يتوافق مع Node.js الإصدار 6.0.0 والإصدارات الأحدث.

يمكنك استخدام مكتبة العملاء مع دمج Dialogflow مع "المهام مع مساعد Google" أو مع حزمة SDK للإجراءات.

للاطّلاع على نماذج الرموز الكاملة لاستخدام مكتبة البرامج، يمكنك الانتقال إلى صفحة النماذج.

عرض مرجع واجهة برمجة التطبيقات

تتم استضافة مرجع واجهة برمجة التطبيقات على صفحة مكتبة عميل Node.js على Google في GitHub.

يمكنك أيضًا إنشاء نسخة محلية من المرجع عن طريق تشغيل الأمر التالي من الدليل الذي نزّلت فيه رمز مكتبة العملاء:

yarn docs

ستكون المستندات التي تم إنشاؤها متاحة في المجلد docs من الدليل الذي نزّلت فيه رمز مكتبة العملاء.

فهم آلية العمل

قبل استخدام مكتبة العملاء، من المفيد فهم كيفية استخدام الرد التلقائي على الويب الخاص بالتنفيذ لمكتبة البرامج لمعالجة طلبات المستخدمين التي ترسلها منصة "المهام مع مساعد Google" إلى تنفيذ طلباتك.

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

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

في ما يلي ملخّص للمهام الرئيسية التي يعالجها الرد التلقائي على الويب الخاص بالتنفيذ بمساعدة مكتبة العميل:

**الشكل 1.** البنية العالية المستوى لمكتبة عميل Node.js

استلام طلبات المستخدم: عندما يُجري مستخدم طلب بحث في "مساعد Google"، يرسل نظام "المهام مع مساعد Google" طلب HTTP إلى الرد التلقائي على الويب الخاص بالتنفيذ. يتضمّن الطلب حمولة بيانات JSON تحتوي على الغرض والبيانات الأخرى مثل النص الأولي لإدخال المستخدم والإمكانيات السطحية لجهاز المستخدم. للحصول على مزيد من الأمثلة على محتوى حمولة JSON، يُرجى الاطّلاع على دليلَي تنسيق الردّ التلقائي على الويب في Dialogflow وتنسيق الردّ التلقائي على الويب للمحادثة.
اكتشاف تنسيق مكالمات إطار العمل: بالنسبة إلى أُطر العمل المتوافقة، ترصد مكتبة العميل تلقائيًا تنسيق طلب إطار العمل (على سبيل المثال، إذا كان الطلب واردًا من إطار عمل الويب السريع أو من AWS Lambda) وتعرِف كيفية التعامل بسهولة مع نظام "المهام مع مساعد Google".
معالجة معالج الخدمة: تمثِّل مكتبة البرامج واجهة برمجة التطبيقات HTTP/JSON الردّ التلقائي على الويب للمحادثة في Dialogflow وحزمة تطوير برامج الإجراءات (SDK) كدالة خدمة. يستخدم الرد التلقائي على الويب الخاص بالتنفيذ الخدمة المناسبة لإنشاء مثيل app عالمي. يعمل مثيل app كمعالج لطلبات HTTP ويفهم البروتوكول الخاص بالخدمة.
معالجة المحادثة: تمثل مكتبة العميل المعلومات لكل محادثة كعنصر Conversation المرفق بالمثيل app. يمكن للردّ التلقائي على الويب الخاص بالتنفيذ استخدام العنصر Conversation لاسترداد البيانات المخزَّنة أو معلومات الحالة من المحادثات المتقاطعة أو إرسال الردود إلى المستخدمين أو إغلاق الميكروفون.
معالجة البرامج الوسيطة: تتيح لك مكتبة العملاء إنشاء البرمجيات الوسيطة لخدمات المحادثة التي تقدّمها، وتتكوّن من وظيفة واحدة أو أكثر تحدّد أنّ مكتبة العملاء يتم تشغيلها تلقائيًا قبل استدعاء معالج الأهداف. يمكن للردّ التلقائي على الويب الخاص بالتنفيذ استخدام البرمجيات الوسيطة لإضافة مواقع أو فئات مساعدة إلى عنصر Conversation.
معالجة معالِج الغرض: تتيح لك مكتبة العملاء تحديد المعالِجات للأغراض التي يفهمها الرد التلقائي على الويب للتنفيذ. بالنسبة إلى Dialogflow، توجّه مكتبة العميل الطلب إلى معالج الغرض الصحيح من خلال التعيين إلى السلسلة الدقيقة لاسم الغرض المحدد في وحدة تحكم Dialogflow. بالنسبة إلى Action SDK، يتم توجيهها استنادًا إلى السمة intent التي تمّ إرسالها من "المهام مع مساعد Google".
إرسال ردود إلى المستخدمين: لإنشاء الردود، يستدعي الرد التلقائي على الويب الخاص بالتنفيذ الدالة Conversation#ask(). يمكن استدعاء الدالة ask() عدة مرات لإنشاء الاستجابة بشكل تزايدي. تضع مكتبة البرامج سلسلة للاستجابة على طلب HTTP يتضمّن حمولة JSON وترسله إلى "المهام مع مساعد Google". تؤدي الدالة close() سلوكًا مماثلاً لسلوك ask()، ولكنّها تغلق المحادثة.

إعداد بيئة التطوير المحلي

قبل تنفيذ الردّ التلقائي على الويب الخاص بالتنفيذ، تأكَّد أولاً من تثبيت مكتبة العميل.

تثبيت مكتبة البرامج

تتمثل أسهل طريقة لتثبيت مكتبة العملاء في بيئة التطوير المحلي في استخدام مدير حزم، مثل npm أو yarn.

لإجراء عملية التثبيت، شغِّل أحد الأوامر التالية من الوحدة الطرفية:

في حال استخدام npm: npm install actions-on-google
في حال استخدام خيط الغزل: yarn add actions-on-google

إعداد مجلدات مشروعك

اعتمادًا على المكان الذي تخطّط فيه لنشر الرد التلقائي على الويب الخاص بالتنفيذ (وظائف السحابة الإلكترونية من Google لمنصة Firebase أو AWS Lambda أو Express)، قد تحتاج إلى إنشاء بنية مجلد مشروع محدّدة لحفظ ملفاتك.

على سبيل المثال، إذا كنت تستخدم دوال السحابة الإلكترونية لبرنامج Firebase، يمكنك إعداد مجلدات المشروع المطلوبة من خلال تنفيذ الخطوات الموضحة في إعداد Node.js وواجهة سطر الأوامر في Firebase وإعداد Firebase لدوال السحابة الإلكترونية. بالنسبة إلى وظائف السحابة الإلكترونية لبرنامج Firebase، عادةً ما تكتب الرد التلقائي على الويب الخاص بالتنفيذ في ملف /functions/index.js.

إنشاء نسخة تطبيق

يستخدم تطبيق "المهام مع مساعد Google" تنسيقات رسائل محدّدة لتبادل الطلبات والردود باستخدام الردّ التلقائي على الويب الخاص بالاستلام، وذلك استنادًا إلى ما إذا كنت تريد إنشاء إجراء حواري باستخدام Dialogflow أو حزمة SDK الخاصة بالإجراءات أو إنشاء إجراء منزلي ذكي.

لتمثيل بروتوكولات الطلب والاستجابة المختلفة هذه، توفر مكتبة العميل ثلاث دوال للخدمة:

يُستخدم بروتوكول الردّ التلقائي على الويب للمحادثة من خلال خدمتَي المحادثة (Dialogflow وحزمة تطوير البرامج (SDK) للإجراءات)، ولكن كل خدمة تضم الرسائل على نحو مختلف.

أنت تستخدم إحدى الخدمات لإنشاء مثيل app. يلخص المثيل app الحالة العامة ومنطق التنفيذ لردك التلقائي على الويب ويعالج التواصل بين "المهام مع مساعد Google" وتنفيذك باستخدام البروتوكول الخاص بالخدمة.

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

لإنشاء مثيل app في الرد التلقائي على الويب الخاص بالتنفيذ، اتّبِع الخطوات التالية:

استدعِ الدالة require() لاستيراد الوحدة "actions-on-google" وتحميل الخدمة التي تريدها. على سبيل المثال، يوضّح المقتطف التالي طريقة تحميل خدمة dialogflow وبعض العناصر المستخدمة لإنشاء الاستجابات، وتعيينها إلى قيمة ثابتة باسم dialogflow:
```
// Import the service function and various response classes
const {
  dialogflow,
  actionssdk,
  Image,
  Table,
  Carousel,
} = require('actions-on-google');
```
هنا، تشير السمة actions-on-google إلى التبعية التي تم تحديدها في ملف package.json في مجلد المشروع (يمكنك الرجوع إلى مثال على ملف package.json للحصول على مثال).

عند الحصول على مثيل app، يمكنك اختياريًا تحديد فئات تمثّل ردودًا منسّقة وأغراضًا للمساعد وغيرها من وظائف "المهام مع مساعد Google" التي تريد استخدامها. للحصول على القائمة الكاملة للفئات الصالحة التي يمكنك تحميلها، راجع المستندات المرجعية وحدتَي الاستجابة للمحادثة ونوايا المساعد.

ملاحظة: يتم تعديل مكتبة البرامج بشكلٍ متكرر. يُرجى الاطّلاع على ملاحظات الإصدار الأخيرة لأي تغييرات في واجهة برمجة التطبيقات.
يمكنك إنشاء مثيل app من خلال طلب الخدمة التي حمّلتها. مثلاً:
```
const app = dialogflow();
```
لإعداد النسخة الافتراضية من app عند الإعداد، يمكنك تقديم العنصر options كوسيطة أولى عند طلب الخدمة. (لمزيد من التفاصيل، يمكنك الاطّلاع على DialogflowOptions.) على سبيل المثال، يوضِّح المقتطف التالي طريقة تسجيل حمولة JSON الأولية من طلب المستخدم أو استجابته من خلال ضبط العلامة { debug: true }:

const app = dialogflow({
  debug: true
});

ضبط المعالجات للأحداث

لمعالجة الأحداث ذات الصلة بـ "المهام مع مساعد Google" التي أنشأتها مكتبة العملاء خلال دورة تفاعل المستخدم مع الإجراء الخاص بك، ستستخدم مكتبة العميل لإنشاء معالِجات لمعالجة طلبات المستخدمين وإرسال الردود.

يمكنك إنشاء دوال تعمل كمعالجات لهذه الأنواع الرئيسية من الأحداث التي تتعرّف عليها مكتبة العملاء:

أحداث الأهداف: إنّ الأهداف هي معرّفات فريدة ترسلها "المهام مع مساعد Google" إلى عملية تنفيذ طلبك عندما يطلب أحد المستخدمين بعض الوظائف المحدّدة. إذا كنت تستخدم Dialogflow، فهذا يتجاوب مع مطابقة Dialogflow لطلب بحث مستخدم مع هدف في وكيل Dialogflow.
أحداث الأخطاء: عند حدوث خطأ في JavaScript أو في مكتبة العميل، يمكنك استخدام دالة catch في مثيل app لمعالجة استثناء الخطأ بشكل مناسب. يجب تنفيذ دالة catch واحدة لمعالجة جميع الأخطاء التي تهم التنفيذ.
الأحداث الاحتياطية: يقع الحدث الاحتياطي عندما يُرسِل المستخدم طلب بحث يتعذّر على "المهام مع مساعد Google" التعرّف عليه. يمكنك استخدام دالة fallback في المثيل app لتسجيل معالج احتياطي عام سيتم تشغيله إذا لم تتم مطابقة أي معالج أهداف مع أي طلب وارد وارد. يجب تنفيذ دالة fallback واحدة لمعالجة جميع الأحداث الاحتياطية. إذا كنت تستخدِم Dialogflow، يمكن أن يؤدي هذا الإجراء إلى تفعيل هدف احتياطي محدَّد في حال عدم مطابقة أي هدف آخر. يجب عليك إنشاء معالج أهداف مطابق لهذا الغرض الاحتياطي.

عندما يرسل المستخدم طلبًا إلى الإجراء الخاص بك، ينشئ المثيل app عنصر Conversation يمثّل جلسة المحادثة تلك. ويتم الوصول إلى هذا الكائن من خلال اسم المتغيّر conv الذي يتم تمريره في دالة معالج الغرض باعتباره وسيطة الدالة الأولى. وستستخدم عادةً الكائن conv في معالِجاتك لإرسال ردّ إلى المستخدم.

يمكن أن تتضمّن طلبات بحث المستخدمين أيضًا مَعلمات يمكن للإجراء الخاص بك استخراجها واستخدامها لتحسين الردود.

إذا كنت تستخدم حزمة تطوير البرامج (SDK)، يمكنك تحديد معلَمات في حزمة الإجراءات. للاطّلاع على مثال حول كيفية استخراج المَعلمات من الأغراض، راجِع نموذج رمز Eliza.
إذا كنت تستخدم Dialogflow، يمكنك الوصول إلى قيم المَعلمات من خلال المتغيّر params. للاطّلاع على أمثلة للتعامل مع الأغراض باستخدام المَعلمات في Dialogflow، اطّلِع على مقالة الوصول إلى المعلَمات والسياقات.

ضبط المعالِجات للأغراض

لضبط المعالج لهدف، عليك استدعاء الدالة intent() لمثيل app. على سبيل المثال، إذا كنت تستخدم Dialogflow، فهذه هي دالة DialogflowApp#intent(). في الوسيطات، حدِّد اسم الغرض وقدِّم دالة المعالِج.

إذا كنت تستخدم Dialogflow، لن تحتاج إلى ضبط معالِجات لكل هدف في وكيلك. بدلاً من ذلك، يمكنك الاستفادة من معالج الاستجابة المدمج في Dialogflow لمعالجة الأهداف تلقائيًا بدون تنفيذ وظائف المعالج الخاصة بك. على سبيل المثال، يمكن تفويض رسالة الترحيب التلقائية إلى Dialogflow بهذه الطريقة.

يعرض المثال التالي معالِجات الغرض من قصدَي "الترحيب" و"الوداع". تأخذ دوال المعالج المجهولة المصدر الوسيطة conv وترسل استجابة سلسلة بسيطة إلى المستخدم من خلال دالة conv.ask():

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('How are you?');
});

app.intent('bye', (conv) => {
  conv.close('See you later!');
});

لاحظ أن الدالة close() تشبه وظيفة ask() باستثناء أنها تغلق الميكروفون وتنتهي المحادثة.

لمعرفة المزيد من المعلومات عن كيفية إنشاء معالِجات للأغراض، يُرجى الاطّلاع على مقالة إنشاء معالج النية.

ضبط المعالجات لأحداث الأخطاء

لضبط المعالجات بحثًا عن الأخطاء، عليك استدعاء الدالة catch() لمثيل app. (على سبيل المثال، إذا كنت تستخدم Dialogflow، فهذه هي دالة DialogflowApp#catch().)

يوضح المثال التالي معالجًا بسيطًا لأخطاء الالتقاط يرسل الخطأ إلى مخرجات وحدة التحكم ويرسل استجابة سلسلة بسيطة مرة أخرى لمطالبة المستخدم عبر الدالة conv.ask():

app.catch((conv, error) => {
  console.error(error);
  conv.ask('I encountered a glitch. Can you say that again?');
});

ضبط معالِجات الأحداث الاحتياطية

لضبط معالِج احتياطي عام في حال عدم مطابقة أيّ هدف للطلب الوارد في التنفيذ، استدعِ الدالة fallback() في مثيل app. (على سبيل المثال، إذا كنت تستخدم Dialogflow، فهذه هي دالة DialogflowApp#fallback().)

يوضّح المثال التالي معالج احتياطي بسيط يرسل استجابة سلسلة بسيطة مرة أخرى لمطالبة المستخدم من خلال الدالة conv.ask():

app.fallback((conv) => {
  conv.ask(`I couldn't understand. Can you say that again?`);
});

إنشاء معالج النية

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

الوصول إلى المَعلمات والسياقات

إذا كنت تستخدم Dialogflow، يمكنك تحديد المَعلمات والسياقات في وكيل Dialogflow للاحتفاظ بمعلومات الحالة والتحكّم في مسار المحادثة.

المعلمات مفيدة لالتقاط الكلمات أو العبارات أو القيم المهمة في طلبات بحث المستخدمين. يعمل Dialogflow على استخلاص المعلَمات المقابلة من طلبات بحث المستخدمين في وقت التشغيل، ويمكنك معالجة قيم المَعلمات هذه في الرد التلقائي على الويب الخاص بالتنفيذ من أجل تحديد كيفية الردّ على المستخدمين.

عندما يرسل المستخدم طلبًا إلى الإجراء الخاص بك، ينشئ مثيل DialogflowApp كائن parameters يمثّل قيم المعلَمات التي استخرجها Dialogflow من هذا الطلب. ويتم الوصول إلى هذا الكائن باستخدام اسم المتغيّر params.

يوضّح المقتطف التالي طريقة الوصول إلى السمة name من عنصر params عندما يرسل المستخدم طلبًا:

app.intent('Default Welcome Intent', (conv, params) => {
  conv.ask(`How are you, ${params.name}?`);
});

إليك مقتطف بديل يؤدي الإجراء نفسه. تُجري الأقواس المعقوفة ({}) تدمير JavaScript لأخذ السمة name من الكائن parameters واستخدامها كمتغير محلي:

app.intent('Default Welcome Intent', (conv, {name}) => {
  conv.ask(`How are you, ${name}?`);
});

في المقتطف التالي، يكون اسم المعلمة هو full-name، ولكن يتم إلغاء ترابطه وتخصيصه لمتغير محلي يُسمى name:

app.intent('Default Welcome Intent', (conv, {'full-name': name}) => {
  conv.ask(`How are you, ${name}?`);
});

السياقات هي ميزة متقدّمة في Dialogflow. يمكنك استخدام السياقات لإدارة حالة المحادثة وتدفقها وتشعّبها. توفّر مكتبة العملاء إمكانية الوصول إلى سياق من خلال الكائن DialogflowConversation#contexts. يوضّح المقتطف التالي كيفية إعداد سياق آليًا في الرد التلقائي على الويب الخاص بالتنفيذ وكيفية استرداد عنصر السياق:

app.intent('intent1', (conv) => {
  const lifespan = 5;
  const contextParameters = {
    color: 'red',
  };
  conv.contexts.set('context1', lifespan, contextParameters);
  // ...
  conv.ask('...');
});

app.intent('intent2', (conv) => {
  const context1 = conv.contexts.get('context1');
  const contextParameters = context1.parameters;
  // ...
  conv.ask('...');
});

app.intent('intent3', (conv) => {
  conv.contexts.delete('context1');
  // ...
  conv.ask('...');
});

الوصول إلى نتائج أهداف المساعد

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

مثال: نتائج مساعد التأكيد

يتيح لك هدف مساعد التأكيد طلب تأكيد بنعم/لا من المستخدم والحصول على الإجابة الناتجة. يوضّح المقتطف التالي كيف يمكن للردّ التلقائي على الويب تخصيص ردّه استنادًا إلى النتائج التي يعرضها قصد مساعد التأكيد. للحصول على مثال أكثر اكتمالاً، راجِع المستندات المرجعية للفئة Confirmation.

// Create Dialogflow intent with `actions_intent_CONFIRMATION` event
app.intent('get_confirmation', (conv, input, confirmation) => {
  if (confirmation) {
    conv.close(`Great! I'm glad you want to do it!`);
  } else {
    conv.close(`That's okay. Let's not do it now.`);
  }
});

مثال: نتائج لوحة العرض الدوّارة

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

app.intent('carousel', (conv) => {
  conv.ask('Which of these looks good?');
  conv.ask(new Carousel({
    items: {
      car: {
        title: 'Car',
        description: 'A four wheel vehicle',
        synonyms: ['automobile', 'vehicle'],
      },
      plane: {
        title: 'Plane',
        description: 'A flying machine',
        synonyms: ['aeroplane', 'jet'],
      }
    }
  }));
});

// Create Dialogflow intent with `actions_intent_OPTION` event
app.intent('get_carousel_option', (conv, input, option) => {
  if (option === 'one') {
    conv.close(`Number one is a great choice!`);
  } else {
    conv.close(`Number ${option} is a great choice!`);
  }
});

ضبط عناصر الرد على المحادثة

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

مثال: صورة

يعرض المقتطف التالي كيف يمكن للردّ التلقائي على الويب الخاص بالتنفيذ إرسال Image في ردّ سيتم إرفاقه تلقائيًا برد BasicCard من خلال المكتبة:

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('Hi, how is it going?');
  conv.ask(`Here's a picture of a cat`);
  conv.ask(new Image({
    url: '/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg',
    alt: 'A cat',
  }));
});

إجراء استدعاءات دوال غير متزامنة

صُممت مكتبة عميل Node.js في "المهام مع مساعد Google" للبرمجة غير المتزامنة. ويمكن أن يعرض معالج النية وعدًا يتم حلّه عند انتهاء الردّ التلقائي على الويب الخاص بالتنفيذ.

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

في هذا المثال، نستخدم واجهة برمجة تطبيقات مزيفة للحصول على بيانات الطقس.

/**
 * Make an external API call to get weather data.
 * @return {Promise<string>}
 */
const forecast = () => {
  // ...
};

app.intent('Default Welcome Intent', (conv) => {
  return forecast().then((weather) => {
    conv.ask('How are you?');
    conv.ask(`Today's weather is ${weather}.`);
  });
});

لمقتطف الرمز المبسّط التالي التأثير نفسه، ولكنه يستخدم ميزة await async التي تم تقديمها في ECMA 2017 (الإصدار 8 من Node.js). لاستخدام هذا الرمز مع دوال السحابة الإلكترونية لمنصة Firebase، احرص على استخدام الإصدار الصحيح من firebase-tools وضبط الإعدادات الصحيحة.

app.intent('Default Welcome Intent', async (conv) => {
  const weather = await forecast();
  conv.ask('How are you?');
  conv.ask(`Today's weather is ${weather}.`);
});

تخزين بيانات المحادثات

تسمح مكتبة العملاء بالرد التلقائي على الويب الخاص بالتنفيذ من أجل حفظ البيانات في المحادثات لاستخدامها في المستقبل. تشمل الكائنات الرئيسية التي يمكنك استخدامها لتخزين البيانات ما يلي:

DialogflowConversation#data أو ActionsSdkConversation#data: يحفظ البيانات بتنسيق JSON لمدة جلسة محادثة واحدة بين المستخدم والإجراء الخاص بك.
Conversation#user.storage: يحفظ البيانات بتنسيق JSON عبر جلسات محادثة متعددة.

يوضّح المقتطف التالي كيفية تخزين الرد التلقائي على الويب الخاص بالتنفيذ للبيانات في موقع عشوائي حددته (someProperty) وإرفاقها بالكائن Conversation#user.storage. للحصول على مثال أكثر اكتمالاً، راجِع المستندات المرجعية للفئة Conversation#user.storage.

app.intent('Default Welcome Intent', (conv) => {
  conv.user.storage.someProperty = 'someValue';
  conv.ask('...');
});

ويمكنك استخدام الكائن Conversation#user للحصول على معلومات عن المستخدم، بما في ذلك معرِّف السلسلة والمعلومات الشخصية. تتطلّب بعض الحقول، مثل conv.user.name.display وconv.user.email، طلب conv.ask(new Permission) لـ NAME وconv.ask(new SignIn) لتسجيل الدخول بحساب Google على التوالي.

const {Permission} = require('actions-on-google');
app.intent('Default Welcome Intent', (conv) => {
  if (conv.user.last.seen) {
    conv.ask('Welcome back! How are you?');
  } else {
    conv.ask('Nice to meet you! How are you doing?');
  }
});

app.intent('permission', (conv) => {
  conv.ask(new Permission({
    context: 'To greet you personally',
    permissions: 'NAME',
  }));
});

// Create Dialogflow intent with `actions_intent_PERMISSION` event
app.intent('get_permission', (conv, input, granted) => {
  if (granted) {
    conv.close(`Hi ${conv.user.name.display}!`);
  } else {
    // User did not grant permission
    conv.close(`Hello!`);
  }
});

التوسع باستخدام البرمجيات الوسيطة

يمكنك توسيع مكتبة العملاء عبر البرمجيات الوسيطة.

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

تعرض خدمتا Dialogflow وحزمة تطوير برامج (SDK) دالة app.middleware() تتيح لك إضافة سمات أو فئات مساعدة إلى المثيل Conversation.

يوضح المقتطف التالي مثالاً على كيفية استخدام البرمجيات الوسيطة:

class Helper {
  constructor(conv) {
    this.conv = conv;
  }

  func1() {
    this.conv.ask(`What's up?`);
  }
}

app.middleware((conv) => {
  conv.helper = new Helper(conv);
});

app.intent('Default Welcome Intent', (conv) => {
  conv.helper.func1();
});

تصدير تطبيقك

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

توضّح المقتطفات التالية كيفية تصدير app خلال أوقات تشغيل مختلفة:

مثال: وظائف السحابة الإلكترونية لبرنامج Firebase

const functions = require('firebase-functions');
// ... app code here
exports.fulfillment = functions.https.onRequest(app);

مثال: محرِّر مضمّن في Dialogflow

const functions = require('firebase-functions');

// ... app code here

// Exported function name must be 'dialogflowFirebaseFulfillment'
exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);

مثال: خادم Express تتم استضافته ذاتيًا (بسيط)

const express = require('express');
const bodyParser = require('body-parser');  

// ... app code here

express().use(bodyParser.json(), app).listen(3000);

مثال: خادم Express تتم استضافته ذاتيًا (مسارات متعددة)

const express = require('express');
const bodyParser = require('body-parser');

// ... app code here

const expressApp = express().use(bodyParser.json());

expressApp.post('/fulfillment', app);

expressApp.listen(3000);

مثال: بوابة AWS Lambda API

// ... app code here

exports.fulfillment = app;