إنشاء "مهام" لخدمة "مساعد Google" باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ "المهام" (المستوى 1)

1. نظرة عامة

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

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

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

ما الذي ستقوم ببنائه

في هذا الدرس التطبيقي حول الترميز، يمكنك إنشاء إجراء بسيط باستخدام الدوال التالية:

• يتم الرد على المستخدمين من خلال رسالة ترحيب.
• طرح سؤال على المستخدمين والرد بشكل مناسب على اختيار المستخدم
• يتم توفير شرائح الاقتراحات التي يمكن للمستخدمين النقر عليها لتقديم إدخالات.
• لتعديل رسالة الترحيب إلى المستخدم استنادًا إلى ما إذا كان مستخدمًا مكرّر الزيارة

عند الانتهاء من هذا الدرس التطبيقي حول الترميز، سيكون للمهمة مسار المحادثة التالي (يمثّل النص بجانب الميكروفون إدخال المستخدم، بينما يشير النص بجانب المتحدّث إلى ردّ الإجراء):

المُعطيات

• كيفية إنشاء مشروع في وحدة تحكّم "المهام"
• كيفية استخدام أداة التفاعلات لنشر مشروع Action الخاص بك وسحبه بين وحدة تحكم "المهام" ونظام الملفات على الجهاز
• كيفية إرسال طلب إلى المستخدم بعد استدعاء الإجراء الخاص بك
• كيفية معالجة إدخالات المستخدم وعرض رد
• كيفية اختبار المهمّة في "محاكي المهام"
• كيفية تنفيذ عملية التنفيذ باستخدام محرِّر Cloud Functions

المتطلبات

يجب أن تتوفّر الأدوات التالية في بيئتك:

• IDE أو محرِّر نصوص من اختيارك
• وحدة طرفية لتشغيل أوامر واجهة الأوامر Node.js وnpm
• متصفِّح ويب، مثل Google Chrome

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

2. إعداد

توضّح الأقسام التالية كيفية إعداد بيئة التطوير وإنشاء مشروع "المهام".

التحقّق من إعدادات أذونات Google

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

لتفعيل الأذونات، اتّبِع الخطوات التالية:

1. الانتقال إلى عناصر التحكم في النشاط
2. سجِّل الدخول باستخدام حسابك على Google إذا لم يسبق لك فعل ذلك.
3. تفعيل الأذونات التالية:

• النشاط على الويب وفي التطبيقات
• ضمن الويب و النشاط على التطبيقات، ضَع علامة في مربّع الاختيار تضمين سجلّ Chrome والأنشطة التي تتم على المواقع والتطبيقات والأجهزة التي تستخدم خدمات Google**.**

إنشاء مشروع على "المهام مع مساعد Google"

مشروع "المهام" هو حاوية للإجراء الخاص بك.

لإنشاء مشروع "المهام" الخاص بهذا الدرس التطبيقي حول الترميز، اتّبِع الخطوات التالية:

1. افتح وحدة تحكّم الإجراءات.
2. انقر على مشروع جديد.
3. أدخِل اسم المشروع، مثل actions-codelab. (الاسم كمرجع داخلي لك. يمكنك لاحقًا ضبط اسم خارجي لمشروعك).

4. انقر على إنشاء مشروع.
5. في شاشة ما نوع الإجراء الذي تريد إنشاءه؟، اختَر البطاقة مخصّصة.
6. انقر على التالي.
7. في شاشة كيف تريد إنشاءه؟، اختَر بطاقة مشروع فارغ.
8. انقر على بدء المبنى.

حفظ رقم تعريف المشروع للإجراء الخاص بك

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

لاسترداد رقم تعريف المشروع، اتّبِع الخطوات التالية:

1. في وحدة تحكّم المهام، انقر على النقاط الرأسية الثلاث (أدخِل الرمز هنا).
2. انقر على إعدادات المشروع.

3. انسخ رقم تعريف المشروع**.**

ربط حساب فوترة

إذا لم يكن لديك حساب فوترة، عليك إنشاء حساب فوترة وربطه بمشروعك في Google Cloud لنشر عملية التنفيذ لاحقًا باستخدام Cloud Functions.

لربط حساب فوترة بمشروعك، اتّبع الخطوات التالية:

1. انتقِل إلى صفحة فوترة Google Cloud Platform.
2. انقر على إضافة حساب فوترة أو إنشاء حساب.
3. أدخِل معلومات الدفع.
4. انقر على بدء الفترة التجريبية المجانية أو إرسال وتفعيل الفوترة.
5. انتقِل إلى صفحة فوترة Google Cloud Platform.
6. انقر على علامة التبويب مشاريعي.
7. انقر على النقاط الثلاث ضمن الإجراءات بجانب مشروع "المهام" الخاص بالدرس التطبيقي حول الترميز.
8. انقر على تغيير الفوترة.
9. في القائمة المنسدلة، اختَر حساب الفوترة الذي ضبطته.
10. انقر على ضبط الحساب.

لتجنُّب تحمُّل الرسوم، اتّبِع الخطوات الواردة في قسم "تنظيف مشروعك" في نهاية هذا الدرس التطبيقي حول الترميز.

تثبيت واجهة سطر أوامر Gactions

في هذا الدرس التطبيقي حول الترميز، يمكنك استخدام أداة واجهة سطر أوامر gactions لمزامنة مشروع "المهام" بين وحدة تحكّم "المهام" ونظام الملفات على الجهاز.

المصطلح الرئيسي:

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

لتثبيت واجهة سطر الأوامر الخاصة بـ Gactions، اتّبِع التعليمات الواردة في تثبيت أداة سطر أوامر gactions.

تنزيل مشروع المهام

ابدأ في تطوير الإجراء الخاص بك من خلال تنزيل مشروع "المهام" الخاص بك من وحدة تحكّم "المهام".

لتنزيل مشروع "المهام"، اتّبِع الخطوات التالية:

1. لإنشاء دليل جديد والتغيير إليه، شغِّل الأوامر التالية:

mkdir myproject
cd myproject

2. لنسخ إعدادات مشروع "الإجراءات" إلى نظام الملفات على الجهاز، شغِّل الأمر التالي:

gactions pull --project-id <projectID>

فهم هيكل الملف

يتم تمثيل مشروع "الإجراءات" الذي تنزّله من وحدة تحكّم "المهام" في بنية ملف YAML. توضح الصورة التالية تمثيلاً عالي المستوى لبنية الملف:

وتتكوّن بنية الملف مما يلي:

• actions/: لتمثيل مشروعك على "المهام" يطلب النظام actions.yaml عند استدعاء الإجراء، ثم يستدعي ملف custom/global/actions.intent.MAIN.yaml.
• custom/: الدليل الذي ستعمل فيه لتعديل الإجراء الخاص بك
• global/: يحتوي هذا الدليل على أهداف النظام التي تضيفها المنصة إلى مشروعك تلقائيًا. ستتعلّم المزيد عن أهداف النظام لاحقًا في هذا الدرس التطبيقي حول الترميز.
• manifest.yaml: ملف يحتوي على معلومات قابلة للنقل أو غير خاص بمشروع معيّن ويمكن نقله بين المشاريع
• settings/: يمثل هذا الحقل إعدادات مشروع في "الإجراءات"، مثل الاسم المعروض واللغة التلقائية والفئة.

3- بدء محادثة

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

عليك تعديل الاستدعاء الرئيسي لتحديد ما يحدث بعد استدعاء المستخدم للإجراء الخاص بك.

المصطلح الرئيسي:

• الاستدعاء الرئيسي: نقطة دخول يمكن للمستخدمين من خلالها بدء محادثات مع الإجراء الخاص بك. عندما يقول المستخدمون عبارة مشابهة لـ "Ok Google، أريد التحدّث إلى <اسم العرض>"، يؤدي الاستدعاء الرئيسي إلى ظهور المستخدم ويردّ عليه.

يقدّم الإجراء الخاص بك طلبًا عامًا تلقائيًا عند تشغيل الاستدعاء ("ابدأ إنشاء الإجراء الخاص بك من خلال تحديد الاستدعاء الرئيسي").

المصطلح الرئيسي:

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

يمكنك استخدام طلب خاص، Canvas، لعرض مرئيات بملء الشاشة للمستخدم. لمزيد من المعلومات حول Canvas، يُرجى الاطّلاع على مستندات لوحة الرسم التفاعلية.

في القسم التالي، يمكنك تخصيص الطلب لاستدعاءك الرئيسي في ملف custom/global/actions.intent.MAIN.yaml.

إعداد الاستدعاء الرئيسي

يمكنك تعديل طلب الاستدعاء الرئيسي في ملف "actions.intent.MAIN.yaml".

لتعديل الطلب الذي يرسله الإجراء مرة أخرى إلى المستخدم عند استدعاء الإجراء، اتّبِع الخطوات التالية:

1. افتح "custom/global/actions.intent.MAIN.yaml" في محرِّر النصوص.
2. استبدِل النص في الحقل speech (Start building your action...) برسالة الترحيب التالية: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of 
                Gryffinberg! Based on your clothes, you are not from around these lands. 
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. احفظ الملف.

اختبِر الاستدعاء الرئيسي في المحاكي

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

للحصول على أحدث المعلومات عن استخدام مُحاكي وحدة تحكّم المهام، أو إذا واجهت أي مشاكل في الخطوات التالية، يمكنك الاطّلاع على صفحة المحاكي.

عند استدعاء الإجراء، من المفترض أن يستجيب الآن للطلب المخصّص الذي أضفته ("تحية رائعة أيها مغامر!...").

يمكنك استخدام الأمر gactions deploy preview لاختبار الإجراء الخاص بك في وحدة التحكّم بدون تحديث إصدار مشروع "المهام". عند تشغيل هذا الأمر، لا يتم نشر أي من التغييرات التي تجريها في نظام الملفات المحلي إلى الإصدارات المنشورة من مشروع الإجراءات، ولكن يمكنك اختبارها على إصدار المعاينة.

لاختبار الاستدعاء الرئيسي للإجراء في المحاكي، اتّبِع الخطوات التالية:

1. لنشر مشروعك على وحدة تحكّم المهام من أجل الاختبار، شغِّل الأمر التالي في الوحدة الطرفية:

gactions deploy preview

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

يُفترض أن تتلقى نتيجة تبدو كما يلي:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. انسخ عنوان URL المقدَّم والصقه في متصفِّح.
3. لاستدعاء الإجراء في المحاكي، اكتب Talk to my test app في حقل إدخال واضغط على Enter.

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

وبدلاً من ذلك، يمكنك النقر على رمز الميكروفون وقول "التحدّث إلى تطبيقي التجريبي" لاستدعاء الإجراء.

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

عرض سجلات الأحداث

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

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

إذا نقرت على السهم المتّجه للأسفل بجانب Talk to my test app في سجلّ الأحداث، يمكنك الاطّلاع على الأحداث، التي تم ترتيبها ترتيبًا زمنيًا، والتي حدثت في ذلك الدور من المحادثة:

• userInput: يتوافق مع الإدخال الذي أدخله المستخدم ("التحدّث إلى تطبيقي التجريبي")
• interactionMatch: يتوافق مع استجابة الاستدعاء الرئيسية للإجراء الخاص بك، والتي تم تشغيلها من خلال إدخال المستخدم. إذا وسعت هذا الصف عن طريق النقر على السهم، يمكنك الاطّلاع على الطلب الذي أضفته للاستدعاء الرئيسي (A wondrous greeting, adventurer!...)
• endConversation: يتجاوب مع عملية النقل المحدّدة في هدف Main invocation، الذي ينهي المحادثة حاليًا. ستتعرَّف على المزيد من المعلومات حول عمليات الانتقال في القسم التالي من هذا الدرس التطبيقي حول الترميز.

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

4. إنشاء محادثة الإجراء الخاص بك

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

المصطلحات الرئيسية:

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

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

على سبيل المثال، تخيل إجراءً افتراضيًا يوفر للمستخدم حقائق عن الحيوانات. عندما يستدعي المستخدم هذا الإجراء، تتم مطابقة الغرض من Main invocation وتؤدي عملية الانتقال إلى مشهد اسمه Facts. يؤدّي هذا الانتقال إلى تفعيل مشهد Facts، الذي يُرسِل الطلب التالي إلى المستخدم: Would you like to hear a fact about cats or dogs? ضِمن مشهد Facts، نجد عبارة مخصّصة حسب النية بالشراء تُسمّى Cat، ويحتوي على عبارات تدريب يمكن للمستخدم قولها عند سماع حقيقة عن القطط، مثل "أريد سماع حقيقة عن قطة" أو "قطة". عندما يطلب المستخدم سماع حقيقة حول قطة، تتم مطابقة القصد من Cat، ويؤدي ذلك إلى الانتقال إلى مشهد اسمه Cat fact.. يتم تفعيل مشهد Cat fact وإرسال طلب إلى المستخدم يتضمّن حقيقة حول قطة.

الشكل 1. مسار المحادثة النموذجي في إجراء تم إنشاؤه باستخدام حزمة تطوير البرامج (SDK) لـ "المهام"

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

الانتقال من الاستدعاء الرئيسي إلى المشهد

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

لإنشاء هذا المشهد وإضافة تأثير انتقال إليه، اتبع الخطوات التالية:

1. افتح "custom/global/actions.intent.MAIN.yaml" في محرِّر النصوص.
2. استبدِل النص في حقل transitionToScene (actions.scene.END_CONVERSATION) بما يلي: transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

يؤدي هذا الإجراء إلى انتقال الإجراء الخاص بك من الاستدعاء الرئيسي إلى مشهد Start.

3. احفظ الملف.
4. في الوحدة الطرفية، أنشِئ دليل scenes جديدًا في دليل custom:

mkdir custom/scenes 

5. أنشِئ ملفًا جديدًا باسم "Start.yaml" في الدليل scenes، ويمثّل المشهد start في الإجراء الخاص بك:

touch custom/scenes/Start.yaml 

6. افتح "Start.yaml" في محرِّر النصوص.
7. الصق الرمز التالي في ملف Start.yaml:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

في رمز الملف Start.yaml، هناك حقل باسم onEnter، وهو المرحلة الأولى التي يتم تشغيلها في مراحل المشهد.

المصطلحات الرئيسية:

• OnEnter: المسرح الذي يتم تشغيله عند تفعيل مشهد. وتحدّد السمة OnEnter ما يحدث عند دخول المستخدم إلى المشهد.

في هذه الحالة، تتم إضافة الطلب (Before you continue on your quest...) إلى قائمة انتظار الطلبات عندما يدخل المستخدم لأول مشهد في Start.

المصطلحات الرئيسية:

• قائمة انتظار الطلبات: يتم إلحاق الطلبات ببعضها في قائمة انتظار الطلبات. قبل أن يتمكّن المستخدم من الردّ، يعرض "مساعد Google" للمستخدم جميع الطلبات في قائمة انتظار الطلبات.

إضافة شرائح الاقتراحات

توفّر شرائح الاقتراحات اقتراحات يمكن للمستخدم النقر عليها ويعالجها الإجراء كإدخال للمستخدم. في هذا القسم، تضيف شريحتَي الاقتراحات Yes وNo اللتين تظهران أسفل الطلب الذي ضبطته للتو (Before you continue on your quest, would you like your fortune told?) لتوفير الدعم للمستخدمين على الأجهزة المزوّدة بشاشات.

لإضافة شرائح اقتراحات إلى طلب مشهد Start، اتّبِع الخطوات التالية:

1. عدِّل الرمز في Start.yaml ليتطابق مع مقتطف الرمز التالي، والذي يتضمّن الرمز لضبط شرائح الاقتراحات:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. احفظ الملف.

اختبِر "الحركة" في المحاكي

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

لاختبار المهمّة في المحاكي، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، شغِّل الأمر التالي:

gactions deploy preview

يُفترض أن تتلقى نتيجة تبدو كما يلي:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. انسخ عنوان URL المقدَّم والصقه في متصفِّح.
3. انقر على اختبار للانتقال إلى المحاكي.
4. اكتب Talk to my test app في حقل إدخال واضغط على Enter. من المفترض أن يستجيب الإجراء الخاص بك للطلب Main invocation وإشعار Start الذي تمت إضافته، وهو "قبل متابعة مهمتك، هل تريد تلقّي تنبؤات عن حظك؟"، مع عرض شرائح الاقتراحات.

توضح لقطة الشاشة التالية هذا التفاعل:

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

5. انقر على شريحة اقتراح نعم أو لا للرد على رسالة الطلب. (يمكنك أيضًا قول "نعم" أو "لا" أو إدخال Yes أو No في حقل الإدخال).

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

المصطلحات الرئيسية:

• NO_MATCH: هدف شامل تتم مطابقته عندما يقول المستخدم شيئًا لا يمكن مطابقته مع هدف آخر في الإجراء الخاص بك.
• نية النظام: هي هدف يتم ضبطه تلقائيًا ويتعامل مع أحداث النظام الشائعة، مثل حالة عدم تقديم المستخدِم للإدخال. تُعدّ السمة NO_MATCH والهدف المرتبط بالاستدعاء الرئيسي أمثلة على نوايا النظام.

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

إضافة yes وno هدفًا

الآن بعد أن تمكّن المستخدمون من الإجابة عن السؤال الذي يطرحه الإجراء، يمكنك ضبط الإجراء الخاص بك لفهم إجراءات المستخدمين. الردود ("نعم" أو "لا"). في الأقسام التالية، تُنشئ أهدافًا مخصّصة تتم مطابقتها عندما يقول المستخدم "نعم" أو "لا"، وتضيف هذه الأهداف إلى مشهد Start.

إنشاء هدف "yes"

لإنشاء هدف yes، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، أنشِئ دليلاً جديدًا باسم intents في دليل custom:

mkdir custom/intents 

2. أنشئ ملفًا جديدًا باسم yes.yaml في دليل intents:

touch custom/intents/yes.yaml

3. افتح "yes.yaml" في محرِّر النصوص.
4. الصق مقتطف الرمز التالي الذي يحتوي على عبارات التدريب في yes.yaml:

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. احفظ الملف.

إضافة هدف واحد (yes) إلى مشهد واحد (Start)

أما الآن، فيمكن أن يتعرّف الإجراء على الحالات التي يعبّر فيها المستخدِم عن نية "نعم". يمكنك إضافة الطلب المخصص حسب النية بالشراء yes إلى المشهد Start، لأنّ المستخدم يستجيب لطلب Start ("قبل متابعة مهمتك، هل تريد الاطّلاع على حظك؟").

لإضافة هذا الجمهور المخصّص حسب النية بالشراء إلى المشهد Start، اتّبِع الخطوات التالية:

1. افتح "custom/scenes/Start.yaml" في محرِّر النصوص.
2. أضِف المعالِج intentEvents وyes إلى نهاية ملف Start.yaml:

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

عند مطابقة هدف "yes"، تتم إضافة الطلب "يعتمد مستقبلك على العنصر الذي تختار استخدامه في مهمتك..." إلى قائمة انتظار الطلبات. ينتقل مشهد Start بعد ذلك إلى مشهد نظام actions.scene.END_CONVERSATION الذي يعرض الطلبات في قائمة انتظار الطلبات وينهي المحادثة.

اختبار هدف "yes" في المحاكي

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

لاختبار هذا النية في المحاكي، اتبع الخطوات التالية:

1. في الوحدة الطرفية، شغِّل الأمر التالي:

gactions deploy preview

يُفترض أن تتلقى نتيجة تبدو كما يلي:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. انسخ عنوان URL المقدَّم والصقه في متصفِّح.
3. انقر على اختبار للانتقال إلى المحاكي.
4. لاختبار الإجراء في المحاكي، اكتب Talk to my test app في حقل الإدخال، ثم اضغط على Enter.
5. اكتب Yes في حقل إدخال واضغط على Enter. أو انقر على شريحة الاقتراح نعم بدلاً من ذلك.

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

إنشاء هدف "no"

يمكنك الآن إنشاء intent في no ليتمكّن الإجراء من فهم المستخدم والاستجابة له في حال عدم رغبته في سماع حظه.

لإنشاء هذا الهدف، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، أنشِئ ملفًا جديدًا باسم no.yaml في دليل intents:

touch custom/intents/no.yaml

2. افتح "no.yaml" في محرِّر النصوص.
3. الصِق العبارات التدريبية التالية في ملف no.yaml:

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. احفظ الملف.

إضافة هدف واحد (no) إلى مشهد واحد (Start)

أما الآن، فيمكن أن يتعرّف المستخدم على كلمة "لا" أو عبارة مشابهة لـ "لا"، مثل "لا". يجب إضافة الإجراء المخصص حسب النية بالشراء no إلى المشهد Start لأن المستخدم يستجيب لطلب Start ("قبل متابعة مهمتك، هل تريد سماع طالعك؟").

لإضافة هذا الهدف للمشهد Start، يُرجى اتّباع الخطوات التالية:

1. افتح "custom/scenes/Start.yaml" في محرِّر النصوص.
2. أضِف معالج no التالي أسفل معالج yes في Start.yaml:

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. احفظ الملف.

اختبار هدف "no" في المحاكي

في هذه المرحلة، يدرك الإجراء الخاص بك الحالات التي لا يرغب المستخدم في سماع حظه فيها ويعرض الاستجابة المناسبة.

لاختبار هذا النية في المحاكي، اتبع الخطوات التالية:

1. في الوحدة الطرفية، شغِّل الأمر التالي:

gactions deploy preview

يُفترض أن تتلقى نتيجة تبدو كما يلي:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. انسخ عنوان URL المقدَّم والصقه في متصفِّح.
3. انقر على اختبار للانتقال إلى المحاكي.
4. اكتب Talk to my test app في حقل إدخال واضغط على Enter.
5. اكتب No في حقل إدخال واضغط على Enter. ويمكنك بدلاً من ذلك النقر على شريحة الاقتراح No.

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

5- تنفيذ عملية التنفيذ

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

المصطلح الرئيسي:

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

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

في هذا الدرس التطبيقي، يمكنك استخدام محرِّر Cloud Functions لتعديل رمز التنفيذ ونشره.

المصطلح الرئيسي:

• محرِّر Cloud Functions: هو محرّر مُدمَج لمشاريع "المهام" يمكنك استخدامه لتعديل رمز التنفيذ ونشره باستخدام الوظائف السحابية لبرنامج Firebase.

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

تعزيز نجاحك

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

لإضافة هذا المنطق إلى التنفيذ، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، تأكَّد من توفُّر الدليل الجذري لمشروعك وأنشِئ دليل webhooks جديدًا:

mkdir webhooks 

2. أنشئ ملفًا جديدًا باسم ActionsOnGoogleFulfillment.yaml في دليل webhooks:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. افتح "ActionsOnGoogleFulfillment.yaml" في محرِّر النصوص.
4. إضافة معالج greeting ومحتوى inlineCloudFunction إلى ملف ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

يحدّد ملف ActionsOnGoogleFulfillment.yaml معالِجات الردّ التلقائي على الويب (مثل معالِج greeting) ويطلب من الإجراء استخدام دوال Cloud كنقطة نهاية للردّ التلقائي على الويب.

5. أنشِئ دليل ActionsOnGoogleFulfillment جديدًا في الدليل webhooks:

mkdir webhooks/ActionsOnGoogleFulfillment

6. أنشئ ملفًا جديدًا باسم index.js في دليل ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. افتح "index.js" في محرِّر النصوص.
8. أضِف الرمز التالي إلى index.js:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

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

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});


exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

يحدّد هذا الرمز معالِج greeting الذي يرسل رسالة الترحيب المناسبة إلى

المستخدم.

9. احفظ الملف.
10. أنشئ ملفًا جديدًا باسم package.json في دليل ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/package.json

يحدّد ملف package.json التبعيات والبيانات الوصفية الأخرى للردّ التلقائي على الويب.

11. افتح "package.json" في محرِّر النصوص.
12. انسخ الرمز من مستودع GitHub والصقه في ملف package.json.
13. احفظ الملف.

فهم الرمز البرمجي

عند تنفيذ هذا الإجراء، يستخدم مكتبة تنفيذ "المهام مع مساعد Google" لـ Node.js، وهو يستجيب لطلبات HTTP الواردة من "مساعد Google".

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

تعديل الاستدعاء الرئيسي لتشغيل ردّ تلقائي على الويب

الآن بعد أن حددت الدالة greeting، يمكنك ضبط معالِج أحداث greeting في الغرض الرئيسي من الاستدعاء حتى يعرف الإجراء الخاص بك استدعاء هذه الدالة عندما يستدعي المستخدم الإجراء الخاص بك.

لضبط الإجراء الخاص بك على طلب معالِج greeting الجديد، اتّبِع الخطوات التالية:

1. افتح "custom/global/actions.intent.MAIN.yaml" في محرِّر النصوص.
2. استبدِل الرمز في actions.intent.MAIN.yaml بالرمز التالي:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. احفظ الملف.

الآن، عندما يتطابق الغرض الرئيسي من الاستدعاء، يتم استدعاء معالج الردّ التلقائي على الويب "greeting".

اختبار الاستدعاء الرئيسي المعدَّل في المحاكي

لاختبار المهمّة في المحاكي، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، شغِّل الأمر التالي:

قد يستغرق الأمر وقتًا أطول من الأوامر السابقة لأنّ هذا الأمر ينشر الردّ التلقائي على الويب ويثبّت التبعيات.

gactions deploy preview

إذا ظهر لك الخطأ 403 في Cloud Build API أو الخطأ 403 بشأن ربط حساب الفوترة، يُرجى الاطّلاع على تفعيل الفوترة أو إيقافها أو تغييرها لمشروع. للنشر باستخدام Cloud Functions، عليك ربط حساب فوترة بمشروعك على Google Cloud. بعد ربط حساب فوترة، شغِّل gactions deploy preview مرة أخرى. لتجنُّب تحمُّل الرسوم، اتّبِع الخطوات الواردة في قسم "تنظيف مشروعك" في نهاية هذا الدرس التطبيقي حول الترميز.

يُفترض أن تتلقى نتيجة تبدو كما يلي:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. انسخ عنوان URL المقدَّم والصقه في متصفِّح.
3. لاختبار الإجراء في المحاكي، اكتب Talk to my test app في حقل الإدخال، ثم اضغط على Enter.

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

6- إنشاء تمثيل مرئي للإجراءات باستخدام "أداة إنشاء المهام"

تتوفّر في حزمة "SDK للإجراءات" إمكانية التشغيل التفاعلي مع بيئة تطوير متكاملة (IDE) مستندة إلى الويب تُسمى أداة إنشاء الإجراءات، وهي مدمجة في وحدة تحكّم المهام. يمكنك إرسال نظام الملفات المحلي إلى مسودة الإجراء الخاص بك في وحدة التحكّم باستخدام الأمر gactions push. على عكس gactions deploy preview الذي يتيح لك اختبار المهمّة فقط في المحاكي، ينقل gactions push كل المحتوى من ملفاتك المحلية إلى "أداة إنشاء المهام".

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

يؤدي تشغيل gactions push إلى إلغاء المسودة الحالية لمشروع الإجراءات إذا كنت تعمل بشكل تعاوني.

لإرسال مشروع "المهام" وعرضه في وحدة تحكّم المهام، اتّبِع الخطوات التالية:

1. في الوحدة الطرفية، شغِّل الأمر التالي لإرسال مشروعك إلى وحدة تحكّم المهام:

gactions push

يُفترض أن تتلقى نتيجة تبدو كما يلي:

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. انسخ عنوان URL المقدَّم والصقه في متصفِّح.
3. في وحدة تحكّم الإجراءات، انقر على تطوير في شريط التنقّل العلوي.
4. انقر على سهم القائمة المنسدلة بجانب المشاهد، ثم انقر على بدء. من المفترَض أن يظهر لك تمثيل مرئي للمشهد Start في الإجراء، كما هو موضّح في لقطة الشاشة التالية:

تنظيف مشروعك [يُنصَح به]

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

لتجنُّب تحمُّل رسوم محتملة، ننصحك بإزالة المشاريع التي لا تنوي استخدامها. لحذف المشاريع التي أنشأتها في هذا الدرس التطبيقي حول الترميز، اتّبِع الخطوات التالية:

1. لحذف المشروع والموارد على Google Cloud، أكمِل الخطوات الواردة في قسم إيقاف المشاريع (حذف).

تأكَّد من اختيار المشروع الصحيح لحذفه في صفحة إعدادات Google Cloud Platform.

2. اختياري: لإزالة مشروعك من وحدة تحكّم الإجراءات على الفور، أكمِل الخطوات المدرَجة في قسم حذف مشروع. في حال عدم إكمال هذه الخطوة، ستتم إزالة مشروعك تلقائيًا بعد 30 يومًا تقريبًا.

7. تهانينا!

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

المواضيع التي تناولتها

• كيفية إعداد مشروع "مهام" في وحدة تحكّم "المهام"
• كيفية استخدام حزمة تطوير البرامج (SDK) الخاصة بـ "المهام" لإنشاء مشروع "المهام" على نظام الملفات على الجهاز
• كيفية إضافة طلب إلى الاستدعاء الرئيسي ليتمكّن المستخدمون من بدء محادثة عن الإجراء الخاص بك
• طريقة إنشاء واجهة محادثة تتضمن المشاهد والعناصر والانتقالات وشرائح الاقتراحات وطريقة التنفيذ
• تعرَّف على كيفية اختبار الحركة باستخدام محاكي المهام

مزيد من المعلومات

يمكنك الاطّلاع على المراجع التالية للحصول على مزيد من المعلومات حول إنشاء "المهام مع مساعد Google":

• الموقع الإلكتروني الرسمي للوثائق لتطوير خدمة "المهام مع مساعد Google"
• صفحة "المهام مع مساعد Google" على GitHub لنماذج الرموز البرمجية والمكتبات
• منتدى Reddit الرسمي للمطوّرين الذين يعملون باستخدام "مساعد Google"

يمكنك متابعة @ActionsOnGoogle على Twitter للاطّلاع على آخر الأخبار، كما يمكنك نشر تغريدة مع #AoGDevs لمشاركة ما تصنعه.

استطلاع لجمع الملاحظات

قبل المغادرة، يُرجى ملء استطلاع قصير حول تجربتك.