1. نظرة عامة
تتيح لك منصة المطوّرين في "مساعد Google" إنشاء برامج لتوسيع وظائف "مساعد Google"، وهو مساعد شخصي افتراضي، على أكثر من مليار جهاز، بما في ذلك مكبرات الصوت الذكية والهواتف والسيارات وأجهزة التلفزيون وسماعات الرأس وغيرها. يتفاعل المستخدمون مع "مساعد Google" في محادثة لإنجاز المهام، مثل شراء البقالة أو حجز رحلة. بصفتك مطوّرًا، يمكنك استخدام "منصة المطوّرين في مساعد Google" لإنشاء تجارب محادثة فعّالة وممتعة بين المستخدمين وخدمة التنفيذ التابعة لجهة خارجية وإدارتها بسهولة.
يغطّي هذا الدرس التطبيقي حول الترميز المفاهيم المتوسّطة المستوى لتطوير التطبيقات باستخدام "مساعد Google"، ويستند إلى "الإجراء" الذي تم إنشاؤه في الدرس التطبيقي حول الترميز إنشاء "إجراءات" في "مساعد Google" باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ "الإجراءات" (المستوى 1). ننصحك بشدة بإكمال المستوى 1 من الدرس العملي قبل البدء في هذا الدرس.
يخبر الإجراء الذي ستنشئه في هذا الدرس التعليمي المستخدمين عن حظهم في رحلتهم في أرض أسطورية، وهي Gryffinberg، استنادًا إلى المساعدة التي يختارونها.
ما ستنشئه
في هذا الدرس التطبيقي حول الترميز، ستنشئ "إجراءً حواريًا" متطوّرًا يتضمّن الوظائف التالية:
- تجمع هذه الوظيفة البيانات من المستخدم، وتعدّل الطلبات الحوارية استنادًا إلى القيمة.
- الردّ بأسئلة متابعة لمواصلة المحادثة
- تنشئ هذه السمة حلقة لعب حتى يتمكّن المستخدم من التفاعل مع الإجراء مرة أخرى بعد تلقّي رسالة حظ.
قبل البدء في إنشاء مهمة، يمكنك التفاعل معها مباشرةً على جهازك المزوّد بخدمة "مساعد Google" من خلال قول "Ok Google، أريد التحدث مع Fate and Fortune". يبدو المسار التلقائي خلال هذا الإجراء للمستخدم المكرر الزيارة على النحو التالي:
أهداف الدورة التعليمية
- كيفية استخدام الفتحات لجمع البيانات من المستخدم
- كيفية استخدام الشروط لإضافة منطق إلى مشهد
- كيفية إضافة حلقة ألعاب
- كيفية إضافة مسار داعم
المتطلبات
تشمل المتطلبات الأساسية لهذا الدرس التطبيقي حول الترميز ما يلي:
- بيئة تطوير متكاملة (IDE) أو محرِّر نصوص من اختيارك
- وحدة طرفية لتنفيذ أوامر shell مع تثبيت NodeJS وnpm وgit
- متصفّح ويب، مثل Google Chrome
- يجب أن يكون لديك مشروع Actions بالمستوى 1 من Codelab.
ننصحك بشدة، ولكن ليس بشكل إلزامي، بأن تكون على دراية بلغة JavaScript (الإصدار ES6) لفهم رمز التنفيذ لهذا الدرس التطبيقي حول الترميز.
اختياري: الحصول على رمز نموذجي
يمكنك اختياريًا الحصول على رمز المشروع الكامل من المستوى 1 من درس Actions Builder التطبيقي حول الترميز مستودع GitHub حتى تتمكّن من متابعة هذا الدرس التطبيقي حول الترميز. يمكنك أيضًا الاطّلاع على رمز المشروع الكامل من المستوى 2 في مستودع Github هذا.
2. مواصلة إنشاء واجهة محادثة
في الدرس التطبيقي الأول حول الترميز، أنشأت "إجراءًا حواريًا" بسيطًا يتضمّن مشهدًا واحدًا، Start.
في هذا الدرس العملي، ستوسّع نطاق محادثة الإجراء. في الأقسام التالية، يمكنك ضبط الإجراء لتنفيذ ما يلي:
- الانتقال إلى مشهد
Fortuneجديد عندما يريد المستخدم معرفة طالعه - اسأل المستخدم عن المساعدة التي يريد اختيارها لرحلته
- عرض رسالة حظ مخصّصة استنادًا إلى اختيار المستخدم
الانتقال إلى مشهد Fortune وإنشاؤه
في هذا القسم، يمكنك إجراء ما يلي:
- أزِل الطلب الحالي من مشهد
Startالذي يستجيب للمستخدم وينهي المحادثة. - حدِّد الانتقال من المشهد
Startإلى المشهدFortune - إنشاء
Fortuneالمشهد
لتعديل المشهد Start وإضافة انتقال إلى المشهد Fortune، اتّبِع الخطوات التالية:
- افتح مشروع Actions من الدرس العملي المستوى 1 في محرِّر النصوص.
- افتح ملف
custom/scenes/Start.yaml. - عدِّل
handlerللغرضyesليتطابق الرمز مع المقتطف أدناه:
Start.yaml
intentEvents:
- intent: "yes"
transitionToScene: Fortune
- handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: I understand, stranger. Best of luck on your quest! Farewell.
intent: "no"
transitionToScene: actions.scene.END_CONVERSATION
- احفظ الملف.
لإنشاء مشهد جديد باسم Fortune، اتّبِع الخطوات التالية:
- انتقِل إلى مشروع "الإجراءات" من المستوى 1 في codelab في نافذة الوحدة الطرفية.
- أنشئ ملفًا جديدًا باسم
Fortune.yamlفي الدليلscenes:
touch custom/scenes/Fortune.yaml
ستعدّل هذا الملف في القسم التالي.
تحديد منطق المحادثة لمشهد Fortune
في هذا الدرس التطبيقي حول الترميز، عليك ضبط مشهد Fortune لطرح السؤال التالي على المستخدم: "ماذا تختار لمساعدتك في مهمتك، تنينًا أم مترجمًا أم بوصلة؟" يمكنك استخدام ميزة ملء الخانات لجمع المعلومات اللازمة من المستخدم قبل المتابعة.
تقدّم "الإجراء" الخاص بك تنبؤات لثلاثة مساعدين: تنين ومترجم وبوصلة. لضبط "الإجراء" من أجل التعرّف على هذه الخيارات الثلاثة في إدخال المستخدم، عليك إنشاء نوع جديد.
يمكنك استخدام الأنواع ضمن مرحلة ملء الخانات في المشهد لتحديد المعلومات التي تريد الحصول عليها من المستخدم. عندما يرصد محرّك الفهم اللغوي الطبيعي تطابقًا لخانة في بيانات أدخلها المستخدم، يستخرج الخانة كمعلَمة مكتوبة، ما يتيح لك تنفيذ منطق باستخدامها في مشهد.
إنشاء نوع available_options
في هذا القسم، يمكنك إنشاء نوع جديد باسم available_options، والذي يحدّد الخيارات الثلاثة التي يمكن للمستخدمين اختيارها (التنين والمترجم والبوصلة) استجابةً للطلب. يمكنك أيضًا تحديد بعض المرادفات لهذه الخيارات في حال قال المستخدم شيئًا مشابهًا. في قسم لاحق، ستضيف النوع available_options إلى خانة لتحديد أنّك تريد الحصول على اختيار المستخدم.
لإنشاء النوع available_options، اتّبِع الخطوات التالية:
- أنشئ دليلاً جديدًا باسم
types:
mkdir custom/types
- أنشئ ملفًا جديدًا باسم
available_options.yamlفي الدليلtypes:
touch custom/types/available_options.yaml
- افتح
custom/types/available_options.yamlفي محرِّر النصوص.
يتم ضبط الأنواع كأزواج من المفاتيح والقيم، حيث يكون المفتاح هو اسم النوع والقيم هي مرادفات لهذا المفتاح. عند تحديد المفتاح، تتم إضافته تلقائيًا كقيمة. باستخدام Actions SDK، يمكنك تمثيل المفاتيح على النحو entities، والقيم على النحو synonyms.
لإضافة الخيارات الثلاثة التي يمكن للمستخدم الاختيار من بينها، اتّبِع الخطوات التالية:
- أضِف
entitiesوsynonymsالتاليَين في الملفavailable_options.yaml:
available_options.yaml
synonym:
entities:
dragon:
synonyms:
- dragon
- hydra
- lizard
translator:
synonyms:
- translator
- communicator
- machine
- decoder
- translate
compass:
synonyms:
- compass
- direction
- guide
- navigator
matchType: EXACT_MATCH
- احفظ الملف.
يفهم تطبيقك الآن أنّ available_options هي تنين ومترجم وبوصلة، ويمكنه أيضًا التعرّف على بعض المرادفات ذات الصلة.
ضبط ملء الخانات
بعد ذلك، عليك ضبط ميزة "ملء الخانات" في مشهد Fortune. لضبط منطق ملء الخانات، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Fortune.yamlفي محرِّر النصوص. - أضِف بيانات
slotsالتالية إلى ملفFortune.yaml:
Fortune.yaml
slots:
- commitBehavior:
writeSessionParam: chosenOptions
name: chosenOptions
promptSettings:
initialPrompt:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: What do you choose to help you on your quest, a dragon, a translator, or a compass?
suggestions:
- title: Dragon
- title: Translator
- title: Compass
required: true
type:
name: available_options
- احفظ الملف.
لقد أضفت الآن النوع available_options إلى الخانة، ما يوضّح لإجراءك المعلومات التي تحتاج إلى جمعها من المستخدم (اختياره للمساعدة) قبل المتابعة. لقد أعددت أيضًا طلبًا ضمن الفتحة، والذي تتم إضافته إلى قائمة انتظار الطلبات عندما يصل المستخدم إلى مرحلة ملء الفتحة في المشهد.
عند تسمية الفتحة chosenOptions، يتم تعديل الحقل writeSessionsParam بالاسم نفسه ($session.params.chosenOptions). ويمكنك الوصول إلى هذه المَعلمة بهذا الاسم في الطلب وفي عملية التنفيذ من خلال مكتبة العميل.
إضافة شرط
بعد إضافة خانة تتطلّب من المستخدم اختيار المساعدة، يمكنك إضافة شرط للتأكّد من الحصول على بيانات الخانة قبل أن يتمكّن المستخدم من مواصلة المحادثة.
في هذا القسم، يمكنك إضافة الشرط scene.slots.status == "FINAL" الذي يتحقّق من اكتمال ملء الخانة. بعد ملء جميع الخانات، يضيف الشرط طلبًا (You picked $session.params.chosenOptions.) إلى قائمة انتظار الطلبات.
لضبط شرط scene.slots.status == "FINAL"، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Fortune.yamlفي محرِّر النصوص. - أضِف بيانات
conditionalEventsإلى أعلى ملفFortune.yaml:
Fortune.yaml
conditionalEvents:
- condition: scene.slots.status == "FINAL"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: You picked $session.params.chosenOptions.
- احفظ الملف.
اختبار الإجراء في المحاكي
في هذه المرحلة، تكون قد حدّدت الخيارات التي يجب أن يختارها المستخدم لملء الفتحة. بعد الحصول على هذه المعلومات من المستخدم، يجب أن يقدّم الإجراء طلبًا يشير إلى الخيار المحدّد الذي اختاره.
لاختبار الإجراء، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- انقر على
Talk to my test appأو اكتبه في حقل الإدخال واضغط على Enter. - اكتب
Yesفي حقل الإدخال واضغط على Enter. يمكنك بدلاً من ذلك النقر على شريحة الاقتراح نعم.
- انقر على
dragonأو اكتبها أو قلها. يجب أن تظهر لك الرسالة "لقد اخترت التنين".
في القسم التالي، يمكنك تخصيص الطلبات لكل أداة مساعدة يمكن للمستخدم اختيارها.
تخصيص الطلبات باستخدام الشروط
في هذا القسم، يمكنك إضافة شروط لكل خيار يمكن للمستخدم اختياره وإضافة طلب مخصّص لكل شرط.
تخصيص رسالة الحظ dragon
لتعديل الشرط وتخصيص الطلب عندما يختار المستخدم "تنين"، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Fortune.yamlفي محرِّر النصوص. - استبدِل بيانات
conditionalEventsبالمقتطف التالي في ملفFortune.yaml:
Fortune.yaml
conditionalEvents:
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "dragon"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: The people of Gryffinberg will be awestruck by the beauty and
power of the ancient dragon. Much to your dismay, the townspeople
fall into dispute over who will receive the honor of riding the dragon
first. You return home from your quest without everlasting glory or
a dragon.
- احفظ الملف.
الآن، عندما يقول المستخدم "تنين" أو كلمة مشابهة، يقدّم لك الإجراء توقعات استنادًا إلى هذا الاختيار. بعد ذلك، ستضيف الاختيارَين المتبقّيَين.
تخصيص رسائل translator وcompass
لإضافة الشروط وتخصيص الطلبات التي تظهر عندما يقول المستخدم "المترجم" أو "البوصلة"، اتّبِع الخطوات التالية:
- في ملف
custom/scenes/Fortune.yaml، أضِف الشرطَين الآخرَين ضمن الشرطdragon:
Fortune.yaml
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "translator"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: With the help of the translator, the rival factions in Gryffinberg
are finally able to communicate with each other and resolve their
disputes. You will complete your quest to restore peace in the town.
The translator will be used on many other journeys across the
earth. After its work is done, it retires honorably to a premier location
in the Gryffinberg History Museum.
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "compass"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: The compass will help you find the mystical and ancient Library
of Gryffinberg. Among its infinite stacks of dusty books, you find
one entitled "Wisdom of the Ages". By the time you've read the 50,000-page
tome, the townspeople have forgotten their problems. You will write
a second edition of "Wisdom of the Ages", but have limited commercial
success.
- احفظ الملف.
اختبار الإجراء في المحاكي
في هذه المرحلة، يجب أن يقدّم الإجراء الخاص بك تنبؤًا مخصّصًا للمستخدم استنادًا إلى الخيار الذي يحدّده.
لاختبار الإجراء، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- اكتب
Talk to my test appفي حقل الإدخال واضغط على Enter. - اكتب Yes في حقل الإدخال واضغط على Enter. يمكنك بدلاً من ذلك النقر على شريحة الاقتراح نعم.
- انقر على
Translatorأو اكتبها أو قلها.
يجب أن تتلقّى التوقّعات المناسبة للخيار "المترجم".
3- إضافة حلقة لعبة
في هذا القسم، يمكنك ضبط الإجراء الخاص بك ليتمكّن المستخدم من اختيار خيار آخر والاستماع إلى توقعات مختلفة بعد إجراء عملية اختيار. يشبه هذا التغيير الرسالة "هل تريد اللعب مجددًا؟" التي تظهر في نهاية اللعبة. لإنشاء هذه الحلقة، يمكنك إعادة استخدام نيتي yes وno اللتين تم إنشاؤهما سابقًا وإضافتهما إلى مشهد جديد باسم Again.
إنشاء مشهد Again
في هذا القسم، يمكنك إنشاء Again مشهد جديد وإضافة طلب يسأل المستخدم عمّا إذا كان يريد اختيار خيار مختلف.
لإنشاء مشهد Again وإعداده، اتّبِع الخطوات التالية:
- أنشئ ملفًا جديدًا باسم
Again.yamlفي الدليلscenes:
touch custom/scenes/Again.yaml
- افتح
custom/scenes/Again.yamlفي محرِّر النصوص. - أضِف بيانات
onEnterالتالية إلىAgain.yaml:
Again.yaml
onEnter:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: That is what I see for you. Would you like to choose a different option and explore another future?
suggestions:
- title: "Yes"
- title: "No"
- احفظ الملف.
إضافة انتقال من المشهد Fortune إلى المشهد Again
بعد أن يتلقّى المستخدم رسالة الحظ، يجب أن تنتقل المحادثة إلى مشهد Again الجديد.
لإضافة انتقال من المشهد Fortune إلى المشهد Again، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Fortune.yamlفي محرِّر النصوص. - أضِف
transitionToScene: Againإلى كل شرط، كما هو موضّح في المقتطف التالي:
Fortune.yaml
conditionalEvents:
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "dragon"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: The people of Gryffinberg will be awestruck by the beauty and
power of the ancient dragon. Much to your dismay, the townspeople
fall into dispute over who will receive the honor of riding the dragon
first. You return home from your quest without everlasting glory or
a dragon.
transitionToScene: Again
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "translator"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: With the help of the translator, the rival factions in Gryffinberg
are finally able to communicate with each other and resolve their
disputes. You will complete your quest to restore peace in the town.
The translator will be used on many other journeys across the
earth. After its work is done, it retires honorably to a premier location
in the Gryffinberg History Museum.
transitionToScene: Again
- condition: scene.slots.status == "FINAL" && session.params.chosenOptions == "compass"
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: The compass will help you find the mystical and ancient Library
of Gryffinberg. Among its infinite stacks of dusty books, you find
one entitled "Wisdom of the Ages". By the time you've read the 50,000-page
tome, the townspeople have forgotten their problems. You will write
a second edition of "Wisdom of the Ages", but have limited commercial
success.
transitionToScene: Again
- احفظ الملف.
اختبار الإجراء في المحاكي
في هذه المرحلة، يجب أن يقدّم تطبيقك على "مساعد Google" الطلب التالي للمستخدم بعد تلقّيه التوقّع: "هذا ما أراه لك. هل تريد اختيار خيار مختلف واستكشاف مستقبل آخر؟"
لاختبار الإجراء، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- اكتب
Talk to my test appفي حقل الإدخال واضغط على Enter. - اكتب
Yesفي حقل الإدخال واضغط على Enter. يمكنك بدلاً من ذلك النقر على شريحة الاقتراح نعم. - انقر على
dragonأو اكتبها أو قلها.
من المفترض أن تتلقّى التوقّعات الخاصة بخيار التنين والطلب Again.
إضافة نوايا والانتقال إلى المشهد Again
في هذا القسم، يمكنك إضافة الغرضين yes وno إلى المشهد Again لكي يفهم الإجراء ما إذا كان المستخدم يريد اختيار خيار جديد أم لا. يمكنك أيضًا إضافة عمليات الانتقال المناسبة للغرضَين yes وno. ينتقل الغرض yes إلى المشهد Fortune، بينما ينتقل الغرض no إلى مشهد النظام End conversation.
لإضافة نوايا وعمليات انتقال إلى مشهد Again، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Again.yamlفي محرِّر النصوص. - أضِف بيانات
intentEventsفي أعلى ملفAgain.yaml، فوقOnEnter:
Again.yaml
intentEvents:
- intent: "yes"
transitionToScene: Fortune
- handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: It pleases me that you are satisfied with your choice. Best
of luck on your quest. Farewell.
intent: "no"
transitionToScene: actions.scene.END_CONVERSATION
- احفظ الملف.
اختبار الإجراء في المحاكي
يجب أن يفهم تطبيقك الآن ما إذا كان المستخدم يريد اختيار خيار جديد أو إنهاء المحادثة.
لاختبار الغرض yes، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- اكتب
Talk to my test appفي حقل الإدخال واضغط على Enter. - اكتب
Yesفي حقل الإدخال واضغط على Enter. يمكنك بدلاً من ذلك النقر على شريحة الاقتراح نعم. - انقر على أحد الخيارات أو اكتبه أو قُله.
- اكتب
Yesفي حقل الإدخال واضغط على Enter.
يجب أن يظهر لك الطلب "ماذا تختار لمساعدتك في رحلتك، تنينًا أم مترجمًا أم بوصلة؟"
لاختبار الغرض no، اتّبِع الخطوات التالية:
- انقر على أحد الخيارات أو اكتبه أو قُله.
- اكتب
Noفي حقل الإدخال واضغط على Enter.
من المفترض أن تتلقّى الطلب End conversation: "يسرّني أنّك راضٍ عن اختيارك. نتمنى لك التوفيق في رحلتك. إلى اللقاء".
4. إضافة مسار داعم
لقد أنشأت الآن المسار الرئيسي الذي يتّبعه معظم المستخدمين في "الإجراء". ومع ذلك، يمكن للمستخدم الردّ على الطلب من المشهد Fortune "ماذا تختار لمساعدتك في مهمتك، تنينًا أم مترجمًا أم بوصلة؟" بخيار ليس من بين الخيارات المقدَّمة.
في هذا القسم، يمكنك ضبط "الإجراء" لفهم ما إذا كان المستخدم يقول "سحر" أو "مال" أو "حصان" أو "هاتف"، وإعادة مطالبة المستخدم بالاختيار من بين الخيارات الثلاثة الأصلية عندما يختار أحد هذه الخيارات. لضبط هذه المنطق، عليك إنشاء type جديد يحتوي على هذه الخيارات الأخرى وطلب جديد، other_option، يتم مطابقته عندما يقول المستخدم أحد هذه الخيارات. عليك أيضًا إضافة تعليقات توضيحية إلى عبارات التدريب ضمن الغرض other_option لتحديد مَعلمات الغرض واستخراجها.
عندما يرصد محرّك معالجة اللغة الطبيعية في "مساعد Google" تطابقًا في المَعلمات في بيانات أدخلها المستخدم، يستخرج القيمة كمَعلمة مكتوبة حتى تتمكّن من تنفيذ منطق باستخدامها في مشهد. في هذا الدرس التطبيقي حول الترميز، ستضبط "الإجراء" لاستخراج المساعدة التي يختارها المستخدم والإشارة إلى هذا الخيار في طلب.
إنشاء نوع unavailable_options
يمكنك الآن إنشاء نوع unavailable_options يحتوي على مجموعة متنوعة من الخيارات المختلفة حتى يتمكّن الإجراء من التعرّف على هذه البيانات في إدخال المستخدم.
لإنشاء النوع unavailable_options، اتّبِع الخطوات التالية:
- أنشئ ملفًا جديدًا باسم
unavailable_options.yamlفي الدليلtypes:
touch custom/types/unavailable_options.yaml
- افتح
custom/types/unavailable_options.yamlفي محرِّر النصوص. - أضِف بيانات
synonymsالتالية إلى ملفunavailable_options.yaml:
unavailable_options.yaml
synonym:
entities:
money:
synonyms:
- money
- cash
- gold
horse:
synonyms:
- horse
- stallion
- steed
magic:
synonyms:
- magic
- enchanted
- spells
phone:
synonyms:
- phone
- cell
- apps
matchType: EXACT_MATCH
- احفظ الملف.
إنشاء نية other_option
بعد ذلك، يمكنك إنشاء غرض باسم other_option وإضافة عبارات تدريبية تتضمّن الخيارات من النوع unavailable_options. تتم مطابقة هذه النية عندما يختار المستخدم خيارًا مضمّنًا في النوع unavailable_options.
لإنشاء نية other_option وضبطها، اتّبِع الخطوات التالية:
- أنشئ ملفًا جديدًا باسم
other_option.yamlفي الدليلintents:
touch custom/intents/other_option.yaml
- افتح
custom/intents/other_option.yamlفي محرِّر النصوص. - أضِف بيانات
parametersوبياناتtrainingPhrasesالتالية إلى ملفother_option.yaml:
other_option.yaml
parameters:
- name: chosenUnavailableOption
type:
name: unavailable_options
trainingPhrases:
- I want to use ($chosenUnavailableOption 'spells' auto=true)
- I really really want to use a ($chosenUnavailableOption 'phone' auto=true)
- ($chosenUnavailableOption 'magic' auto=true)!
- ($chosenUnavailableOption 'cash' auto=true)
- I want to ride a ($chosenUnavailableOption 'horse' auto=true)
في هذه الخطوة، يمكنك إضافة تعليقات توضيحية يدويًا إلى عبارات التدريب باستخدام الخيارات غير المتاحة التي حدّدتها في القسم السابق. تتيح لك مَعلمة الغرض، chosenUnavailableOption، استخراج اسم الخيار واستخدامه في طلب، وهو ما ستفعله في القسم التالي.
- احفظ الملف.
إضافة النية other_option إلى المشهد Fortune
لديك الآن غرض، other_option، يمكنه التعامل مع مستخدم يحدّد خيارًا ليس من الخيارات الأصلية. في هذا القسم، يمكنك إضافة الغرض other_option إلى المشهد Fortune. يمكنك استخدام مَعلمة النية لتخصيص الطلب استنادًا إلى إدخال المستخدم.
لإضافة نية other_option إلى مشهد Fortune، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Fortune.yamlفي محرِّر النصوص. - أضِف بيانات
intentEventsالتالية بين بياناتconditionalEventsوبياناتslots:
Fortune.yaml
intentEvents:
- handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: I have seen the future and a $intent.params.chosenUnavailableOption.original will not aid you on your journey.
intent: other_option
- احفظ الملف.
يشير التعبير $intent.params.chosenUnavailableOption إلى عنصر مَعلمة الغرض، ويشير $intent.params.chosenUnavailableOption.original إلى قيمة هذا العنصر. تشير السمة original إلى الإدخال الأولي الذي يحدّده المستخدم.
عندما يذكر المستخدم خيارًا مُدرَجًا في النوع unavailable_options أثناء المشهد Fortune، يتمّ الربط مع الغرض other_option وتتمّ إضافة طلب إلى قائمة انتظار الطلبات. بما أنّه لم يتم تحديد أي انتقال، تستمر حلقة تنفيذ المشهد من خلال إعادة تقييم مرحلة الشروط. بعد ذلك، يضيف خانة chosenOptions طلبها إلى قائمة انتظار الطلبات، ويتم تسليم قائمة انتظار الطلبات إلى المستخدم.
اختبار الإجراء في المحاكي
يجب أن يستجيب الإجراء الآن بشكل مناسب عندما يختار المستخدم أحد الخيارات المُدرَجة في النوع unavailable_options وأن يحدّد المساعدة التي اختارها المستخدم. يجب أن يطلب تطبيقك من المستخدم مجددًا اختيار أحد الخيارات الأصلية (تنين أو مترجم أو بوصلة).
لاختبار الإجراء في المحاكي، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- اكتب
Talk to my test appفي حقل الإدخال واضغط على Enter. - اكتب
Yesفي حقل الإدخال واضغط على Enter. يمكنك بدلاً من ذلك النقر على شريحة الاقتراح نعم. - اكتب
magicفي حقل الإدخال واضغط على Enter.
قد تلاحظ أنّ الطلب لا يبدو صحيحًا عندما يختار المستخدم "السحر" بسبب أداة التعريف "a" الموضوعة قبلها. يمكنك معالجة هذه المشكلة في الأقسام التالية.
إضافة معالج unavailable_options
لوضع أداة التعريف "a" قبل الخيارات المناسبة من النوع unavailable_options، يمكنك ضبط معالج أحداث في منطق التنفيذ للتحقّق مما إذا كان الخيار الذي يحدده المستخدم يحتاج إلى أداة التعريف "a" قبله. أولاً، عليك ضبط الإجراء لاستدعاء المعالج من مشهد Fortune.
لإضافة معالج unavailable_options إلى مشهد Fortune، اتّبِع الخطوات التالية:
- افتح
custom/scenes/Fortune.yamlفي محرِّر النصوص. - عدِّل ملف
Fortune.yamlباستخدام بياناتintentEventsالتالية:
Fortune.yaml
intentEvents:
- handler:
webhookHandler: unavailable_options
intent: other_option
- احفظ الملف.
تعديل عملية التنفيذ ونشرها
بعد إعداد الإجراء لاستدعاء معالج الحدث unavailable_options، يمكنك تعديل المعالج في عملية التنفيذ ونشره.
لتعديل معلومات التنفيذ، اتّبِع الخطوات التالية:
- افتح
webhooks/ActionsOnGoogleFulfillment/index.jsفي محرِّر النصوص. - أضِف الرمز التالي إلى
index.jsضمن معالجgreeting:
index.js
app.handle('unavailable_options', conv => {
const option = conv.intent.params.chosenUnavailableOption.original;
const optionKey = conv.intent.params.chosenUnavailableOption.resolved;
let message = 'I have seen the future and ';
if(optionsNeedA.has(optionKey)){
message = message + 'a ';
}
message = message + `${option} will not aid you on your journey. `;
conv.add(message);
});
- أضِف الرمز التالي ضمن
const app = conversation({debug:true});:
index.js
const optionsNeedA = new Set();
optionsNeedA.add('horse').add('phone');
- احفظ الملف.
فهم الرمز البرمجي
ينفِّذ معالج unavailable_options ما يلي:
- يحصل على بيانات
optionمن العنصرconvويُعيّنoptionللسمةoriginal، وهي الإدخال الأولي من المستخدم - تُعيّن القيمة
optionKeyللسمةresolved، وهي المفتاح لنوعunavailable_options - تتحقّق هذه السمة مما إذا كان
optionKeyأحد الخيارات التي تحتاج إلى "a"، وإذا كان كذلك، تنشئ الرسالة مع إضافة "a". - إضافة الرسالة عبر
conv.add(message)
معالجات التحديث
للسماح للإجراء باستخدام unavailable_options، أضِف معالج unavailable_options إلى webhooks/ActionsOnGoogleFulfillment.yaml.
- أضِف اسم معالج
unavailable_optionsإلىActionsOnGoogleFulfillment.yaml:
ActionsOnGoogleFulfillment.yaml
handlers: - name: greeting - name: unavailable_options inlineCloudFunction: executeFunction: ActionsOnGoogleFulfillment
- احفظ الملف.
اختبار الإجراء في المحاكي
يجب أن يعدّل الإجراء الآن الطلب استنادًا إلى ما إذا كان خيار المستخدم من النوع unavailable_options يتطلّب أداة التعريف "a" قبله.
لاختبار الإجراء، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- انقر على
Talk to my test appأو اكتبه في حقل الإدخال واضغط على Enter. - اكتب
Yesفي حقل الإدخال واضغط على Enter. يمكنك بدلاً من ذلك النقر على شريحة الاقتراح نعم. - اكتب
magicفي حقل الإدخال واضغط على Enter. بعد ذلك، اكتبhorseفي حقل الإدخال واضغط على Enter.
يجب أن يضيف الإجراء الخاص بك أداة التعريف "a" قبل الخيار "horse"، مع إنشاء الطلب بدون أداة التعريف "a" للخيار "magic".
5- تصوُّر الإجراء في "وحدة تحكّم المهام"
تتضمّن Actions SDK إمكانية التشغيل التفاعلي مع بيئة تطوير متكاملة مستندة إلى الويب تُسمى Actions Builder ومدمجة في Actions Console. يمكنك نقل نظام الملفات على جهازك إلى مسودة "الإجراء" في وحدة التحكّم باستخدام الأمر gactions push. توفّر "وحدة تحكّم الإجراءات" تمثيلاً مرئيًا لإعدادات الإجراء. يمكن أن يكون عرض "الإجراء" بشكل مرئي مفيدًا أثناء عملية التطوير، ولا يؤثر في إصدار "الإجراء" الذي يتم عرضه للاختبار.
لإرسال مشروع "الإجراءات" وعرضه في وحدة تحكّم "الإجراءات على Google"، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي لنقل مشروعك إلى "وحدة تحكّم الإجراءات":
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.
- انسخ عنوان URL المقدَّم والصقه في متصفّح.
- في وحدة تحكّم الإجراءات، انقر على تطوير في شريط التنقّل العلوي.
- انقر على سهم القائمة المنسدلة بجانب المشاهد، ثم انقر على بدء. من المفترض أن يظهر لك تمثيل مرئي لمشهد
Startفي مهمّتك، كما هو موضّح في لقطة الشاشة التالية:
تنظيف مشروعك [يُنصح به]
لتجنُّب تحمّل رسوم محتملة، ننصحك بإزالة المشاريع التي لا تنوي استخدامها. لحذف المشاريع التي أنشأتها في هذا الدرس العملي، اتّبِع الخطوات التالية:
- لحذف مشروع Cloud والموارد، أكمِل الخطوات الواردة في قسم إيقاف المشاريع (حذفها).
- اختياري: لإزالة مشروعك على الفور من وحدة تحكّم "الإجراءات"، أكمِل الخطوات الواردة في قسم حذف مشروع. إذا لم تُكمل هذه الخطوة، ستتم إزالة مشروعك تلقائيًا بعد 30 يومًا تقريبًا.
6. تهانينا!
أصبحت لديك الآن المهارات المتوسطة اللازمة لإنشاء "مهام مع مساعد Google" باستخدام Actions SDK.
المواضيع التي تناولتها
- كيفية تطوير "إجراءات حوارية" باستخدام مكتبة التنفيذ Node.js
- كيفية استخدام الخانات لجمع البيانات من المستخدم
- كيفية استخدام الشروط لإضافة منطق إلى المشهد
- كيفية إضافة حلقة ألعاب
- كيفية إضافة مسار داعم
مزيد من المعلومات
يمكنك استكشاف الموارد التالية للتعرّف على كيفية إنشاء "مهام مع مساعد Google":
- المستندات الخاصة بتطوير "المهام مع مساعد Google"
- صفحة "المهام على Google" على GitHub للحصول على عيّنات التعليمات البرمجية والمكتبات
- منتدى Reddit الرسمي للمطوّرين الذين يعملون مع "مساعد Google"
- إرشادات تصميم المحادثات للتعرّف على أفضل الممارسات والإرشادات المتعلّقة بالإجراءات الحوارية
تابِعنا على Twitter @ActionsOnGoogle للاطّلاع على آخر إشعاراتنا، وشاركنا ما أنشأته من خلال التغريد باستخدام الهاشتاغ #AoGDevs.
استطلاع لجمع الملاحظات
قبل إنهاء المحادثة، يُرجى ملء استطلاع موجز حول تجربتك.