施設階層管理API

Note: Sign in to the developer console to build or publish your skill.

施設階層管理API

注：このAPIは、登録済みのAlexa Smart Properties in Hospitalityパートナーのみ使用できます。Alexa Smart Properties for Hospitality APIで開発を始めるを参照してください。

施設階層の構成要素はユニットです。組織の下に施設を表すユニットを作成し、その下にルームを表す複数のユニットを作成できます。または、階層のレベルを1つ増やす必要がある場合は、施設ユニットの下に施設のフロアを表すユニットを作成し、各フロアユニットの下に、そのフロアの部屋を表すユニットを追加できます。ユニット管理APIでは、階層に最大15レベルのユニットを作成して施設を表現することができます。施設の階層が3レベル以上になる場合は、APIを使用して管理する必要があります。このような施設をコンソールで管理することはできません。

APIエンドポイント

施設階層管理APIのエンドポイントは、https://api.amazonalexa.comです。

認証

すべてのAPIリクエストには認可ヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。

操作

施設階層管理APIには、以下の操作が用意されています。

操作	HTTPメソッドとURI
ユニットを作成する	`POST /v2/units`
ユニットを取得する	`GET /v2/units/{unitId}`
ユニットのリストを取得する	`GET /v2/units`
ユニットを更新する	`PUT /v2/units/{unitId}`
ユニットを削除する	`DELETE /v2/units/{unitId}`

ユニットを作成する

物理的な構成単位（施設、フロア、翼棟、部屋など）を表すユニットを作成するには、POST /v2/unitsを呼び出します。

ユニットとは、Alexaシステムと対話する人およびリソース（スキルやデバイス）を編成するための管理構造です。ユニットは階層的であり、0個以上のサブユニットを持つことができます。ユニットの親を、そのユニットのサブユニットにすることはできません。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	ドイツ、イタリア	なし	カナダ、ドイツ、フランス、イタリア、英国、米国	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

POST /v2/units HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

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

ありません。

リクエスト本文の形式

{
  "name": {
              "type": "PLAIN",
              "value": {
                   "text": "name of unit"
               }
            },
  "parentId": "amzn1.alexa.unit.did.{unitId}"
}

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

フィールド	説明	型	必須
`name.type`	name.valueフィールドに想定される形式のタイプです。有効な値： `PLAIN`	文字列	◯
`name.value`	ユニットの名前です。ユニット名には、英数字および特殊文字_ - = # ; : ? @ &を使用できます。スペースとピリオドは使用できません。ユニット名は250文字以内にする必要があります。	NameValue	◯
`parentId`	新しく作成されるユニットを格納する親ユニットです。	文字列	◯

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units"

フィールド	説明	型	必須
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列	◯
`propertyId`	施設IDです。`Location`ヘッダーにURIの一部として含まれます。	文字列	◯

応答本文

{
  "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
米国	ドイツ、イタリア	なし	カナダ、ドイツ、フランス、イタリア、英国、米国	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

GET /v2/units/{unitId}
&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

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

フィールド	説明	型	必須
`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/を呼び出します。子ユニットがない場合は、空のリストが返されます。呼び出し元からアクセスできるユニットのみが返されます。サブユニットがある場合は、指定した深さまでのサブユニットがすべて返されます。

注：結果が最後まで取得されたことを確認するために、ページ分割トークンがnullかどうかをチェックする必要があります。場合によっては、認可チェックですべてのユニットがフィルタリングされ、空の結果が返されることがあります。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	ドイツ、イタリア	なし	カナダ、ドイツ、フランス、イタリア、英国、米国	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

GET /v2/units/
&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

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

フィールド	説明	型	必須
`parentId`	子ユニットを取得するユニットのIDです。形式は`"amzn1.alexa.unit.did.{id}"`です。	文字列	◯
`maxResults`	1回のリクエストで取得するエントリ数です。デフォルトでは 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パラメーターなし

GET /v2/units?parentId={unitId}&queryDepth=1 HTTP/1.1

queryDepth=all、expandパラメーターなし

GET /v2/units?parentId={unitId}&queryDepth=all HTTP/1.1

ユニットを更新する

ユニットの名前を更新するには、PUT /v2/units/{unitId}を呼び出します。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	ドイツ、イタリア	なし	カナダ、ドイツ、フランス、イタリア、英国、米国	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

PUT /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

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

フィールド	説明	型	必須
`unitId`	更新するユニットのIDです。形式は`"amzn1.alexa.unit.did.{id}"`です。	文字列	◯

リクエスト本文の形式

{
   "name": {
             "type": "PLAIN",
              "value": {
                  "text": "NAME"
               }
           }
}

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

フィールド	説明	型	必須
`name.type`	name.valueフィールドに想定される形式のタイプです。有効な値： `PLAIN`	文字列	◯
`name.value`	ユニットの名前です。ユニットの名前です。ユニット名には、英数字および特殊文字_ - = # ; : ? @ &を使用できます。スペースとピリオドは使用できません。ユニット名は250文字以内にする必要があります。	NameValue	◯

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Location: "/v2/units/{unitId}"

フィールド	説明	型	必須
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列	◯
`propertyId`	施設IDです。`Location`ヘッダーにURIの一部として含まれます。	文字列	◯

応答本文

ありません。

応答本文のパラメーター

ありません。

エラー応答

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
米国	ドイツ、イタリア	なし	カナダ、ドイツ、フランス、イタリア、英国、米国	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

DELETE /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

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

フィールド	説明	型	必須
`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_Child	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 月 16 日