角色端點

上次更新: 2024-01-30
  • 建立對象:
  • Developer
    User
    Admin
    Leader
注意

如果傳遞的是使用者權杖,則權杖的使用者必須具有請求組織的「組織管理員」角色。

角色定義管理員、專家或一般使用者對貴組織資源的存取權。 在基於角色的存取控制環境中,使用者存取布建是透過共同責任和需求進行分組。 一個角色具有一組給定的權限,您的組織成員可以指派到一個或多個角色,依據他們需要的視圖範圍或寫入權限而定。

/roles 以屬性為基礎的存取控制API中的端點可讓您以程式設計方式管理組織中的角色。

快速入門

本指南中使用的API端點屬於屬性型存取控制API的一部分。 在繼續之前,請檢閱 快速入門手冊 如需相關檔案的連結,請參閱本檔案範例API呼叫的指南,以及有關成功呼叫任何Experience PlatformAPI所需標題的重要資訊。

擷取角色清單

您可以透過向以下人員發出GET請求,列出屬於您組織的所有現有角色: /roles 端點。

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-definedsystem-defined.
permissionSets 許可權集代表管理員可套用至角色的一組許可權。 管理員可以將許可權集指派給角色,而不是指派個別許可權。 這可讓您從包含一組許可權的預定義角色建立自訂角色。
sandboxes 此屬性會顯示貴組織內為特定角色布建的沙箱。
subjectAttributes 指出主旨與其可存取之平台資源之間關聯的屬性。
subjectAttributes.labels 顯示套用至查詢角色的資料使用標籤。

查詢角色

您可以透過提出包含對應角色的GET請求來查詢個別角色 roleId 在請求路徑中。

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-definedsystem-defined.
permissionSets 許可權集代表管理員可套用至角色的一組許可權。 管理員可以將許可權集指派給角色,而不是指派個別許可權。 這可讓您從包含一組許可權的預定義角色建立自訂角色。
sandboxes 此屬性會顯示貴組織內為特定角色布建的沙箱。
subjectAttributes 指出主旨與其可存取之平台資源之間關聯的屬性。
subjectAttributes.labels 顯示套用至查詢角色的資料使用標籤。

依角色ID查詢主題

您也可以向以下網站發出GET要求來擷取主題: /roles 端點並提供 {ROLE_ID}.

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。

建立角色

POST若要建立新角色,請向 /roles 端點,同時提供角色名稱、說明和角色型別的值。

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-definedsystem-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-definedsystem-defined.
permissionSets 許可權集代表管理員可套用至角色的一組許可權。 管理員可以將許可權集指派給角色,而不是指派個別許可權。 這可讓您從包含一組許可權的預定義角色建立自訂角色。
sandboxes 此屬性會顯示貴組織內為特定角色布建的沙箱。
subjectAttributes 指出主旨與其可存取之平台資源之間關聯的屬性。
subjectAttributes.labels 顯示套用至查詢角色的資料使用標籤。

更新角色

您可以透過向以下專案發出PATCH請求來更新角色的屬性: /roles 端點,並為您要套用的作業提供對應的角色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 用於定義更新角色所需動作的操作呼叫。 操作包括: addreplace、和 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-definedsystem-defined.
permissionSets 許可權集代表管理員可套用至角色的一組許可權。 管理員可以將許可權集指派給角色,而不是指派個別許可權。 這可讓您從包含一組許可權的預定義角色建立自訂角色。
sandboxes 此屬性會顯示貴組織內為特定角色布建的沙箱。
subjectAttributes 指出主旨與其可存取之平台資源之間關聯的屬性。
subjectAttributes.labels 顯示套用至查詢角色的資料使用標籤。

依角色ID更新角色

您可以透過向以下專案發出PUT請求來更新角色: /roles 端點,並指定與您要更新的角色對應的角色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-definedsystem-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-definedsystem-defined.
permissionSets 許可權集代表管理員可套用至角色的一組許可權。 管理員可以將許可權集指派給角色,而不是指派個別許可權。 這可讓您從包含一組許可權的預定義角色建立自訂角色。
sandboxes 此屬性會顯示貴組織內為特定角色布建的沙箱。
subjectAttributes 指出主旨與其可存取之平台資源之間關聯的屬性。
subjectAttributes.labels 顯示套用至查詢角色的資料使用標籤。

依角色ID更新主旨

PATCH若要更新與角色相關聯的主體,請向 /roles 端點,同時提供您要更新之主體的角色ID。

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 用於定義更新角色所需動作的操作呼叫。 操作包括: addreplace、和 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若要刪除角色,請向 /roles 端點,並指定您要刪除的角色的ID。

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認證

若要新增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 用於定義更新角色所需動作的操作呼叫。 操作包括: addreplace、和 remove.
path 要新增的引數的路徑。
value 您想要用來新增引數的值。

回應

成功的回應會傳回HTTP狀態204 (無內容)和空白內文。

本頁內容