メモ
CLOVA Developer Center βでは CLOVA Home Extensionの情報登録を受け付けておりません。CLOVA Home Extensionを利用した連携に興味のある企業様は、LINE Partners よりお問い合わせください。
CLOVA Home Extension APIは、CEKとIoTサービス間で情報を交換するために使用されるメッセージ仕様です。CLOVA Home Extension APIについては以下をご確認ください。
CEKとExtensionが通信する際、HTTP/1.1を使用して基本的なHTTPSリクエストとHTTPSレスポンスをやり取りします。CEKとExtensionが通信する際、HTTPメッセージのボディには、JSON形式のメッセージが含まれます。ここでは、CEKとExtensionがやり取りする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 }}
SignatureCEK
フィールドとRSA公開鍵を使用して、CLOVAから送信されたリクエストかどうかを検証することができます。逆に、ExtensionがCLOVAに処理結果を返す際、HTTPレスポンスを使用します。その際のHTTPレスポンスヘッダーは、以下のように設定をしてください。
HTTP/1.1 200 OK
Content-Type: application/json;charset-UTF-8
ExtensionがCEKからHTTPリクエストを受信するとき、そのリクエストが第三者ではなく、CLOVAから送信された信頼できるリクエストかどうかを検証する必要があります。検証の方法については、リクエストメッセージを検証するを参照してください。
リクエストメッセージとレスポンスメッセージのボディはJSON形式で、解析されたユーザーの発話情報や、Extensionの処理結果が含まれています。それぞれのメッセージの構成は、使用するExtensionの種類によって異なります。メッセージ構成の詳細については、Custom 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`のような名前で返される必要があります。
{
"header": {
"messageId": {{string}},
"namespace": {{string}},
"name": {{string}},
"payloadVersion": {{string}}
},
"payload": {{object}}
}
フィールド名 | データ型 | フィールドの説明 | 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オブジェクトの構成とフィールド値が異なります。 |
例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メッセージのインターフェースは、次のようなものがあります。
インターフェース
共有オブジェクト