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

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

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

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

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

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

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

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

cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/grpc/

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 دانلود کنید.

   توجه: در لینوکس، chmod +x gactions را اجرا کنید تا باینری دانلود شده قابل اجرا باشد.

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

   rm creds.data

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

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

   توجه: اگر پیغام Requested entity is not found مشاهده کردید، باید این کار را انجام دهید پروژه خود را وارد کنید در Action Console.

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 آزمایش کنید.

   توجه: مدت زمان حالت تست 30 روز است. در صورت انقضا، gactions test دوباره اجرا کنید.

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

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

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

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

nano pushtotalk.py

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

توجه: اگر نمونه را بر روی Raspberry Pi با LED خارجی اجرا می‌کنید، می‌توانید دستورالعمل‌های GPIO را در زیر اضافه کرده و از نظر خارج کنید:

...

device_handler = device_helpers.DeviceRequestHandler(device_id)

@device_handler.command('com.example.commands.BlinkLight')
def blink(speed, number):
    logging.info('Blinking device %s times.' % number)
    delay = 1
    if speed == "SLOWLY":
        delay = 2
    elif speed == "QUICKLY":
        delay = 0.5
    for i in range(int(number)):
        logging.info('Device is blinking.')
        # GPIO.output(25, 1)
        time.sleep(delay)
        # GPIO.output(25, 0)
        time.sleep(1)

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

کد منبع را اجرا کنید.

python pushtotalk.py

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

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

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