Estado do relatório

Report State é um recurso importante que permite que a Ação do Google Home informe proativamente o status mais recente do dispositivo do usuário 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 procurar 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 luzes de vários provedores em uma sala de estar, o comando Ok Google, aumente o brilho da minha sala de estar 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, o Assistant precisa ter o estado atual de um dispositivo, sem exigir uma ida e volta ao dispositivo.

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 disso, o Home Graph armazena apenas o estado enviado com Report State.

Ao chamar Report State, forneça dados de estado completos para um determinado atributo. 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 o 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 da API HomeGraph.

   Acesse a página da API HomeGraph
2. Selecione o projeto que corresponde ao ID do projeto do 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 no Google Cloud Console:

1. No Google Cloud Console, acesse a página Contas de serviço.

   Acesse a página Contas de serviço.

   Talvez seja necessário selecionar um projeto antes de acessar a página "Contas de serviço".

2. Clique em addCriar 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. No campo Descrição da conta de serviço, insira uma descrição.

6. Clique em Criar e continuar.

7. No menu suspenso Papel, selecione Contas de serviço > Criador de token de identidade do OpenID Connect da conta de serviço.

8. Clique em Continuar.

9. Clique em Concluído.

10. Selecione a conta de serviço que você acabou de criar na lista de contas de serviço e selecione Gerenciar chaves no menu more_vert Ações.

11. Selecione Adicionar chave > Criar nova chave.

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

13. Clique em Criar. Um arquivo JSON com sua chave será salvo 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).execute();
}
    

Estado do relatório de teste

Para preparar sua integração do Cloud-to-cloud para a certificação, é importante testar o Report State.

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

O painel do 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 do 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 do 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 para seu projeto, baixe 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 seguinte URL (substitua your_project_id pelo ID do seu projeto):

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

No painel, faça o seguinte:

• Escolha o arquivo de chave da conta
• Adicione seu agentUserId

Em seguida, clique em Listar.

Todos os seus dispositivos estã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.

Discrepância no estado do relatório

A precisão do estado do relatório com base em consulta mede o quanto o estado do relatório mais recente de um dispositivo corresponde ao status do dispositivo quando um usuário faz uma consulta. Esse valor precisa ser de 99,5%. Para mais detalhes sobre o status atual da precisão do estado do relatório do seu projeto, consulte Integridade do dispositivo: precisão do estado. Também é possível ver os detalhes do registro de discrepância do estado do relatório na Análise de registros.

Veja um exemplo de registro de discrepância do estado do relatório:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Definições de campo do registro de discrepância de estado do relatório

Respostas de erro

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

400 Solicitação inválida

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 Não encontrado

Não foi possível encontrar o recurso solicitado, mas ele pode estar disponível no futuro. Normalmente, isso 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.

Quando uma chamada ReportState falha com um erro 404 NOT_FOUND, isso indica uma incompatibilidade de sincronização entre sua nuvem e o Home Graph. Isso pode acontecer se um dispositivo for removido do Home Graph ou se um usuário desvincular a conta.

Para lidar com erros 404 do Report State, use o seguinte procedimento:

1. Verifique o status da conta de usuário: chame devices.sync para o agentUserId que retornou um erro 404. Isso ajuda a determinar se o erro é para toda a conta de usuário ou para um dispositivo específico.
   • Se SYNC retornar um erro 404, a conta de usuário não estará mais vinculada ao Google. Pare de enviar o estado do relatório e a sincronização de solicitação para os dispositivos desse usuário.
   • Se SYNC retornar 200 OK, a conta do usuário ainda está vinculada, o que significa que o erro 404 é específico do dispositivo.
2. Reconciliar a lista de dispositivos: se SYNC retornar 200 OK, você precisará identificar quais dispositivos não são mais conhecidos pelo Google. Recomendamos que você compare a lista de dispositivos que o Google tem para o usuário com seu banco de dados de dispositivos e identifique os dispositivos no seu sistema que estão ausentes da lista do Google. Se um dispositivo precisa ser sincronizado com o Google, mas ainda não foi compartilhado com o Google, use SYNC para garantir que o dispositivo seja sincronizado com o Google. Se um dispositivo precisar ser desvinculado do Google, pare de informar o estado dele e continue informando para outros dispositivos válidos nesse agentUserId.

Relatórios de estado on-line e off-line

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }