ロールAPI

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

ロールAPI

注：このAPIは、登録済みのAlexa Smart Properties in Senior Livingパートナーのみ使用できます。Alexa Smart Properties in Senior Living 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}"`形式で指定します。	文字列	`unitId`と`targetEntityId`のどちらかを指定する必要があります。
`targetEntityId`	ターゲットエンティティのIDです。	文字列	`unitId`と`targetEntityId`のどちらかを指定する必要があります。
`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
   }
}

応答本文のパラメーター

注：ユニットベースのロールでは、応答の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を取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。

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

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 日