Clova Home Extension APIのリファレンス

Clova Home Extension APIは、CEKとIoTサービス間で情報を交換するために使用されるメッセージ仕様です。Clova Home Extension APIについては以下をご確認ください。

• HTTPメッセージ
• Clova Home Extensionメッセージ

HTTPメッセージ

CEKとExtensionが通信する際、HTTP/1.1を使用して基本的なHTTPSリクエストとHTTPSレスポンスをやり取りします。CEKとExtensionが通信する際、HTTPメッセージのボディには、JSON形式のメッセージが含まれます。ここでは、CEKとExtensionがやり取りするHTTPメッセージの構成について説明します。

• HTTPヘッダー
  • リクエストメッセージの検証
• HTTPボディ

HTTPヘッダー

CEKがExtensionに解析されたユーザーの発話情報を渡す際、HTTPリクエストを使用します。その際、HTTPリクエストのヘッダーは、次のように構成されます。

POST /APIpath HTTP/1.1
Host: YOUR_EXTENSION_ENDPOINT
Content-Type: application/json;charset-UTF-8
Accept: application/json
Accept-Charset: utf-8
SignatureCEK：{{ SignatureCEK }}

• HTTP/1.1バージョンでHTTP通信し、POSTメソッドを使用します。
• Hostとリクエストパスは、Extensionの開発者があらかじめ定義したURIに設定されます。
• リクエストボディのデータはJSON形式で、UTF-8エンコーディングを使用します。
• SignatureCEKフィールドとRSA公開鍵を使用して、Clovaから送信されたリクエストかどうかを検証することができます。

逆に、ExtensionがClovaに処理結果を返す際、HTTPレスポンスを使用します。その際のHTTPレスポンスヘッダーは、以下のように設定をしてください。

HTTP/1.1 200 OK
Content-Type: application/json;charset-UTF-8

• CEKから渡されたHTTPリクエストに対するレスポンスとして、処理結果を返します。
• ボディのデータはJSON形式で、UTF-8エンコーディングを使用します。

リクエストメッセージの検証

ExtensionがCEKからHTTPリクエストを受信するとき、そのリクエストが第三者ではなく、Clovaから送信された信頼できるリクエストかどうかを検証する必要があります。検証の方法については、リクエストメッセージを検証するを参照してください。

HTTPボディ

リクエストメッセージとレスポンスメッセージのボディはJSON形式で、解析されたユーザーの発話情報や、Extensionの処理結果が含まれています。それぞれのメッセージの構成は、使用するExtensionの種類によって異なります。メッセージ構成の詳細については、Custom ExtensionメッセージとClova Home Extensionメッセージを参照してください。

Clova Home Extensionメッセージ

Clova Home Extensionメッセージは、IoTデバイスを制御するExtensionがCEKと情報のやり取りをする際、専用で使用するメッセージ仕様です。ここでは、Clova Home Extensionメッセージのメッセージフォーマットとインターフェースについて説明します。

メッセージフォーマット

Clova Home Extensionメッセージは、headerフィールドとpayloadで構成されます。リクエストメッセージとレスポンスメッセージの両方に共通します。そのうち、payloadは、使用されたインターフェースによって構成が異なることがあります。ここでは、Clova Home Extensionメッセージの共通フォーマットについて説明します。

Message structure

{
  "header": {
    "messageId": {{string}},
    "namespace": {{string}},
    "name": {{string}},
    "payloadVersion": {{string}}
  },
  "payload": {{object}}
}

Message fields

フィールド名	データ型	フィールドの説明	Optional
header	object	メッセージのヘッダー
header.messageId	string	メッセージID(UUID)。個別メッセージを区別するために、Clovaで作成された識別子です。
header.name	string	メッセージのAPI名
header.namespace	string	このフィールドは"ClovaHome"に固定されます
header.payloadVersion	string	header.nameに明示されたClova Home Extensionメッセージのバージョン。このバージョンによって、payloadフィールドの構成が異なることがあります。
payload	object	header.nameに指定されたインターフェースによって、payloadオブジェクトの構成とフィールド値が異なります。

Message example

例1：DiscoverAppliancesRequest - リクエストメッセージ
{
  "header": {
    "messageId": "8ddd7f05-7703-4cb4-a6dd-93c209c6647b",
    "name": "DiscoverAppliancesRequest",
    "namespace": "ClovaHome",
    "payloadVersion": "1.0"
  },
  "payload": {
    "accessToken": "92ebcb67fe33"
  }
}

例2：DiscoverAppliancesResponse - レスポンスメッセージ
{
  "header": {
    "messageId": "99f9d8ff-9366-4cab-a90c-b4c7eca0abbe",
    "name": "DiscoverAppliancesResponse",
    "namespace": "ClovaHome",
    "payloadVersion": "1.0"
  },
  "payload": {
    "discoveredAppliances": [
      {
        "applianceId": "device-001",
        "manufacturerName": "device-manufacturer-name",
        "modelName": "スマート照明",
        "version": "v1.0",
        "friendlyName": "リビングの照明",
        "friendlyDescription": "スマートフォンで制御できる照明",
        "isIr": false,
        "isReachable": true,
          "actions": [
            "DecrementBrightness",
            "HealthCheck",
            "IncrementBrightness",
            "SetBrightness",
            "TurnOn",
            "TurnOff"
        ],
        "applianceTypes": ["LIGHT"],
        "additionalApplianceDetails": {
        }
      },
      {
        "applianceId": "device-002",
        "manufacturerName": "device-manufacturer-name",
        "modelName": "スマートコンセント",
        "version": "v1.0",
        "friendlyName": "キッチンのコンセント",
        "friendlyDescription": "節電コンセント",
        "isIr": false,
        "isReachable": true,
        "actions": [
          "HealthCheck",
          "TurnOn",
          "TurnOff"
        ],
        "applianceTypes": ["SMARTPLUG"],
        "additionalApplianceDetails": {
        }
      }
    ]
  }
}

例3：IncrementTargetTemperatureConfirmation - レスポンスメッセージ
{
  "header": {
    "messageId": "4ec35000-88ce-4724-b7e4-7f52050558fd",
    "name": "IncrementTargetTemperatureConfirmation",
    "namespace": "ClovaHome",
    "payloadVersion": "1.0"
  },
  "payload": {
    "targetTemperature": {
      "value": 25.0
    },
    "previousState": {
      "targetTemperature": {
        "value": 22.0
      }
    }
  }
}

例4：TargetOffLineError - エラーレスポンスメッセージ
{
  "header": {
    "messageId": "fef949b7-eb94-4bda-a417-2cfb604194c3",
    "namespace": "ClovaHome",
    "name": "TargetOfflineError",
    "payloadVersion": "1.0"
  },
  "payload": {
  }
}

次の項目も参照してください。

• Clova Home Extensionを作成する
• インターフェース

インターフェース

Clova Home Extensionメッセージのインターフェースは、次のようなものがあります。

• インターフェース

  • Discoveryインターフェース
  • Controlインターフェース
  • Errorインターフェース

• 共有オブジェクト

  • 共有オブジェクト