施設階層管理REST APIリファレンス

施設階層管理REST APIリファレンス

施設階層管理REST APIを使用して、施設をフロア、ユニット、ルームの階層として表すことができます。

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

デフォルトの音楽ステーションプロバイダーなど、ユニットの設定を行うには、ユニット設定REST APIリファレンスを参照してください。

APIエンドポイント

組織が所在する国に応じて、リクエストヘッダーのHostパラメーターを、以下のいずれかのAPIエンドポイントに設定してください。

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。

操作

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

操作 HTTPメソッドとURI

ユニットを作成する

POST /v2/units

ユニットを削除する

DELETE /v2/units/{unitId}

ユニットを取得する

GET/v2/units?maxResults={maxResults}&nextToken={nextToken}

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

GET /v2/units

ユニットを更新する

PUT /v2/units/{unitId}

ユニットを作成する

物理的な施設、フロア、翼棟、部屋を表すユニットを作成します。

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ユニットを作成するには、/v2/unitsリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v2/units
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
  "name": {
        "type": "PLAIN",
        "value": {
            "text": "Room-100"
        }
    },
  "parentId": "amzn1.alexa.unit.did.1"
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

name

ユニットの名前。

NameValueオブジェクト

◯

parentId

新しいユニットを作成する親ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

応答

正常に完了すると、HTTP 200 OKと共に、新しく作成されたユニットのIDが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
  "id": "amzn1.alexa.unit.did.100"
}

応答本文のプロパティ

プロパティ 説明 型

unitId

新しいユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

新しいユニットのIDが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

ユニットを削除する

指定されたユニットを削除します。子ユニットまたは関連付けられたエンドポイントがあるユニットを削除することはできません。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ユニットを削除するには、/v2/unitsリソースに対してDELETEリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

DELETE /v2/units/{unitId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

unitId

パス

削除するユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

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

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

  • UNIT_HAS_CHILD - 1つ以上の子ユニットがあるため、このユニットを削除できません。
  • UNIT_HAS_ENDPOINT - 1つ以上のエンドポイントが関連付けられているため、ユニットを削除できません。以下は、エラーコードとメッセージを含む応答本文の例です。 
    {
   "message": "The property is outside the allowed range.",
   "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

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

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

ユニットを取得する

指定されたユニットの詳細を取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ユニットを取得するには、/v2/unitsリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v2/units/{unitId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

unitId

パス

ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、ユニットの詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
    "id": "amzn1.alexa.unit.did.1",
    "name": {
        "type": "PLAIN",
        "value": {
            "text": "Room-100"
        }
    },
    "level": 0,
    "parentId": null
}

応答本文のプロパティ

プロパティ 説明 型

unitId

指定されたユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

name

ユニットの名前。

NameValueオブジェクト

level

ルートユニットからのレベル数。
ルートユニットのレベルは0です。

整数

parentId

指定されたユニットが属している親ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたユニットに関する詳細が応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

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

指定された親ユニットの下にあるユニットのリストを取得します。子ユニットがない場合は、空のリストが返されます。この操作では、呼び出し元からアクセスできるユニットのみが返されます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ユニットのリストを取得するには、/v2/unitsリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET/v2/units?parentId={parentId}&queryDepth={queryDepth}&expand={expand}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

parentId

パス

子ユニットのリストを取得する親ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

queryDepth

クエリ

取得する子ユニットのレベル数を制御します。
デフォルト値は 1です。
有効な値は次のとおりです。

  • all - 深さは制限されず、すべての子ユニットが返されます。
  • 1 - parentIdの直下の子が返されます。
  • 1より大きい値 - 階層の最深レベルか、queryDepthで指定された深さのどちらかに達するまで子ユニットのリストを取得します。
    たとえば、queryDepth=4を指定すると、ユニットの階層が4レベルあれば、深さ4レベル分が返されます。階層が3レベルしかない場合は、深さ3レベル分が返されます。

文字列

✕

expand

クエリ

各ユニットに関する詳細情報を取得します。
ユニットのアトリビュートを取得する場合は、allを指定します。ユニットIDのみを取得する場合は、このパラメーターを含めないでください。
有効な値はallです。

文字列

✕

maxResults

クエリ

応答で返される結果の最大数。
有効な値は 1～50です。デフォルト値は 10です。

整数

✕

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。

文字列

✕

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、指定された親ユニットの下にあるユニットのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、親ユニットの1レベル下にあるユニットの詳細を取得するparentId=amzn1.alexa.unit.2&expand=allのクエリパラメーターを含むリクエストへの応答の例です。

以下は、親ユニットの1レベル下にあるユニットを取得するparentId=amzn1.alexa.unit.1のクエリパラメーターを含むリクエストへの応答の例です。リクエストにexpand=allが指定されていないため、level、name、parentIdのプロパティにはnullが返されます。

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

応答本文のプロパティ

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

プロパティ 説明 型

results

指定された親IDの下にあるユニットのリスト。

オブジェクトの配列

results[].id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].name

ユニットの名前。

NameValueオブジェクト

results[].parentId

親ユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].level

ルートユニットからのレベル数。
ルートユニットのレベルは0です。

整数

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。
詳細については、APIのクエリ結果のページ分割を処理するを参照してください。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。この値は後続のリクエストで使用します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定された親ユニットの下にあるユニットのリストが応答本文に含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

ユニットを更新する

ユニットの名前を更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ユニットを更新するには、/v2/unitsリソースに対してPUTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

PUT /v2/units/{unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 位置 説明 型 必須

unitId

パス

更新するユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
    "name": {
        "type": "PLAIN",
        "value": {
            "text": "Room 101A"
        }
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

name

ユニットの名前。

NameValueオブジェクト

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

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

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

オブジェクトの定義

施設階層管理APIでは、以下のオブジェクトが定義されています。

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、エラータイプとメッセージを含む応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
プロパティ 説明 型

type

発生したエラーのタイプ。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

読み取り可能なエラーメッセージ。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

NameValueオブジェクト

NameValueオブジェクトは、オブジェクトの名前のコンテナーです。

以下の表は、オブジェクトのプロパティの定義です。

プロパティ 説明 型

type

値フィールドの形式。現時点でサポートされる形式は、プレーンテキストのみです。
有効な値は PLAINです。

文字列

value

名前。

オブジェクト

value.text

プレーンテキストで指定された名前。
最大長： 250文字。
有効な値は 英数字および特殊文字の文字列です。スペースとピリオドは使用できません。使用可能な特殊文字は、_ - = # ; : ? @ &です。

文字列

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

最終更新日: 2024 年 11 月 20 日