스마트 홈 작업 알림

알림을 통해 smart home 작업에서 다음을 사용할 수 있습니다. Google Assistant: 중요한 메시지를 사용자에게 기기 관련 이벤트 또는 변경사항입니다. 알림을 구현하여 시의적절한 기기 이벤트(예: 누군가 문 앞에 있을 때) 또는 요청된 기기 상태 변경을 보고할 수 있습니다(예: 도어락 볼트가 방해가 될 수 있습니다.

smart home 작업은 다음 유형의 데이터를 전송할 수 있습니다. 사용자에게 보내는 알림:

  • 사전 알림: 사용자에게 smart home을 알립니다. 기기에 대한 이전 사용자 요청이 없는 기기 이벤트(예: 초인종이 울립니다.

  • 후속 응답: 기기 명령어 요청 확인 성공 또는 실패(예: 문을 잠글 때)입니다. 알림 사용 용도 실행하는 데 시간이 걸리는 기기 명령어입니다. 후속 응답은 스마트 스피커 및 스마트 스피커에서 기기 명령 요청을 전송할 때 있습니다.

Assistant에서는 사용자에게 다음 알림을 제공합니다. 알림을 전송합니다. 능동적 알림 기본적으로 사용 중지되어 있습니다. 사용자는 Google Home app (GHA)

알림을 트리거하는 이벤트

기기 이벤트가 발생하면 작업 처리에서 알림 요청을 전송합니다. Google에 문의하기 smart home 작업의 기기 특성 는 사용할 수 있는 알림 이벤트의 유형과 포함할 수 있습니다.

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

특성 이벤트
ObjectDetection 인식된 얼굴이 인식된 경우와 같이 기기에서 감지된 객체 차량이 문에서 감지되었습니다. 예: "윤아와 정민이가 현관문 앞에 있어요."
RunCycle 기기에서 주기를 완료합니다. 예: "세탁기의 완료되었습니다.'
SensorState 기기에서 지원되는 센서 상태를 감지합니다. 예를 들면 다음과 같습니다. "연기 감지기에서 연기가 감지되었습니다."

다음 특성은 후속 응답을 지원합니다.

특성 이벤트
LockUnlock 실행 후 완료 상태 및 상태 변경 action.devices.commands.LockUnlock 기기 명령어. 대상 예: "현관문이 잠겼습니다." 또는 "현관문이 막혔습니다."
NetworkControl 실행 후 완료 상태 및 상태 변경 action.devices.commands.TestNetworkSpeed 기기 명령어. 대상 예: '네트워크 속도 테스트가 완료되었습니다. 다운로드 속도 사무실 라우터는 현재 80.2Kbps, 업로드 속도는 9.3Kbps입니다."
OpenClose 실행 후 완료 상태 및 상태 변경 action.devices.commands.OpenClose 기기 명령어. 대상 예: "현관문이 열렸습니다" 또는 "현관문을 열 수 없습니다"

모든 기기 유형은 관련 트레잇의 알림을 지원합니다.

스마트 홈 작업용 알림 빌드

다음 단계에서 smart home 작업에 알림을 추가하세요.

  1. Google에 알림이 사용 설정된 경우 smart home 기기 앱입니다. 사용자가 알림을 사용 설정 또는 중지하는 경우 앱에서 SYNC 요청을 보내 Google에 기기 변경을 알립니다.
  2. 관련 기기 이벤트 또는 상태 변경이 발생하여 알림을 보내려면 Report State reportStateAndNotification API 만약 상태 및 알림 페이로드를 둘 다 전송할 수 있으므로 Report State 및 알림 호출에 함께 사용합니다.

다음 섹션에서 이 단계를 자세히 설명합니다.

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

사용자는 다음 방법으로 사전 알림을 받을지 선택할 수 있습니다. GHA에서 이 기능을 사용 설정합니다. 앱에서 smart home 기기에서 사용자가 기기(예: 확인할 수 있습니다

동기화 요청 통화 기기 데이터를 업데이트합니다. 다음과 같은 SYNC 요청을 전송해야 할 때마다 사용자가 앱에서 이 설정을 변경할 수 있습니다.

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

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

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

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

Google에 알림 요청 보내기

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

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. 역할 목록에서 서비스 계정 >을 선택합니다. <ph type="x-smartling-placeholder"></ph> 서비스 계정 토큰 생성자로 이동합니다.

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

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

알림 보내기

다음을 사용하여 알림 요청을 호출합니다. devices.reportStateAndNotification API JSON 요청에는 eventId이 포함되어야 하며, 이는 알림을 트리거하는 이벤트에 대한 플랫폼입니다. eventId는 다음과 같이 작동해야 합니다. 알림 요청을 보낼 때마다 다른 임의 ID여야 합니다.

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

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

사전 알림 페이로드 보내기

API를 호출하려면 다음 탭 중 하나에서 옵션을 선택합니다.

HTTP

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

  1. 다운로드한 서비스 계정 JSON 파일을 사용하여 JSON 웹을 만듭니다. 토큰 (JWT)입니다. 자세한 내용은 <ph type="x-smartling-placeholder"></ph> 서비스 계정을 사용하여 인증을 참조하세요.
  2. 다음을 사용하여 OAuth 2.0 액세스 토큰을 가져옵니다. https://www.googleapis.com/auth/homegraph 범위 사용 oauth2l:
  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. HTTP POST에서 Report State, 알림 JSON, 토큰을 결합합니다. 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);
    
후속 응답 페이로드 전송

후속 응답의 페이로드에는 요청 상태, 오류 메시지, 이벤트 실패 코드(해당하는 경우) 및 유효한 followUpToken EXECUTE 인텐트 요청 중에 제공됩니다. followUpToken를 사용해야 합니다. 응답을 적절하게 연관시킬 수 있도록 5분 이내에 할 수 있습니다.

다음 스니펫은 단일 요청 IP가 포함된 EXECUTE 요청 페이로드의 예시를 followUpToken 필드

{
  "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)입니다. 자세한 내용은 <ph type="x-smartling-placeholder"></ph> 서비스 계정을 사용하여 인증을 참조하세요.
  2. 다음을 사용하여 OAuth 2.0 액세스 토큰을 가져옵니다. https://www.googleapis.com/auth/homegraph 범위 사용 oauth2l:
  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. HTTP POST에서 Report State, 알림 JSON, 토큰을 결합합니다. 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으로 이벤트 로그에 액세스에 설명된 대로 이벤트 로깅을 지원합니다. 이러한 로그는 Google Cloud 내에서 알림 품질을 테스트하고 유지하는 데 있습니다.

다음은 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)도 포함될 수 있습니다.