ロールAPI


ロールAPI

Alexa Smart PropertiesユーザーがAlexa Smart Propertiesリソースにアクセスできるようにするには、ユーザーにロールを割り当てておく必要があります。ユニットの作成者には、そのユニットの管理者ロールが自動的に割り当てられます。

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

APIエンドポイント

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

エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。

操作

ロールAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

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

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

ロールを割り当てる

POST /v1/roles/{roleId}/assignments

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

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

ロールを取得する

GET /v1/roles/{roleId}

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

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

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

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

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

DELETE /v1/roles/{roleId}/assignments

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

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

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

指定したユニットまたはターゲットエンティティに対して定義された、ユーザーに割り当て可能なロールのリストを取得するには、GET /v1/roles?unitId={unitId}&roleName={roleName}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}を呼び出します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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

リクエスト本文

なし。

リクエストのクエリパラメーター

フィールド 説明 必須

unitId

ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。

文字列

unitIdtargetEntityIdのどちらかを指定する必要があります。

targetEntityId

ターゲットエンティティのID。

文字列

unitIdtargetEntityIdのどちらかを指定する必要があります。

roleName

クライアントが特定のロールの詳細のみを必要としている場合に、ロール名を指定してフィルタリングできます。

文字列

nextToken

前回のロールリストの取得に対する応答で、応答オブジェクトに返された継続トークン。

文字列

maxResults

表示する結果の最大数。値は1~10の間で指定します。デフォルト値は10です。

整数

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

{
   "results": [
      {
         "roleId": "amzn1.alexa.role.did.example",
         "roleName": "{roleName}",
         "unitId": "amzn1.alexa.unit.did.example",
         "targetEntityId": "example-target-entity-id"         
      }
   ],
   "paginationContext": {
      "nextToken": null
   }
}

応答本文のパラメーター

フィールド 説明

roleId

ロールID。

文字列

roleName

ロール名。

文字列

unitId

ユニットのID。

文字列

targetEntityId

ターゲットエンティティのID。

文字列

paginationContext.nextToken

次回のリクエストで、結果の次のページを取得するための継続トークン(nextTokenクエリパラメーター)として使用できるトークン。

文字列

エラー応答

{
    "description": string
}

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

フィールド 説明

description

エラーの説明。例:"HTTP/1.1 401 The request has a missing or an invalid access token."

文字列

HTTP応答コード

ステータスコード 名前 説明

200

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

操作を実行する権限がユーザーにありません。

404

Not found

リクエストされたロールが見つかりませんでした。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

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

503

Service Unavailable

サーバーが一時的に使用できません。

ロールを割り当てる

指定したプリンシパルにロールを割り当てるには、POST /v1/roles/{roleId}/assignmentsを呼び出します。既にロールが割り当てられているプリンシパルに同じロールを割り当てようとすると、このAPIは400 Bad Request例外をスローします。プリンシパルの指定に必要なユーザーIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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

リクエスト本文の例

{
   "principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A",
   "propagate" : true
}

リクエストのパスパラメーター

フィールド 説明 必須

roleId

割り当てるロールのID。"amzn1.alexa.role.did.{id}"というAmazon Common Identifier(ACI)形式で表します。

文字列

リクエスト本文のパラメーター

フィールド 説明 必須

principalId

ロールの割り当て先となるプリンシパルのユーザーID。

文字列

propagate

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

ブール値

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文

なし。

エラー応答

{
    "description": string
}

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

フィールド 説明

description

エラーの説明。例:"HTTP/1.1 401 The request has a missing or an invalid access token."

文字列

HTTP応答コード

ステータスコード 名前 説明

202

Accepted

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

204

No content

リクエストが成功しました。この応答コードは、リクエストで伝播フラグが設定されなかった場合にのみ発生します。

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

操作を実行する権限がユーザーにありません。

404

Not found

リクエストされたロールが見つかりませんでした。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

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

503

Service Unavailable

サーバーが一時的に使用できません。

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

指定した複数のプリンシパルにロールを割り当てるには、POST /v1/roles/{roleId}/assignments/batchAssignを呼び出します。プリンシパルの指定に必要なユーザーIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。

リクエストの受け付けが完了したら、この操作は同期の検証を実行し、202(Accepted)の応答を返します。その後、各プリンシパルがバックグラウンドで非同期的にロールに割り当てられます。

入力が無効な場合は、バッチ操作全体が失敗します。つまり、リクエスト項目はすべて処理されるか、まったく処理されないかのどちらかになります。

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

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

Healthcare Hospitality Senior Living Core

米国

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

米国、カナダ

米国

リクエストの形式

POST /v1/roles/{roleId}/assignments/batchAssign
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

リクエスト本文の例

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

リクエストのパスパラメーター

フィールド 説明 必須

roleId

割り当てるロールのID。"amzn1.alexa.role.did.{id}"というAmazon Common Identifier(ACI)形式で表します。

文字列

リクエスト本文のパラメーター

フィールド 説明 必須

items

ロールの割り当てリクエストオブジェクトの配列。バッチリクエストで処理できるリクエスト項目の最大数は50です。

配列

items[*].itemId

リクエスト項目の一意のID。

整数

items[*].principalId

ロールの割り当て先となるプリンシパルのユーザーID。

文字列

items[*].propagate

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

ブール値

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文

正常に完了した場合、応答の本文はありません。

エラー応答本文の例

{
  "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)."
    }
  ]
}

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

フィールド 説明

errors

エラーの説明を含むオブジェクトの配列。考えられるエラーコードの一覧については、HTTP応答コードを参照してください。

配列

errors[*].itemId

リクエスト項目の一意のID。

整数

errors[*].status

エラーのステータス。例: 400

文字列

errors[*].errorCode

エラーコード。例: INVALID_PRINCIPAL_ID

文字列

errors[*].errorDescription

エラーの説明。例: Invalid principalId specified.

文字列

HTTP応答コード

ステータスコード 名前 説明

202

ACCEPTED

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

400

INVALID_PRINCIPAL_ID

principalIdが無効です。

400

NO_UNIT_FOR_ROLE

ロールがユニットでサポートされていません。伝播はサポートされていません。

400

ROLE_ASSIGNMENT_NOT_SUPPORTED

既に伝播されているロール割り当てをスタンドアロンの割り当てにダウングレードすることはサポートされていません。propagateフラグはtrueでなければなりません。

400

DUPLICATE_REQUEST_ITEM_FOUND

リクエストに重複したリクエスト項目が含まれています。

400

BAD_REQUEST

リクエストの形式が正しくないか、必須パラメーターが不足しています。

400

INVALID_ROLE_ID

roleIdが無効です。

400

REQUEST_LIMIT_EXCEEDED

リクエストのロール割り当てのプリンシパル数が、1回のリクエストあたりの上限を超えています。

401

UNAUTHORIZED

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

403

FORBIDDEN

操作を実行する権限がユーザーにありません。

404

ROLE_NOT_FOUND

リクエストされたロールが見つかりませんでした。

429

TOO_MANY_REQUESTS

リクエストが制限されています。

500

INTERNAL_SERVER_ERROR

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

503

SERVICE_UNAVAILABLE

サーバーが一時的に使用できません。

ロールを取得する

指定したロールの詳細を取得するには、GET /v1/roles/{roleId}を呼び出します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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

リクエストのパスパラメーター

フィールド 説明 必須

roleId

ロールID。"amzn1.alexa.role.did.{id}"というAmazon Common Identifier(ACI)形式で表します。ロールをユーザーに割り当てるときは、このIDを使用します。

文字列

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

{
   "roleId": "amzn1.alexa.role.did.example",
   "roleName": "Admin",
   "unitId": "amzn1.alexa.unit.did.example",
   "targetEntityId": "example-target-entity-id"
}

応答本文のパラメーター

フィールド 説明

roleId

ロールID。

文字列

roleName

ロール名。

文字列

unitId

このロールが定義されているユニットのユニットID。

文字列

targetEntityId

このロールが定義されているターゲットエンティティのID。

文字列

エラー応答

{
    "description": string
}

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

フィールド 説明

description

エラーの説明。例:"HTTP/1.1 401 The request has a missing or an invalid access token."

文字列

HTTP応答コード

ステータスコード 名前 説明

201

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

操作を実行する権限がユーザーにありません。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

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

503

Service Unavailable

サーバーが一時的に使用できません。

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

指定したユニットまたはターゲットエンティティにおける、指定したプリンシパルに対するロールの割り当てリストを取得するには、GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}を呼び出します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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 {LWA Token}

リクエストのパスパラメーター

フィールド 説明 必須

roleId

ロールID。"amzn1.alexa.role.did.{id}"というAmazon Common Identifier(ACI)形式で表します。

文字列

リクエストのクエリパラメーター

フィールド 説明 必須

principalId

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

文字列

unitId

ユニットID。"amzn1.alexa.unit.did.{id}"というAmazon Common Identifier(ACI)形式で表します。

文字列

targetEntityId

ターゲットエンティティのID。

文字列

nextToken

結果の次のページを取得するためのトークン。

文字列

maxResults

表示する結果の最大数。値は1~10の間で指定します。デフォルト値は10です。

整数

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

{
  "results" : [
    {
      "roleId" : "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
      "principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
    }
  ],
    "paginationContext": {
      "nextToken": null
  }
}

応答本文のパラメーター

フィールド 説明

results

結果(ロールの割り当て)のリスト。

リスト

results[i].roleId

ロールID。

文字列

results[i].principalId

プリンシパルID。

文字列

paginationContext

ページ分割情報を含むオブジェクト。これがある場合、応答に含まれている結果は不完全です。ない場合は、すべての結果が既に返されています。詳細については、クエリ結果のページ分割を処理するを参照してください。

オブジェクト

paginationContext.nextToken

次回のリクエストで、結果の次のページを取得するための継続トークン(nextTokenクエリパラメーター)として使用できるトークン。

文字列

エラー応答

{
    "description": string
}

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

フィールド 説明

description

エラーの説明。例:"HTTP/1.1 401 The request has a missing or an invalid access token."

文字列

HTTP応答コード

ステータスコード 名前 説明

200

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

操作を実行する権限がユーザーにありません。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

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

503

Service Unavailable

サーバーが一時的に使用できません。

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

指定したロールに対するプリンシパルの割り当てリストを取得するには、GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken}を呼び出します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

リクエストのパスパラメーター

フィールド 説明 必須

roleId

ロールID。"amzn1.alexa.role.did.{id}"というAmazon Common Identifier(ACI)形式で表します。

文字列

リクエストのクエリパラメーター

フィールド 説明 必須

nextToken

結果の次のページを取得するためのトークン。

文字列

maxResults

表示する結果の最大数。値は1~10の間で指定します。デフォルト値は10です。

整数

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

{
   "results": [
      {
         "roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
         "principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
      }
   ],
   "paginationContext": {
      "nextToken": null
   }
}

応答本文のパラメーター

フィールド 説明

results

結果(ロールの割り当て)のリスト。

リスト

results[i].roleId

ロールID。

文字列

results[i].principalId

プリンシパルID。

文字列

paginationContext

ページ分割情報を含むオブジェクト。これがある場合、応答に含まれている結果は不完全です。ない場合は、すべての結果が既に返されています。詳細については、クエリ結果のページ分割を処理するを参照してください。

オブジェクト

paginationContext.nextToken

次回のリクエストで、結果の次のページを取得するための継続トークン(nextTokenクエリパラメーター)として使用できるトークン。

文字列

エラー応答

{
    "description": string
}

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

フィールド 説明

description

エラーの説明。例:"HTTP/1.1 401 The request has a missing or an invalid access token."

文字列

HTTP応答コード

ステータスコード 名前 説明

200

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

操作を実行する権限がユーザーにありません。

404

Not found

リクエストされたロールが見つかりませんでした。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

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

503

Service Unavailable

サーバーが一時的に使用できません。

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

指定したプリンシパルからロールを取り消すには、DELETE /v1/roles/{roleId}/assignmentsを呼び出します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

DELETE /v1/roles/{roleId}/assignments HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

リクエストと応答の例

DELETE /v1/roles/amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ/assignments?principalId=amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2Ax&propagate=false

204 No Content

リクエスト本文

なし。

リクエストのパスパラメーター

フィールド 説明 必須

roleId

取り消すロールのロールID。

文字列

リクエストのクエリパラメーター

フィールド 説明 必須

principalId

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

文字列

propagate

伝播を有効にするかどうかを示すクエリパラメーターフラグ。伝播を有効にすると、ユニット階層全体からロールが取り消されます。ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。

ブール値

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文

なし。

エラー応答

{
    "description": string
}

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

フィールド 説明

description

エラーの説明。例:"HTTP/1.1 401 The request has a missing or an invalid access token."

文字列

HTTP応答コード

ステータスコード 名前 説明

202

Accepted

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

204

No content

プリンシパルからロールが取り消されました。この応答コードは、取り消しリクエストで伝播フラグが設定されなかった場合にのみ発生します。

400

Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。たとえば、次のような理由が考えられます。
  • 別のユニットから伝播されたロールの割り当てを取り消そうとしました。
  • propagateフラグを指定せずに、伝播されたロールの割り当てを取り消そうとしました(または、その逆を行おうとしました)。

401

Unauthorized

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

403

Forbidden

操作を実行する権限がユーザーにありません。

404

Not found

リクエストされたロールが見つかりませんでした。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

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

503

Service Unavailable

サーバーが一時的に使用できません。

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

指定した複数のプリンシパルからロールを取り消すには、POST /v1/roles/{roleId}/assignments/batchRevokeを呼び出します。プリンシパルの指定に必要なユーザーIDを取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。

リクエストの受け付けが完了したら、この操作は同期の検証を実行し、202(Accepted)の応答を返します。その後、ロールに対する各プリンシパルの割り当てがバックグラウンドで非同期的に取り消されます。

入力が無効な場合は、バッチ操作全体が失敗します。つまり、リクエスト項目はすべて処理されるか、まったく処理されないかのどちらかになります。

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

Healthcare Hospitality Senior Living Core

米国

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

米国、カナダ

米国

リクエストの形式

POST /v1/roles/{roleId}/assignments/batchRevoke
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

リクエスト本文の例

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

リクエストのパスパラメーター

フィールド 説明 必須

roleId

割り当てを取り消すロールのID。"amzn1.alexa.role.did.{id}"というAmazon Common Identifier(ACI)形式で表します。

文字列

リクエスト本文のパラメーター

フィールド 説明 必須

items

ロールの割り当てリクエストオブジェクトの配列。バッチリクエストで処理できるリクエスト項目の最大数は50です。

配列

items[*].itemId

リクエスト項目の一意のID。

整数

items[*].principalId

ロールの割り当て先となるプリンシパルのユーザーID。

文字列

items[*].propagate

伝播を有効にするかどうかを示すフラグ。伝播を有効にすると、ユニット階層全体にロールが割り当てられます。ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。このフラグの値は、指定したroleIdprincipalIdのロール割り当てに関連付けられているフラグの値と一致する必要があります。一致しない場合は、エラーが発生します。
デフォルト値はfalseです。

ブール値

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文

正常に完了した場合、応答の本文はありません。

エラー応答本文の例

{
  "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)."
    }
  ]
}

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

フィールド 説明

errors

エラーの説明を含むオブジェクトの配列。考えられるエラーコードの一覧については、HTTP応答コードを参照してください。

配列

errors[*].itemId

リクエスト項目の一意のID。

整数

errors[*].status

エラーのステータス。例: 400

文字列

errors[*].errorCode

エラーコード。例: INVALID_PRINCIPAL_ID

文字列

errors[*].errorDescription

エラーの説明。例: Invalid principalId specified.

文字列

HTTP応答コード

ステータスコード 名前 説明

202

ACCEPTED

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

400

INVALID_PRINCIPAL_ID

principalIdが無効です。

400

PROPAGATED_FROM_ANOTHER_ROLE

伝播されたロールの割り当てを取り消そうとしました。伝播のソースでpropagateフラグをtrueに設定して取り消しを再開してください。

400

PRINCIPAL_IS_PROPAGATED

プリンシパルでロールの取り消しがサポートされていません。現在のロールの割り当ては、伝播チェーンのソースです。propagateフラグにtrueの値を設定して渡す必要があります。

400

PRINCIPAL_IS_NOT_PROPAGATED

プリンシパルでロールの取り消しがサポートされていません。現在のロールの割り当ては、伝播されていない割り当てです。propagateフラグを渡さないようにするか、propagateフラグをfalseに設定してください。

400

DUPLICATE_REQUEST_ITEM_FOUND

リクエストに重複したリクエスト項目が含まれています。

400

BAD_REQUEST

リクエストの形式が正しくないか、必須パラメーターが不足しています。

400

INVALID_ROLE_ID

roleIdが無効です。

400

REQUEST_LIMIT_EXCEEDED

リクエストのロール割り当てのプリンシパル数が、1回のリクエストあたりの上限を超えています。

401

UNAUTHORIZED

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

403

FORBIDDEN

操作を実行する権限がユーザーにありません。

404

ROLE_NOT_FOUND

リクエストされたロールが見つかりませんでした。

429

TOO_MANY_REQUESTS

リクエストが制限されています。

500

INTERNAL_SERVER_ERROR

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

503

SERVICE_UNAVAILABLE

サーバーが一時的に使用できません。


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

最終更新日: 2023 年 11 月 30 日