役割エンドポイント

最終更新日： 2025年4月4日

トピック：
{"id":"adf04a6a-050f-44bc-a52c-db79ccb22ebf"},{"id":"c132d929-fa62-4271-803e-b823be07b914"}

作成対象：

{"id":"ff6a42d2-313e-452e-93a6-792e4fad9ff8"}

NOTE

ユーザートークンが渡される場合、トークンのユーザーは、リクエストされた組織の「組織管理者」役割を持っている必要があります。

役割は、管理者、スペシャリストまたはエンドユーザーが組織内のリソースに対して持つアクセス権を定義します。役割ベースのアクセス制御環境では、ユーザーアクセスプロビジョニングは、共通の責任とニーズによってグループ化されます。役割には特定の権限セットがあり、必要な表示または書き込みアクセスの範囲に応じて、組織のメンバーを 1 つ以上の役割に割り当てることができます。

属性ベースのアクセス制御APIの/roles エンドポイントを使用すると、組織内の役割をプログラムで管理できます。

はじめに

このガイドで使用するAPI エンドポイントは、属性ベースのアクセス制御APIの一部です。先に進む前に、はじめる前にを参照し、関連ドキュメントへのリンク、このドキュメントのサンプル API 呼び出しを読み取るためのガイドおよび任意の Experience Platform API を正常に呼び出すために必要なヘッダーに関する重要な情報を確認してください。

役割のリストの取得 list

組織に属する既存のすべての役割を一覧表示するには、/roles エンドポイントにGET リクエストを実行します。

API 形式

GET /roles/

リクエスト

次のリクエストは、組織に属する役割のリストを取得します。

curl -X GET \
  https://platform.adobe.io/data/foundation/access-control/administration/roles \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

応答

応答が成功すると、各役割タイプ、権限セット、件名の属性に関する情報を含む、組織内の役割のリストが返されます。

{
  "roles": [
    {
      "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "name": "Administrator Role",
      "description": "Role for administrator type of responsibilities and access",
      "roleType": "user-defined",
      "permissionSets": [
        "manage-datasets",
        "manage-schemas"
      ],
      "sandboxes": [
        "prod"
      ],
      "subjectAttributes": {
        "labels": [
          "core/S1"
        ]
      },
      "createdBy": "{CREATED_BY}",
      "createdAt": 1648153201825,
      "modifiedBy": "{MODIFIED_BY}",
      "modifiedAt": 1648153201825,
      "etag": null
    }
  ],
  "_page": {
    "limit": 1,
    "count": 1
  },
  "_links": {
    "next": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "templated": true
    },
    "page": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "templated": true
    },
    "subjects": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "templated": true
    }
  }
}

プロパティ

説明

id

役割に対応するID。このIDは自動生成されます。

name

役割の名前。

description

description プロパティは、役割に関する追加情報を提供します。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

permissionSets

権限セットは、管理者が役割に適用できる権限のグループを表します。管理者は、個々の権限を割り当てる代わりに、役割に権限セットを割り当てることができます。これにより、権限のグループを含む事前定義済みの役割からカスタムの役割を作成できます。

sandboxes

このプロパティは、特定の役割にプロビジョニングされた組織内のサンドボックスを表示します。

subjectAttributes

件名と、アクセス権のあるExperience Platform リソースとの相関関係を示す属性。

subjectAttributes.labels

クエリされた役割に適用されたデータ使用ラベルを表示します。

役割の検索 lookup

リクエストパスに対応するroleIdを含むGET リクエストを作成することで、個々の役割を検索できます。

API 形式

GET /roles/{ROLE_ID}

パラメーター

説明

{ROLE_ID}

検索する役割のID。

リクエスト

次のリクエストは、{ROLE_ID}の情報を取得します。

curl -X GET \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

応答

応答が成功すると、役割タイプ、権限セット、件名の属性に関する情報など、クエリされた役割IDの詳細が返されます。

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator Role",
  "description": "Role for administrator type of responsibilities and access",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}

プロパティ

説明

id

役割に対応するID。このIDは自動生成されます。

name

役割の名前。

description

description プロパティは、役割に関する追加情報を提供します。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

permissionSets

sandboxes

このプロパティは、特定の役割にプロビジョニングされた組織内のサンドボックスを表示します。

subjectAttributes

件名と、アクセス権のあるExperience Platform リソースとの相関関係を示す属性。

subjectAttributes.labels

クエリされた役割に適用されたデータ使用ラベルを表示します。

役割IDで被写体を検索

また、{ROLE_ID}を指定しながら/roles エンドポイントにGET リクエストを行うことで、オブジェクトを取得することもできます。

API 形式

GET /roles/{ROLE_ID}/subjects

パラメーター

説明

{ROLE_ID}

検索する被写体に関連付けられている役割のID。

リクエスト

次のリクエストは、3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809に関連付けられているオブジェクトを取得します。

curl -X GET \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809/subjects \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

応答

応答が成功すると、対応する件名IDと件名タイプを含む、クエリされた役割IDに関連付けられた件名が返されます。

{
  "items": [
      {
          "roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
          "subjectType": "user",
          "subjectId": "03Z07HFQCCUF3TUHAX274206@AdobeID"
      },
      {
          "roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
          "subjectType": "user",
          "subjectId": "PIRJ7WE5T3QT9Z4TCLVH86DE@AdobeID"
      },
      {
          "roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
          "subjectType": "user",
          "subjectId": "WHPWE00MC26SHZ7AKBFG403D@AdobeID"
      },
  ]
  "_page": {
    "limit": 0,
    "count": 0
  },
  "_links": {
      "self": {
          "href": "/roles/{ROLE_ID}/subjects",
          "templated": false,
          "type": null,
          "method": null
      },
      "page": {
          "href": "/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}",
          "templated": true,
          "type": null,
          "method": null
      }
  }
}

プロパティ

説明

roleId

クエリされた件名に関連付けられた役割ID。

subjectType

クエリされた件名の種類。

subjectId

クエリされた件名に対応するID。

役割の作成 create

新しい役割を作成するには、役割の名前、説明、役割タイプの値を指定しながら、/roles エンドポイントにPOST リクエストを行います。

API 形式

POST /roles/

リクエスト

curl -X POST \
  https://platform.adobe.io/data/foundation/access-control/administration/roles \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -d'{
    "name": "Administrator Role",
    "description": "Role for administrator type of responsibilities and access",
    "roleType": "user-defined"
  }'

プロパティ

説明

name

役割の名前。役割の名前がわかりやすいものであることを確認します。これを使用して、役割に関する情報を検索できます。

description

（オプション）役割に関する詳細情報を提供するために含めることができる記述的な値。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

応答

応答が成功すると、新しく作成した役割と、対応する役割ID、役割タイプ、権限セット、件名の属性に関する情報が返されます。

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator Role",
  "description": "Role for administrator type of responsibilities and access",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}

プロパティ

説明

id

役割に対応するID。このIDは自動生成されます。

name

役割の名前。

description

description プロパティは、役割に関する追加情報を提供します。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

permissionSets

sandboxes

このプロパティは、特定の役割にプロビジョニングされた組織内のサンドボックスを表示します。

subjectAttributes

件名と、アクセス権のあるExperience Platform リソースとの相関関係を示す属性。

subjectAttributes.labels

クエリされた役割に適用されたデータ使用ラベルを表示します。

役割の更新 patch

ロールのプロパティを更新するには、/roles エンドポイントに対してPATCH リクエストを行い、対応するロール IDと適用する操作の値を指定します。

API 形式

PATCH /roles/{ROLE_ID}

パラメーター

説明

{ROLE_ID}

更新する役割のID。

リクエスト

curl -X PATCH \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/{ROLE_ID} \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -d'{
    "operations": [
      {
        "op": "add",
        "path": "/description",
        "value": "Role with permission sets for admin type of access"
      }
    ]
  }'

運用

説明

op

役割の更新に必要なアクションを定義するために使用される操作呼び出し。操作には、add、replace、remove があります。

path

更新するパラメーターのパス。

value

パラメーターの更新に使用する新しい値。

応答

応答が成功すると、更新した役割が返されます。これには、更新するように選択したプロパティの新しい値が含まれます。

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator Role",
  "description": "Role with permission sets for admin type of access",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}

プロパティ

説明

id

役割に対応するID。このIDは自動生成されます。

name

役割の名前。

description

description プロパティは、役割に関する追加情報を提供します。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

permissionSets

sandboxes

このプロパティは、特定の役割にプロビジョニングされた組織内のサンドボックスを表示します。

subjectAttributes

件名と、アクセス権のあるExperience Platform リソースとの相関関係を示す属性。

subjectAttributes.labels

クエリされた役割に適用されたデータ使用ラベルを表示します。

役割IDによる役割の更新 put

役割を更新するには、/roles エンドポイントにPUT リクエストを行い、更新する役割に対応する役割IDを指定します。

API 形式

PUT /roles/{ROLE_ID}

リクエスト

次のリクエストは、役割ID 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809の名前、説明、および役割タイプを更新します。

curl -X PUT \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -d'{
    "name": "Administrator role for ACME",
    "description": "New administrator role for ACME",
    "roleType": "user-defined"
  }'

パラメーター

説明

name

役割の更新された名前。

description

役割の更新された説明。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

応答

応答が成功すると、名前、説明、役割タイプの新しい値を含む、更新された役割が返されます。

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator role for ACME",
  "description": "New administrator role for ACME",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}

プロパティ

説明

id

役割に対応するID。このIDは自動生成されます。

name

役割の名前。

description

description プロパティは、役割に関する追加情報を提供します。

roleType

役割の指定されたタイプ。役割の種類に使用できる値はuser-definedとsystem-definedです。

permissionSets

sandboxes

このプロパティは、特定の役割にプロビジョニングされた組織内のサンドボックスを表示します。

subjectAttributes

件名と、アクセス権のあるExperience Platform リソースとの相関関係を示す属性。

subjectAttributes.labels

クエリされた役割に適用されたデータ使用ラベルを表示します。

役割IDで件名を更新

ロールに関連付けられているサブジェクトを更新するには、更新するサブジェクトのロール IDを指定しながら、/roles エンドポイントに対してPATCH リクエストを行います。

API 形式

PATCH /roles/{ROLE_ID}/subjects

パラメーター

説明

{ROLE_ID}

更新するサブジェクトに関連付けられている役割のID。

リクエスト

次のリクエストは、{ROLE_ID}に関連付けられているオブジェクトを更新します。

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/access-control/administration/roles/<ROLE_ID>/subjects' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "op": "add",
        "path": "/user",
        "value": "{USER ID}"
    }
]'

運用

説明

op

役割の更新に必要なアクションを定義するために使用される操作呼び出し。操作には、add、replace、remove があります。

path

更新するパラメーターのパス。

value

パラメーターの更新に使用する新しい値。

応答

応答が成功すると、件名の新しい値を含む、更新された役割が返されます。

{
  "subjects": [
    [
      {
        "subjectId": "03Z07HFQCCUF3TUHAX274206@AdobeID",
        "subjectType": "user"
      }
    ]
  ],
  "_page": {
    "limit": 1,
    "count": 1
  },
  "_links": {
    "self": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects",
      "templated": true
    },
    "page": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}",
      "templated": true
    }
  }
}

役割の削除 delete

ロールを削除するには、削除するロールのIDを指定しながら、/roles エンドポイントに対してDELETE リクエストを行います。

API 形式

DELETE /roles/{ROLE_ID}

パラメーター

説明

{ROLE_ID}

削除する役割のID。

リクエスト

次のリクエストは、{ROLE_ID}のIDを持つ役割を削除します。

curl -X DELETE \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/{ROLE_ID} \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

応答

正常な応答の場合は、空白の本文とともに HTTP ステータス 204 （コンテンツなし）が返されます。

削除を確認するには、役割に対してルックアップ（GET）リクエストを試みます。役割が管理から削除されたため、HTTP ステータス 404 （見つかりません）が表示されます。

API資格情報の追加 apicredential

API資格情報を追加するには、PATCH リクエストを/roles エンドポイントに対して行い、サブジェクトのロール IDを指定します。

API 形式

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/access-control/administration/roles/<ROLE_ID>/subjects' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "op": "add",
        "path": "/api-integration",
        "value": "{TECHNICAL ACCOUNT ID}"
    }
]'

運用

説明

op

役割の更新に必要なアクションを定義するために使用される操作呼び出し。操作には、add、replace、remove があります。

path

追加するパラメーターのパス。

value

パラメーターを追加する値。

応答

正常な応答の場合は、空白の本文とともに HTTP ステータス 204 （コンテンツなし）が返されます。

recommendation-more-help

experience-platform-help-access-control