施設階層管理API

施設階層管理API

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

APIエンドポイント

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

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.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

米国

米国、ドイツ、イタリア、スペイン、日本

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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.text ユニットの名前。ユニット名には、英数字および特殊文字_ - = # ; : ? @ &を使用できます。スペースとピリオドは使用できません。ユニット名は250文字以内にする必要があります。 文字列 ◯
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つ以上の必須パラメーターがありません。

  • INVALID_PARENT_ID - 指定された親ユニットIDが無効です。
  • INVALID_UNIT_NAME - 名前をnullまたは空にすることはできません。
  • 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

米国

米国、ドイツ、イタリア、スペイン、日本

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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.text ユニットの名前。 文字列 ◯
level ルートユニットからこのユニットまでのレベル数。ルートユニットのレベルは0です。 整数 ◯
parentId 取得したユニットの親ユニットのID。 文字列 ◯

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド 説明 型 必須
type エラータイプです。 文字列 ✕
message エラーのエラーメッセージ。 文字列 ✕

HTTP応答コード

ステータス 説明

200 OK

リクエストが成功しました。

400 Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

  • INVALID_UNIT_ID - unitIdが無効です。

401 Unauthorized

アクセストークンがないか、無効です。

403 Forbidden

サービスにアクセスする権限がユーザーにありません。

404 Not Found

NO_SUCH_UNIT - リクエストされたユニットが見つかりませんでした。

429 Too Many Requests

リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。

500 Internal Server Error

内部サービスエラーのためリクエストを処理できませんでした。

ユニットのリストを取得する

ユニットのリストを取得するには、GET /v2/units/を呼び出します。子ユニットがない場合は、空のリストが返されます。この操作では、呼び出し元からアクセスできるユニットが返されます。サブユニットの深さを指定している場合は、指定した深さまでのサブユニットがすべて返されます。

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

Healthcare Hospitality Senior Living Core

米国

米国、ドイツ、イタリア、スペイン、日本

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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です。

整数

✕

nextToken

次の項目セットを取得するためのトークン。このプロパティは、前回の応答のpaginationContext.nextTokenプロパティで返されたトークンに設定します。最初のリクエストと同じフィルターパラメーターを使用してください。フィルターパラメーターが変更されると、400 Bad Request例外が返されます。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

✕

queryDepth

取得するサブユニットの深さを制御します。設定しない場合、デフォルト値は1です。

  • queryDepth=all - サブユニットの深さは制限されず、すべての子ユニットが返されます。
  • queryDepth=1（デフォルト）- parentUnitIdの直下の子が返されます。
  • queryDepth=1より大きい値 - 階層の最深レベルか、パラメーターで指定された深さのどちらかに達するまで取得が行われます。たとえば、queryDepth=4を指定すると、ユニットの階層が4レベルあれば、深さ4レベル分が返されます。階層が3レベルしかない場合は、深さ3レベル分が返されます。

文字列

✕

expand

応答に含めるアトリビュートまたはアトリビュートのセット。現在サポートされている値は、allです。


expandが設定されていない場合、各ユニットの応答では、idプロパティにユニットID、その他の応答本文のプロパティにnullが返されます。expandがallに設定されている場合、各ユニットの応答では、該当するすべてのプロパティの値が返されます。

文字列

✕

リクエスト本文

なし。

応答ヘッダー

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"
  }
}

応答本文のパラメーター

フィールド 説明 型 必須
results リクエストに一致するユニット。 ユニットオブジェクトの配列 ◯
results[*].id ユニットのID。 文字列 ◯
results[*].name.type name.valueフィールドに想定される形式のタイプ。有効な値： PLAIN 文字列 ◯
results[*].name.value.text ユニットの名前。 文字列 ◯
results[*].parentId このユニットの親ユニットのID。 文字列 ◯
results[*].level ルートユニットからこのユニットまでのレベル数。ルートユニットのレベルは0です。 整数 ◯
paginationContext.nextToken 結果の次のページを取得するためのトークン。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

リクエストにexpand=allが指定されていない場合、各ユニットの応答にlevel、name、parentIdのプロパティは含まれますが、nullが返されます。

その他のリクエストと応答の例

以下は、expandパラメーターとqueryDepthパラメーターを使用して、親ユニットのすべてのユニットと、各ユニットの詳細を取得するリクエストの例です。

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

以下は、queryDepthパラメーターを使用して、1レベル分のユニットを取得するリクエストの例です。このリクエストでは、詳細はすべて取得しません。リクエストにexpand=allが指定されていないため、level、name、parentIdのプロパティにはすべてnullが返されます。

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

以下は、queryDepthパラメーターを使用して、親ユニットのすべてのユニットを取得するリクエストの例です。このリクエストでは、詳細は取得しません。リクエストにexpand=allが指定されていないため、level、name、parentIdのプロパティにはすべてnullが返されます。

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

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}"
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド 説明 型 必須
type エラータイプです。 文字列 ✕
message エラーのエラーメッセージ。 文字列 ✕

HTTP応答コード

ステータス 説明

200 OK

リクエストが成功しました。

400 Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

  • INVALID_NEXT_TOKEN - nextTokenで指定されたトークンが無効か、有効期限が切れています。
  • INVALID_MAX_RESULT - リクエストされた結果の数が、サポートされている最大数を超えています。
  • INVALID_PARENT_ID - 親ユニットIDがnullまたは空です。

401 Unauthorized

アクセストークンがないか、無効です。

403 Forbidden

サービスにアクセスする権限がユーザーにありません。

404 Not Found

NO_SUCH_UNIT - リクエストされたユニットが見つかりませんでした。

429 Too Many Requests

リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。

500 Internal Server Error

内部サービスエラーのためリクエストを処理できませんでした。

ユニットを更新する

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

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

Healthcare Hospitality Senior Living Core

米国

米国、ドイツ、イタリア、スペイン、日本

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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.text ユニットの名前。ユニットの名前。ユニット名には、英数字および特殊文字_ - = # ; : ? @ &を使用できます。スペースとピリオドは使用できません。ユニット名は250文字以内にする必要があります。 文字列 ◯

応答ヘッダー

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応答コード

ステータス 説明

200 OK

ユニットが更新されました。

400 Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

  • INVALID_UNIT_NAME - 名前をnullまたは空にすることはできません。
  • 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

米国

米国、ドイツ、イタリア、スペイン、日本

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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応答コード

ステータス 説明

200 OK

ユニットが削除されました。

400 Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

  • UNIT_HAS_CHILD - 1つ以上の子ユニットがあるため、このユニットを削除できません。
  • UNIT_HAS_ENDPOINT - 1つ以上のエンドポイントが関連付けられているため、ユニットを削除できません。

401 Unauthorized

アクセストークンがないか、無効です。

403 Forbidden

サービスにアクセスする権限がユーザーにありません。

404 Not Found

NO_SUCH_UNIT - リクエストされたユニットが見つかりませんでした。

429 Too Many Requests

リクエストが制限されました。1秒後に再試行したら、エクスポネンシャルバックオフを行い、待機間隔が256秒になったら、以降は429以外の応答を受信するまで256秒ごとに再試行します。

500 Internal Server Error

内部サービスエラーのためリクエストを処理できませんでした。

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

最終更新日: 2024 年 06 月 19 日