Estado do relatório

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 precisar de 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.

Ao chamar Report State, forneça dados de estado completos para um determinado trait. 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
• Criar uma chave de conta de serviço
• Chamar a API

Ativar a API Google HomeGraph

1. No Google Cloud Console, acesse a página API HomeGraph.

   Acessar a página da API HomeGraph
2. Selecione o projeto que corresponde ao ID do projeto smart home.
3. 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:

1. 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"
2. Na lista Conta de serviço, selecione Nova conta de serviço.
3. No campo Nome da conta de serviço, insira um nome.
4. No campo ID da conta de serviço, insira um ID.

5. Na lista Papel, selecione Contas de serviço > Criador de token de conta de serviço.

6. Em Tipo de chave, selecione a opção JSON.

7. 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:

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
          }
        }
      }
    }
  }
});
    

  // 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);
}
    

Testar o estado do relatório

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

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.

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 Atualizar 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.