註冊自訂裝置動作

裝置可能具備目前一組特徵 無法涵蓋的特殊功能，例如可閃爍裝置燈的「閃爍我的燈」特徵。您可以為裝置定義自訂動作，指定傳送至裝置的指令以觸發特殊功能。

如要定義自訂裝置動作，您需要下列項目：

  • 與使用者查詢比對的模式
  • 與比對相符的查詢建立關聯的自訂裝置動作
  • 如果裝置支援這項操作，系統會朗讀給使用者的文字
  • 傳回到裝置的指令名稱，以及所有參數

將這項資訊放入動作套件，即可建立自訂裝置動作。動作套件會定義 Google 助理回應的格式。與 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) 會替換為使用者實際叫用的字詞。

如需許多欄位的說明，請參閱 ActionPackage 說明文件。

部署動作套件

在動作套件中建構自訂裝置動作後，即可開放 Google 助理存取動作套件。

雖然您可以在裝置上執行本節所述的步驟，但在開發系統上操作可能會比較簡單。下列指令不需要虛擬環境執行。

  1. 下載 gactions 指令列工具。

  2. 移除 gactions 工具所在目錄中的任何現有憑證。

    rm creds.data

  3. 使用 gactions CLI 將動作套件儲存至 Google。將 project_id 替換成您的 Actions Console 專案 ID。

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

  4. 首次執行這個指令時，系統會提供您網址並要求您登入。請複製網址並貼到瀏覽器中 (任何系統都不需要這麼做)。 該頁面會要求你登入 Google 帳戶。登入在先前的 步驟。

  5. 在您核准 API 的權限要求之後，瀏覽器內會出現一組代碼，例如「4/XXXX」。複製以下程式碼並貼到終端機中：

    Enter the authorization code:

    如果授權成功，您會看到類似以下的回應：

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

  6. 使用 gactions CLI 將動作套件部署至測試模式。執行這個指令之前，您必須至少將動作套件儲存到 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 次。

請注意，查詢必須符合動作套件中的查詢模式。