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

1. نظرة عامة

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

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

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

ما ستقوم بإنشائه

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

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

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

أهداف الدورة التعليمية

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

المتطلبات

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

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

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

2. إعداد

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

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

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

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

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

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

إنشاء مشروع على Actions on Google

مشروع الإجراءات هو حاوية لإجرائك.

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

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

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

احفظ رقم تعريف المشروع الخاص بـ Action.

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

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

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

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

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

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

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

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

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

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

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

مصطلح رئيسي:

• gactions CLI: أداة تتيح لك إعداد ملفات مشاريع الإجراءات، وإرسال التحديثات إلى وحدة تحكّم الإجراءات، ونشر مشاريع الإجراءات، والمزيد.

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

تنزيل مشروع Actions

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

لتنزيل مشروعك على Actions، اتّبِع الخطوات التالية:

1. لإنشاء دليل جديد والانتقال إليه، نفِّذ الأمرَين التاليَين:

mkdir myproject
cd myproject

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

gactions pull --project-id <projectID>

فهم بنية الملف

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

تتألف بنية الملف مما يلي:

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

3- بدء محادثة

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

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

مصطلح رئيسي:

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

By default, your Action provides a generic prompt when your invocation is triggered ("Start building your Action by defining main invocation.").

مصطلح رئيسي:

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

يمكنك استخدام طلب خاص، وهو Canvas، لعرض مرئيات بملء الشاشة للمستخدم. لمزيد من المعلومات حول Canvas، يُرجى الاطّلاع على مستندات Interactive 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 لاختبار الإجراء في وحدة التحكّم بدون تحديث إصدار مشروع الإجراءات. عند تشغيل هذا الأمر، لن يتم نشر أي من التغييرات التي تجريها في نظام الملفات المحلي على الإصدارات المنشورة من مشروع الإجراءات، ولكن يمكنك اختبارها على إصدار مبكر حصري.

لاختبار عبارة التفعيل الرئيسية لـ Action في المحاكي، اتّبِع الخطوات التالية:

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.

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

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

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

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

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

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

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

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

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

4. إنشاء محادثة الإجراء

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

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

• المشهد: هو وحدة أساسية في مهمّتك يعالج إدخالات المستخدم وينشئ عادةً الردّ للمستخدم. غالبًا ما تعمل النيات المخصّصة على تفعيل مَشاهد أخرى، ولكن يمكن أيضًا تفعيل المَشاهد بطرق أخرى.
• النية المخصّصة: تحدّد هذه السمة البيانات التي يُدخلها المستخدم ويمكن أن يفهمها الإجراء. ويمكنك تحديد عبارات التدريب لهذه الأهداف. عندما يقول المستخدمون شيئًا يطابق عبارة تدريب أو يشبهها، تتم مطابقة الغرض المقابل.
• عبارات التدريب: أمثلة على ما قد يقوله المستخدم لمطابقة نية. يوسّع محرّك فهم اللغات الطبيعية (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 والهدف المرتبط بالاستدعاء الرئيسي هما مثالان على أهداف النظام.

يوفّر القصد التلقائي للنظام 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"

يمكنك الآن إنشاء هدف 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: محرِّر مدمج لمشاريع Actions، يمكنك استخدامه لتعديل رمز التنفيذ ونشره باستخدام وظائف 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 Functions كنقطة نهاية الويب هوك.

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(&#>39;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. احفظ الملف.

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

يستجيب التنفيذ، الذي يستخدم مكتبة Actions on Google Fulfillment لـ 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. تصوُّر الإجراء باستخدام أداة Actions Builder

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

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

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

لنشر مشروعك على Actions on Google وعرضه في وحدة تحكّم المهام، اتّبِع الخطوات التالية:

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" باستخدام حزمة تطوير برامج الإجراءات (المستوى 2)، على المشروع الذي أنشأته في هذا الدرس التطبيقي حول الترميز. إذا كنت تخطّط لإجراء الدرس التطبيقي حول الترميز من المستوى 2، لا تحذف مشروعك، بل يمكنك حذفه في قسم "تنظيف مشروعك" في نهاية الدرس التطبيقي حول الترميز من المستوى 2.

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

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

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

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

7. تهانينا!

أن تكون على دراية بأساسيات إنشاء إجراءات "مساعد Google" باستخدام حزمة تطوير برامج الإجراءات

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

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

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

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

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

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

استطلاع رأي

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