동기화 요청

동기화 요청은 지정된 agentUserId (원래 SYNC 요청에서 전송함)가 연결된 기기를 사용하는 모든 Google 사용자에 대해 처리자에게 SYNC 요청을 트리거합니다. 이렇게 하면 계정을 연결 해제하고 다시 연결하지 않고도 사용자의 기기를 업데이트할 수 있습니다. 이 식별자에 연결된 모든 사용자에게 SYNC 요청이 전송됩니다.

SYNC 요청을 트리거해야 합니다.

  • 사용자가 새 기기를 추가하는 경우
  • 사용자가 기존 기기를 삭제하는 경우
  • 사용자가 기존 기기의 이름을 변경하는 경우
  • 새 기기 유형, 트레잇을 구현하거나 새 기기 기능을 추가하는 경우.

시작하기

요청 동기화를 구현하려면 다음 단계를 따르세요.

Google HomeGraph API 사용 설정

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

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

서비스 계정 키 만들기

Google Cloud Console에서 서비스 계정 키를 생성하려면 다음 안내를 따르세요.

참고: 이 단계를 수행할 때 올바른 GCP 프로젝트를 사용하고 있는지 확인하세요. smart home 프로젝트 ID와 일치하는 프로젝트입니다.

  1. Google Cloud 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
  3. agentUserId를 사용하여 JSON 요청을 만듭니다. 다음은 요청 동기화의 샘플 JSON 요청입니다.
    4. {
  "agentUserId": "user-123"
}
  4. Google Home 그래프 엔드포인트에 대한 HTTP POST 요청에서 요청 동기화 JSON과 토큰을 결합합니다. 다음은 테스트로 curl를 사용하여 명령줄에서 요청하는 방법의 예입니다.
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:requestSync"

gRPC

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

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

Node.js

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

  1. 애플리케이션 기본 사용자 인증 정보를 사용하여 google.homegraph 서비스를 초기화합니다.
  2. RequestSyncDevicesRequest를 사용하여 requestSync 메서드를 호출합니다. 빈 RequestSyncDevicesResponse가 포함된 Promise를 반환합니다.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});

자바

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

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

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);

오류 응답

동기화 요청을 호출할 때 다음 오류 응답 중 하나가 표시될 수 있습니다. 이러한 응답은 HTTP 상태 코드 형식으로 제공됩니다.

  • 400 Bad Request - 잘못된 문법으로 인해 서버에서 클라이언트가 전송한 요청을 처리할 수 없습니다. 일반적인 원인으로는 잘못된 형식의 JSON 또는 문자열 값에 '' 대신 null를 사용하는 경우를 들 수 있습니다.
  • 403 Forbidden - 토큰을 새로고침하는 동안 오류가 발생하여 서버에서 지정된 agentUserId에 대한 요청을 처리하지 못했습니다. OAuth 엔드포인트가 토큰 새로고침 요청에 올바르게 응답하는지 확인하고 사용자의 계정 연결 상태를 확인합니다.
  • 404 Not Found - 요청된 리소스를 찾을 수 없지만 향후 사용할 수 있을 수도 있습니다. 일반적으로 이는 사용자 계정이 Google에 연결되어 있지 않거나 잘못된 agentUserId가 수신되었음을 의미합니다. agentUserId가 SYNC 응답에 제공된 값과 일치하고 DISCONNECT 인텐트를 올바르게 처리하고 있는지 확인합니다.
  • 429 Too Many Requests - 지정된 agentUserId의 최대 동시 동기화 요청 수가 초과되었습니다. async 플래그가 true로 설정되지 않은 한 호출자는 동시 동기화 요청을 하나만 실행할 수 있습니다.
이전
연결 해제
다음
보고서 상태 구현