O Report State é um recurso importante que permite que a
ação Google Home informe proativamente o status mais recente do
dispositivo do usuário de volta ao Google Home Graph , em vez de esperar por uma
intent QUERY.
O Report State informa ao Google os estados dos dispositivos do usuário
com o agentUserId especificado associado a eles (enviado na solicitação
SYNC original). Quando o Google Assistant quer realizar uma ação
que exige a compreensão do estado atual de um dispositivo, ele pode simplesmente consultar
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 Report State , considerando as luzes de vários provedores em
uma sala de estar, o comando Ok Google, brighten my living room exige
a resolução de várias intents QUERY enviadas para várias nuvens, em vez de
simplesmente procurar os valores de brilho atuais com base no que foi
informado anteriormente. Para oferecer a melhor experiência do usuário,
Assistant precisa ter o estado atual de um dispositivo,
sem exigir uma ida e volta para o dispositivo.
Após a SYNC inicial de um dispositivo, a plataforma envia uma intent QUERY
que reúne o estado do dispositivo para preencher Home Graph .
Depois disso, Home Graph armazena apenas o estado enviado
com Report State .
Observação : as informações de estado subsequentes retornadas por intents EXECUTE e QUERY
não serão armazenadas em Home Graph . É sua responsabilidade
chamar Report State para atualizar Home Graph
com as informações de estado mais recentes. Ao chamar Report State , forneça dados de estado
completos para uma determinada característica. O Home Graph atualiza os estados por
atributo e substitui todos os dados desse atributo quando uma
chamada Report State é feita. Por exemplo, se você estiver informando
o estado do atributo StartStop , o payload
precisa incluir valores para isRunning e isPaused.
Primeiros passos
Para implementar Report State , siga estas etapas:
Ativar a API Google HomeGraph
No 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 :
Observação : verifique se você está usando o projeto correto do GCP ao realizar
estas etapas. Esse é o projeto que corresponde ao ID do projeto smart home .
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 , insira 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 baixado para criar um token da Web JSON (JWT). Para mais informações, consulte
Como autenticar usando uma conta de serviço .
Receba um token de acesso do OAuth 2.0 com o
escopo https://www.googleapis.com/auth/homegraph usando
oauth2l :
oauth2l fetch --credentials service-account.json \
--scope https://www.googleapis.com/auth/homegraph
Crie a solicitação JSON com o agentUserId.
Confira um exemplo de solicitação JSON para o estado e a notificação do relatório:
{
"requestId": "123ABC",
"agentUserId": "user-123",
"payload": {
"devices": {
"states": {
"light-123": {
"on": true
}
}
}
}
} Combine o estado do relatório e o JSON de notificação e o token na sua solicitação HTTP POST
ao endpoint do Google Home Graph. Confira um exemplo de como
fazer a solicitação na linha de comando usando curl, como
teste:
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN " \
-H "Content-Type: application/json" \
-d @request-body.json \
"https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
Java
A biblioteca de cliente da API HomeGraph para Java fornece vinculações para a API Home Graph.
Inicialize o HomeGraphApiServicecredenciais padrão do aplicativo .
Chame o método reportStateAndNotificationReportStateAndNotificationRequestReportStateAndNotificationResponse
// 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 );
}
Observação : Report State deve ser chamada apenas quando
uma intent DISCONNECT for recebida,
indicando que o usuário desvinculou a conta. Testar o estado do relatório
Ferramentas recomendadas para esta tarefa
Para preparar a integração da Cloud-to-cloud para
certificação, é importante testar a Report State .
Para isso, recomendamos usar a ferramenta Home Graph Viewer,
que é um app da Web independente que não requer download nem implantação.
O painel Report State ainda está disponível, mas foi descontinuado e não tem mais suporte.
Painel de estado do relatório
Descontinuado : o uso do Painel Report State foi descontinuado. Pré-requisitos
Antes de testar a integração com Cloud-to-cloud , você precisa
da chave da conta de serviço e do agentUserId. Se você já tiver a chave da conta de serviço e o agentUserId, consulte Implantar o painel Report State .
Observação : para fins de certificação, essa chave JSON é diferente da chave JSON de
produção.
Crie uma nova chave temporária da conta de serviço para testes, que poderá ser excluída
quando a certificação for concluída.
Como 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 :
Observação : verifique se você está usando o projeto correto do GCP ao realizar
estas etapas. Esse é o projeto que corresponde ao ID do projeto smart home .
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 , insira 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.
Como recuperar o agentUserId
Siga estas etapas para recuperar seu agentUserId:
Abra a ferramenta OAuth Playground .
Clique no ícone de engrenagem no canto superior direito para abrir a caixa de diálogo Configuração do OAuth 2.0 .
No campo Endpoints do OAuth , selecione Personalizado .
Especifique os seguintes parâmetros de vinculação de conta usando os valores definidos no console de ações quando você criou o projeto de casa inteligente. Clique em Fechar para salvar suas alterações.
Endpoint de autorização : defina esse parâmetro como o URL de autorização no console.Endpoint do token : defina esse parâmetro como o URL do token no console.ID do cliente OAuth : defina esse parâmetro com o mesmo valor do console.Chave secreta do cliente do OAuth : defina esse parâmetro com o mesmo valor do console.
Figura 1: configuração do OAuth 2.0.
Abra a Etapa 1: selecionar e autorizar APIs . No campo de texto "Input your own scopes", insira "devices" e clique em Authorize APIs .
Observação :se você especificou outros escopos no console, também
especifique-os na Etapa 1 .
Se a etapa anterior tiver sido concluída, você será redirecionado para o endpoint OAuth. Faça login
usando a conta de usuário que você quer testar. Depois de fazer login, você será redirecionado
novamente para o OAuth Playground com a etapa 2 aberta e preenchida com um código de autorização
gerado para você.
Clique em Troca de código autorizado por tokens para receber um token de atualização e um token de acesso.
Na Etapa 3: configurar a solicitação para a API , siga estas etapas:
Defina Método HTTP como POST .
Defina o URI da solicitação como o URL de entrega.
Clique em Enter request body e adicione este exemplo de entrada:
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"inputs": [{
"intent": "action.devices.SYNC"
}]
}
Clique em Enviar a solicitação .
Encontre o valor do campo "agentUserId" na resposta.
Implantar o painel "Estado do relatório"
Depois de ter a chave da conta de serviço e o ID do usuário do agente para seu projeto,
faça o download e implante a versão mais recente no
painel
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 o arquivo de chave da conta
Adicione o agentUserId
Em seguida, clique em Listar .
Todos os seus dispositivos são listados. Depois que a lista for preenchida, use o botão
Refresh para atualizar os estados do dispositivo. Se houver uma mudança no estado do dispositivo,
a linha será destacada em verde.
Respostas de erro
Você pode receber uma das seguintes respostas de erro ao chamar
Report State . Essas respostas são enviadas 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 . As causas comuns
incluem JSON malformado ou o uso de null 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. Isso geralmente significa que não
conseguimos encontrar o dispositivo solicitado. Também pode significar que a conta de usuário
não está vinculada ao Google ou que recebemos um agentUserId inválido. Verifique
se o agentUserId corresponde ao valor fornecido na resposta
SYNC e se você está processando corretamente
as intents DISCONNECT .
Observação : quando um dispositivo está off-line, você precisa informar {"online": false} para
o estado do relatório em até cinco minutos após o comportamento do dispositivo. Consulte
Erros e exceções para mais
detalhes. 
