1. نظرة عامة
تتيح لك منصة المطوّرين على "مساعد Google" إنشاء برامج لتوسيع نطاق وظائف "مساعد Google"، المساعد الشخصي الافتراضي، على أكثر من مليار جهاز، بما في ذلك مكبّرات الصوت الذكية والهواتف والسيارات وأجهزة التلفزيون وسماعات الرأس وغيرها. يتفاعل المستخدمون مع "مساعد Google" في المحادثة لإنجاز المهام، مثل شراء البقالة أو حجز رحلة. وبصفتك مطوِّرًا، يمكنك استخدام منصة المطوّرين على "مساعد Google" لإنشاء تجارب محادثات ممتعة وفعّالة وإدارتها بسهولة بين المستخدمين وخدمة تنفيذ الطلبات التابعة لجهات خارجية.
يتناول هذا الدرس التطبيقي حول الترميز مفاهيم متوسطة المستوى للتطوير باستخدام "مساعد Google"، كما يستند إلى المهمّة التي تم إنشاؤها في الدرس التطبيقي حول الترميز إنشاء مهام لمساعد Google باستخدام حزمة تطوير البرامج (SDK) الخاصة بالإجراءات (المستوى 1). ننصحك بشدّة بإكمال الدرس التطبيقي حول الترميز من المستوى 1 قبل البدء في هذا الدرس.
يخبر "الإجراء" الذي تبنيه في هذا الدرس التطبيقي حول الترميز المستخدمين حظهم في مهمة البحث عن أرض أسطورية، Gryffinberg، استنادًا إلى المساعدة التي يختارونها.
ما الذي ستقوم ببنائه
في هذا الدرس التطبيقي حول الترميز، يمكنك إنشاء "إجراء حواري" متطوّر باستخدام الدوال التالية:
- يتم جمع البيانات من المستخدم، وتعديل الطلبات الحوارية استنادًا إلى القيمة.
- يرد بأسئلة متابعة لتعزيز المحادثة.
- تنشئ حلقة ألعاب حتى يتمكن المستخدم من التفاعل مع المهمّة مرة أخرى بعد تلقّي حظ.
قبل البدء بإنشاء المحتوى، يمكنك التفاعل مع الإجراء المباشر على جهازك المزوّد بخدمة "مساعد Google" عبر قول "Ok Google، أريد التحدّث إلى Fate and Fortune". يبدو المسار التلقائي من خلال هذا الإجراء للمستخدِم المكرّر الزيارة على النحو التالي:
المُعطيات
- كيفية استخدام الخانات لجمع البيانات من المستخدم
- كيفية استخدام الشروط لإضافة منطق إلى مشهد
- كيفية إضافة حلقة ألعاب
- كيفية إضافة مسار داعم
المتطلبات
تشمل المتطلبات الأساسية لهذا الدرس التطبيقي حول الترميز ما يلي:
- محرِّر نصوص/بيئات IDE من اختيارك
- وحدة طرفية لتشغيل أوامر واجهة الأوامر مع تثبيت NodeJS وnpm وgit
- متصفِّح ويب، مثل Google Chrome
- مشروع مكتمل في مهام المستوى 1 من الدروس التطبيقية حول الترميز
ننصحك بأهمية الإلمام باستخدام JavaScript (ES6) لفهم رمز التنفيذ في هذا الدرس التطبيقي حول الترميز، وإن لم يكن ذلك مطلوبًا.
اختياري: احصل على رمز النموذج
يمكنك، إن أردت، الحصول على الرمز الكامل لمشروع المستوى 1 من مستودع GitHub ضمن المستوى 1 من "الدرس التطبيقي حول الترميز" في "أداة إنشاء المهام"، وذلك كي تتمكّن من متابعة هذا الدرس التطبيقي حول الترميز. يمكنك أيضًا عرض رمز مشروع المستوى 2 الكامل في مستودع جيت هب هذا.
2. متابعة إنشاء واجهة محادثة
في أول درس تطبيقي حول الترميز، أنشأت إجراءً حواريًا بسيطًا يضم مشهدًا واحدًا، وهو Start.
في هذا الدرس التطبيقي حول الترميز، يمكنك توسيع نطاق محادثة الإجراء. في الأقسام التالية، يمكنك ضبط الإجراء الخاص بك لتنفيذ ما يلي:
- الانتقال إلى مشهد جديد في
Fortuneعندما يريد المستخدم سماع حظه - سؤال المستخدم عن المساعدة التي يريد اختيارها لرحلته
- تقديم حظ مخصص بناءً على اختيار المستخدم
الانتقال إلى مشهد واحد (Fortune) وإنشاؤه
في هذا القسم، قم بما يلي:
- إزالة الطلب الحالي من مشهد
Start، والذي يستجيب للمستخدم وينهي المحادثة - تحديد الانتقال من المشهد
Startإلى المشهدFortune - إنشاء مشهد
Fortune
لتعديل مشهد Start وإضافة تأثير انتقال إلى المشهد Fortune، اتّبِع الخطوات التالية:
- افتح مشروع "المهام" من خلال الدرس التطبيقي حول الترميز من المستوى 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" ضمن الدرس التطبيقي حول الترميز في الوحدة الطرفية.
- أنشئ ملفًا جديدًا باسم
Fortune.yamlفي دليلscenes:
touch custom/scenes/Fortune.yaml
ستعدِّل هذا الملف في القسم التالي.
تعريف المنطق الحواري لمشهد Fortune
في هذا الدرس التطبيقي حول الترميز، يمكنك ضبط مشهد Fortune لطرح سؤال على المستخدم، مثل "ماذا تختار لمساعدتك في مهمتك أم تنين أم مترجم أم بوصلة؟" يمكنك استخدام ميزة تُسمى ملء الخانة لجمع المعلومات اللازمة من المستخدم قبل المتابعة.
يوفّر الإجراء الخاص بك حظًا لثلاث أدوات مساعدة: تنين ومترجم وبوصلة. لضبط الإجراء الخاص بك لتحديد هذه الخيارات الثلاثة في البيانات التي أدخلها المستخدم، عليك إنشاء نوع جديد.
يمكنك استخدام الأنواع في مرحلة ملء خانة المشهد لتحديد المعلومات التي تريدها من المستخدم. عندما يكتشف محرك NLU تطابق فتحة في إدخال المستخدم، فإنه يستخرج الفتحة كمعلمة مكتوبة، وبالتالي يمكنك تطبيق المنطق معها في المشهد.
إنشاء نوع 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" في محرِّر النصوص.
يتم ضبط الأنواع كأزواج مفاتيح/قيم، حيث يكون المفتاح هو اسم النوع والقيم مرادفة لهذا المفتاح. عند تعريف المفتاح، تتم إضافته تلقائيًا كقيمة. باستخدام حزمة 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. - اكتب "نعم" في حقل إدخال واضغط على 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
- احفظ الملف.
اختبِر "الحركة" في المحاكي
في هذه المرحلة، يجب أن يقدّم الإجراء الخاص بك الطلب التالي للمستخدم بعد حصوله على حظه: "هذا ما أرى. هل تريد تحديد خيار مختلف واستكشاف مستقبل آخر؟"
لاختبار الإجراء، يُرجى اتّباع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي:
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. يمكنك استخدام مَعلمة intent لتخصيص الطلب استنادًا إلى البيانات التي أدخلها المستخدم.
لإضافة other_option intent إلى المشهد 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.
قد تلاحظ أنّ رسالة المطالبة لا تبدو صحيحة عندما يختار المستخدم "magic" بسبب الحرف "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" مقالة قبل "الحصان" الاختيار، أثناء إنشاء المطالبة بدون "a" مقالة حول "السحر" خِيَار.
5- عرض "الإجراء" في وحدة تحكّم "المهام"
تتوفّر في حزمة "SDK للإجراءات" إمكانية التشغيل التفاعلي مع بيئة تطوير متكاملة (IDE) مستندة إلى الويب تُسمى أداة إنشاء الإجراءات، وهي مدمجة في وحدة تحكّم المهام. يمكنك إرسال نظام الملفات المحلي إلى مسودة الإجراء الخاص بك في وحدة التحكّم باستخدام الأمر gactions push. توفّر وحدة تحكّم المهام تمثيلاً مرئيًا لإعدادات الإجراء الخاص بك. إنّ عرض الإجراء الذي تم رسمه بشكل مرئي يمكن أن يكون مفيدًا أثناء التطوير، ولا يؤثّر في إصدار الإجراء المعروض للاختبار.
لإرسال مشروع "المهام" وعرضه في وحدة تحكّم المهام، اتّبِع الخطوات التالية:
- في الوحدة الطرفية، شغِّل الأمر التالي لإرسال مشروعك إلى وحدة تحكّم المهام:
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" باستخدام "حزمة SDK الخاصة بـ المهام".
المواضيع التي تناولتها
- كيفية تطوير "الإجراءات الحوارية" باستخدام مكتبة تنفيذ Node.js
- كيفية استخدام الخانات لجمع البيانات من المستخدم
- كيفية استخدام الشروط لإضافة عناصر منطقية إلى المشهد
- كيفية إضافة حلقة ألعاب
- كيفية إضافة مسار داعم
مزيد من المعلومات
يمكنك الاطّلاع على المراجع التالية للحصول على معلومات حول إنشاء "المهام مع مساعد Google":
- مستندات لتطوير خدمة "المهام مع مساعد Google"
- صفحة "المهام مع مساعد Google" على GitHub لنماذج الرموز البرمجية والمكتبات
- منتدى Reddit الرسمي للمطوّرين الذين يعملون باستخدام "مساعد Google"
- إرشادات تصميم المحادثات لمعرفة أفضل الممارسات والإرشادات المتعلّقة بـ "إجراءات المحادثات"
يمكنك متابعتنا على Twitter @ActionsOnGoogle لمعرفة آخر الأخبار، كما يمكنك نشر تغريدة على #AoGDevs لمشاركة ما أنجزته.
استطلاع لجمع الملاحظات
قبل المغادرة، يُرجى ملء استطلاع قصير حول تجربتك.