ثبت اقدامات دستگاه سفارشی

دستگاه شما ممکن است توانایی های خاصی داشته باشد که توسط مجموعه فعلی پوشش داده نشده استصفات-- مانند ویژگی "چراغ من چشمک زن" برای دستگاهی که می تواند چراغ های خود را چشمک بزند. می توانید اقدامات سفارشی را برای دستگاه خود تعریف کنید که دستورات ارسال شده به دستگاه شما را برای راه اندازی توانایی های ویژه مشخص می کند.

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

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

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

یک بسته اکشن ایجاد کنید

با استفاده از موارد زیر به عنوان مثال، یک فایل (مانند actions.json ) ایجاد کنید که دستور تست را تعریف می کند: چشمک زدن یک LED. فایل را از نمونه کدی که در مرحله قبل دانلود کرده اید کپی کنید:

cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/library/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .

مثال 
{
    "manifest": {
        "displayName": "Blinky light",
        "invocationName": "Blinky light",
        "category": "PRODUCTIVITY"
    },
    "actions": [
        {
            "name": "com.example.actions.BlinkLight",
            "availability": {
                "deviceClasses": [
                    {
                        "assistantSdkDevice": {}
                    }
                ]
            },
            "intent": {
                "name": "com.example.intents.BlinkLight",
                "parameters": [
                    {
                        "name": "number",
                        "type": "SchemaOrg_Number"
                    },
                    {
                        "name": "speed",
                        "type": "Speed"
                    }
                ],
                "trigger": {
                    "queryPatterns": [
                        "blink ($Speed:speed)? $SchemaOrg_Number:number times",
                        "blink $SchemaOrg_Number:number times ($Speed:speed)?"
                    ]
                }
            },
            "fulfillment": {
                "staticFulfillment": {
                    "templatedResponse": {
                        "items": [
                            {
                                "simpleResponse": {
                                    "textToSpeech": "Blinking $number times"
                                }
                            },
                            {
                                "deviceExecution": {
                                    "command": "com.example.commands.BlinkLight",
                                    "params": {
                                        "speed": "$speed",
                                        "number": "$number"
                                    }
                                }
                            }
                        ]
                    }
                }
            }
        }
    ],
    "types": [
        {
            "name": "$Speed",
            "entities": [
                {
                    "key": "SLOWLY",
                    "synonyms": [
                        "slowly",
                        "slow"
                    ]
                },
                {
                    "key": "NORMALLY",
                    "synonyms": [
                        "normally",
                        "regular"
                    ]
                },
                {
                    "key": "QUICKLY",
                    "synonyms": [
                        "quickly",
                        "fast",
                        "quick"
                    ]
                }
            ]
        }
    ]
}
actions.json

مثال قبلی از اطلاعات زیر برای تعریف عملکرد دستگاه سفارشی استفاده می کند:

  • الگویی برای مطابقت با درخواست کاربر ( N بار چشمک زدن )
  • عملکرد دستگاه سفارشی برای مرتبط کردن با یک جستجوی منطبق ( com.example.actions.BlinkLight ) برای اهداف سازمانی
  • در صورتی که دستگاه از این عمل پشتیبانی کند، متن به کاربر بازگردانده می‌شود ( N بار چشمک می‌زند )
  • نام فرمان ( com.example.commands.BlinkLight ) که به همراه هر پارامتری (یک عدد و احتمالاً شرح سرعت) به دستگاه ارسال می‌شود.

برای تعریف الگوی پرس و جو به موارد زیر توجه کنید:

  • می توانید از انواع تعریف شده توسط schema.org در الگوی پرس و جو استفاده کنید.
  • آرایه types [...] لیستی از انواع سفارشی را تعریف می کند (مثلاً $Speed ).
  • می توانید از انواع سفارشی در الگوی پرس و جو استفاده کنید. کاربر می تواند هر یک از مترادف ها را در نوع سفارشی شما برای مطابقت با الگوی پرس و جو بیان کند.
  • هنگامی که یک مترادف مطابقت دارد، نوع نمونه ( speed ) کلید نرمال شده ( SLOWLY ) را برمی گرداند. در صورتی که به عنوان مثال، چراغ های مختلفی وجود داشته باشد که سرعت های مختلف چشمک زدن را پشتیبانی می کند، می تواند چندین موجود باشد.
  • بخش هایی از الگوی TTS درخواست می تواند اختیاری باشد. به عنوان مثال، از ($Speed:speed)? در الگوی پرس و جو تا این قسمت اختیاری شود.
  • $ type .raw (به عنوان مثال، $speed.raw ) در پاسخ TTS با کلمه(هایی) که کاربر واقعا صحبت کرده است جایگزین می شود.

برای توضیحات بسیاری از این فیلدها، به مستندات ActionPackage مراجعه کنید.

بسته اکشن را مستقر کنید

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

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

  1. ابزار خط فرمان gactions دانلود کنید.

  2. هر گونه اعتبار موجود را از همان دایرکتوری ابزار gactions حذف کنید.

    rm creds.data

  3. با استفاده از gactions CLI بسته Action خود را در Google ذخیره کنید. شناسه پروژه Actions Console خود را جایگزین project_id کنید.

    ./gactions update --action_package actions.json --project project_id

  4. اولین باری که این دستور را اجرا می کنید یک URL به شما داده می شود و از شما خواسته می شود که وارد شوید. URL را کپی کرده و در مرورگر جایگذاری کنید (این کار را می توان در هر سیستمی انجام داد). صفحه از شما می خواهد که به حساب Google خود وارد شوید. وارد حساب Google شوید که پروژه را در قبلی ایجاد کرده استقدم .

  5. پس از تایید درخواست مجوز از API، کدی مانند "4/XXX" در مرورگر شما ظاهر می شود. این کد را کپی کرده و در ترمینال قرار دهید:

    Enter the authorization code:

    اگر مجوز موفقیت آمیز بود، پاسخی شبیه به زیر خواهید دید: 

    Your app for the Assistant for project my-devices-project was successfully
updated with your actions.

  6. بسته اکشن خود را با استفاده از gactions CLI در حالت تست قرار دهید. قبل از اجرای این دستور باید حداقل یک بار بسته Action خود را در Google ذخیره کرده باشید. حالت تست بسته Action را فقط در حساب کاربری شما فعال می کند. 

    ./gactions test --action_package actions.json --project project_id

    در حال حاضر، نمی توانید پروژه را با استفاده از شبیه ساز Actions آزمایش کنید.

  7. برای به روز رسانی بسته Action از دستور gactions update استفاده کنید.

  8. (اختیاری) می‌توانید بسته‌های اکشن محلی را برای پشتیبانی از زبان‌ها و زبان‌های مختلف به طور همزمان در یک پروژه ایجاد کنید.

نمونه را اصلاح کنید

مراحل این قسمت را روی دستگاه انجام دهید. 

nano hotword.py

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

import time # Add this to the imports near the top of the file

...

if event.type == EventType.ON_DEVICE_ACTION:
    for command, params in event.actions:
        print('Do command', command, 'with params', str(params))

        # Add the following lines after the existing line above:

        if command == "com.example.commands.BlinkLight":
            number = int( params['number'] )
            for i in range(int(number)):
                print('Device is blinking.')
                # GPIO.output(25, 1)
                time.sleep(1)
                # GPIO.output(25, 0)
                time.sleep(1)

نمونه را اجرا کنید

کد منبع اصلاح شده را اجرا کنید. 

python hotword.py --device-model-id my-model

یک پرس و جو را امتحان کنید. برای مثال بالا، موارد زیر را امتحان کنید:

اوکی گوگل، 5 بار پلک بزنید.

توجه داشته باشید که پرس و جو باید با الگوی پرس و جو در Action Package مطابقت داشته باشد.