스마트 홈 작업을 개발하는 방법을 알아볼 수 있는 새로운 공간인 Google Home 개발자 센터에 오신 것을 환영합니다. 참고: Actions 콘솔에서 작업을 계속 만들 수 있습니다.

보고서 상태

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
175

보고서 상태는 스마트 홈 작업이 QUERY 인텐트를 기다리지 않고 사전에 사용자 기기의 최신 상태를 Google Home Graph에 다시 보고할 수 있는 중요한 기능입니다.

상태 agentUserId (원래 SYNC 요청에 전송됨)이 연결된 사용자 기기의 상태를 Google에 보고합니다. Google 어시스턴트는 기기의 현재 상태를 알아야 하는 작업을 수행하려고 할 때 EXECUTE 인텐트를 실행하기 전에 다양한 타사 클라우드에 QUERY 인텐트를 실행하는 대신 홈 그래프에서 상태 정보를 조회하기만 하면 됩니다.

Report State를 사용하지 않는 경우 Ok Google, 거실 밝게 하기 명령은 거실에 있는 여러 제공업체의 조명이 제공되기 때문에 이전에 보고된 항목을 기반으로 현재 밝기 값을 찾는 것이 아니라 여러 클라우드에 전송된 여러 QUERY 인텐트를 확인해야 합니다. 최상의 사용자 환경을 제공하려면 Google 어시스턴트가 기기를 왕복하지 않고도 기기의 현재 상태를 파악하고 있어야 합니다.

기기의 초기 SYNC 다음에 플랫폼은 홈 그래프를 채우기 위해 기기의 상태를 수집하는 QUERY 인텐트를 전송합니다. 그 시점이 지나면 홈 그래프에는 보고서 상태와 함께 전송되는 상태만 저장됩니다.

보고서 상태를 호출할 때 지정된 특성의 전체 상태 데이터를 제공해야 합니다. 홈 그래프는 속성별로 상태를 업데이트하고 보고서 상태 호출이 발생할 때 해당 특성의 모든 데이터를 덮어씁니다. 예를 들어 StartStop 특성의 상태를 보고하는 경우 페이로드에 isRunningisPaused에 대한 값이 모두 포함되어야 합니다.

시작하기

보고서 상태를 구현하려면 다음 단계를 따르세요.

Google HomeGraph API 사용 설정

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

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

서비스 계정 키 만들기

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

참고: 이 단계를 수행할 때는 올바른 GCP 프로젝트를 사용하고 있는지 확인하세요. 스마트 홈 프로젝트 ID와 일치하는 프로젝트입니다.
  1. GCP Console에서 서비스 계정 키 만들기 페이지로 이동합니다.

    서비스 계정 키 만들기 페이지로 이동
  2. 서비스 계정 목록에서 새 서비스 계정을 선택합니다.
  3. 서비스 계정 이름 필드에 이름을 입력합니다.
  4. 서비스 계정 ID 필드에 ID를 입력합니다.
  5. 역할 목록에서 서비스 계정 > 서비스 계정 토큰 생성자를 선택합니다.

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

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

API 호출

아래 탭에서 옵션을 선택하세요.

HTTP

Home Graph API가 HTTP 엔드포인트를 제공합니다.

  1. 다운로드한 서비스 계정 JSON 파일을 사용하여 JSON 웹 토큰 (JWT)을 만듭니다. 자세한 내용은 서비스 계정을 사용하여 인증을 참조하세요.
  2. oauth2l을 사용하여 https://www.googleapis.com/auth/homegraph 범위로 OAuth 2.0 액세스 토큰을 가져옵니다.
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId를 사용하여 JSON 요청을 만듭니다. 다음은 보고서 상태 및 알림에 대한 JSON 요청 샘플입니다.
  5. {
      "requestId": "123ABC",
      "agentUserId": "user-123",
      "payload": {
        "devices": {
          "states": {
            "light-123": {
              "on": true
            }
          }
        }
      }
    }
    
  6. 보고서 상태 및 알림 JSON과 HTTP POST 요청의 토큰을 Google Home Graph 엔드포인트에 결합합니다. 다음은 테스트로 curl를 사용하여 명령줄에서 요청하는 방법의 예입니다.
  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

Home Graph API가 gRPC 엔드포인트를 제공합니다.

  1. Home Graph API의 프로토콜 버퍼 서비스 정의를 가져옵니다.
  2. gRPC 개발자 문서에 따라 지원되는 언어 중 하나의 클라이언트 스텁을 생성합니다.
  3. ReportStateAndNotification 메서드를 호출합니다.

Node.js

Google API Node.js 클라이언트는 Home Graph API에 대한 바인딩을 제공합니다.

  1. 애플리케이션 기본 사용자 인증 정보를 사용하여 google.homegraph 서비스를 초기화합니다.
  2. ReportStateAndNotificationRequest를 사용하여 reportStateAndNotification 메서드를 호출합니다. ReportStateAndNotificationResponse와 함께 Promise를 반환합니다.
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
          }
        }
      }
    }
  }
});
    

자바

자바용 HomeGraph API 클라이언트 라이브러리는 Home Graph API에 대한 바인딩을 제공합니다.

  1. 애플리케이션 기본 사용자 인증 정보를 사용하여 HomeGraphApiService를 초기화합니다.
  2. ReportStateAndNotificationRequest를 사용하여 reportStateAndNotification 메서드를 호출합니다. 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);
}
    

테스트 보고서 상태

작업을 인증받을 수 있도록 보고서 상태를 테스트하는 것이 중요합니다.

기본 요건

작업을 테스트하려면 서비스 계정 키와 agentUserId이 필요합니다. 서비스 계정 키와 agentUserId이 이미 있다면 보고서 상태 대시보드 배포를 참조하세요.

보고서 상태 대시보드 배포

프로젝트의 서비스 계정 키와 AgentUserId가 준비되었으면 보고서 상태 대시보드에서 최신 버전을 다운로드하고 배포합니다. 최신 버전을 다운로드한 후 포함된 README.MD 파일의 안내를 따릅니다.

보고서 상태 대시보드를 배포한 후 다음 URL에서 대시보드에 액세스합니다 (your_project_id를 프로젝트 ID로 대체).

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

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

  • 계정 키 파일 선택
  • 에이전트 사용자 ID 추가

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

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

오류 응답

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

  • 400 Bad Request - 잘못된 구문으로 인해 서버에서 보낸 요청을 서버에서 처리할 수 없습니다. 일반적인 원인으로는 잘못된 형식의 JSON 또는 문자열 값에 '''이 아닌 null 사용 등이 있습니다.
  • 404 Not Found - 요청된 리소스를 찾을 수 없지만 나중에 사용할 수 있습니다. 일반적으로 이는 요청된 기기를 찾을 수 없음을 의미합니다. 또한 사용자 계정이 Google과 연결되지 않았거나 잘못된 agentUserId이 수신되었음을 의미할 수도 있습니다. agentUserIdSYNC 응답에 제공된 값과 일치하고 DISCONNECT 인텐트를 적절하게 처리하는지 확인합니다.