Build Actions برای Google Assistant با استفاده از Actions SDK (سطح 1)

1. بررسی اجمالی

هشدار: کنش‌های مکالمه در 13 ژوئن 2023 منسوخ شد. برای اطلاعات بیشتر، غروب کنش‌های مکالمه را ببینید .

پلتفرم توسعه‌دهنده Google Assistant به شما امکان می‌دهد نرم‌افزاری ایجاد کنید تا عملکرد Google Assistant، یک دستیار شخصی مجازی، را در بیش از 1 میلیارد دستگاه، از جمله بلندگوهای هوشمند، تلفن‌ها، خودروها، تلویزیون‌ها، هدفون‌ها و موارد دیگر گسترش دهید. کاربران برای انجام کارهایی مانند خرید مواد غذایی یا رزرو سواری، دستیار را در مکالمه قرار می دهند. به‌عنوان یک توسعه‌دهنده، می‌توانید از پلتفرم توسعه‌دهنده Assistant برای ایجاد و مدیریت تجربیات گفتگوی لذت‌بخش و مؤثر بین کاربران و سرویس‌های شخص ثالث خود استفاده کنید.

این نرم افزار کد مفاهیم سطح مبتدی را برای توسعه با Actions SDK برای دستیار Google پوشش می دهد. برای تکمیل آن نیازی به تجربه قبلی با پلتفرم ندارید. در این نرم‌افزار، شما یک Action ساده برای دستیار Google می‌سازید که به کاربران می‌گوید در حالی که ماجراجویی خود را در سرزمین افسانه‌ای گریفینبرگ آغاز می‌کنند، ثروتشان را به دست می‌آورند. در نوار کد Actions SDK سطح 2، شما این Action را بیشتر می سازید تا ثروت کاربر را بر اساس ورودی آنها سفارشی کنید.

چیزی که خواهی ساخت

در این کد لبه، شما یک Action ساده با توابع زیر می سازید:

• با یک پیام تبریک به کاربران پاسخ می دهد
• از کاربران سوال می پرسد و به انتخاب کاربر پاسخ مناسب می دهد
• تراشه های پیشنهادی را ارائه می دهد که کاربران می توانند برای ارائه ورودی کلیک کنند
• پیام تبریک به کاربر را بر اساس اینکه آیا کاربر بازگشتی است یا خیر، تغییر می‌دهد

هنگامی که این لبه کد را تمام کردید، Action تکمیل شده شما جریان مکالمه زیر را خواهد داشت (متن کنار میکروفون ورودی کاربر را نشان می دهد، در حالی که متن کنار بلندگو نشان دهنده پاسخ Action است):

چیزی که یاد خواهید گرفت

• نحوه ایجاد پروژه در کنسول Actions
• نحوه استفاده از ابزار gactions برای فشار دادن و کشیدن پروژه Action خود بین کنسول Actions و سیستم فایل محلی شما
• نحوه ارسال یک درخواست برای کاربر پس از فراخوانی Action شما
• نحوه پردازش ورودی کاربر و بازگشت پاسخ
• چگونه اکشن خود را در شبیه ساز اکشن تست کنید
• نحوه پیاده سازی تکمیل با استفاده از ویرایشگر توابع ابری

آنچه شما نیاز دارید

ابزارهای زیر باید در محیط شما باشند:

• یک IDE یا ویرایشگر متن به انتخاب شما
• ترمینالی برای اجرای دستورات پوسته برای Node.js و npm
• یک مرورگر وب، مانند گوگل کروم

اگر ترجیح می‌دهید با ابزارهای بصری بیشتری برای ساخت Actions کار کنید، به جای آن ، Build Actions را برای Google Assistant با استفاده از Actions Builder (سطح 1) کد لباب انجام دهید، که همان Action را با استفاده از Actions Builder IDE داخل کنسول می‌سازد.

2. راه اندازی کنید

بخش‌های زیر نحوه راه‌اندازی محیط توسعه و ایجاد پروژه Actions را توضیح می‌دهند.

تنظیمات مجوز Google خود را بررسی کنید

برای آزمایش اکشنی که در این کد لبه می سازید، باید مجوزهای لازم را فعال کنید تا شبیه ساز بتواند به اکشن شما دسترسی داشته باشد.

برای فعال کردن مجوزها، مراحل زیر را دنبال کنید:

1. به Activity Controls بروید.
2. اگر قبلاً این کار را نکرده‌اید، با حساب Google خود وارد شوید.
3. مجوزهای زیر را فعال کنید:

• فعالیت وب و برنامه
• در بخش «فعالیت وب و برنامه» ، کادر تأیید شامل سابقه و فعالیت Chrome از سایت‌ها، برنامه‌ها و دستگاه‌هایی که از خدمات Google استفاده می‌کنند ** را انتخاب کنید.**

یک پروژه Actions ایجاد کنید

پروژه Actions شما محفظه ای برای Action شماست.

برای ایجاد پروژه Actions خود برای این کد لبه، مراحل زیر را دنبال کنید:

1. کنسول Actions را باز کنید.
2. پروژه جدید را کلیک کنید.
3. نام پروژه مانند actions-codelab را وارد کنید. (این نام برای مرجع داخلی شما است. بعداً می توانید یک نام خارجی برای پروژه خود تعیین کنید.)

4. روی ایجاد پروژه کلیک کنید.
5. در چه نوع اکشنی می خواهید بسازید؟ کارت سفارشی را انتخاب کنید.
6. روی Next کلیک کنید.
7. در چگونه می خواهید آن را بسازید؟ صفحه، کارت پروژه خالی را انتخاب کنید.
8. روی Start building کلیک کنید.

شناسه پروژه را برای اکشن خود ذخیره کنید

شناسه پروژه یک شناسه منحصر به فرد برای Action شما است. برای چندین مرحله در این کد لبه به شناسه پروژه خود نیاز دارید.

برای بازیابی ID پروژه خود، این مراحل را دنبال کنید:

1. در کنسول Actions، روی سه نقطه عمودی کلیک کنید (آیکون را در اینجا وارد کنید).
2. روی تنظیمات پروژه کلیک کنید.

3. شناسه پروژه را کپی کنید**.**

یک حساب صورتحساب را مرتبط کنید

اگر قبلاً یک حساب صورت‌حساب ندارید، باید یک حساب صورت‌حساب ایجاد کنید و آن را با پروژه خود در Google Cloud مرتبط کنید تا بعداً با توابع Cloud اجرا شود.

برای مرتبط کردن یک حساب صورتحساب با پروژه خود، این مراحل را دنبال کنید:

1. به صفحه صورتحساب Google Cloud Platform بروید.
2. روی افزودن حساب صورت‌حساب یا ایجاد حساب کلیک کنید.
3. اطلاعات پرداخت خود را وارد کنید
4. روی شروع نسخه آزمایشی رایگان یا ارسال و فعال کردن صورتحساب کلیک کنید.
5. به صفحه صورتحساب Google Cloud Platform بروید.
6. روی تب My Projects کلیک کنید.
7. روی سه نقطه در زیر Actions در کنار پروژه Actions برای کد لبه کلیک کنید.
8. روی تغییر صورتحساب کلیک کنید.
9. در منوی کشویی، حساب صورت‌حساب را که پیکربندی کرده‌اید انتخاب کنید.
10. روی تنظیم حساب کلیک کنید.

برای جلوگیری از تحمیل هزینه، مراحل موجود در بخش Clean up your project در انتهای این کد لبه را دنبال کنید.

رابط خط فرمان gactions را نصب کنید

در این کد لبه، شما از ابزار رابط خط فرمان gactions (CLI) برای همگام سازی پروژه Actions خود بین کنسول Actions و سیستم فایل محلی خود استفاده می کنید.

اصطلاح کلیدی :

• gactions CLI : ابزاری که به شما امکان می‌دهد فایل‌های پروژه Action را مقداردهی اولیه کنید، به‌روزرسانی‌ها را به کنسول Actions فشار دهید، پروژه‌های Actions را مستقر کنید و موارد دیگر.

برای نصب gactions CLI، دستورالعمل‌های Install the gactions command-line tool را دنبال کنید.

پروژه Actions خود را دانلود کنید

با دانلود پروژه Actions خود از کنسول Actions، توسعه Action خود را شروع کنید.

برای دانلود پروژه Actions، مراحل زیر را دنبال کنید:

1. برای ایجاد یک دایرکتوری جدید و تغییر در آن دایرکتوری، دستورات زیر را اجرا کنید:

mkdir myproject
cd myproject

2. برای کپی کردن پیکربندی پروژه Actions در سیستم فایل محلی خود، دستور زیر را اجرا کنید:

gactions pull --project-id <projectID>

ساختار فایل را درک کنید

پروژه Actions که از کنسول Actions دانلود می کنید در یک ساختار فایل YAML نشان داده شده است. تصویر زیر نمایش سطح بالایی از ساختار فایل را نشان می دهد:

ساختار فایل شامل موارد زیر است:

• actions/ : نمایانگر پروژه Actions شماست. هنگامی که Action شما فراخوانی می شود، سیستم actions.yaml را فراخوانی می کند، که سپس فایل custom/global/actions.intent.MAIN.yaml را فراخوانی می کند.
• custom/ : دایرکتوری که برای اصلاح Action خود در آن کار می کنید.
• global/ : این دایرکتوری حاوی اهداف سیستمی است که پلتفرم به طور خودکار به پروژه شما اضافه می کند. بعداً در این Codelab درباره مقاصد سیستم بیشتر خواهید آموخت.
• manifest.yaml : فایلی که حاوی اطلاعاتی است که قابل انتقال است یا مختص هر پروژه ای نیست و می تواند بین پروژه ها جابجا شود.
• settings/ : تنظیمات یک پروژه Actions را نشان می دهد، مانند نام نمایشی، محلی پیش فرض، و دسته.

3. یک مکالمه را شروع کنید

کاربران مکالمه را با Action شما از طریق فراخوانی شروع می کنند. برای مثال، اگر اکشنی به نام MovieTime دارید، کاربران می‌توانند با گفتن عبارتی مانند «Hey Google, talk to MovieTime» که در آن MovieTime نام نمایشی است، Action شما را فراخوانی کنند. اگر می‌خواهید اکشن شما را در تولید اجرا کنید، باید نام نمایشی داشته باشد. با این حال، برای آزمایش Action خود، نیازی به تعریف نام نمایشی ندارید. در عوض، می توانید از عبارت Talk to my test app در شبیه ساز برای فراخوانی Action خود استفاده کنید. در ادامه این بخش درباره شبیه ساز بیشتر خواهید آموخت.

شما باید فراخوان اصلی را ویرایش کنید تا مشخص کنید پس از اینکه کاربر اقدام شما را فراخواند چه اتفاقی می افتد.

اصطلاح کلیدی :

• فراخوان اصلی : نقطه ورود کاربران برای شروع مکالمه با Action شما. وقتی کاربران عبارتی شبیه به "Hey Google, talk to <display name>" را می گویند، فراخوان اصلی کاربر را فعال می کند و به او پاسخ می دهد.

به‌طور پیش‌فرض، Action شما هنگامی که فراخوانی شما راه‌اندازی می‌شود، یک اعلان عمومی ارائه می‌دهد ( "با تعریف فراخوان اصلی شروع به ساختن کنش کنید.").

اصطلاح کلیدی :

• Prompt : تعریف می کند که Action شما چه چیزی را به عنوان پاسخ برای کاربران ارسال می کند. درخواست‌ها می‌توانند پاسخ‌های نوشتاری و گفتاری ساده یا پیام‌های غنی مانند کارت‌ها و تصاویر باشند.

برای بازگرداندن تصاویر تمام صفحه به کاربر، می‌توانید از یک فرمان ویژه، Canvas استفاده کنید. برای اطلاعات بیشتر در مورد Canvas ، به مستندات بوم تعاملی مراجعه کنید.

در بخش بعدی، درخواست فراخوان اصلی خود را در فایل custom/global/actions.intent.MAIN.yaml سفارشی می کنید.

فراخوانی اصلی را تنظیم کنید

می توانید درخواست اصلی خود را در فایل actions.intent.MAIN.yaml ویرایش کنید.

برای اصلاح درخواستی که Action شما هنگام فراخوانی Action شما برای کاربر ارسال می‌کند، این مراحل را دنبال کنید:

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. فایل را ذخیره کنید.

فراخوانی اصلی را در شبیه ساز تست کنید

کنسول Actions یک ابزار وب برای آزمایش Action شما به نام شبیه ساز ارائه می دهد. این رابط دستگاه‌های سخت‌افزاری و تنظیمات آن‌ها را شبیه‌سازی می‌کند، بنابراین می‌توانید با Action خود طوری صحبت کنید که گویی روی نمایشگر هوشمند، تلفن، بلندگو یا KaiOS اجرا می‌شود.

برای آخرین اطلاعات در مورد استفاده از شبیه ساز کنسول Actions، یا اگر در مراحل زیر با مشکلی مواجه شدید، به صفحه Simulator مراجعه کنید.

وقتی اکشن خود را فراخوانی می‌کنید، اکنون باید با درخواست سفارشی‌شده‌ای که اضافه کرده‌اید پاسخ دهد ( "یک سلام شگفت‌انگیز، ماجراجو!...") .

می‌توانید از دستور gactions deploy preview برای آزمایش Action خود در کنسول بدون به‌روزرسانی نسخه پروژه Actions خود استفاده کنید. هنگامی که این دستور را اجرا می کنید، هیچ یک از تغییراتی که در سیستم فایل محلی خود ایجاد می کنید به نسخه های مستقر پروژه Actions شما منتشر نمی شود، اما می توانید آنها را در نسخه پیش نمایش آزمایش کنید.

برای آزمایش فراخوانی اصلی Action خود در شبیه ساز، این مراحل را دنبال کنید:

1. برای استقرار پروژه خود در کنسول Actions برای آزمایش، دستور زیر را در ترمینال اجرا کنید:

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. برای فراخوانی Action خود در شبیه ساز، Talk to my test app را در قسمت Input تایپ کنید و Enter فشار دهید.

نکته: همچنین می‌توانید روی تراشه پیشنهادی برنامه آزمایشی Talk to my test در «پیشنهادات» کلیک کنید، که به همان روش ورودی کاربر گفتاری یا تایپ شده پردازش می‌شود.

همچنین، می‌توانید روی نماد میکروفون کلیک کنید و بگویید «Talk to my test app» برای فراخوانی Action خود.

وقتی فراخوان اصلی Action خود را فعال می‌کنید، «دستیار» با پیام خوش‌آمدگویی سفارشی‌شده شما پاسخ می‌دهد. در این مرحله، پس از پاسخ دستیار با سلام و احوالپرسی، مکالمه به پایان می رسد. در بخش بعدی، Action خود را تغییر می دهید تا گفتگو ادامه یابد.

مشاهده گزارش رویداد

هنگامی که در تب Test در کنسول Actions هستید، پانل گزارش های رویداد را نشان می دهد که تاریخچه مکالمه را به عنوان گزارش رویداد نمایش می دهد. هر گزارش رویداد رویدادهایی را که در آن نوبت مکالمه اتفاق می‌افتد نمایش می‌دهد.

Action شما در حال حاضر یک گزارش رویداد دارد که هم ورودی کاربر ( "Talk to my test app" ) و هم پاسخ Action شما را نشان می دهد. اسکرین شات زیر گزارش رویداد Action شما را نشان می دهد:

اگر روی پیکان رو به پایین کنار Talk to my test app در گزارش رویداد کلیک کنید، می‌توانید رویدادهایی را که به ترتیب زمانی در آن نوبت از مکالمه رخ داده‌اند، مشاهده کنید:

• userInput : مربوط به ورودی کاربر است ( "Talk to my test app" )
• interactionMatch : مربوط به پاسخ فراخوانی اصلی Action شما است که توسط ورودی کاربر فعال شده است. اگر این ردیف را با کلیک کردن روی فلش گسترش دهید، می‌توانید اعلانی را که برای فراخوانی اصلی اضافه کرده‌اید مشاهده کنید ( A wondrous greeting, adventurer!... )
• endConversation : مربوط به انتقال انتخاب شده در هدف Main invocation که در حال حاضر مکالمه را پایان می دهد. در بخش بعدی این کد لبه درباره انتقال ها بیشتر خواهید آموخت.

گزارش‌های رویداد، نحوه عملکرد Action شما را نشان می‌دهند و در صورت داشتن هر گونه مشکل، ابزار مفیدی برای اشکال‌زدایی Action شما هستند. برای مشاهده جزئیات یک رویداد، همانطور که در تصویر زیر نشان داده شده است، روی فلش کنار نام رویداد کلیک کنید:

4. مکالمه Action خود را ایجاد کنید

اکنون که مشخص کرده اید پس از فراخوانی یک کاربر Action شما چه اتفاقی می افتد، می توانید بقیه مکالمه Action خود را بسازید. قبل از ادامه کار با این لبه کد، با اصطلاحات زیر آشنا شوید تا بفهمید مکالمه Action شما چگونه کار می کند:

اصطلاحات کلیدی :

• صحنه : بلوک ساختمانی برای Action شما که ورودی کاربر را پردازش می کند و معمولاً پاسخ کاربر را ایجاد می کند. هدف های سفارشی اغلب صحنه های دیگر را فعال می کنند، اما صحنه ها می توانند به روش های دیگری نیز فعال شوند.
• قصد سفارشی : ورودی کاربر را که Action می تواند درک کند را تعریف می کند. شما عبارات آموزشی را برای این مقاصد تعریف کنید. هنگامی که کاربران چیزی را می گویند که مطابق یا شبیه یک عبارت آموزشی است، هدف مربوطه مطابقت داده می شود.
• عبارات آموزشی : نمونه هایی از آنچه ممکن است یک کاربر برای مطابقت با یک هدف بگوید. موتور درک زبان طبیعی (NLU) Assistant به طور طبیعی این عبارات آموزشی را گسترش می دهد تا عبارات مشابه دیگر را نیز در بر گیرد.
• Transition : مشخص می کند که پس از برآورده شدن شرایط، به کدام صحنه منتقل شود.

اکشن شما می تواند یک یا چند صحنه داشته باشد و قبل از اجرا باید هر صحنه را فعال کنید. اکشنی که در این کد لبه می‌سازید فقط یک صحنه با عنوان Start دارد. رایج ترین راه برای فعال کردن یک صحنه این است که Action خود را به گونه ای پیکربندی کنید که وقتی ورودی کاربر با یک intent در یک صحنه مطابقت دارد، آن intent انتقال به صحنه دیگری را آغاز کرده و آن را فعال می کند.

به عنوان مثال، یک اقدام فرضی را تصور کنید که حقایق حیوانی را در اختیار کاربر قرار می دهد. هنگامی که کاربر این Action را فراخوانی می کند، هدف Main invocation مطابقت داده می شود و انتقال به صحنه ای به نام Facts. این انتقال صحنه Facts را فعال می‌کند، که پیام زیر را برای کاربر ارسال می‌کند: Would you like to hear a fact about cats or dogs? در صحنه Facts یک هدف سفارشی به نام Cat وجود دارد که شامل عبارات آموزشی است که کاربر ممکن است برای شنیدن یک واقعیت گربه بگوید، مانند "من می خواهم یک واقعیت گربه را بشنوم" یا "گربه" . هنگامی که کاربر درخواست شنیدن یک واقعیت گربه را می‌دهد، هدف Cat مطابقت داده می‌شود و انتقال به صحنه‌ای به نام Cat fact. صحنه Cat fact فعال می‌شود و پیامی را برای کاربر ارسال می‌کند که شامل یک واقعیت گربه است.

شکل 1. جریان یک چرخش مکالمه معمولی در یک Action ساخته شده با Actions SDK.

صحنه‌ها، مقاصد و انتقال‌ها با هم، منطق مکالمه شما را تشکیل می‌دهند و مسیرهای مختلفی را که کاربر شما می‌تواند در مکالمه Action طی کند، تعریف می‌کند. در قسمت زیر، یک صحنه ایجاد می کنید و نحوه فعال شدن آن صحنه پس از فراخوانی Action توسط کاربر را مشخص می کنید.

انتقال از فراخوان اصلی به صحنه

در این بخش، شما یک صحنه جدید به نام 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

این به Action شما می‌گوید که از فراخوانی اصلی به صحنه Start منتقل شود.

3. فایل را ذخیره کنید.
4. در ترمینال، یک دایرکتوری scenes جدید در فهرست custom ایجاد کنید:

mkdir custom/scenes 

5. یک فایل جدید به نام Start.yaml در فهرست scenes ایجاد کنید که نمایانگر صحنه start در Action شما است:

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 تعریف می کند که با ورود کاربر به صحنه چه اتفاقی می افتد.

در این حالت، هنگامی که کاربر برای اولین بار وارد صحنه Start می شود، اعلان ( Before you continue on your quest... ) به صف prompt اضافه می شود.

اصطلاحات کلیدی:

• صف اعلان: اعلان ها در یک صف اعلان به یکدیگر اضافه می شوند. قبل از اینکه کاربر بتواند پاسخ دهد، Assistant همه درخواست‌های موجود در صف درخواست را به کاربر ارائه می‌دهد.

تراشه های پیشنهادی را اضافه کنید

تراشه‌های پیشنهاد پیشنهادات قابل کلیکی را برای کاربر ارائه می‌دهند که Action شما به عنوان ورودی کاربر پردازش می‌کند. در این بخش، تراشه‌های پیشنهادی 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. فایل را ذخیره کنید.

اکشن خود را در شبیه ساز تست کنید

در این مرحله، Action شما باید از فراخوانی اصلی به صحنه Start منتقل شود و از کاربر بپرسد که آیا مایل است طالع خود را بیان کند یا خیر. تراشه های پیشنهادی نیز باید در نمایشگر شبیه سازی شده ظاهر شوند.

برای آزمایش 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. روی Test کلیک کنید تا به شبیه ساز هدایت شوید.
4. Talk to my test app را در قسمت Input تایپ کنید و Enter فشار دهید. اکشن شما باید با فرمان Main invocation و اعلان صحنه Start اضافه شده پاسخ دهد، "قبل از اینکه به جستجوی خود ادامه دهید، آیا دوست دارید بخت شما گفته شود؟" ، با تراشه های پیشنهادی نمایش داده شده است.

تصویر زیر این تعامل را نشان می دهد:

گزارش‌های رویداد هر یک از تعاملات شبیه‌ساز شما را در جلسه جاری ثبت می‌کنند، بنابراین گزارش رویداد از آزمایش‌های قبلی شما در این Codelab به عنوان اولین گزارش رویداد ظاهر می‌شود. برای پاک کردن گزارش‌های رویداد، روی Reset Test کلیک کنید.

5. روی تراشه پیشنهاد بله یا خیر کلیک کنید تا به درخواست پاسخ دهید. (همچنین می توانید بگویید "بله" یا "خیر" یا Yes یا No را در قسمت ورودی وارد کنید.)

وقتی به درخواست پاسخ می‌دهید، Action شما با پیامی پاسخ می‌دهد که نشان می‌دهد نمی‌تواند ورودی شما را بفهمد: "متأسفم، متوجه نشدم. می‌توانید دوباره امتحان کنید؟" از آنجایی که هنوز Action خود را برای درک و پاسخ دادن به ورودی «بله» یا «خیر» پیکربندی نکرده‌اید، Action شما ورودی شما را با یک هدف NO_MATCH مطابقت می‌دهد.

اصطلاحات کلیدی:

• NO_MATCH : یک هدف catch-all که وقتی کاربر چیزی می گوید که نمی تواند با هدف دیگری در Action شما مطابقت داشته باشد مطابقت دارد.
• هدف سیستم : هدفی که به طور پیش‌فرض پیکربندی می‌شود و رویدادهای رایج سیستم را مدیریت می‌کند، مانند زمانی که کاربر ورودی ارائه نمی‌کند. NO_MATCH و intent مرتبط با فراخوانی اصلی نمونه هایی از مقاصد سیستم هستند.

به طور پیش‌فرض، هدف سیستم NO_MATCH پاسخ‌های عمومی را ارائه می‌دهد، اما می‌توانید این پاسخ‌ها را سفارشی کنید تا به کاربر نشان دهید که ورودی او را متوجه نشده‌اید. دستیار مکالمه کاربر با Action شما را پس از اینکه سه بار با ورودی کاربر مطابقت نداشته باشد پایان می‌دهد.

نیات yes و no اضافه کنید

اکنون که کاربران می‌توانند به سؤالی که Action شما می‌پرسد پاسخ دهند، می‌توانید Action خود را برای درک پاسخ‌های کاربران پیکربندی کنید ( "بله" یا "خیر" ). در بخش‌های بعدی، مقاصد سفارشی ایجاد می‌کنید که با گفتن «بله» یا «خیر» کاربر مطابقت دارند و این مقاصد را به صحنه 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 intent را به صحنه Start اضافه کنید

اکنون، Action می‌تواند بفهمد که یک کاربر قصد «بله» را بیان می‌کند. می‌توانید هدف سفارشی yes به صحنه Start اضافه کنید، زیرا کاربر به دستور Start پاسخ می‌دهد (" قبل از اینکه به تلاش خود ادامه دهید، آیا می‌خواهید بخت خود را بگویید؟" ).

برای افزودن این هدف سفارشی به صحنه Start ، مراحل زیر را دنبال کنید:

1. custom/scenes/Start.yaml را در ویرایشگر متن خود باز کنید.
2. intentEvents و yes handler را به انتهای فایل 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 را در شبیه ساز تست کنید

در این مرحله، 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. روی Test کلیک کنید تا به شبیه ساز هدایت شوید.
4. برای آزمایش Action خود در شبیه ساز، Talk to my test app را در قسمت Input تایپ کنید و Enter فشار دهید.
5. Yes را در قسمت Input تایپ کرده و Enter فشار دهید. یا روی تراشه پیشنهاد بله کلیک کنید.

اکشن شما به کاربر پاسخ می دهد و به او می گوید که ثروت او به کمکی که انتخاب می کند بستگی دارد. سپس Action شما جلسه را به پایان می‌رساند زیرا شما انتقال 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 اضافه کنید

اکنون، Action می‌تواند بفهمد که کاربر در حال بیان «نه» یا چیزی شبیه به «نه» ، مانند «نه» است. شما باید هدف no سفارشی را به صحنه Start اضافه کنید زیرا کاربر به دستور Start پاسخ می دهد (" قبل از اینکه به جستجوی خود ادامه دهید، آیا می خواهید بخت خود را بگویید؟" ).

برای افزودن این intent به صحنه Start ، مراحل زیر را دنبال کنید:

1. custom/scenes/Start.yaml را در ویرایشگر متن خود باز کنید.
2. در Start.yaml زیر no yes زیر را اضافه کنید:

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 قصد در شبیه ساز تست کنید

در این مرحله، 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. روی Test کلیک کنید تا به شبیه ساز هدایت شوید.
4. Talk to my test app را در قسمت Input تایپ کنید و Enter فشار دهید.
5. No را در قسمت Input تایپ کنید و Enter فشار دهید. یا روی تراشه No پیشنهاد کلیک کنید.

Action شما به جای اینکه به کاربر ثروت خود را بدهید، برای او در سفر آرزوی موفقیت می کند. سپس Action شما جلسه را به پایان می‌رساند زیرا شما انتقال End conversation را برای no قصد پیکربندی کرده‌اید.

5. اجرای تحقق

در حال حاضر، پاسخ‌های Action شما ثابت هستند. هنگامی که یک صحنه حاوی یک درخواست فعال می شود، Action شما هر بار همان درخواست را ارسال می کند. در این بخش، شما تحققی را پیاده سازی می کنید که حاوی منطق ایجاد یک پاسخ مکالمه پویا است.

اصطلاح کلیدی :

• Fulfillment : کدی که حاوی منطق Action شماست. یک وب هوک بر اساس رویدادهایی که در Actions شما رخ می دهد، تماس هایی را برای تحقق شما ایجاد می کند.

تکمیل شما مشخص می کند که کاربر یک کاربر بازگشتی است یا یک کاربر جدید و پیام تبریک Action را برای کاربران بازگشتی تغییر می دهد. پیام تبریک برای کاربران بازگشتی کوتاه شده و بازگشت کاربر را تأیید می کند: " یک سلام شگفت انگیز، ماجراجو! به سرزمین افسانه ای گریفینبرگ خوش آمدید!"

برای این لبه کد، از ویرایشگر توابع ابری برای ویرایش و استقرار کد تکمیل خود استفاده می کنید.

اصطلاح کلیدی :

• ویرایشگر Cloud Functions : یک ویرایشگر یکپارچه برای پروژه‌های Actions که می‌توانید از آن برای ویرایش و استقرار کد تکمیل خود با استفاده از Cloud Functions برای Firebase استفاده کنید.

Action شما می‌تواند وب هوک‌هایی را راه‌اندازی کند که انجام شما را از رویدادی که در طول فراخوانی یا بخش‌های خاصی از اجرای صحنه رخ می‌دهد، مطلع می‌کند. هنگامی که یک وب هوک راه‌اندازی می‌شود، Action شما درخواستی را با یک بار JSON به همراه نام کنترل‌کننده برای پردازش رویداد ارسال می‌کند. این کنترلر مقداری منطق را انجام می دهد و یک پاسخ JSON مربوطه را برمی گرداند.

رضایت خود را بسازید

در این بخش، اجرای خود را تغییر می‌دهید تا وقتی کاربران Action شما را فراخوانی می‌کنند، درخواست‌های مختلفی برای کاربران بازگشتی و کاربران جدید ایجاد کنید.

برای افزودن این منطق به تحقق خود، این مراحل را دنبال کنید:

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 ) را تعریف می‌کند و به Action شما می‌گوید که از توابع ابری به‌عنوان نقطه پایانی هوک استفاده کند.

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 Fulfillment برای Node.js استفاده می‌کند، به درخواست‌های HTTP از دستیار Google پاسخ می‌دهد.

در قطعه کد قبلی، کنترل کننده greeting را تعریف می کنید، که بررسی می کند آیا کاربر قبلاً از Action با ویژگی lastSeenTime بازدید کرده است یا خیر. اگر خاصیت lastSeenTime تعریف نشده باشد، کاربر جدید است و تبریک در نظر گرفته شده برای کاربران جدید را دریافت می کند. در غیر این صورت، پیام بازگشت کاربر را تأیید می کند و یک تبریک اصلاح شده ایجاد می کند.

فراخوان اصلی را به‌روزرسانی کنید تا یک هوک را راه‌اندازی کنید

اکنون که تابع greeting را تعریف کرده‌اید، می‌توانید کنترل‌کننده رویداد greeting را در هدف فراخوانی اصلی خود پیکربندی کنید تا Action شما بداند وقتی کاربر اقدام شما را فراخوانی می‌کند، این تابع را فراخوانی کند.

برای پیکربندی Action خود برای فراخوانی کنترل کننده greeting جدید، این مراحل را دنبال کنید:

1. custom/global/actions.intent.MAIN.yaml را در ویرایشگر متن خود باز کنید.
2. کد زیر را جایگزین کد actions.intent.MAIN.yaml کنید:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. فایل را ذخیره کنید.

اکنون، هنگامی که هدف اصلی فراخوانی شما مطابقت دارد، کنترل کننده وب هوک greeting فراخوانی می شود.

فراخوان اصلی به روز شده را در شبیه ساز تست کنید

برای آزمایش Action خود در شبیه ساز، مراحل زیر را دنبال کنید:

1. در ترمینال دستور زیر را اجرا کنید:

از آنجایی که این دستور webhook را مستقر می کند و وابستگی ها را نصب می کند، ممکن است بیشتر از دستورات قبلی طول بکشد.

gactions deploy preview

اگر خطای 403 در مورد Cloud Build API یا خطای 403 در مورد مرتبط کردن حساب صورت‌حساب خود دریافت کردید، به فعال کردن، غیرفعال کردن یا تغییر صورت‌حساب برای یک پروژه مراجعه کنید. برای استقرار با استفاده از توابع Cloud، باید یک حساب صورت‌حساب را با پروژه خود در Google Cloud مرتبط کنید. پس از مرتبط کردن یک حساب صورت‌حساب، gactions deploy preview اجرا کنید. برای جلوگیری از تحمیل هزینه، مراحل موجود در بخش Clean up your project در انتهای این کد لبه را دنبال کنید.

شما باید خروجی به شکل زیر دریافت کنید:

✔ 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. برای آزمایش Action خود در شبیه ساز، Talk to my test app را در قسمت Input تایپ کنید و Enter فشار دهید.

از آنجایی که اکشن خود را قبلاً در این کد لبه آزمایش کرده‌اید، کاربر جدیدی نیستید، بنابراین پیام تبریک کوتاه شده زیر را دریافت می‌کنید: " یک سلام شگفت‌انگیز، ماجراجو! به سرزمین افسانه‌ای گریفینبرگ خوش آمدید!..."

6. Action را با Actions Builder تجسم کنید

Action SDK دارای قابلیت همکاری با یک IDE مبتنی بر وب به نام Actions Builder است که در کنسول Actions ادغام شده است. شما می توانید سیستم فایل محلی خود را به پیش نویس Action خود در کنسول با دستور gactions push دهید. برخلاف gactions deploy preview ، که فقط به شما اجازه می‌دهد تا Action خود را در شبیه‌ساز آزمایش کنید، gactions push تمام محتوا را از فایل‌های محلی شما به Actions Builder منتقل می‌کند.

کنسول Actions یک نمایش بصری از پیکربندی Action شما ارائه می دهد. دیدن Action شما که به صورت بصری ترسیم شده است می تواند در طول توسعه مفید باشد و بر نسخه ای از Action شما که برای آزمایش ارائه می شود تأثیر نمی گذارد.

در صورتی که به صورت مشترک کار می کنید، gactions push در حال اجرا، پیش نویس فعلی پروژه Actions شما را لغو می کند.

برای انجام پروژه Actions خود و مشاهده آن در کنسول Actions، این مراحل را دنبال کنید:

1. در ترمینال، دستور زیر را اجرا کنید تا پروژه خود را به کنسول Actions هدایت کنید:

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. در کنسول Actions ، روی Develop در نوار پیمایش بالا کلیک کنید.
4. روی پیکان کشویی کنار صحنه ها کلیک کنید و روی Start کلیک کنید. همانطور که در تصویر زیر نشان داده شده است، باید یک نمایش بصری از صحنه Start Action خود را ببینید:

پروژه خود را تمیز کنید [توصیه می شود]

احتیاط : آزمایشگاه کد سطح 2، Build Actions for Google Assistant با استفاده از Actions SDK (سطح 2) ، پروژه ای را که در این کد ایجاد کرده اید، ایجاد می کند. اگر در حال برنامه ریزی برای انجام کدهای سطح 2 هستید، پروژه خود را حذف نکنید. در عوض، می‌توانید آن را در بخش «پاکسازی پروژه‌تان» در انتهای صفحه کد سطح 2 حذف کنید.

برای جلوگیری از تحمیل هزینه های احتمالی، توصیه می شود پروژه هایی را که قصد استفاده از آنها را ندارید حذف کنید. برای حذف پروژه هایی که در این کد لبه ایجاد کرده اید، مراحل زیر را دنبال کنید:

1. برای حذف پروژه Cloud و منابع، مراحل ذکر شده در بخش Shutting down (حذف) پروژه ها را کامل کنید.

مطمئن شوید که پروژه صحیح را برای حذف در صفحه تنظیمات پلتفرم Google Cloud انتخاب کرده اید.

2. اختیاری: برای حذف فوری پروژه از کنسول Actions، مراحل فهرست شده در بخش Delete a project را تکمیل کنید. اگر این مرحله را کامل نکنید، پروژه شما به طور خودکار پس از تقریبا 30 روز حذف می شود.

7. تبریک می گویم!

شما اصول اولیه ساخت Actions برای Google Assistant را با Actions SDK می دانید.

آنچه شما پوشش داده اید

• نحوه راه اندازی یک پروژه Actions در کنسول Actions
• چگونه از Actions SDK برای ساخت پروژه Actions خود در سیستم فایل محلی خود استفاده کنید
• چگونه یک درخواست به فراخوان اصلی اضافه کنیم تا کاربران بتوانند با Action شما گفتگو را شروع کنند
• نحوه ایجاد یک رابط مکالمه با صحنه‌ها، مقاصد، انتقال‌ها، تراشه‌های پیشنهاد و تحقق
• چگونه اکشن خود را با شبیه ساز اکشن تست کنید

بیشتر بدانید

منابع زیر را کاوش کنید تا درباره ساخت Actions برای Google Assistant اطلاعات بیشتری کسب کنید:

• سایت اسناد رسمی برای توسعه Actions for Google Assistant
• اقدامات در صفحه Google GitHub برای کد نمونه و کتابخانه ها
• انجمن رسمی Reddit برای توسعه دهندگانی که با Assistant کار می کنند

برای آخرین اطلاعیه‌ها ، @ActionsOnGoogle را در توییتر دنبال کنید و با #AoGDevs توییت کنید تا آنچه می‌سازید به اشتراک بگذارید!

نظرسنجی بازخورد

قبل از رفتن، لطفاً یک نظرسنجی مختصر در مورد تجربه خود پر کنید.