ロールAPI


ロールAPI

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

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

APIエンドポイント

このAPIのエンドポイントは、https://api.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

ロールを取得する

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 class="non-printable-char non-printable-space"> /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 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 Residential 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

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

ロールを取得する

指定したロールの詳細を取得するには、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 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 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 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 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 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 Residential 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

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


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