ロールAPI

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

ロールAPI

注：このAPIは、登録済みのAlexa Smart Properties in Hospitalityパートナーのみ使用できます。Alexa Smart Properties for Hospitality 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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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}"`です。	文字列	`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を取得する方法の詳細については、ユーザープロファイル情報を取得するを参照してください。

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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値は、リクエストの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	サーバーが一時的に使用できません。

ロールを取得する

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

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

Healthcare	Hospitality	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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値は、リクエストの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	Residential	Senior Living	Core
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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値は、リクエストの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.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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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値は、リクエストの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.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
米国	米国、英国、フランス、カナダ、イタリア、ドイツ	米国、カナダ	米国、英国、フランス、カナダ、イタリア、ドイツ	米国

リクエストの形式

注：リクエストヘッダーでは、組織が所在する地域に応じて、Hostをapi.amazonalexa.comまたはapi.eu.amazonalexa.comのどちらかに設定してください。

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値は、リクエストの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	サーバーが一時的に使用できません。

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

フィードバックを送信

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