施設階層管理API
ユニットは、施設階層の構成要素を形成します。まず、組織の下に施設を表すユニットを作成し、その下に部屋を表すユニットを複数作成することができます。また、階層内にもう1つレベルを増やしたい場合は、施設ユニットの下に施設の階を表すユニットを作成し、各階のユニットの下にその階にあるルームを表すユニットを作成することができます。ユニット管理APIを使用して、施設を表すのに、最大15レベルのユニットを作成することができます。2レベル以上の施設階層については、APIを使用して管理する必要があり、このような施設はコンソールで管理することはできません。
APIエンドポイント
施設階層管理APIのエンドポイントは、https://api.amazonalexa.com
です。
認証
すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。
操作
施設階層管理APIには、以下の操作があります。
操作 | HTTPメソッドとURI |
---|---|
| |
| |
| |
| |
|
ユニットを作成する
施設内の物理ユニット(施設、階、そで、ルームなど)を表すユニットを作成するには、POST /v2/units
を呼び出します。
ユニットは、Alexaシステムと対話する人とリソース(スキル、デバイス)を組織化するための管理構造です。ユニットは、階層的なものであり、0個以上のサブユニットを持つことができます。ユニットの親は、サブユニットになれません。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
ドイツ、イタリア |
なし |
カナダ、ドイツ、フランス、イタリア、英国、米国 |
米国 |
リクエストの形式
POST /v2/units HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
なし。
リクエスト本文の形式
{
"name": {
"type": "PLAIN",
"value": {
"text": "name of unit"
}
},
"parentId": "amzn1.alexa.unit.did.{unitId}"
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
name.type |
name.valueフィールドの予想される形式タイプ。 有効な値: PLAIN |
文字列 | ◯ |
name.value |
ユニットの名前です。 | NameValue | ◯ |
parentId |
新しく作成されるユニットの上のユニット。 | 文字列 | ◯ |
応答ヘッダー
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units"
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
propertyId |
Location ヘッダーのURIに含まれる施設IDです。 |
文字列 | ◯ |
応答本文
{
"id": "amzn1.alexa.unit.did.{id}"
}
応答本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
新しいユニットのユニットIDです。 | 文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}"
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラータイプ。 | 文字列 | ✕ |
message |
エラーのエラーメッセージです。 | 文字列 | ✕ |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
201 | Created | ユニットが正常に作成されました。 |
400 | Bad Request | リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
400 | Invalid_Parent_Id | 指定された親ユニットIDが無効です。 |
400 | Invalid_Unit_Name | 名前はnullまたは空にできません。 |
400 | Level_Limit_Exceeded | 16レベル以上のユニットは作成できません。 |
401 | Unauthorized | アクセストークンがないか、無効です。 |
403 | Forbidden | サービスにアクセスする権限がユーザーにありません。 |
429 | Too many requests | リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。 |
500 | Internal Server Error | 内部サービスエラーのためリクエストを処理できませんでした。 |
ユニットを取得する
ユニットを取得するには、GET /v2/units/{unitId}
を呼び出します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
ドイツ、イタリア |
なし |
カナダ、ドイツ、フランス、イタリア、英国、米国 |
米国 |
リクエストの形式
GET /v2/units/{unitId}
&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
unitId |
取得するユニットのID。形式は"amzn1.alexa.unit.did.{id}" 。 |
文字列 | ◯ |
リクエスト本文
なし。
応答ヘッダー
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
応答本文
{
"id": "amzn1.alexa.unit.did.{unitId}",
"name": {
"type": "PLAIN",
"value": {
"text": "UnitName"
}
},
"level": 0,
"parentId": null
}
応答本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
name.type |
name.valueフィールドの予想される形式タイプ。 有効な値: PLAIN |
文字列 | ◯ |
name.value |
ユニットの名前です。 | NameValue | ◯ |
level |
ルームユニットからそのユニットまでのレベル数。ルームユニットのレベルは0です。 | 整数 | ◯ |
parentId |
新しく作成されるユニットの上のユニット。 | 文字列 | ◯ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}"
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラータイプ。 | 文字列 | ✕ |
message |
エラーのエラーメッセージです。 | 文字列 | ✕ |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
200 | OK | リクエストが成功しました。 |
400 | Bad_Request | リクエストの形式が正しくありませんでした。 |
400 | Invalid_Unit_Id | unitId が無効です。 |
401 | Unauthorized | アクセストークンがないか、無効です。 |
403 | Forbidden | サービスにアクセスする権限がユーザーにありません。 |
404 | No_Such_Unit | リクエストされたユニットが見つかりませんでした。 |
429 | Too_many_requests | リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。 |
500 | Internal Server Error | 内部サービスエラーのためリクエストを処理できませんでした。 |
ユニットのリストを取得する
GET /v2/units/
を呼び出して、ユニットを取得します。子ユニットがない場合、空のリストが返されます。呼び出し元によってアクセスできるユニットのみが返されます。指定された深さまでのすべてのサブユニットが返されます(指定されている場合)。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
ドイツ、イタリア |
なし |
カナダ、ドイツ、フランス、イタリア、英国、米国 |
米国 |
リクエストの形式
GET /v2/units/
&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのクエリパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
parentId |
子ユニットを返すその親ユニットのID。形式は"amzn1.alexa.unit.did.{id}" 。 |
文字列 | ◯ |
maxResults |
リクエストで取得するエントリ数。デフォルト: 10エントリが返されます。現在の最大値は50です。 | 整数 | ✕ |
nextToken |
次の項目セットを取得するためのトークンです。最初のリクエストと同じフィルターパラメーターを指定する必要があります。パラメーターが変更されていると、400 Bad Request例外が返されます。 | 文字列 | ✕ |
queryDepth |
返されるサブユニットの深さを制御します。 デフォルト: デフォルトのサブユニットの深さは1です。queryDepth = all の場合は、サブユニットの深さの制限がないため、すべての子ユニットが返されます。queryDepth = 1 の場合は、parentUnitId直下の子が取得されます。queryDepth > 1 の場合は、最大深さ値としてその階層のレベルまで、またはパラメーターで指定されている深さまで取得されます。例:queryDepth=4の場合、そのユニットの階層が4レベルであれば、深さ4レベル分が返されます。階層に3レベルしかなければ、深さ3レベル分のみ返されます。 |
文字列 | ✕ |
expand |
応答に含めるアトリビュート(またはアトリビュートのセット)。現在サポートされている値:all リクエストで expand=all が渡されない場合、ユニットのid プロパティのみ返されます。 |
文字列 | ✕ |
リクエスト本文
なし。
応答ヘッダー
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
応答本文
{
"results": [
{
"id": "amzn1.alexa.unit.{unitId}",
"name": {
"type": "PLAIN",
"value": {
"text": "unitName"
}
}
"parentId": "amzn1.alexa.unit.{unitID}",
"level":0
}
],
"paginationContext": {
"nextToken": "ABCD1234"
}
}
応答本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
id |
ユニットのIDです。 | 文字列 | ◯ |
name.type |
name.valueフィールドの予想される形式タイプ。 有効な値: PLAIN |
文字列 | ◯ |
name.value |
ユニットの名前です。 | NameValue | ◯ |
parentId |
新しく作成されるユニットの上のユニット。 | 文字列 | ◯ |
level |
ルームユニットからそのユニットまでのレベル数。ルームユニットのレベルは0です。 | 整数 | ◯ |
nextToken |
結果の次のページを取得するためのトークンです。詳細については、クエリ結果のページ分割を処理するを参照してください。 | 文字列 | ✕ |
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}"
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラータイプ。 | 文字列 | ✕ |
message |
エラーのエラーメッセージです。 | 文字列 | ✕ |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
200 | OK | リクエストが成功しました。 |
400 | Bad_Request | リクエストの形式が正しくありませんでした。 |
400 | Invalid_Next_Token | ページ分割トークンが無効か、有効期限が切れています。 |
400 | Invalid_Max_Result | リクエストした結果数が、サポートされている最大数を超えています。 |
400 | Invalid_Parent_Id | 親ユニットIDがnullか空です。 |
401 | Unauthorized | アクセストークンがないか、無効です。 |
403 | Forbidden | サービスにアクセスする権限がユーザーにありません。 |
404 | No_Such_Unit | リクエストされたユニットが見つかりませんでした。 |
429 | Too_many_requests | リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。 |
500 | Internal Server Error | 内部サービスエラーのためリクエストを処理できませんでした。 |
一番下までの子ユニットと全情報を含める
これは、次のexpand=all
パラメーターとqueryDepth=all
パラメーターを使って、親ユニットの下にあるすべてのユニットと、各ユニットの詳細情報を含めるリクエストの例です。
GET /v2/units?parentId={unitId}&queryDepth=all&expand=all HTTP/1.1
queryDepthは1、拡張パラメーターはなし
これは、次のexpand=all
パラメーターとqueryDepth=all
パラメーターを使って、親ユニットの下にあるすべてのユニットと、各ユニットの詳細情報を含めるリクエストの例です。
GET /v2/units?parentId={unitId}&queryDepth=1 HTTP/1.1
queryDepth all、拡張パラメーターはなし
これは、次のexpand=all
パラメーターとqueryDepth=all
パラメーターを使って、親ユニットの下にあるすべてのユニットと、各ユニットの詳細情報を含めるリクエストの例です。
GET /v2/units?parentId={unitId}&queryDepth=all HTTP/1.1
ユニットを更新する
ユニットの名前を更新するには、PUT /v2/units/{unitId}
を呼び出します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
ドイツ、イタリア |
なし |
カナダ、ドイツ、フランス、イタリア、英国、米国 |
米国 |
リクエストの形式
PUT /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
unitId |
更新するユニットのID。形式は"amzn1.alexa.unit.did.{id}" 。 |
文字列 | ◯ |
リクエスト本文の形式
{
"name": {
"type": "PLAIN",
"value": {
"text": "NAME"
}
}
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
name.type |
name.valueフィールドの予想される形式タイプ。 有効な値: PLAIN |
文字列 | ◯ |
name.value |
ユニットの名前です。 | NameValue | ◯ |
応答ヘッダー
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units/{unitId}"
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
propertyId |
Location ヘッダーのURIに含まれる施設IDです。 |
文字列 | ◯ |
応答本文
なし。
応答本文のパラメーター
なし。
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}"
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラータイプ。 | 文字列 | ✕ |
message |
エラーのエラーメッセージです。 | 文字列 | ✕ |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
204 | OK | ユニットが正常に更新されました。 |
400 | Bad Request | リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
400 | Invalid_Unit_Name | 名前はnullまたは空にできません。 |
400 | Invalid_Unit_ID | unitId が無効です。 |
401 | Unauthorized | アクセストークンがないか、無効です。 |
403 | Forbidden | サービスにアクセスする権限がユーザーにありません。 |
429 | Too many requests | リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。 |
500 | Internal Server Error | 内部サービスエラーのためリクエストを処理できませんでした。 |
ユニットを削除する
ユニットを削除するには、DELETE /v2/units/{unitId}
を呼び出します。そのユニットが子ユニットを持っている場合、400 Bad Requestが返されます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
ドイツ、イタリア |
なし |
カナダ、ドイツ、フランス、イタリア、英国、米国 |
米国 |
リクエストの形式
DELETE /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
unitId |
削除するユニットのID。形式は"amzn1.alexa.unit.did.{id}" 。 |
文字列 | ◯ |
リクエスト本文の形式
なし。
リクエスト本文のパラメーター
なし。
応答ヘッダー
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units/{unitId}"
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
X-Amzn-RequestId |
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 | 文字列 | ◯ |
応答本文
なし。
応答本文のパラメーター
なし。
エラー応答
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}"
"message": "{ErrorMessage}"
}
エラー応答のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
エラータイプ。 | 文字列 | ✕ |
message |
エラーのエラーメッセージです。 | 文字列 | ✕ |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
204 | OK | ユニットが正常に削除されました。 |
400 | Bad Request | リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
400 | Invalid_Unit_ID | unitId が無効です。 |
400 | Unit_Has_Chile | 子ユニットが1つ以上あるため、このユニットを削除できません。 |
400 | Invalid_Unit_ID | 1つ以上のエンドポイントが関連付けられているため、このユニットを削除できません。 |
401 | Unauthorized | アクセストークンがないか、無効です。 |
403 | Forbidden | サービスにアクセスする権限がユーザーにありません。 |
404 | No_Such_Unit | このユニットは存在しません。 |
429 | Too many requests | リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。 |
500 | Internal Server Error | 内部サービスエラーのためリクエストを処理できませんでした。 |
最終更新日: 2023 年 03 月 06 日