エンドポイント機能REST APIリファレンス

エンドポイント機能REST APIリファレンス

エンドポイント機能REST APIを使用すると、スマートホーム照明の電源状態など、Alexaコネクテッドエンドポイントのプロパティを表示および更新できます。Amazonビジネスアカウントで所有されているデバイスの設定を表示および更新する場合は、エンドポイント機能APIとエンドポイントREST APIを併せて使用します。Wi-Fi設定を管理するには、エンドポイントWi-Fi管理REST APIリファレンスを参照してください。

APIエンドポイント

組織が所在する国に応じて、リクエストヘッダーのHostパラメーターを、以下のいずれかのAPIエンドポイントに設定してください。

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

ドイツ、スペイン、フランス、イタリア、英国

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。

操作

エンドポイント機能APIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

Bluetoothのプロパティを取得する

GET /v2/endpoints/{endpointId}/features/bluetooth

輝度を取得する

GET /v2/endpoints/{endpointId}/features/brightness

色を取得する

GET /v2/endpoints/{endpointId}/features/color

色温度を取得する

GET /v2/endpoints/{endpointId}/features/colorTemperature

接続ステータスを取得する

GET /v2/endpoints/{endpointId}/features/connectivity

電源状態を取得する

GET /v2/endpoints/{endpointId}/features/power

スピーカーのプロパティを取得する

GET /v2/endpoints/{endpointId}/features/speaker

温度センサーを取得する

GET /v2/endpoints/{endpointId}/features/temperatureSensor

サーモスタットのプロパティを取得する

GET /v2/endpoints/{endpointId}/features/thermostat

Bluetoothデバイスとのペアリングを解除する

POST /v2/endpoints/{endpointId}/features/bluetooth/unpair

輝度を更新する

POST /v2/endpoints/{endpointId}/features/brightness/{operation}

色を更新する

POST /v2/endpoints/{endpointId}/features/color/setColor

色温度を更新する

POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation}

電源状態を更新する

POST /v2/endpoints/{endpointId}/features/power/{operation}

スピーカーのプロパティを更新する

POST /v2/endpoints/{endpointId}/features/speaker/{operation}

Bluetoothのプロパティを取得する

指定されたエンドポイントのBluetoothのプロパティを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

なし

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

なし

リクエスト

Bluetoothのプロパティを取得するには、features/bluetoothリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/bluetooth
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のパラメーター

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、Bluetoothのプロパティが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、応答の例です。

{
  "operations": [
    {
       "name": "unpair",
       "path": "/v2/endpoints/{endpointId}/features/bluetooth/unpair"
    }
   ]
}

応答本文のパラメーター

パラメーター 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はnoneです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

configuration

呼び出し元にアクセスできる設定データ。
有効な値はnoneです。

設定オブジェクトのリスト。

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

輝度を取得する

指定されたエンドポイントの輝度レベルを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

輝度レベルを取得するには、features/brightnessリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/brightness
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、現在の輝度レベルが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "brightness",
        "type": "RETRIEVABLE",
        "value": {
            "value": 50
        },
        "timeOfSample": "2024-08-23T12:00:30.02Z"
    }],
   "operations": [
       {
          "name": "setBrightness",
          "path": "/v2/endpoints/{id}/features/brightness/setBrightness"
       },
       {
          "name": "adjustBrightness",
          "path": "/v2/endpoints/{id}/features/brightness/adjustBrightness"
       }
   ]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はbrightnessです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

輝度のプロパティ。

オブジェクト

properties[].value.value

エンドポイントの現在の輝度レベル。
有効な値は 0～100です。

整数

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

色を取得する

指定されたエンドポイントの色相、彩度、輝度を取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

色を取得するには、features/colorリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/color
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、エンドポイントの現在の色相、彩度、輝度が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "color",
        "type": "RETRIEVABLE",
        "value": {
            "hue": 20,
            "saturation": 0.5,
            "brightness": 0.7
        },
        "timeOfSample": "2024-07-02T06:20:50.52Z"
    }],
   "operations": [
      {
         "name": "setColor",
         "path": "/v2/endpoints/{endpointId}/features/color/setColor"
      }
   ]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はcolorです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

エンドポイントの現在の色。

Colorオブジェクト

properties[].value.hue

色の現在の色相値。
有効な値は 0～360です。

整数

properties[].value.saturation

色の現在の彩度レベル。
有効な値は 0.0～1.0です（両端の値を含みます）。

浮動小数点

properties[].value.brightness

現在の輝度。
有効な値は 0.0～1.0です（両端の値を含みます）。

浮動小数点

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

色温度を取得する

白色光を調整可能なエンドポイント（電球など）の色温度を取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

色温度を取得するには、features/colorTemperatureリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/colorTemperature
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、現在の色温度が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "colorTemperatureInKelvin",
        "type": "RETRIEVABLE",
        "value": {
            "value": 2700
        },
        "timeOfSample": "2024-07-02T06:20:50.52Z"
    }],
   "operations": [
      {
          "name": "setColorTemperature",
          "path": "/v2/endpoints/{id}/features/colorTemperature/setColorTemperature"
      },
      {
         "name": "increaseColorTemperature",
         "path": "/v2/endpoints/{id}/features/colorTemperature/increaseColorTemperature"
      },
      {
         "name": "decreaseColorTemperature",
         "path": "/v2/endpoints/{id}/features/colorTemperature/decreaseColorTemperature"
      }
   ]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はcolorTemperatureInKelvinです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

色のプロパティ。

オブジェクト

properties[].value

エンドポイントの現在の色温度（ケルビン単位）。白の色調の詳細については、色温度の値を参照してください。
有効な値は 1000～10000です。

整数

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

接続ステータスを取得する

指定されたエンドポイントの接続ステータスを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

接続ステータスを取得するには、features/connectivityリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/connectivity
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、エンドポイントの接続ステータスが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "reachability",
        "type": "RETRIEVABLE",
        "value": {
            "value": "OK"
        },
        "timeOfSample": "2024-07-03T10:20:50.52Z"
    }]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はreachabilityです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

接続プロパティ。

オブジェクト

properties[].value.value

エンドポイントの現在の接続ステータス。有効な値は次のとおりです。

  • OK - デバイスはネットワークに接続されています。
  • UNREACHABLE - デバイスはネットワークに接続されていません。たとえば、デバイスがケーブルに接続されていない場合や、ネットワークが利用できない場合などがあります。
  • NOT_FOUND - デバイスが30日以上オフライン状態になっているか、デバイスの状態が報告されていません。このステータスは通常、デバイスがケーブルに接続されていないことを示します。

文字列

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

電源状態を取得する

指定されたエンドポイントの電源のオン／オフ状態を確認します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

電源状態を取得するには、features/powerリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/power
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、エンドポイントの電源状態が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "powerState",
        "type": "RETRIEVABLE",
        "value": {
            "value": "ON"
        },
        "timeOfSample": "2024-07-02T06:44:02.32Z"
    }],
   "operations": [
      {
         "name": "turnOn",
         "path": "/v2/endpoints/{endpointID}/features/power/turnOn"
      },
      {
         "name": "turnOff",
         "path": "/v2/endpoints/{endpointID}/features/power/turnOff"
      }
   ]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はpowerStateです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

電源のプロパティ。

オブジェクト

properties[].value.value

エンドポイントの現在の電源状態。有効な値は ON、OFF。

文字列

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

スピーカーのプロパティを取得する

指定されたエンドポイントのスピーカーのプロパティを取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

スピーカーのプロパティを取得するには、features/speakerリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/speaker
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、エンドポイントのスピーカーのプロパティが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "volume",
        "type": "RETRIEVABLE",
        "value": {
            "value": "42"
        },
        "timeOfSample": "2024-08-13T10:20:50.52Z"
    }],
    "operations": [
        {
            "name": "setVolume",
            "path": "/v2/endpoints/<id>/features/speaker/setVolume"
        },
        {
            "name": "adjustVolume",
            "path": "/v2/endpoints/<id>/features/speaker/adjustVolume"
        }
    ]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はvolumeです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

スピーカーのプロパティ。

オブジェクト

properties[].value.value

現在の音量。有効な値は 0～100です。

整数

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

温度センサーを取得する

指定されたエンドポイントで検出された現在の温度を取得します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

温度を取得するには、features/temperatureSensorリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/temperatureSensor
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、現在の温度が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "properties": [{
        "name": "temperature",
        "type": "RETRIEVABLE",
        "value": {
            "value": 68.0,
            "scale": "FAHRENHEIT"
        },
        "timeOfSample": "2024-07-02T06:44:02.32Z"
    }]
}

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はtemperatureです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

温度のプロパティ。

Temperatureオブジェクト

properties[].value.value

エンドポイントで検出された現在の温度。

浮動小数点

properties[].value.scale

温度の単位。
有効な値は CELSIUS、FAHRENHEIT、KELVINです。

文字列

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

サーモスタットのプロパティを取得する

指定されたエンドポイントのサーモスタットモードと設定値を取得します。設定値が1つのサーモスタットの場合、温度設定は1つだけです。設定値が2つのサーモスタットには、上限と下限の設定値があります。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

サーモスタットのプロパティを取得するには、features/thermostatリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/endpoints/{endpointId}/features/thermostat
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、サーモスタットエンドポイントのサーモスタットモードと設定値が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、設定値が1つのサーモスタットのサーモスタットプロパティの例です。

以下は、設定値が2つのサーモスタットのサーモスタットプロパティの例です。

応答本文のプロパティ

プロパティ 説明 型

properties

エンドポイントのプロパティのリスト。
データを表示する権限がない場合、このリストは空になります。

オブジェクトの配列

properties[].name

プロパティの名前。
有効な値はthermostatMode、targetSetpoint、lowerSetpoint、upperSetpointです。

文字列

properties[].type

プロパティのタイプ。
ERRORに設定されている場合、リクエストを再試行できます。
有効な値は RETRIEVABLE、NOT_RETRIEVABLE、ERRORです。

文字列

properties[].value

指定されたエンドポイントのサーモスタットのプロパティ。

オブジェクト

properties[].value.value

nameで指定されているプロパティの現在の値。thermostatModeの場合、有効な値は HEAT、COOL、AUTO、ECO、OFFです。targetSetpoint、lowerSetpoint、upperSetpointの場合、有効な値は 現在の温度です。

文字列（thermostatModeの場合）、浮動小数点（設定値の場合）

properties[].value.scale

温度の単位。targetSetpoint、lowerSetpoint、upperSetpointの場合にのみ含まれます。
有効な値は CELSIUS、FAHRENHEIT、KELVINです。

文字列

properties[].timeOfSample

エンドポイントが状態変更を検出した時刻。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

properties[].error

（オプション）発生したエラーについての説明。
type = ERRORの場合に含まれます。

Errorオブジェクト

configuration

サポートされるサーモスタットモード。

オブジェクト

supportedModes

サーモスタットエンドポイントがサポートするモードのリスト。有効な値は HEAT、COOL、AUTO、ECO、OFFです。

文字列の配列

operations

この機能とエンドポイントで使用可能な更新操作のリスト。
データを表示する権限がない場合、このリストは空になります。

Operationオブジェクトの配列

HTTPステータスコード

ステータス 説明

200 OK

リクエストされたプロパティの現在の値が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

Bluetoothデバイスとのペアリングを解除する

指定したAlexa搭載エンドポイントからすべてのBluetoothデバイスとのペアリングを解除します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、カナダ、ドイツ、スペイン、フランス、イタリア、英国、日本

米国、カナダ、ドイツ、スペイン、フランス、イタリア、英国、日本

米国

リクエスト

Bluetoothデバイスとのペアリングを解除するには、features/bluetooth/リソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/endpoints/{endpointId}/features/bluetooth/unpair
Host: api.amazonalexa.com
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 202 Acceptedが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

202 Accepted

デバイスとのペアリングが正常に解除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

輝度を更新する

指定されたエンドポイントの輝度レベルを設定します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国

リクエスト

輝度を設定するには、features/brightnessリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/endpoints/{endpointId}/features/brightness/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

operation

パス

輝度レベルを調整または設定するための操作。有効な値はadjustBrightness、setBrightnessです。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

以下は、adjustBrightness操作のリクエスト本文の例です。

クリップボードにコピーされました。

{
    "payload": {
        "brightnessDelta": -25
    }
}

以下は、setBrightness操作のリクエスト本文の例です。

クリップボードにコピーされました。

{
    "payload": {
        "brightness": 75
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

payload

brightnessプロパティの制御に必要な情報。
brightness、brightnessDeltaのいずれかを含めます。

オブジェクト

◯

payload.brightness

エンドポイントの輝度の設定値（％）。
setBrightness操作の場合に含めます。
有効な値は 0～100です。

整数

✕

payload.brightnessDelta

エンドポイントの輝度の変更量（％）。adjustBrightness操作の場合に含めます。
輝度を下げる場合は負の値、輝度を上げる場合は正の値を使用します。
有効な値は–100～100です。

整数

✕

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントでプロパティが正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

色を更新する

指定されたエンドポイントの色を設定します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国

リクエスト

色を設定するには、features/colorリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/endpoints/{endpointId}/features/color/setColor`
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
    "payload": {
        "color": {
            "hue": 20,
            "saturation": 0.75,
            "brightness": 0.34
        }
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

payload

colorプロパティの制御に必要な情報。

オブジェクト

◯

payload.color

エンドポイントの設定色を定義します。

整数

◯

payload.color.hue

色の現在の色相値。
有効な値は 0～360です。

整数

◯

payload.color.saturation

色の現在の彩度レベル。
有効な値は 0.0～1.0です（両端の値を含みます）。

浮動小数点

◯

payload.color.brightness

現在の輝度。
有効な値は 0.0～1.0です（両端の値を含みます）。

浮動小数点

◯

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントでプロパティが正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

色温度を更新する

指定されたエンドポイントの色温度を設定します。色温度は特定の値に設定できます。または、色温度を上げて現在の設定よりも寒色または白色にしたり、色温度を下げて現在の設定よりも暖色または柔らかい色にしたりすることもできます。設定をどの程度増減するかの選択はエンドポイントの製造元が行います。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国

リクエスト

色温度を設定するには、features/colorTemperatureリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/endpoints/{endpointId}/features/colorTemperature/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

operation

パス

色温度を調整または設定するための色温度操作。
有効な値はdecreaseColorTemperature、increaseColorTemperature、setColorTemperatureです。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

decreaseColorTemperatureおよびincreaseColorTemperature操作には、リクエスト本文はありません。

以下は、setColorTemperature操作のリクエスト本文の例です。

クリップボードにコピーされました。

{
    "payload": {
        "colorTemperatureInKelvin": 2000
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

payload

setColorTemperature操作のcolorTemperatureInKelvinプロパティの制御に必要な情報。

オブジェクト

✕

payload.colorTemperatureInKelvin

エンドポイントの色温度（ケルビン単位）。白の色調の詳細については、色温度の値を参照してください。
有効な値は 1000～10000です。

整数

✕

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントでプロパティが正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

電源状態を更新する

指定されたエンドポイントの電源のオン／オフを切り替えます。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、日本

米国

リクエスト

電源状態を設定するには、features/powerリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/endpoints/{endpointId}/features/power/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

operation

パス

電源のオン／オフを切り替えるための操作。有効な値はturnOn、turnOffです。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントでプロパティが正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

スピーカーのプロパティを更新する

指定されたエンドポイントのスピーカーの音量を設定または調整します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本

米国

リクエスト

スピーカーのプロパティを設定するには、features/speakerリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/endpoints/{endpointId}/features/speaker/{operation}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

endpointId

パス

このエンドポイントの一意のID。ユーザーデバイスごとにAmazonから割り当てられています。
amzn1.alexa.endpoint.{id}というACI形式で表します。

文字列

◯

operation

パス

スピーカーの音量を設定または調整するための操作。有効な値はsetVolume、adjustVolumeです。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

以下は、adjustVolume操作のリクエスト本文の例です。

クリップボードにコピーされました。

{
    "payload": {
        "volumeDelta": -25
    }
}

以下は、setVolume操作のリクエスト本文の例です。

クリップボードにコピーされました。

{
    "payload": {
        "volume": 75
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

payload

speakerプロパティの制御に必要な情報。
volume、volumeDeltaのいずれかを含めます。

オブジェクト

◯

payload.volume

エンドポイントの音量の設定値。
setVolume操作の場合に含めます。
有効な値は 0～100です。

整数

✕

payload.volumeDelta

エンドポイントの音量の変更量。adjustVolume操作の場合に含めます。
音量を下げる場合は負の値、音量を上げる場合は正の値を使用します。
有効な値は–100～100です。

整数

✕

応答

正常に完了すると、HTTP 200 OKが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンドポイントでプロパティが正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

オブジェクトの定義

エンドポイント機能APIでは、以下のオブジェクトとプロパティ値が定義されています。

色温度の値

次の表に、白の色調と対応する色温度の値の例を示します。

色調 絶対色温度（ケルビン単位）

暖色

2200

電球色

2700

白っぽい色

4000

昼白色

5500

クールホワイト

7000

Operationオブジェクト

Operationオブジェクトは、指定されたエンドポイントや機能で使用可能な更新操作を表します。

プロパティ 説明 型

name

更新操作の名前。

文字列

path

更新操作でnameプロパティの設定に使用できる完全なHTTPパス。

文字列

Temperatureオブジェクト

Temperatureオブジェクトは、エンドポイントで検出された現在の温度を表します。

プロパティ 説明 型

value

温度（度単位）。

浮動小数点

scale

温度の単位。
targetSetpoint、lowerSetpoint、upperSetpointの場合にのみ含まれます。
有効な値は CELSIUS、FAHRENHEIT、KELVINです。

文字列

ThermostatModeの値

次の表に、サーモスタットのモード値の文字列を示します。サーモスタットによっては、すべてのモードがサポートされていない場合があります。

値 説明

AUTO

現在の温度と設定値に基づく自動暖房／冷房モード。

COOL

冷房モード。

ECO

エコノミーモード。

EM_HEAT

緊急暖房モード。
このモードでは、追加の熱源としてバックアップ熱源を使用します。たとえば、非常に寒いときやヒートポンプが故障したときなどに、ユーザーは緊急暖房を使用する場合があります。

HEAT

暖房モード。

OFF

暖房・冷房はオフですが、デバイスの電源が入っている可能性があります。

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "ENDPOINT_UNREACHABLE",
    "message": "The endpoint is offline or unreachable."
}
プロパティ 説明 型

type

発生したエラーのタイプ。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

読み取り可能なエラーメッセージ。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

このページは役に立ちましたか？

最終更新日: 2024 年 11 月 20 日