施設階層管理API

施設階層管理API

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

APIエンドポイント

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

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値には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

米国

ドイツ、イタリア

なし

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

米国

リクエストの形式

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 日