施設階層管理API


施設階層管理API

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

APIエンドポイント

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを以下のいずれかに設定してください。

エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.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 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 ユニットの名前。ユニット名には、英数字および特殊文字_ - = # ; : ? @ &を使用できます。スペースとピリオドは使用できません。ユニット名は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 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 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 1回のリクエストで取得するエントリ数。デフォルトでは 10個のエントリが返されます。現在の最大値は50です。 Integer
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パラメーターなし

以下の例は、expand=allパラメーターとqueryDepth=allパラメーターを使用して、親ユニットの下にあるすべてのユニットと、各ユニットの詳細を含める方法を示しています。

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

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

以下の例は、expand=allパラメーターとqueryDepth=allパラメーターを使用して、親ユニットの下にあるすべてのユニットと、各ユニットの詳細を含める方法を示しています。

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

ユニットを更新する

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

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

Healthcare Hospitality 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 ユニットの名前。ユニットの名前。ユニット名には、英数字および特殊文字_ - = # ; : ? @ &を使用できます。スペースとピリオドは使用できません。ユニット名は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 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_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 年 11 月 30 日