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

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

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

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

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

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