보고서 상태

Report State은(는) Google Home 작업이 사용자 기기의 최신 상태를 Google Home Graph에 사전에 보고할 수 있는 중요한 기능입니다. QUERY 인텐트를 기다릴 필요가 없습니다.

Report State는 원래 SYNC 요청에서 전송된 지정된 agentUserId가 연결된 사용자 기기의 상태를 Google에 보고합니다. Google Assistant가 기기의 현재 상태를 파악해야 하는 작업을 실행하려는 경우 EXECUTE 인텐트를 실행하기 전에 다양한 서드 파티 클라우드에 QUERY 인텐트를 실행하는 대신 Home Graph에서 상태 정보를 조회하면 됩니다.

보고서 상태가 없으면 거실에 여러 제공업체의 조명이 있는 경우 _Ok Google, 거실 조명 밝게 해 줘_ 명령어를 실행하려면 이전에 보고된 내용을 기반으로 현재 밝기 값을 조회하는 대신 여러 클라우드에 전송된 여러 인텐트를 해결해야 합니다.Report StateQUERY 최상의 사용자 환경을 제공하려면 Assistant 기기로의 왕복 없이 기기의 현재 상태를 파악해야 합니다.

기기의 초기 SYNC 후 플랫폼은 기기의 상태를 수집하여 Home Graph를 채우는 QUERY 인텐트 를 전송합니다. 이 시점 이후 Home Graph는 Report State와 함께 전송된 상태만 저장합니다.

Report State을 호출할 때는 지정된 특성에 대한 전체 상태 데이터를 제공해야 합니다. Home Graph는 특성별로 상태를 업데이트하고 Report State 호출이 이루어지면 해당 특성의 모든 데이터를 덮어씁니다. 예를 들어 StartStop 특성의 상태를 보고하는 경우 페이로드에는 isRunning 및 isPaused의 값이 모두 포함되어야 합니다.

시작하기

Report State을 구현하려면 다음 단계를 따르세요.

• Google HomeGraph API 사용 설정
• 서비스 계정 키 만들기
• API 호출

Google HomeGraph API 사용 설정

1. Google Cloud Console에서 HomeGraph API 페이지로 이동합니다.

   HomeGraph API 페이지로 이동
2. smart home 프로젝트 ID와 일치하는 프로젝트를 선택합니다.
3. 사용 설정 을 클릭합니다.

서비스 계정 키 만들기

다음 안내에 따라 Google Cloud Console에서 서비스 계정 키를 생성합니다.

1. Google Cloud Console에서 서비스 계정 페이지로 이동합니다.

   서비스 계정 페이지로 이동합니다.

   서비스 계정 페이지로 이동하기 전에 프로젝트를 선택해야 할 수도 있습니다.

2. 추가add서비스 계정 만들기 를 클릭합니다.

3. 서비스 계정 이름 필드에 이름을 입력합니다.

4. 서비스 계정 ID 필드에 ID를 입력합니다.

5. 서비스 계정 설명 필드에 설명을 입력합니다.

6. 만들고 계속하기 를 클릭합니다.

7. 역할 드롭다운에서 서비스 계정 > 서비스 계정 OpenID Connect ID 토큰 생성자를 선택합니다.

8. 계속 을 클릭합니다.

9. 완료 를 클릭합니다.

10. 서비스 계정 목록에서 방금 만든 서비스 계정을 선택하고 키 관리를 more_vert 작업 메뉴에서 선택합니다.

11. 키 추가 > 새 키 만들기 를 선택합니다.

12. 키 유형으로 JSON 옵션을 선택합니다.

13. 만들기 를 클릭합니다. 키가 포함된 JSON 파일이 컴퓨터에 다운로드됩니다.

API 호출

아래 탭에서 옵션을 선택합니다.

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

보고서 상태 테스트

Cloud-to-cloud 통합을 인증을 받을 수 있도록 준비하려면 Report State을(를) 테스트하는 것이 중요합니다.

이렇게 하려면 다운로드 또는 배포가 필요 없는 독립형 웹 앱인 Home Graph 뷰어 도구를 사용하는 것이 좋습니다.

Report State 대시보드는 계속 사용할 수 있지만 지원 중단되었으며 더 이상 지원되지 않습니다.

보고서 상태 대시보드

기본 요건

Cloud-to-cloud 통합을 테스트하려면 서비스 계정 키와 agentUserId가 필요합니다. 서비스 계정 키와 agentUserId가 이미 있는 경우 배포 Report State 대시보드를 참고하세요.

보고서 상태 대시보드 배포

프로젝트의 서비스 계정 키와 에이전트 사용자 ID가 있으면 최신 버전을 다운로드하고 Report State 대시보드에서 배포합니다. 최신 버전을 다운로드한 후 포함된 README.MD 파일의 안내를 따르세요.

Report State 대시보드를 배포한 후 다음 URL에서 대시보드에 액세스합니다 (your_project_id를 프로젝트 ID로 바꿈).

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

대시보드에서 다음을 실행합니다.

• 계정 키 파일 선택
• agentUserId 추가

그런 다음 목록 을 클릭합니다.

모든 기기가 나열됩니다. 목록이 채워지면 새로고침 버튼을 사용하여 기기 상태를 업데이트할 수 있습니다. 기기 상태가 변경되면 행이 녹색으로 강조표시됩니다.

보고서 상태 불일치

쿼리 기반 보고서 상태 정확도는 사용자가 기기를 쿼리할 때 기기의 최신 보고서 상태가 기기의 상태와 얼마나 일치하는지 측정합니다. 이 값은 99.5%여야 합니다. 프로젝트의 보고서 상태 정확도 의 현재 상태에 관한 자세한 내용은 기기 상태 - 상태 정확도를 참고하세요. 로그 탐색기에서 보고서 상태 불일치 로그의 세부정보를 볼 수도 있습니다.

다음은 보고서 상태 불일치 로그의 예입니다.

{
  "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"
}

보고서 상태 불일치 로그 필드 정의

오류 응답

보고서 상태를 호출할 때 다음 오류 응답 중 하나가 표시될 수 있습니다. Report State 이러한 응답은 HTTP 상태 코드 형식으로 제공됩니다.

• 400 Bad Request - 서버에서 클라이언트가 보낸 요청을 잘못된 구문으로 인해 처리할 수 없습니다. 일반적인 원인으로는 잘못된 JSON 또는 문자열 값에 "" 대신 null을 사용하는 것이 있습니다.
• 404 Not Found - 요청된 리소스를 찾을 수 없지만 나중에 제공될 수 있습니다. 일반적으로 이는 요청된 기기를 찾을 수 없음을 의미합니다. 사용자 계정이 Google과 연결되어 있지 않거나 잘못된 agentUserId를 수신했음을 의미할 수도 있습니다. 가 agentUserId 응답에 제공된 값과 일치하고 SYNC 인텐트를 올바르게 처리하는지 확인합니다.

온라인 및 오프라인 상태 보고

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