ロールREST APIリファレンス

ロールREST APIリファレンス

Alexa Smart Properties（ASP）の組織のロールを管理するには、ロールREST APIを使用します。ロールは、ユーザーがユニットに対して実行できる操作を定義します。ユーザーがASPリソースにアクセスできるようにするには、まずユーザーにロールを割り当てる必要があります。ユニットの作成者には、Alexaによって自動的に管理者ロールが割り当てられます。

組織のロールの詳細については、Alexa Smart Propertiesのロールを管理するを参照してください。

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 /v1/roles/{roleId}/assignments

ロールを一括で割り当てる

POST /v1/roles/{roleId}/assignments/batchAssign

ロールの割り当てを一括で取り消す

POST /v1/roles/{roleId}/assignments/batchRevoke

ロールを取得する

GET /v1/roles/{roleId}

プリンシパルの割り当てリストを取得する

GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken}

ロールのリストを取得する

GET /v1/roles?unitId={unitId}&targetEntityId={targetEntityId}&roleName={roleName}&maxResults={maxResults}&nextToken={nextToken}

ロールの割り当てリストを取得する

GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}

ロールの割り当てを取り消す

DELETE /v1/roles/{roleId}/assignments?principalId={principalId}&propagate={propagate}

ロールを割り当てる

指定したプリンシパルに、指定したロールを割り当てます。既にロールが割り当てられているプリンシパルに、同じロールを割り当てることはできません。プリンシパルのユーザーIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ロールを割り当てると同時に、必要に応じてロールの割り当てをプロパティ階層に伝播できます。また、ロールを一時的に割り当てることもできます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ロールを割り当てるには、/v1/roles/{roleId}/assignmentsリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/roles/{roleId}/assignments HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

roleId

パス

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

   "principalId" : "amzn1.account.1",
   "propagate" : true,
   "expiresAt": "2021-11-02T12:51:00.000Z"

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

プロパティ 説明 型 必須

principalId

ロールの割り当て先となるプリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。
プリンシパルIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ユーザープロファイルの応答で受け取ったuser_idを、principalIdの値として使用します。

文字列

◯

propagate

ロールの割り当てをユニット階層全体に伝播するかどうかを示します。
ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。
デフォルト値はfalseです。

ブール値

×

expiresAt

指定したプリンシパルに、指定した有効期限の日時までロールを割り当てます。
有効期限は、現在の時刻から30分後～30日後の間で指定する必要があります。設定しない場合、ロールの割り当ての有効期限が切れることはありません。expiresAtに値が設定されている場合、propagateがtrueであれば、ユニット階層内のすべての割り当てで有効期限が継承されます。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

×

応答

正常に完了すると、HTTP 202 AcceptedまたはHTTP 204 No contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

202 Accepted

ロールが正常に割り当てられ、指定されたプリンシパルの伝播リクエストが受け付けられました。

204 No content

ロールが正常に割り当てられました。伝播は指定されませんでした。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

ロールを一括で割り当てる

指定したロールをプリンシパルのリストに割り当てます。プリンシパルのユーザーIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ロールを割り当てると同時に、必要に応じてロールの割り当てをプロパティ階層に伝播できます。また、ロールを一時的に割り当てることもできます。

この操作は、リクエストを受け付けると同期的に検証を実行し、成功応答を返します。その後、各プリンシパルがバックグラウンドで非同期的にロールに割り当てられます。無効な入力がある場合は、操作全体が失敗します。リクエスト項目はすべて処理されるか、まったく処理されないかのどちらかになります。

特定のroleIdとprincipalIdに対してpropagateがfalseに設定された既存のロール割り当てがある場合、同じroleIdとprincipalIdに対してpropagateの値をtrueに設定してロールの割り当てリクエストを行うと、既存のロール割り当てが更新され、伝播が有効になります。

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

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、日本

米国、カナダ、日本

米国

リクエスト

ロールを割り当てるには、/v1/roles/{roleId}/assignments/batchAssignリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/roles/{roleId}/assignments/batchAssign HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

roleId

パス

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
   "items": [
     {
        "itemId" : 0,
        "principalId"</span>:<//span> "amzn1.alexa.user.2",
        "propagate": false,
        "expiresAt": "2021-11-02T12:51:00.000Z"
     },
     {
        "itemId" : 1,         
        "principalId": "amzn1.alexa.user.3",
        "propagate": true
     },
     {
        "itemId" : 2,
        "principalId": "amzn1.alexa.user.4",
        "propagate": false
     }
   ]
}

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

プロパティ 説明 型 必須

items

ロールの割り当て先となるプリンシパルのリスト。

オブジェクトの配列

◯

items[].itemId

割り当ての一意のID。

整数

◯

items[].principalId

ロールの割り当て先となるプリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。
プリンシパルIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ユーザープロファイルの応答で受け取ったuser_idを、principalIdの値として使用します。

文字列

◯

items[].propagate

ロールの割り当てをユニット階層全体に伝播するかどうかを示します。
ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。

ブール値

×

items[].expiresAt

指定したプリンシパルに、指定した有効期限の日時までロールを割り当てます。
有効期限は、現在の時刻から30分後～30日後の間で指定する必要があります。設定しない場合、ロールの割り当ての有効期限が切れることはありません。expiresAtに値が設定されている場合、propagateがtrueであれば、ユニット階層内のすべての割り当てで有効期限が継承されます。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

×

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

202 Accepted

指定されたプリンシパルに対するロールの割り当てリクエストが受け付けられました。

400 Bad Request

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

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • BAD_REQUEST - リクエストの形式が正しくないか、必須パラメーターが不足しています。
  • DUPLICATE_REQUEST_ITEM_FOUND - リクエストに重複するリクエスト項目が含まれています。
  • INVALID_PRINCIPAL_ID - principalIdが無効です。
  • INVALID_ROLE_ID - roleIdが無効です。
  • NO_UNIT_FOR_ROLE - ロールがユニットに基づいていません。伝播はサポートされません。
  • REQUEST_LIMIT_EXCEEDED - リクエストに指定されたロール割り当てのプリンシパル数が、1回のリクエストあたりの上限を超えています。
  • ROLE_ASSIGNMENT_NOT_SUPPORTED - 既に伝播されているロール割り当てをスタンドアロンの割り当てにダウングレードすることはできません。propagateフラグはtrueでなければなりません。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

ロールの割り当てを一括で取り消す

指定したプリンシパルのリストに対するロールの割り当てを削除します。ロールの割り当ての取り消しをプロパティ階層に伝播できます。

この操作は、リクエストを受け付けると同期的に検証を実行し、成功応答を返します。その後、各プリンシパルのロールがバックグラウンドで非同期的に取り消されます。無効な入力がある場合は、操作全体が失敗します。リクエスト項目はすべて処理されるか、まったく処理されないかのどちらかになります。

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

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、日本

米国、カナダ、日本

米国

リクエスト

ロールを削除するには、/v1/roles/{roleId}/assignments/batchRevokeリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/roles/{roleId}/assignments/batchRevoke
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

roleId

パス

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
   "items": [
     {
        "itemId" : 0,
        "principalId": "amzn1.alexa.user.example1",
        "propagate": false
     },
     {
        "itemId" : 1,         
        "principalId": "amzn1.alexa.user.3",
        "propagate": true
     },
     {
        "itemId" : 2,
        "principalId": "amzn1.alexa.user.4",
        "propagate": false
     }
   ]
}

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

プロパティ 説明 型 必須

items

ロールを取り消すプリンシパルのリスト。

オブジェクトの配列

◯

items[].itemId

割り当ての一意のID。

整数

◯

items[].principalId

ロールを取り消すプリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。
プリンシパルIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ユーザープロファイルの応答で受け取ったuser_idを、principalIdの値として使用します。

文字列

◯

items[].propagate

ロールの取り消しをユニット階層全体に伝播するかどうかを示します。
ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。

ブール値

×

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

202 Accepted

指定されたプリンシパルに対するロールの取り消しリクエストが受け付けられました。

400 Bad Request

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

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • BAD_REQUEST - リクエストの形式が正しくないか、必須パラメーターが不足しています。
  • DUPLICATE_REQUEST_ITEM_FOUND - リクエストに重複するリクエスト項目が含まれています。
  • INVALID_PRINCIPAL_ID - principalIdが無効です。
  • INVALID_ROLE_ID - roleIdが無効です。
  • NO_UNIT_FOR_ROLE - ロールがユニットに基づいていません。伝播はサポートされません。
  • PRINCIPAL_IS_PROPAGATED - このプリンシパルに対するロールの取り消しはサポートされません。現在のロールの割り当ては、伝播チェーンのソースです。propagateフラグにtrueの値を設定して渡す必要があります。
  • PRINCIPAL_IS_NOT_PROPAGATED - このプリンシパルに対するロールの取り消しはサポートされません。現在のロールの割り当ては、伝播されていない割り当てです。propagateフラグを渡さないようにするか、propagateフラグをfalseに設定してください。
  • PROPAGATED_FROM_ANOTHER_ROLE - 伝播されたロールの割り当てを取り消そうとしました。伝播元から、propagateフラグをtrueに設定して取り消しの伝播を再実行してください。
  • REQUEST_LIMIT_EXCEEDED - リクエストに指定されたロール割り当てのプリンシパル数が、1回のリクエストあたりの上限を超えています。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

ロールを取得する

指定したロールの詳細を取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

ロールの詳細を取得するには、/v1/roles/{roleId}リソースに対してGETリクエストを実行します。

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

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

GET /v1/roles/{roleId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

roleId

パス

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、ロールの詳細が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

{
   "roleId": "amzn1.alexa.role.did.1",
   "roleName": "Admin",
   "unitId": "amzn1.alexa.unit.did.101",
   "targetEntityId": "target.entity.1"
}

応答本文のプロパティ

プロパティ 説明 型

roleId

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

文字列

roleName

ロールの名前。

文字列

unitId

ロールに関連付けられているユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

targetEntityId

ロールが割り当てられているターゲットエンティティを識別します。

文字列

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

米国

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

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

米国

リクエスト

割り当てのリストを取得するには、/v1/roles/{roleId}/assignmentsリソースに対してGETリクエストを実行します。

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

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

GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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

パラメーター 指定場所 説明 型 必須

roleId

パス

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

maxResults

クエリ

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

整数

×

nextToken

クエリ

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

文字列

×

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、ロールの割り当てリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

{
  "results": [
    {
      "roleId": "amzn1.alexa.role.did.1",
      "principalId": "amzn1.account.1",
      "expiresAt": "2021-06-10T14:00:00Z",
      "propagatedRoleId": "amzn1.alexa.role.originRoleId"
    },
    {
      "roleId": "amzn1.alexa.role.did.1",
      "principalId": "amzn1.account.2",
      "expiresAt": "2021-06-10T14:00:00Z",
      "propagatedRoleId": "amzn1.alexa.role.originRoleId"
    }
  ],
  "paginationContext": {
    "nextToken": null
  }
}

応答本文のプロパティ

プロパティ 説明 型

results

ロールの割り当てリスト。

オブジェクトの配列

results[].roleId

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].principalId

ロールに割り当てられているプリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].expiresAt

（オプション）割り当てられているロールの有効期限の日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].propagatedRoleId

（オプション）このロール割り当ての伝播元のロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

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

米国

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

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

米国

リクエスト

ロールのリストを取得するには、/v1/rolesリソースに対してGETリクエストを実行します。

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

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

GET /v1/roles?unitId={unitId}&targetEntityId={targetEntityId}&roleName={roleName}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

unitId

クエリ

ユニットでフィルタリングします。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。
リクエストには、unitIdかtargetEntityIdのどちらかを指定する必要があります。

文字列

×

targetEntityId

クエリ

ターゲットエンティティの名前でフィルタリングします。
リクエストには、unitIdかtargetEntityIdのどちらかを指定する必要があります。

文字列

×

roleName

クエリ

ロールの名前でフィルタリングします。

文字列

×

maxResults

クエリ

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

整数

×

nextToken

クエリ

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

文字列

×

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたユニットまたはターゲットエンティティのロールのリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

{
   "results": [
      {
         "roleId": "amzn1.alexa.role.did.1",
         "roleName": "Admin",
         "unitId": "amzn1.alexa.unit.did.101",
         "targetEntityId": "amzn1.alexa.unit.did.101"         
      },
      {
         "roleId": "amzn1.alexa.role.did.2",
         "roleName": "ReadOnly",
         "unitId": "amzn1.alexa.unit.did.101",
         "targetEntityId": "amzn1.alexa.unit.did.101"         
      }     
   ],
   "paginationContext": {
      "nextToken": someToken.1
   }
}

応答本文のプロパティ

プロパティ 説明 型

results

指定されたユニットまたはターゲットエンティティのロールのリスト。

オブジェクトの配列

results[].roleId

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

文字列

results[].roleName

ロールの名前。

文字列

results[].unitId

ロールに関連付けられているユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].targetEntityId

ロールが割り当てられているターゲットエンティティを識別します。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

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

米国

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

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

米国

リクエスト

割り当てのリストを取得するには、/v1/roles/assignmentsリソースに対してGETリクエストを実行します。

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

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

GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

principalId

クエリ

ロールの割り当てを取得するプリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。
プリンシパルIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ユーザープロファイルの応答で受け取ったuser_idを、principalIdの値として使用します。

文字列

◯

unitId

クエリ

ユニットでフィルタリングします。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

×

targetEntityId

クエリ

ターゲットエンティティの名前でフィルタリングします。

文字列

×

maxResults

クエリ

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

整数

×

nextToken

クエリ

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

文字列

×

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたプリンシパルに対するロールの割り当てリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

{
  "results" : [
    {
      "roleId" : "amzn1.alexa.role.did.1",
      "principalId" : "amzn1.account.1",
      "expiresAt": "2021-06-10T14:00:00Z",
      "propagatedRoleId": "amzn1.alexa.role.originRoleId"
    }
  ],
    "paginationContext": {
      "nextToken": null
  }
}

応答本文のプロパティ

プロパティ 説明 型

results

指定されたプリンシパルのロールのリスト。

オブジェクトの配列

results[].roleId

指定されたプリンシパルに割り当てられているロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[i].principalId

プリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].expiresAt

（オプション）割り当てられているロールの有効期限の日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

results[].propagatedRoleId

（オプション）このロール割り当ての伝播元のロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

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

米国

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

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

米国

リクエスト

ロールの割り当てを削除するには、/v1/roles/{roleId}/assignmentsリソースに対してDELETEリクエストを実行します。

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

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

DELETE /v1/roles/{roleId}/assignments?principalId={principalId}&propagate={propagate}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

パラメーター 指定場所 説明 型 必須

roleId

パス

ロールを識別します。
amzn1.alexa.role.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

principalId

クエリ

ロールの割り当てを取り消すプリンシパルを識別します。
amzn1.account.{id}というAmazon Common Identifier（ACI）形式で表します。
プリンシパルIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。ユーザープロファイルの応答で受け取ったuser_idを、principalIdの値として使用します。

文字列

◯

propagate

クエリ

ロールの取り消しをユニット階層全体に伝播するかどうかを示します。
ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。
デフォルト値はfalseです。

ブール値

×

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 202 AcceptedまたはHTTP 204 No contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文に人が読める形式のdescriptionが追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

202 Accepted

ロールが正常に取り消され、指定されたプリンシパルの伝播リクエストが受付られました。

204 No content

ロールが正常に取り消されました。伝播は指定されませんでした。

400 Bad Request

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

応答には、以下のいずれかのエラーを示すdescriptionが含まれる場合があります。

  • 別のユニットから伝播されたロールの割り当てを取り消そうとしました。
  • propagateフラグを指定せずに、伝播されたロールの割り当てを取り消そうとしました（または、その逆を行おうとしました）。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

オブジェクトの定義

ロールAPIでは、以下のオブジェクト定義が定義されています。

BatchErrorオブジェクト

BatchErrorオブジェクトは、バッチ操作中にエラーが発生した場合に応答に含まれるエラーコードと説明を定義します。

以下は、応答本文の例です。

{
  "errors": [
    {
       "itemId": 0,
       "status": 400,   
       "errorCode" : "INVALID_PRINCIPAL_ID",   
       "errorDescription": "Invalid principalId specified."
    },
    {
       "itemId": 1,
       "status": 400,      
       "errorCode" : "REQUEST_LIMIT_EXCEEDED",
       "errorDescription": "The number of request items in the batch request exceeds the limit (50)."
    }
  ]
}

BatchErrorオブジェクトには、以下のプロパティが定義されています。

プロパティ 説明 型

itemId

（オプション）失敗したリクエスト項目を識別します。

整数

status

HTTPステータスコード。

文字列

errorCode

発生したエラーのタイプ。

文字列

errorDescription

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

文字列

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

最終更新日: 2025 年 07 月 14 日