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

1. نظرة عامة

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

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

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

ما ستنشئه

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

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

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

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

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

المتطلبات

يجب أن تتضمّن بيئتك الأدوات التالية:

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

إذا كنت تفضّل العمل باستخدام أدوات مرئية أكثر لإنشاء الإجراءات، يمكنك تجربة درس تطبيقي حول الترميز حول إنشاء إجراءات لـ "مساعد 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

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

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

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

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

تنزيل مشروع "الإجراءات"

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

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

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

mkdir myproject
cd myproject

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

gactions pull --project-id <projectID>

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

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

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

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

3- بدء محادثة

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

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

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

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

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

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

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

يمكنك استخدام طلب خاص، 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.

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

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

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

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

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. إنشاء محادثة تطبيقك

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

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

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

اختبار الإجراء في المحاكي

في هذه المرحلة، يجب أن ينتقل تطبيقك على "مساعد Google" من عملية الاستدعاء الرئيسية إلى مشهد 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- تنفيذ الطلبات

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

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

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

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

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

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

• محرِّر Cloud Functions: محرِّر مدمج لمشاريع "إجراءات Google"، يمكنك استخدامه لتعديل رمز التنفيذ ونشره باستخدام وظائف 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('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 لـ 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 webhook.

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

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

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

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

gactions deploy preview

إذا ظهر لك الخطأ 403 بشأن Cloud Build API أو الخطأ 403 بشأن ربط حساب الفوترة، يُرجى الاطّلاع على تفعيل الفوترة أو إيقافها أو تغييرها في أحد المشاريع. للنشر باستخدام "وظائف السحابة"، يجب ربط حساب فوترة بمشروعك في 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.

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

6. تمثيل الإجراء بصريًا باستخدام "أداة إنشاء الإجراءات"

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

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

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

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

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

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

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

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

7. تهانينا!

لديك معرفة أساسية بإنشاء "مهام" في "مساعد Google" باستخدام Actions SDK.

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

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

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

يمكنك استكشاف المراجع التالية لمعرفة المزيد حول إنشاء "مهام" لـ "مساعد Google":

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

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

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

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