Zarejestruj działania niestandardowe na urządzeniu

Urządzenie może mieć szczególne umiejętności, których nie obejmuje obecny zestawcechy – na przykład „mrugnięcie światłem” w przypadku urządzenia, które może migać lampkami. Możesz zdefiniować dla urządzenia niestandardowe działania, czyli polecenia wysyłane do urządzenia, które aktywują specjalne umiejętności.

Aby zdefiniować niestandardowe działanie urządzenia, potrzebne są:

  • Wzorzec pasujący do zapytania użytkownika
  • Niestandardowe działanie związane z urządzeniem do powiązania z dopasowanym zapytaniem
  • Tekst odczytywany użytkownikowi, jeśli urządzenie obsługuje to działanie.
  • nazwa polecenia, która jest wysyłana z powrotem na urządzenie, wraz z wszystkimi parametrami;

Niestandardowe działanie urządzenia możesz utworzyć, umieszczając te informacje w pakiecie działań. Pakiety akcji określają format odpowiedzi Asystenta. W odróżnieniu od pakietu SDK Actions niestandardowe działania urządzeń są wykonywane lokalnie – nie określa się punktu końcowego do przetwarzania żądań i odpowiadania na nie. Niestandardowe działania na urządzeniach nie mają charakteru konwersacyjnego.

Utwórz pakiet działań

Na podstawie tego przykładu utwórz plik (np. actions.json) z definicją polecenia testowego: mruganie diodą LED. Skopiuj go z przykładowego kodu pobranego w poprzednim kroku:

cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/grpc/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .
Przykład
{
    "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"
                    ]
                }
            ]
        }
    ]
}

W poprzednim przykładzie do zdefiniowania niestandardowego działania na urządzeniu służą te informacje:

  • Wzorzec pasujący do zapytania użytkownika (mrugnięcie N razy)
  • Niestandardowe działanie związane z urządzeniem, które ma być powiązane z dopasowanym zapytaniem (com.example.actions.BlinkLight) na potrzeby organizacji
  • Tekst odczytywany do użytkownika, jeśli urządzenie obsługuje to działanie (miga N razy)
  • Nazwa polecenia (com.example.commands.BlinkLight), która jest wysyłana z powrotem na urządzenie, wraz ze wszystkimi parametrami (liczbą i ewentualnie opisem szybkości).

Aby zdefiniować wzorzec zapytania, pamiętaj o tych kwestiach:

  • We wzorcu zapytania możesz używać typów zdefiniowanych schema.org.
  • Tablica types [...] definiuje listę typów niestandardowych (np. $Speed).
  • We wzorcu zapytania możesz używać typów niestandardowych. Użytkownik może wypowiedzieć dowolny z synonimów pasujących do wzorca zapytania,
  • Jeśli synonimy zostaną dopasowane, wystąpienie typu (speed) zwróci znormalizowany klucz (SLOWLY). W takim przypadku może istnieć wiele elementów, np. różne światła obsługują różne szybkości migania.
  • Niektóre części wzorca zamiany tekstu na mowę żądania mogą być opcjonalne. Na przykład użyj we wzorcu zapytania ($Speed:speed)?, aby ta część była opcjonalna.
  • Ciąg $type.raw (np. $speed.raw) w przekształcaniu tekstu w odpowiedzi jest zastępowany słowami, które faktycznie wymówił.

Opisy wielu z tych pól znajdziesz w dokumentacji ActionPackage.

Wdrażanie pakietu akcji

Po utworzeniu niestandardowego działania urządzenia w pakiecie akcji możesz udostępnić ten pakiet akcji Asystentowi.

Opisane tu czynności można wykonać na urządzeniu, ale w systemie programistycznym może być łatwiej. Poniższe polecenia nie wymagają do uruchomienia środowiska wirtualnego.

  1. Pobierz narzędzie wiersza poleceń gactions.

  2. Usuń wszystkie dane logowania z tego samego katalogu co narzędzie gactions.

    rm creds.data
  3. Zapisz pakiet Action w Google za pomocą interfejsu wiersza poleceń gactions. Zastąp project_id identyfikatorem projektu w Actions Console.

    ./gactions update --action_package actions.json --project project_id
  4. Przy pierwszym uruchomieniu tego polecenia otrzymasz adres URL i prośbę o zalogowanie się. Skopiuj adres URL i wklej go w przeglądarce (można to zrobić w dowolnym systemie). Na stronie pojawi się prośba o zalogowanie się na konto Google. Zaloguj się na konto Google, na którym utworzono projekt w poprzednim krok.

  5. Gdy zatwierdzisz prośbę o zgodę z interfejsu API, w przeglądarce pojawi się kod, np. „4/XXXX”. Skopiuj ten kod i wklej go do terminala:

    Enter the authorization code:

    Jeśli autoryzacja się powiodła, zobaczysz odpowiedź podobną do tej:

    Your app for the Assistant for project my-devices-project was successfully
    updated with your actions.
    
  6. Wdróż pakiet akcji w trybie testowym za pomocą interfejsu wiersza poleceń gactions. Przed uruchomieniem tego polecenia musisz co najmniej raz zapisać pakiet akcji w Google. Tryb testowy włącza pakiet akcji tylko na Twoim koncie użytkownika.

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

    Obecnie nie możesz przetestować projektu za pomocą Actions Simulator (Symulatora Actions).

  7. Aby zaktualizować pakiet akcji, użyj polecenia gactions update.

  8. (Opcjonalnie) Możesz tworzyć zlokalizowane pakiety działań, aby umożliwić obsługę wielu różnych języków i regionów jednocześnie w ramach jednego projektu.

Modyfikowanie przykładu

Wykonaj czynności opisane w tej sekcji na urządzeniu.

nano pushtotalk.py

Dodaj moduł obsługi działania niestandardowego. Zwróć uwagę, że poniższy moduł obsługi został już dodany do przykładowego kodu podanego powyżej przykładowego pakietu akcji.

...

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)

Uruchamianie przykładu

Uruchom kod źródłowy.

python pushtotalk.py

Spróbuj zadać zapytanie. W podanym wyżej przykładzie spróbuj wykonać te czynności:

Mrugnij 5 razy.

Pamiętaj, że zapytanie musi pasować do wzorca zapytania w pakiecie akcji.