Registrar ações personalizadas do dispositivo

Seu dispositivo pode ter habilidades especiais não cobertas pelo conjunto atual de características , como "piscar minha luz" para um dispositivo que pode piscar as luzes. Você pode definir ações personalizadas para o dispositivo que especificam os comandos enviados para acionar habilidades especiais.

Para definir uma ação de dispositivo personalizada, você precisa do seguinte:

  • Um padrão para corresponder à consulta do usuário
  • Uma ação de dispositivo personalizada para associar a uma consulta correspondente
  • Texto falado para o usuário se o dispositivo for compatível com a ação
  • Um nome de comando que é enviado de volta ao seu dispositivo, com todos os parâmetros

Crie a ação personalizada do dispositivo colocando essas informações em um pacote de ações. Os pacotes de ações definem o formato das respostas do Google Assistente. Ao contrário do SDK do Actions, as ações personalizadas dos dispositivos são realizadas localmente. Você não especifica um endpoint para processar solicitações e fornecer respostas. As ações personalizadas do dispositivo não são conversacionais por natureza.

Criar um pacote de ações

Usando o exemplo a seguir, crie um arquivo (como actions.json) que defina um comando de teste: um LED piscando. Copie-o do exemplo de código que você salvou em uma etapa anterior:

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

O exemplo anterior usa as seguintes informações para definir a ação personalizada do dispositivo:

  • Um padrão para corresponder à consulta do usuário (pisque N vezes)
  • A ação personalizada do dispositivo a ser associada a uma consulta correspondente (com.example.actions.BlinkLight) para fins organizacionais.
  • Texto falado para o usuário se o dispositivo oferecer suporte à ação (Piscando N vezes).
  • Um nome de comando (com.example.commands.BlinkLight) que é enviado de volta ao dispositivo, com todos os parâmetros (um número e possivelmente uma descrição da velocidade).

Para definir o padrão de consulta, observe o seguinte:

  • É possível usar tipos definidos pelo schema.org no padrão de consulta.
  • A matriz types [...] define a lista de tipos personalizados (por exemplo, $Speed).
  • Você pode usar tipos personalizados no padrão de consulta. O usuário pode falar qualquer um dos sinônimos do tipo personalizado para corresponder ao padrão de consulta.
  • Quando um sinônimo corresponde, a instância de tipo (speed) retorna a chave normalizada (SLOWLY). Pode haver várias entidades no caso, por exemplo, se houver luzes diferentes com suporte a diferentes velocidades de piscar.
  • Partes do padrão de TTS da solicitação podem ser opcionais. Por exemplo, use ($Speed:speed)? no padrão de consulta para tornar essa parte opcional.
  • $type.raw (por exemplo, $speed.raw) na TTS de resposta é substituído pelas palavras que o usuário realmente falou.

Para ver descrições de muitos desses campos, consulte a documentação do ActionPackage.

Implantar o pacote de ações

Depois de criar a ação personalizada do dispositivo em um pacote de ações, ele pode ser acessado pelo Google Assistente.

Embora seja possível realizar as etapas desta seção no seu dispositivo, elas podem ser mais fáceis no seu sistema de desenvolvimento. Os comandos a seguir não exigem um ambiente virtual para serem executados.

  1. Faça o download da ferramenta de linha de comando gactions.

  2. Remova todas as credenciais atuais do mesmo diretório que a ferramenta gactions.

    rm creds.data
  3. Salve o pacote de ações no Google usando a CLI gactions. Substitua project_id pelo ID do projeto do Console do Actions.

    ./gactions update --action_package actions.json --project project_id
    .
  4. Na primeira vez que você executar este comando, receberá um URL e precisará fazer login. Copie e cole o URL em um navegador. Isso pode ser feito em qualquer sistema. A página solicitará que você faça login na sua Conta do Google. Faça login na Conta do Google que criou o projeto em uma etapa etapa.

  5. Depois que você aprovar a solicitação de permissão da API, um código será exibido no navegador, como "4/XXXX". Copie e cole este código no terminal:

    Enter the authorization code:

    Se a autorização for bem-sucedida, você verá uma resposta semelhante a esta:

    Your app for the Assistant for project my-devices-project was successfully
    updated with your actions.
    
  6. Implante o pacote de ação no modo de teste usando a CLI gactions. Você precisa salvar seu pacote de ações no Google pelo menos uma vez antes de executar este comando. O modo de teste ativa o pacote de ações apenas na sua conta de usuário.

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

    No momento, não é possível testar o projeto usando o simulador do Actions.

  7. Para atualizar o pacote de ações, use o comando gactions update.

  8. (Opcional) Você pode criar pacotes de ações localizadas para oferecer suporte a vários idiomas e localidades diferentes ao mesmo tempo em um único projeto.

Modificar o exemplo

Siga as etapas desta seção no dispositivo.

nano pushtotalk.py

Adicione um gerenciador para sua ação personalizada. O gerenciador abaixo já foi adicionado ao exemplo de código do exemplo de pacote de ações acima.

...

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)

Executar a amostra

Execute o código-fonte.

python pushtotalk.py

Faça uma consulta. Para o exemplo acima, tente o seguinte:

Pisque cinco vezes.

A consulta precisa corresponder ao padrão no pacote de ações.