角色端点

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：
访问控制

创建对象：

开发人员

NOTE

如果传递的是用户令牌，则该令牌的用户必须具有所请求组织的“组织管理员”角色。

角色定义了管理员、专家或最终用户对组织中资源的访问权限。在基于角色的访问控制环境中，用户访问设置是通过共同的责任和需求进行分组的。一个角色具有一组给定的权限，可将您组织的成员分配给一个或多个角色，具体取决于他们需要的查看或写入访问权限的范围。

基于属性的访问控制API中的/roles端点允许您以编程方式管理组织中的角色。

快速入门

本指南中使用的API端点属于基于属性的访问控制API。在继续之前，请查看快速入门指南，以获取相关文档的链接、阅读本文档中示例API调用的指南，以及有关成功调用任何Experience PlatformAPI所需的所需标头的重要信息。

检索角色列表 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

表示主体与其有权访问的平台资源之间的关联的属性。

subjectAttributes.labels

显示应用于查询角色的数据使用标签。

查找角色 lookup

您可以通过发出请求（请求路径中包含相应的roleId）来查找单个GET。

API格式

GET /roles/{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

表示主体与其有权访问的平台资源之间的关联的属性。

subjectAttributes.labels

显示应用于查询角色的数据使用标签。

按角色ID查找主题

您还可以在提供{ROLE_ID}的同时通过向/roles端点发出GET请求来检索主题。

API格式

GET /roles/{ROLE_ID}/subjects

参数

描述

与要查找的主题关联的角色的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

表示主体与其有权访问的平台资源之间的关联的属性。

subjectAttributes.labels

显示应用于查询角色的数据使用标签。

更新角色 patch

您可以通过对/roles端点发出PATCH请求来更新角色的属性，同时为要应用的操作提供相应的角色ID和值。

API格式

PATCH /roles/{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

表示主体与其有权访问的平台资源之间的关联的属性。

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

表示主体与其有权访问的平台资源之间的关联的属性。

subjectAttributes.labels

显示应用于查询角色的数据使用标签。

按角色ID更新主题

要更新与角色关联的主体，请在提供要更新的主体的角色ID的同时向/roles端点发出PATCH请求。

API格式

PATCH /roles/{ROLE_ID}/subjects

参数

描述

与要更新的主体关联的角色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

要删除角色，请在指定要删除的DELETE的ID时向/roles端点发出角色请求。

API格式

DELETE /roles/{ROLE_ID}

参数

描述

要删除的角色的ID。

请求

以下请求删除ID为{ROLE_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凭据，请在提供主体的PATCHID的同时向/roles端点发出角色请求。

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

631fcab2-5cb1-46ef-ba66-fe098ac723e0