O Report State é um recurso importante que permite que a
ação Home informe proativamente o status mais recente do
dispositivo do usuário para Google Home Graph em vez de esperar uma
intent QUERY
.
O Report State informa ao Google os estados dos dispositivos de usuários
com o agentUserId
especificado associado a eles (enviado na solicitação
SYNC
original). Quando o Google Assistant quiser realizar uma ação
que exija a compreensão do estado atual de um dispositivo, ele poderá simplesmente pesquisar
as informações de estado no Home Graph em vez
de emitir uma intent QUERY
para várias nuvens de terceiros antes de emitir a
intent EXECUTE
.
Sem o Report State, considerando as luzes de vários provedores em uma sala de estar, o comando Ok Google, iluminar minha sala de estar requer a resolução de várias intents QUERY
enviadas para várias nuvens, em vez de simplesmente procurar os valores atuais de brilho com base no que foi informado anteriormente. Para a melhor experiência do usuário,
o Assistant precisa ter o estado atual de um dispositivo,
sem a necessidade de um trajeto de ida e volta.
Após o SYNC
inicial de um dispositivo, a plataforma envia uma intent QUERY
que coleta o estado do dispositivo para preencher Home Graph.
Depois desse ponto, o Home Graph armazena apenas o estado
enviado com Report State.
Ao chamar Report State, forneça dados de estado
completos para uma determinada característica. Home Graph atualiza os estados
por característica e substitui todos os dados dessa característica quando uma
chamada Report State é feita. Por exemplo, se você estiver relatando o estado da característica StartStop, o payload precisará incluir valores para isRunning
e isPaused
.
Começar
Para implementar o Report State, siga estas etapas:
Ativar a API Google HomeGraph
-
Em Google Cloud Console, acesse a página API HomeGraph.
Acessar a página da API HomeGraph - Selecione o projeto que corresponde ao ID do projeto smart home.
- Clique em ATIVAR.
Criar uma chave de conta de serviço
Siga estas instruções para gerar uma chave de conta de serviço do Google Cloud Console:
-
No Google Cloud Console, acesse a página Criar chave da conta de serviço.
Acessar página "Criar chave da conta de serviço" - Na lista Conta de serviço, selecione Nova conta de serviço.
- No campo Nome da conta de serviço, insira um nome.
- No campo ID da conta de serviço, digite um ID.
Na lista Papel, selecione Contas de serviço > Criador de token de conta de serviço.
Em Tipo de chave, selecione a opção JSON.
- Clique em Criar. O download de um arquivo JSON com a chave é feito no computador.
Chamar a API
Selecione uma opção nas guias abaixo:
HTTP
O Home Graph fornece um endpoint HTTP
- Use o arquivo JSON da conta de serviço salvo para criar um JSON Web Token (JWT). Para mais informações, consulte Como autenticar usando uma conta de serviço.
- Consiga um token de acesso do OAuth 2.0 com o escopo
https://www.googleapis.com/auth/homegraph
usando oauth2l: - Crie a solicitação JSON com o
agentUserId
. Veja um exemplo de solicitação JSON para o estado e a notificação do relatório: - Combine o JSON de estado e notificação e o token na solicitação HTTP POST para o endpoint do Google Home Graph. Confira um exemplo de como
fazer a solicitação na linha de comando usando
curl
, como teste:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
O Home Graph fornece um endpoint gRPC
- Acesse a definição de serviço de buffers de protocolo para a API Home Graph.
- Siga a documentação do desenvolvedor do gRPC para gerar stubs de cliente para um dos idiomas compatíveis.
- Chame o método ReportStateAndNotification.
Node.js
O cliente Node.js das APIs do Google fornece vinculações para a API Home Graph.
- Inicialize o serviço
google.homegraph
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com o ReportStateAndNotificationRequest. Ela retorna umPromise
com ReportStateAndNotificationResponse.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
A biblioteca de cliente da API HomeGraph para Java fornece vinculações para a API Home Graph.
- Inicialize o
HomeGraphApiService
usando o Application Default Credentials. - Chame o método
reportStateAndNotification
com oReportStateAndNotificationRequest
. Ela retorna umReportStateAndNotificationResponse
.
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Build device state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
Estado do relatório de teste
Para preparar sua ação para a certificação, é importante testar Report State.
Para fazer isso, recomendamos o uso da ferramenta Visualizador Home Graph, que é um app da Web autônomo que não requer download ou implantação.
O dashboard Report State ainda está disponível, mas foi descontinuado e não é mais compatível.
Painel de estado do relatório
Pré-requisitos
Antes de testar a ação, você precisa da chave da conta de serviço
e do agentUserId
. Se você já tiver a chave da conta de serviço e agentUserId
, consulte Implantar o painel Report State.
Implantar o painel de estado do relatório
Depois de ter a chave da conta de serviço e o ID do usuário do agente do seu projeto,
faça o download e implante a versão mais recente no
Painel do
Report State.
Depois de fazer o download da versão mais recente, siga as instruções do
arquivo README.MD
incluído.
Depois de implantar o painel Report State, acesse-o pelo URL a seguir. Substitua your_project_id pelo ID do projeto:
http://<your-project-id>.appspot.com
No painel, faça o seguinte:
- Escolha seu arquivo de chave da conta
- Adicionar agentUserId
Em seguida, clique em Lista.
Todos os seus dispositivos estão listados. Depois de preencher a lista, use o botão Refresh para atualizar os estados do dispositivo. Se houver uma mudança de estado do dispositivo, a linha será destacada em verde.
Respostas de erro
Talvez você receba uma das seguintes respostas de erro ao chamar Report State. Essas respostas vêm na forma de códigos de status HTTP.
400 Bad Request
: o servidor não conseguiu processar a solicitação enviada pelo cliente devido a uma sintaxe inválida. Causas comuns incluem JSON malformado ou uso denull
em vez de "" para um valor de string.404 Not Found
: o recurso solicitado não foi encontrado, mas pode estar disponível no futuro. Normalmente, isso significa que não encontramos o dispositivo solicitado. Também pode significar que a conta de usuário não está vinculada ao Google ou que recebemos umagentUserId
inválido. Verifique seagentUserId
corresponde ao valor fornecido na resposta SYNC e se você está processando as intents DISCONNECT corretamente.