ロール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}
を呼び出します。
この操作は以下の国で使用できます。
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トークン}
リクエスト本文
ありません。
リクエストのクエリパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ユニットIDです。形式は |
文字列 |
|
|
ターゲットエンティティのIDです。 |
文字列 |
|
|
クライアントが特定のロールの詳細のみを必要としている場合に、ロール名を指定してフィルタリングできます。 |
文字列 |
✕ |
|
前回のロールリストの取得に対する応答で、応答オブジェクトに返された継続トークンです。 |
文字列 |
✕ |
|
表示する結果の最大数です。値は1~10の間で指定します。デフォルト値は10です。 |
整数 |
✕ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意の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または空になります。フィールド | 説明 | 型 |
---|---|---|
|
ロールIDです。 |
文字列 |
|
ロール名です。 |
文字列 |
|
ユニットのIDです。 |
文字列 |
|
ターゲットエンティティのIDです。 |
文字列 |
|
次回のリクエストで、結果の次のページを取得するための継続トークン( |
文字列 |
エラー応答
{
"description": string
}
エラー応答のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
エラーの説明です。たとえば、"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
}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
割り当てるロールのIDです。 |
文字列 |
◯ |
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ロールの割り当て先となるプリンシパルのユーザーIDです。 |
文字列 |
◯ |
|
伝播を有効にするかどうかを示すフラグです。伝播を有効にすると、ユニット階層全体にロールが割り当てられます。ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。 |
ブール値 |
✕ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文
ありません。
エラー応答
{
"description": string
}
エラー応答のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
エラーの説明です。たとえば、"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トークン}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ロールIDです。 |
文字列 |
◯ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文の例
{
"roleId": "amzn1.alexa.role.did.example",
"roleName": "Admin",
"unitId": "amzn1.alexa.unit.did.example",
"targetEntityId": "example-target-entity-id"
}
応答本文のパラメーター
unitId
フィールドとtargetEntityId
フィールドの両方に同じ値が含まれます。ターゲットエンティティベースのロールでは、応答にtargetEntityId
フィールドが含まれ、unitId
フィールドはnullまたは空になります。フィールド | 説明 | 型 |
---|---|---|
|
ロールIDです。 |
文字列 |
|
ロール名です。 |
文字列 |
|
このロールが定義されているユニットのユニットIDです。 |
文字列 |
|
このロールが定義されているターゲットエンティティのIDです。 |
文字列 |
エラー応答
{
"description": string
}
エラー応答のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
エラーの説明です。たとえば、"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トークン}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ロールIDです。 |
文字列 |
◯ |
リクエストのクエリパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
プリンシパルIDです。形式は |
文字列 |
◯ |
|
ユニットIDです。 |
文字列 |
◯ |
|
ターゲットエンティティのIDです。 |
文字列 |
◯ |
|
結果の次のページを取得するためのトークンです。 |
文字列 |
✕ |
|
表示する結果の最大数です。値は1~10の間で指定します。デフォルトは10です。 |
整数 |
✕ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文の例
{
"results" : [
{
"roleId" : "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
}
],
"paginationContext": {
"nextToken": null
}
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
結果(ロールの割り当て)のリストです。 |
リスト |
|
ロールIDです。 |
文字列 |
|
プリンシパルIDです。 |
文字列 |
|
ページ分割情報を含むオブジェクトです。これが存在する場合、応答に含まれている結果は完全ではありません。存在しない場合、すべての結果が既に返されています。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
オブジェクト |
|
次回のリクエストで、結果の次のページを取得するための継続トークン( |
文字列 |
エラー応答
{
"description": string
}
エラー応答のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
エラーの説明です。たとえば、"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トークン}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ロールIDです。 |
文字列 |
◯ |
リクエストのクエリパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
結果の次のページを取得するためのトークンです。 |
文字列 |
✕ |
|
表示する結果の最大数です。値は1~10の間で指定します。デフォルトは10です。 |
整数 |
✕ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文の例
{
"results": [
{
"roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
}
],
"paginationContext": {
"nextToken": null
}
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
結果(ロールの割り当て)のリストです。 |
リスト |
|
ロールIDです。 |
文字列 |
|
プリンシパルIDです。 |
文字列 |
|
ページ分割情報を含むオブジェクトです。これが存在する場合、応答に含まれている結果は完全ではありません。存在しない場合、すべての結果が既に返されています。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
オブジェクト |
|
次回のリクエストで、結果の次のページを取得するための継続トークン( |
文字列 |
エラー応答
{
"description": string
}
エラー応答のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
エラーの説明です。たとえば、"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
リクエスト本文
ありません。
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
取り消すロールのロールIDです。 |
文字列 |
◯ |
リクエストのクエリパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ロールを取り消すプリンシパルのプリンシパルIDです。 |
文字列 |
◯ |
|
伝播を有効にするかどうかを示すクエリパラメーターフラグです。伝播を有効にすると、ユニット階層全体からロールが取り消されます。ロールを伝播できるのは、AmazonビジネスアカウントのプリンシパルIDのみです。 |
ブール値 |
✕ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文
ありません。
エラー応答
{
"description": string
}
エラー応答のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
エラーの説明です。たとえば、"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 |
サーバーが一時的に使用できません。 |
最終更新日: 2023 年 03 月 16 日