ロールAPI

Note: Sign in to the developer console to build or publish your skill.

ロールAPI

注：このAPIは、登録済みのAlexa Smart Propertiesパートナーのみが使用できます。Alexa Smart Properties APIで開発を始めるを参照してください。

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

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

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
ロールのリストを取得する	`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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン、日本	米国

リクエストの形式

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

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}"`形式で指定します。	文字列	`unitId`か`targetEntityId`のどちらかを指定する必要があります。
`targetEntityId`	ターゲットエンティティのID。	文字列	`unitId`か`targetEntityId`のどちらかを指定する必要があります。
`roleName`	クライアントが特定のロールの詳細のみを必要としている場合に、ロール名を指定してフィルタリングできます。	文字列	✕
`nextToken`	前回のロールリストの取得に対する応答で、応答オブジェクトに返された継続トークン。	文字列	✕
`maxResults`	表示する結果の最大数。値は1～10の間で指定します。デフォルト値は10です。	整数	✕

応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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

応答本文のパラメーター

注：ユニットベースのロールでは、応答のunitIdフィールドとtargetEntityIdフィールドの両方に同じ値が含まれます。ターゲットエンティティベースのロールでは、応答にtargetEntityIdフィールドが含まれ、unitIdフィールドは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を取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。

ロールを一時的に割り当てるには、リクエスト本文にexpiresAtプロパティを設定します。

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

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,
   "expiresAt": "2021-11-02T12:51:00.000Z"
}

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

フィールド	説明	型	必須
`roleId`	割り当てるロールのID。`"amzn1.alexa.role.did.{id}"`というAmazon Common Identifier（ACI）形式で表します。	文字列	◯

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

フィールド説明型必須

フィールド	説明	型	必須
`principalId`	ロールの割り当て先となるプリンシパルのユーザーID。	文字列	◯
`propagate`	伝播を有効にするかどうかを示すフラグ。伝播を有効にすると、ユニット階層全体にロールが割り当てられます。ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。	ブール値	✕
`expiresAt`	指定された日時まで、指定されたプリンシパルにロールを割り当てます。日時は、ISO-8601形式のUTCタイムスタンプ（`yyyy-MM-ddTHH:mm:ss[.mmm]Z`）として指定します。有効期限は、現在の時刻から30分後～30日後の間で指定する必要があります。設定しない場合、ロールの割り当ての有効期限が切れることはありません。 `expiresAt`に値が設定されている場合、`propagate`が`true`であれば、ユニット階層内のすべての割り当てで有効期限が継承されます。	文字列	✕

principalId

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

文字列

◯

propagate

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

ブール値

expiresAt

指定された日時まで、指定されたプリンシパルにロールを割り当てます。日時は、ISO-8601形式のUTCタイムスタンプ（yyyy-MM-ddTHH:mm:ss[.mmm]Z）として指定します。有効期限は、現在の時刻から30分後～30日後の間で指定する必要があります。設定しない場合、ロールの割り当ての有効期限が切れることはありません。

expiresAtに値が設定されている場合、propagateがtrueであれば、ユニット階層内のすべての割り当てで有効期限が継承されます。

文字列

応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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）の応答を返します。その後、各プリンシパルがバックグラウンドで非同期的にロールに割り当てられます。

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

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

注：この操作では、伝播されたロールの割り当てをダウングレードすることはできません。特定のroleIdとprincipalIdに対してpropagateがtrueに設定された既存のロール割り当てがある場合、同じroleIdとprincipalIdに対してpropagateの値をfalseに設定してロールの割り当てリクエストを実行しようとすると、エラーが発生します。伝播されたロールの割り当てをダウングレードするには、まずロールの割り当てを取り消すまたはロールの割り当てを一括で取り消すの操作を行って、ロールの割り当てを取り消してから、再度割り当てる必要があります。

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

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,
        "expiresAt": "2021-11-02T12:51:00.000Z"
     },
     {
        "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です。	ブール値	✕
`items[*].expiresAt`	指定された日時まで、指定されたプリンシパルにロールを割り当てます。日時は、ISO-8601形式のUTCタイムスタンプ（`yyyy-MM-ddTHH:mm:ss[.mmm]Z`）として指定します。有効期限は、現在の時刻から30分後～30日後の間で指定する必要があります。設定しない場合、ロールの割り当ての有効期限が切れることはありません。 `expiresAt`に値が設定されている場合、`propagate`が`true`であれば、ユニット階層内のすべての割り当てで有効期限が継承されます。	文字列	✕

応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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値は、リクエストのHost値と同じになります。

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}

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

フィールド	説明	型	必須
`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値は、リクエストのHost値と同じになります。

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

応答本文の例

{
  "results" : [
    {
      "roleId" : "amzn1.alexa.role.did.1",
      "principalId" : "amzn1.account.1",
      "expiresAt": "1715786400000",
      "propagatedRoleId": "amzn1.alexa.role.a4h.originRoleId"
    }
  ],
    "paginationContext": {
      "nextToken": null
  }
}

応答本文のパラメーター

フィールド	説明	型
`results`	結果（ロールの割り当て）のリスト。	リスト
`results[i].roleId`	ロールID。	文字列
`results[i].principalId`	プリンシパルID。	文字列
`results[i].expiresAt`	プリンシパルに割り当てられたロールの有効期限を示すエポックタイム形式のタイムスタンプ（`1715786400000`）。ロールの割り当て時に`expiresAt`が設定された場合に含まれます。	文字列
`results[i].propagatedRoleId`	このロール割り当ての伝播元となる元のロールの`roleId`。	文字列
`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値は、リクエストのHost値と同じになります。

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

フィールド	説明	型
`X-Amzn-RequestId`	リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。	文字列

応答本文の例

{
  "results": [
    {
      "roleId": "amzn1.alexa.role.did.1",
      "principalId": "amzn1.account.1",
      "expiresAt": "1715786400000",
      "propagatedRoleId": "amzn1.alexa.role.a4h.originRoleId"
    }
  ],
  "paginationContext": {
    "nextToken": null
  }
}

応答本文のパラメーター

フィールド	説明	型
`results`	結果（ロールの割り当て）のリスト。	リスト
`results[i].roleId`	ロールID。	文字列
`results[i].principalId`	プリンシパルID。	文字列
`results[i].expiresAt`	プリンシパルに割り当てられたロールの有効期限を示すエポックタイム形式のタイムスタンプ（`1715786400000`）。ロールの割り当て時に`expiresAt`が設定された場合に含まれます。	文字列
`results[i].propagatedRoleId`	このロール割り当ての伝播元となる元のロールの`roleId`。	文字列
`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値は、リクエストのHost値と同じになります。

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）の応答を返します。その後、ロールに対する各プリンシパルの割り当てがバックグラウンドで非同期的に取り消されます。

注：この操作では、propagateフラグを指定せずに伝播されたロールの割り当てを取り消すことはできません。また、伝播されていないロールの割り当てをpropagateフラグを指定して取り消すこともできません。つまり、特定のroleIdとprincipalIdに既存のロール割り当てがある場合、同じroleIdとprincipalIdに対して逆のpropagate値を設定してロールの割り当てリクエストを実行しようとすると、エラーが発生します。

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

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のみです。このフラグの値は、指定した`roleId`と`principalId`のロール割り当てに関連付けられているフラグの値と一致する必要があります。一致しない場合は、エラーが発生します。デフォルト値はfalseです。	ブール値	✕

応答ヘッダー

注：応答ヘッダーで返されるHost値は、リクエストのHost値と同じになります。

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	サーバーが一時的に使用できません。

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

フィードバックを送信

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