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

스마트 홈 작업 알림

알림을 사용하면 smart home 작업에서 Google Assistant를 사용하여 중요한 기기 관련 이벤트 또는 변경사항에 관해 사용자와 통신할 수 있습니다. 예를 들어 누군가 현관에 있을 때 사용자에게 적시에 기기 이벤트를 알리거나 도어락 볼트에 성공적으로 참여했거나 걸렸을 때와 같이 요청된 기기 상태 변화를 보고하도록 알림을 구현할 수 있습니다.

smart home 작업은 사용자에게 다음 유형의 알림을 보낼 수 있습니다.

  • 사전 알림: 초인종을 울리는 등의 이전 사용자 요청 없이 smart home 기기 이벤트를 사용자에게 알립니다.

  • 후속 응답: 도어를 잠근 경우와 같이 기기 명령어 요청이 성공 또는 실패했다는 확인입니다. 완료하는 데 시간이 걸리는 기기 명령어에 이러한 알림을 사용하세요. 후속 응답은 스마트 스피커 및 스마트 디스플레이에서 기기 명령어 요청이 전송되는 경우에만 지원됩니다.

Assistant는 스마트 스피커 및 스마트 디스플레이에서 사용자에게 이러한 알림을 제공합니다. 사전 알림은 기본적으로 사용 중지되어 있습니다. 사용자는 Google Home app (GHA)에서 모든 사전 알림을 사용 설정하거나 중지할 수 있습니다.

알림을 트리거하는 이벤트

기기 이벤트가 발생하면 작업 처리에서 Google에 알림 요청을 전송합니다. smart home 작업이 지원하는 기기 특성에 따라 사용 가능한 알림 이벤트의 유형과 이러한 알림에 포함할 수 있는 데이터가 결정됩니다.

사전 알림을 지원하는 특성은 다음과 같습니다.

특성 이벤트
객체 감지 인식된 얼굴이 현관에서 감지된 경우 등의 기기에서 감지된 객체 예: "현수님과 현우님이 현관 앞에 있습니다."
RunCycle 기기에서 주기 완료 예: " 세탁기 사이클이 완료되었습니다."
센서 상태 기기가 지원되는 센서 상태를 감지합니다. 예: "연기 감지기에서 연기가 감지되었습니다."
온도 제어 기기가 온도 설정값에 도달했습니다. 예: "오븐이 350도로 예열되었습니다."
ArmDisarm 시스템이 열린 문으로 트리거되어 출입 카운트다운이 포함된 사전 알람을 시작합니다.
카메라 스트림 기기에서 사물이나 움직임이 감지된 후 카메라의 실시간 스트림에 연결합니다.
MotionDetection '2020년 7월 1일 오후 12시에 움직임이 감지되었습니다.'

후속 대응을 지원하는 특성은 다음과 같습니다.

특성 이벤트
ArmDisarm action.devices.commands.ArmDisarm 기기 명령어를 실행한 후 완료 상태 및 상태 변경. 예: "보안 시스템이 설정되었습니다."
잠금 해제 action.devices.commands.LockUnlock 기기 명령어를 실행한 후 완료 상태 및 상태 변경. 예: "현관이 잠겼습니다." 또는 "현관문이 걸려 움직이지 않습니다."
NetworkControl action.devices.commands.TestNetworkSpeed 기기 명령어를 실행한 후 완료 상태 및 상태 변경. 예: '네트워크 속도 테스트가 완료되었습니다. 현재 사무실 라우터의 다운로드 속도는 80.2Kbps이고 업로드 속도는 9.3Kbps입니다."
OpenClose action.devices.commands.OpenClose 기기 명령어를 실행한 후 완료 상태 및 상태 변경. 예: "현관을 열었습니다." 또는 "현관을 열 수 없습니다."
시작 중지 action.devices.commands.StartStop 기기 명령어를 실행한 후 완료 상태 및 상태 변경. 예: "진공 청소기가 시작되었습니다."

모든 기기 유형은 관련 특성에 관한 알림을 지원합니다.

스마트 홈 작업을 위한 알림 빌드

다음 단계에서 smart home 작업에 알림을 추가합니다.

  1. smart home 기기 앱에서 알림이 사용 설정되어 있는지 Google에 알립니다. 사용자가 앱에서 알림을 사용 설정하거나 사용 중지하면 SYNC 요청을 전송하여 Google에 기기 변경사항을 알립니다.
  2. 알림을 트리거하는 관련 기기 이벤트 또는 상태 변경이 발생하면 Report State reportStateAndNotification API를 호출하여 알림 요청을 전송합니다. 기기 상태가 변경되면 Report State 및 알림 호출에서 상태 및 알림 페이로드를 모두 보낼 수 있습니다.

다음 섹션에서는 이러한 단계를 더 자세히 다룹니다.

앱에서 알림이 사용 설정되어 있는지 표시

사용자는 GHA에서 이 기능을 사용 설정하여 사전 알림을 수신할지 선택할 수 있습니다. smart home 기기의 앱에서 사용자가 기기 설정(예: 앱 설정)에서 알림을 명시적으로 전환할 수 있는 기능도 선택적으로 추가할 수 있습니다.

기기 데이터를 업데이트하도록 SYNC 요청 호출을 실행하여 기기에 알림이 사용 설정되었음을 Google에 알립니다. 사용자가 앱에서 이 설정을 변경할 때마다 이와 같은 SYNC 요청을 전송해야 합니다.

SYNC 응답에서 다음 업데이트 중 하나를 전송합니다.

  • 사용자가 기기 앱에서 명시적으로 알림을 사용 설정했거나 전환 옵션을 제공하지 않는 경우 devices.notificationSupportedByAgent 속성을 true로 설정합니다.
  • 사용자가 기기 앱에서 알림을 명시적으로 사용 중지한 경우 devices.notificationSupportedByAgent 속성을 false로 설정합니다.

다음 스니펫은 SYNC 응답을 설정하는 방법의 예를 보여줍니다.

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Google에 알림 요청 보내기

Assistant에서 알림을 트리거하기 위해 처리에서 Report State 및 Notification API 호출을 통해 Google Home Graph로 알림 페이로드를 전송합니다.

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 파일이 컴퓨터에 다운로드됩니다.

알림 보내기

devices.reportStateAndNotification API를 사용하여 알림 요청을 호출합니다. JSON 요청에는 eventId가 포함되어야 합니다. 이는 플랫폼에서 알림을 트리거하는 이벤트용으로 생성된 고유 ID입니다. eventId는 알림 요청을 전송할 때마다 다른 임의의 ID여야 합니다.

API 호출에서 전달하는 notifications 객체에 알림이 표시되는 방식을 정의하는 priority 값을 포함합니다. notifications 객체는 기기 특성에 따라 다른 필드를 포함할 수 있습니다.

다음 경로 중 하나를 따라 페이로드를 설정하고 API를 호출하세요.

사전 알림 페이로드 전송

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 요청을 만듭니다. 다음은 Report State 및 알림에 대한 샘플 JSON 요청입니다.
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "ObjectDetection": {
                "priority": 0,
                "detectionTimestamp": 1534875126750,
                "objects": {
                  "named": [
                    "Alice"
                  ],
                  "unclassified": 2
                }
              }
            }
          }
        }
      }
    }
    
  6. Report State 및 알림 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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

Java

자바용 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 notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    
후속 응답 페이로드 전송

후속 응답의 페이로드에는 요청 상태, 이벤트 실패 시 오류 코드(해당하는 경우), EXECUTE 인텐트 요청 중에 제공된 유효한 followUpToken가 포함됩니다. followUpToken를 5분 이내에 사용하여 유효 상태를 유지하고 응답을 원래 요청과 올바르게 연결해야 합니다.

다음 스니펫은 followUpToken 필드가 있는 EXECUTE 요청 페이로드의 예를 보여줍니다.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

Google은 followUpToken를 사용하여 사용자가 원래 상호작용하고 있던 기기에만 알림을 출력하고 사용자의 모든 기기에 브로드캐스트하지 않습니다.

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 요청을 만듭니다. 다음은 Report State 및 알림에 대한 샘플 JSON 요청입니다.
  5. {
      "agentUserId": "PLACEHOLDER-USER-ID",
      "eventId": "PLACEHOLDER-EVENT-ID",
      "requestId": "PLACEHOLDER-REQUEST-ID",
      "payload": {
        "devices": {
          "notifications": {
            "PLACEHOLDER-DEVICE-ID": {
              "NetworkControl": {
                "priority": 0,
                "followUpResponse": {
                  "status": "SUCCESS",
                  "followUpToken": "PLACEHOLDER",
                  "networkDownloadSpeedMbps": 23.3,
                  "networkUploadSpeedMbps": 10.2
                }
              }
            }
          }
        }
      }
    }
    
  6. Report State 및 알림 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 followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

Java

자바용 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();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

로깅

알림은 Cloud Logging으로 이벤트 로그 액세스에 설명된 대로 이벤트 로깅을 지원합니다. 이 로그는 작업 내에서 알림 품질을 테스트하고 유지관리하는 데 유용합니다.

다음은 notificationLog 항목의 스키마입니다.

속성 설명
requestId 알림 요청 ID
structName 알림 구조체의 이름입니다(예: 'ObjectDetection').
status 알림의 상태를 나타냅니다.

status 필드에는 알림 페이로드의 오류를 나타낼 수 있는 다양한 상태가 포함됩니다. 이 중 일부는 프로덕션으로 출시되지 않은 작업에서만 사용할 수 있습니다.

상태의 예는 다음과 같습니다.

상태 설명
EVENT_ID_MISSING 필수 eventId 필드가 없음을 나타냅니다.
PRIORITY_MISSING priority 필드가 누락되었음을 나타냅니다.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE SYNC에 제공된 알림 기기의 notificationSupportedByAgent 속성이 false임을 나타냅니다.
NOTIFICATION_ENABLED_BY_USER_FALSE 사용자가 GHA의 알림 기기에서 알림을 사용 설정하지 않았음을 나타냅니다. 이 상태는 프로덕션으로 출시되지 않은 작업에서만 사용할 수 있습니다.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE 사용자가 알림 기기를 집/구조에 할당하지 않았음을 나타냅니다. 이 상태는 프로덕션으로 출시되지 않은 작업에서만 사용할 수 있습니다.

모든 알림에 적용될 수 있는 이러한 일반 상태 외에도 status 필드에는 해당하는 경우 특성별 상태 (예: OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING)도 포함될 수 있습니다.