ロールAPI


ロールAPI

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

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

APIエンドポイント

ロールAPIのエンドポイントは、https://api.amazonalexa.comです。

認証

すべてのAPIリクエストには認可ヘッダーが必要であり、その値には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

ロールを取得する

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

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

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

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

Healthcare Hospitality Residential 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トークン}

リクエスト本文

ありません。

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

フィールド 説明 必須

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 Residential Senior Living Core

米国

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

米国、カナダ

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

米国

リクエストの形式

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

リクエスト本文の例

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

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

ロールを取得する

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

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国、カナダ

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

米国

リクエストの形式

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

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

フィールド 説明 必須

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 Residential 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トークン}

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

フィールド 説明 必須

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 Residential 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トークン}

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

フィールド 説明 必須

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 Residential Senior Living Core

米国

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

米国、カナダ

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

米国

リクエストの形式

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

リクエストと応答の例

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

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


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

最終更新日: 2023 年 03 月 16 日