Estado do relatório

Report State é um recurso importante que permite Home A ação informa proativamente o status mais recente do o dispositivo do usuário de volta para Google Home Graph em vez de esperar QUERY.

O Report State informa ao Google os estados dos dispositivos dos usuários com os agentUserId especificados associados a elas (enviados no solicitação SYNC). Quando Google Assistant quiser realizar uma ação que requer a compreensão do estado atual de um dispositivo, ele pode simplesmente as informações de estado na Home Graph em vez de emitir uma intent QUERY para várias nuvens de terceiros antes de emitir EXECUTE.

Sem Report State, considerando luzes de vários fornecedores em em uma sala de estar, o comando Ok Google, ilumine minha sala de estar exige resolver várias intents QUERY enviadas a várias nuvens, em vez de simplesmente procurando os valores atuais de brilho com base no que relatadas anteriormente. Para a melhor experiência do usuário, O Assistant precisa ter o estado atual de um dispositivo. sem precisar de ida e volta até o dispositivo.

Seguindo o SYNC inicial de um dispositivo, a plataforma envia uma intent QUERY que coleta o estado do dispositivo para preencher Home Graph. Depois disso, o Home Graph armazena apenas o estado que enviado com Report State.

Ao chamar Report State, forneça dados de estado para uma determinada característica. Home Graph atualiza estados em uma com base na característica e substitui todos os dados dessa característica quando A chamada Report State é feita. Por exemplo, se você está relatando para a característica StartStop, o payload precisa incluir valores para isRunning e isPaused.

Primeiros passos

Para implementar Report State, siga estas etapas:

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 seu projeto do smart home.
  3. Clique em ATIVAR.

Criar uma chave de conta de serviço

Siga estas instruções para gerar uma chave da conta de serviço do Google Cloud Console:

Observação: verifique se você está usando o projeto correto do GCP ao executar estas etapas. Esse é o projeto que corresponde ao ID do seu projeto do smart home.
  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 da conta de serviço.

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

  7. Clique em Criar. Um arquivo JSON que contém a chave para o seu computador.

Chamar a API

Selecione uma opção nas guias abaixo:

HTTP

O Home Graph fornece um endpoint HTTP.

  1. 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.
  2. Consiga um token de acesso do OAuth 2.0 com a escopo https://www.googleapis.com/auth/homegraph usando oauth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Crie a solicitação JSON com o agentUserId. Este é um exemplo de solicitação JSON para estado e notificação do relatório:
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. Combine o estado do relatório e o JSON de notificação com o token em seu HTTP POST para o endpoint do Google Home Graph. Aqui está um exemplo de como para fazer a solicitação na linha de comando usando curl, conforme um teste:
  7. 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 (em inglês).

  1. Confira a definição do serviço de buffers de protocolo para a API Home Graph.
  2. Siga a documentação do desenvolvedor do gRPC para gerar stubs de cliente para uma das linguagens compatíveis.
  3. Chame o método ReportStateAndNotification.

Node.js

O cliente Node.js das APIs do Google fornece vinculações para a API Home Graph.

  1. Inicialize o serviço google.homegraph com o Application Default Credentials.
  2. Chame o método reportStateAndNotification com o ReportStateAndNotificationRequest. Ele retorna um Promise com o 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 à API Home Graph.

  1. Inicialize o HomeGraphApiService usando o Application Default Credentials.
  2. Chame o método reportStateAndNotification com o ReportStateAndNotificationRequest. Ele retorna um ReportStateAndNotificationResponse.
  // 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

Ferramentas recomendadas para esta tarefa

Para preparar sua ação para a certificação, é importante testar Report State:

Para isso, recomendamos usar a ferramenta Viewer Home Graph, que é um app da Web independente que não requer download nem implantação.

O painel Report State ainda está disponível, mas descontinuada e não recebe mais suporte.

Painel de estado do relatório

Pré-requisitos

Para testar sua ação, você precisa ter uma conta de serviço Chave e seu agentUserId. Se você já tem a chave da conta de serviço agentUserId, consulte Implantar o Report State Painel.

Implantar o painel de estado do relatório

Quando você tiver a chave da conta de serviço e o ID de usuário do agente do seu projeto, fazer o download e implantar a versão mais recente no Report State Painel. 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 do Report State, acesse o painel do seguinte URL (substitua your_project_id pelo seu ID do projeto):

http://<your-project-id>.appspot.com

No painel, faça o seguinte:

  • Escolha o arquivo da chave da conta
  • Adicionar o agentUserId

Em seguida, clique em Lista.

Todos os seus dispositivos estão listados. Depois que a lista for preenchida, você poderá usar o método Botão Atualizar para atualizar os estados do dispositivo. Se houver uma mudança de estado do dispositivo, a linha é destacada em verde.

Respostas de erro

Você pode receber uma das seguintes respostas de erro ao chamar Report State: Essas respostas vêm na forma de status HTTP e códigos personalizados.

  • 400 Bad Request: não foi possível processar o servidor a solicitação enviada pelo cliente devido a uma sintaxe inválida. Causas comuns incluir JSON incorreto ou usar null em vez de "" para um valor de string.
  • 404 Not Found - O recurso solicitado não pôde ser foram encontradas, mas podem estar disponíveis no futuro. Normalmente, isso significa que não consegue encontrar o dispositivo solicitado. Isso também pode significar que a conta do usuário não está vinculado ao Google ou recebemos um agentUserId inválido. Garanta que o agentUserId corresponde ao valor fornecido no SYNC e estará processamento de intents DISCONNECT.