メモ

CLOVA Developer Center βでは CLOVA Home Extensionの情報登録を受け付けておりません。CLOVA Home Extensionを利用した連携に興味のある企業様は、LINE Partners よりお問い合わせください。

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メッセージの共通フォーマットについて説明します。

メモ

CLOVA Home Extensionメッセージは、リクエストメッセージとレスポンスメッセージの2種類があります。CEKがExtensionに渡すリクエストメッセージは、`XxxxRequest`のような名前を持ちます。ExtensionからCEKに返すレスポンスメッセージは、`XxxxConfirmation`または`XxxxResponse`のような名前を持ちます。また、エラーが発生しても正常にHTTPレスポンス(200 OK)を返す必要があり、その際、レスポンスメッセージは`XxxxError`のような名前で返される必要があります。

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インターフェース
  • 共有オブジェクト

    • 共有オブジェクト