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

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

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

المقدمة

مكتبة برامج Node.js هي مكتبة لتوصيل الطلبات إلى المهام في Google توفّر الميزات التالية:

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

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

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

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

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

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

yarn docs

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

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

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

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

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

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

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

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

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

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

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

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

لتثبيت التطبيق، شغِّل أحد الأوامر التالية في الوحدة الطرفية:

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

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

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

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

إنشاء مثيل تطبيق

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

لتمثيل بروتوكولات الطلب وطلبات الاستجابة المختلفة، توفّر مكتبة البرامج ثلاث وظائف خدمة:

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

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

يمكنك ضبط خصائص مثيل المثيل app واستدعاء أساليبه لتوجيه سلوك الرد التلقائي على الويب بطريقة التنفيذ. ويمكنك أيضًا توصيل مثيل app بسهولة ببيئة حوسبة بدون خادم، مثل Cloud Functions for 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 التي تم إنشاؤها من خلال "مكتبة العملاء" أثناء مراحل تفاعل المستخدم مع الإجراء، ستستخدم مكتبة البرامج لإنشاء معالجات لمعالجة طلبات المستخدمين وإرسال الردود اللاحقة.

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

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

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

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

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

ضبط معالجات intent

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

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

يوضّح المثال التالي معالجات intent هدفَي "مرحبًا" و"وداعًا". تأخذ دوال المعالج المجهولة وسيطة 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() باستثناء أنّها تغلق الميكروفون وانتهت المحادثة.

للاطّلاع على مزيد من المعلومات حول كيفية إنشاء معالجات لأهداف intent، يمكنك الاطّلاع على إنشاء معالج intent.

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

لضبط معالِجات الأخطاء، اطلب الدالة 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?`);
});

إنشاء معالج intent

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

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

إذا كنت تستخدم 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" عندما تريد أن يتعامل "مساعد 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',
  }));
});

إجراء طلبات وظائف غير متزامنة

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

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

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

/**
 * 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}.`);
  });
});

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

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) للاسم و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 وإضافة وظائف أخرى.

تعرِض حِزم تطوير البرامج (SDK) في Dialogflow و"الإجراءات" دالة 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

// ... app code here

exports.fulfillment = app;