تسجيل إجراءات الجهاز المخصَّصة

قد يكون لجهازك قدرات خاصة لا تشملها مجموعة السمات -- مثل "وميض المصباح" لجهاز يمكنه وميض أضوائه. إِنْتَ تحديد إجراءات مخصصة لجهازك تحدد الأوامر المرسلة إلى جهازك لإطلاق قدرات خاصة.

لتحديد إجراء مخصّص للجهاز، يجب توفّر ما يلي:

• نمط للمطابقة مع طلب بحث المستخدم
• إجراء مخصّص في الجهاز لربطه بطلب بحث مطابق
• النص الذي يتم قوله للمستخدم إذا كان الجهاز يدعم الإجراء
• اسم أمر يتم إرساله مرة أخرى إلى جهازك، بالإضافة إلى أي معلمات

يمكنك إنشاء إجراء الجهاز المخصص من خلال وضع هذه المعلومات في الإجراء. تحدِّد حِزم الإجراءات تنسيق ردود "مساعد Google". وعلى عكس حزمة تطوير البرامج (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 التوثيق.

نشر حزمة الإجراءات

بعد إنشاء إجراء الجهاز المخصّص في حزمة إجراءات، يمكنك إجراء ما يلي: حزمة الإجراءات متاحة لـ "مساعد Google".

يمكنك تنفيذ الخطوات الواردة في هذا القسم على جهازك، ولكن قد يكون ذلك أكثر سهولة. لتنفيذها على نظام التطوير لديك لا تتطلب الأوامر التالية بيئة افتراضية لتشغيلها.

1. نزِّل أداة سطر الأوامر gactions.

2. أزِل أي بيانات اعتماد حالية من الدليل نفسه الذي يتضمّن gactions. .

   rm creds.data

3. احفظ حزمة الإجراءات على Google باستخدام واجهة سطر الأوامر "gactions". استبدال project_id بمشروعك في "وحدة تحكّم المهام" المعرّف:

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

4. عند تشغيل هذا الأمر لأول مرة، سيظهر لك عنوان URL وسيُطلب منك لتسجيل الدخول. انسخ عنوان URL والصقه في متصفح (يمكن إجراء ذلك على أي نظام). ستطلب منك الصفحة تسجيل الدخول إلى حسابك في Google. تسجيل إلى حساب Google الذي أنشأ المشروع في الخطوة.

5. بعد الموافقة على طلب الإذن من واجهة برمجة التطبيقات، سيظهر رمز في المتصفح، مثل " 4/XXXX". انسخ هذا الرمز والصقه في محطة طرفية:

   Enter the authorization code:

   إذا تمت عملية التفويض بنجاح، سيظهر لك ردّ مشابه ما يلي:

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

6. انشر حزمة الإجراءات في وضع الاختبار باستخدام واجهة سطر الأوامر gactions. يجب أن تكون قد حفظت حزمة الإجراءات الخاصة بك في Google مرة واحدة على الأقل من قبل. بتشغيل هذا الأمر. يعمل وضع الاختبار على تفعيل حزمة الإجراءات على حساب المستخدم فقط.

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

   لا يمكنك حاليًا اختبار المشروع باستخدام محاكي الإجراءات.

7. لتعديل حزمة الإجراءات، استخدِم الأمر gactions update.

8. (اختياري) يمكنك إنشاء حِزم إجراءات مترجَمة. لإتاحة العديد من اللغات واللغات المختلفة في نفس الوقت في مشروع واحد.

تعديل النموذج

نفِّذ الخطوات الواردة في هذا القسم على الجهاز.

nano pushtotalk.py

أضِف معالجًا للإجراء المخصّص. تجدر الإشارة إلى أنّه سبق أن تمّت إضافة المعالج أدناه. إلى نموذج التعليمات البرمجية لنموذج حزمة الإجراءات أعلاه.

...

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 مرات:

لاحظ أن الاستعلام يحتاج إلى مطابقة نمط الاستعلام في حزمة الإجراءات.