教學課程：使用 REST API 管理 Microsoft Purview 集合上的角色型存取控制

發行項
08/23/2023

在 2021 年 8 月，Microsoft Purview 中的存取控制從 Azure Identity & Access Management (IAM) (控制平面移至資料平面) ) (Microsoft Purview 集合。這項變更可讓企業資料編者和系統管理員對其 Microsoft Purview 所掃描的資料來源進行更精確、更細微的存取控制。此變更也可讓組織稽核其資料的正確存取和正確使用。

本教學課程會引導您逐步使用 Microsoft Purview 中繼資料原則 API，以協助您將使用者、群組或服務主體新增至集合，以及管理或移除其在該集合中的角色。 REST API 是使用 Azure 入口網站或 Microsoft Purview 治理入口網站來達成相同細微角色型存取控制的替代方法。

如需 Microsoft Purview 中內建角色的詳細資訊，請參閱 Microsoft Purview 許可權指南。本指南會將角色對應至授與使用者的存取權限層級。

中繼資料原則 API 參考摘要

下表提供 Microsoft Purview 中繼資料原則 API 參考的概觀。

注意事項

在執行這些 API 之前，請以您的 Microsoft Purview 帳戶名稱取代 {pv-acc-name}。例如，如果您的 Microsoft Purview 帳戶名稱為 FabrikamPurviewAccount，您的 API 端點就會變成 FabrikamPurviewAccount.purview.azure.com。「api-version」參數可能會變更。如需最新的「api-version」和 API 簽章，請參閱 Microsoft Purview 中繼資料原則 REST API 檔。

API 函式	REST 方法	API 端點	描述
讀取所有中繼資料角色	GET	HTTPs://{pv-acc-name}.purview.azure.com /policystore/metadataroles？ &api-version=2021-07-01	從您的 Microsoft Purview 帳戶讀取所有中繼資料角色。
依集合名稱讀取中繼資料原則	GET	HTTPs://{pv-acc-name}.purview.azure.com /policystore/collections/{collectionName}/metadataPolicy？ &api-version=2021-07-01	使用指定的集合名稱讀取中繼資料原則， (Microsoft Purview 在建立原則) 時所產生的六個字元隨機名稱。
依 PolicyID 讀取中繼資料原則	GET	HTTPs://{pv-acc-name}.purview.azure.com /policystore/metadataPolicies/{policyId}？ &api-version=2021-07-01	使用指定的原則識別碼讀取中繼資料原則。原則識別碼是 GUID 格式。
讀取所有中繼資料原則	GET	HTTPs://{pv-acc-name}.purview.azure.com /policystore/metadataPolicies？ &api-version=2021-07-01	從您的 Microsoft Purview 帳戶讀取所有中繼資料原則。您可以從此 API 產生的 JSON 輸出清單中挑選要使用的特定原則。
更新/PUT 中繼資料原則	把	HTTPs://{pv-acc-name}.purview.azure.com /policystore/metadataPolicies/{policyId}？ &api-version=2021-07-01	使用指定的原則識別碼更新中繼資料原則。原則識別碼是 GUID 格式。

Microsoft Purview 目錄集合 API 參考摘要

下表提供 Microsoft Purview 集合 API 的概觀。如需每個 API 的完整檔，請選取左欄中的 API 作業。

作業	描述
建立或更新集合	建立或更新集合實體。
刪除集合	刪除集合實體。
取得集合	取得集合。
取得集合路徑	取得代表集合路徑的父名稱和顯示名稱鏈結。
列出子集合名稱	列出集合中的子集合名稱。
列出集合	列出帳戶中的集合。

如果您使用 API，執行 API 的服務主體、使用者或群組應該具有在 Microsoft Purview 中指派的集合管理員角色，才能成功執行此 API。
對於所有需要 {collectionName} 的 Microsoft Purview API，您必須使用 「name」 (而非 「friendlyName」) 。將 {collectionName} 取代為實際的六個字元英數位元集合名稱字串。

注意事項

此名稱與您在建立集合時提供的易記顯示名稱不同。如果您沒有方便的 {collectionName}，請使用清單集合 API 從 JSON 輸出中選取六個字元的集合名稱。

以下是範例 JSON 檔案：

{
    "name": "74dhe7", 
    "friendlyName": "Friendly Name",
    "parentCollection": {
        "type": "CollectionReference",
        "referenceName": "{your_purview_account_name}"
    },
    "systemData": {
        "createdBy": "{guid}",
        "createdByType": "Application",
        "createdAt": "2021-08-26T21:21:51.2646627Z",
        "lastModifiedBy": "7f8d47e2-330c-42f0-8744-fcfb1ecb3ea0",
        "lastModifiedByType": "Application",
        "lastModifiedAt": "2021-08-26T21:21:51.2646628Z"
    },
    "collectionProvisioningState": "Succeeded"
}

原則 JSON 描述

以下是從集合 API 接收的 JSON 輸出中的一些重要識別碼：

名稱：原則的名稱。

標識符：原則的唯一識別碼。

版本：原則的最新版本號碼。

重要事項

每次呼叫 Update-Metadata-Policy API 時，版本號碼都會遞增。請務必叫用 Get-Policy-by-Policy-ID API 來擷取原則的最新複本。每次呼叫更新原則之前，請先執行此重新整理 (PUT) API，讓您一律擁有最新版的 JSON 檔案。

DecisionRules：列出此原則的規則和效果。針對中繼資料原則，效果一律為「Permit」。

從集合或角色新增或移除使用者

使用 Microsoft Purview REST API 從集合或角色新增或移除使用者、群組或服務主體。詳細的 API 使用方式會連同範例 JSON 輸出一起提供。強烈建議您循序遵循下一節中的指示，以充分瞭解 Microsoft Purview 中繼資料原則 API。

取得所有中繼資料角色

若要列出所有可用的中繼資料存取權限角色，請根據您使用的入口網站執行下列其中一個命令：

傳統 Microsoft Purview 治理入口網站：

GET https://{your_purview_account_name}.purview.azure.com/policystore/metadataroles?api-version=2021-07-01

新的 Microsoft Purview 入口網站：

GET https://api.purview-service.microsoft.com/policystore/metadataroles?api-version=2021-07-01

輸出 JSON 會以這種格式描述角色及其相關聯的許可權。

下表列出預設中繼資料角色：

角色識別碼	權限	角色描述
purviewmetadatarole_builtin_data-source-administrator	Microsoft.Purview/accounts/scan/read Microsoft.Purview/accounts/scan/write Microsoft.Purview/accounts/collection/read	授與其他人讀取、寫入收集、註冊資料來源和觸發程式掃描的存取權。
purviewmetadatarole_builtin_collection系統管理員	Microsoft.Purview/accounts/collection/read Microsoft.Purview/accounts/collection/write	系統管理員層級完整存取整個集合，包括新增或移除使用者和服務主體名稱， (SPN) 集合、管理許可權，以及授與或撤銷存取權。在某些情況下，集合管理員可能會與集合的建立者不同。
purviewmetadatarole_builtin_purview讀取器	Microsoft.Purview/accounts/data/read Microsoft.Purview/accounts/collection/read	只授與集合中資料處理和所有中繼資料的讀取存取權，包括分類、敏感度標籤、深入解析和讀取資產，但掃描系結除外。
purviewmetadatarole_builtin_data-purviewmetadatarole_builtin_data	Microsoft.Purview/accounts/data/read Microsoft.Purview/accounts/data/write Microsoft.Purview/accounts/collection/read	授與集合中資料處理和所有中繼資料的完整存取權，包括分類、敏感度標籤、深入解析和讀取資產，但掃描系結除外。
purviewmetadatarole_builtin_data-share-contributor	Microsoft.Purview/accounts/share/read Microsoft.Purview/accounts/share/write	以參與者身分授與資料共用的存取權。

{
  "values": [
    {
      "id": "purviewmetadatarole_builtin_data-curator",
      "name": "data-curator",
      "type": "Microsoft.Purview/role",
      "properties": {
        "provisioningState": "Provisioned",
        "roleType": "BuiltIn",
        "friendlyName": "Data Curator",
        "cnfCondition": [
          [
            {
              "attributeName": "request.azure.dataAction",
              "attributeValueIncludedIn": [
                "Microsoft.Purview/accounts/data/read",
                "Microsoft.Purview/accounts/data/write",
                "Microsoft.Purview/accounts/collection/read"
              ]
            }
          ]
        ],
        "version": 1
      }
    },
    {
      "id": "purviewmetadatarole_builtin_data-source-administrator",
      "name": "data-source-administrator",
      "type": "Microsoft.Purview/role",
      "properties": {
        "provisioningState": "Provisioned",
        "roleType": "BuiltIn",
        "friendlyName": "Data Source Administrator",
        "cnfCondition": [
          [
            {
              "attributeName": "request.azure.dataAction",
              "attributeValueIncludedIn": [
                "Microsoft.Purview/accounts/scan/read",
                "Microsoft.Purview/accounts/scan/write",
                "Microsoft.Purview/accounts/collection/read"
              ]
            }
          ]
        ],
        "version": 1
      }
    },
    {
      "id": "purviewmetadatarole_builtin_collection-administrator",
      "name": "collection-administrator",
      "type": "Microsoft.Purview/role",
      "properties": {
        "provisioningState": "Provisioned",
        "roleType": "BuiltIn",
        "friendlyName": "Collection Administrator",
        "cnfCondition": [
          [
            {
              "attributeName": "request.azure.dataAction",
              "attributeValueIncludedIn": [
                "Microsoft.Purview/accounts/collection/read",
                "Microsoft.Purview/accounts/collection/write"
              ]
            }
          ]
        ],
        "version": 1
      }
    },
    {
      "id": "purviewmetadatarole_builtin_purview-reader",
      "name": "purview-reader",
      "type": "Microsoft.Purview/role",
      "properties": {
        "provisioningState": "Provisioned",
        "roleType": "BuiltIn",
        "friendlyName": "Microsoft Purview Reader",
        "cnfCondition": [
          [
            {
              "attributeName": "request.azure.dataAction",
              "attributeValueIncludedIn": [
                "Microsoft.Purview/accounts/data/read",
                "Microsoft.Purview/accounts/collection/read"
              ]
            }
          ]
        ],
        "version": 1
      }
    },
    {
      "id": "purviewmetadatarole_builtin_data-share-contributor",
      "name": "data-share-contributor",
      "type": "Microsoft.Purview/role",
      "properties": {
        "provisioningState": "Provisioned",
        "roleType": "BuiltIn",
        "friendlyName": "Data share contributor",
        "cnfCondition": [
          [
            {
              "attributeName": "request.azure.dataAction",
              "attributeValueIncludedIn": [
                "Microsoft.Purview/accounts/share/read",
                "Microsoft.Purview/accounts/share/write"
              ]
            }
          ]
        ],
        "version": 1
      }
    }
  ]
}

取得所有中繼資料原則

傳統 Microsoft Purview 治理入口網站：

GET https://{your_purview_account_name}.purview.azure.com/policystore/metadataPolicies?api-version=2021-07-01

新的 Microsoft Purview 入口網站：

GET https://api.purview-service.microsoft.com/policystore/metadataPolicies?api-version=2021-07-01

上述命令會以樹狀格式列出整個集合階層中所有可用的中繼資料原則，從頂端的根集合到其所有子原則。每個子集合都包含其下一個層級子系。

範例：

{
  "values": [
    {
      "name": "policy_FabrikamPurview",
      "id": "9b2f1cb9-584c-4a16-811e-9232884b5cac",
      "version": 30,
      "properties": {
        "description": "",
        "decisionRules": [
          {
            "kind": "decisionrule",
            "effect": "Permit",
            "dnfCondition": [
              [
                {
                  "attributeName": "resource.purview.collection",
                  "attributeValueIncludes": "fabrikampurview"
                },
                {
                  "fromRule": "permission:fabrikampurview",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "permission:fabrikampurview"
                }
              ]
            ]
          }
        ],
        "attributeRules": [
          {
            "kind": "attributerule",
            "id": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview",
            "name": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview",
            "dnfCondition": [
              [
                {
                  "attributeName": "principal.microsoft.id",
                  "attributeValueIncludedIn": [
                    "2f656762-e440-4b62-9eb6-a991d17d64b0",
                    "04314867-60a4-4e5a-ae16-8e5856f415d9",
                    "8988fe5c-5736-4179-9435-0a64c273b90b",
                    "6d563253-1d5b-48f2-baaa-5489f22ddce9",
                    "26f98046-5b02-4fa9-b709-e0519c658891",
                    "73fc02dc-becd-468b-a2a3-82238e722dae"
                  ]
                },
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
                },
                {
                  "attributeName": "principal.microsoft.groups",
                  "attributeValueIncludedIn": [
                    "ffd851fa-86ec-431b-95ea-8b84d5012383",
                    "cf84b126-4384-4952-91f1-7f705b25e569",
                    "5046aba1-5b81-411c-8fec-b84600f3f08b",
                    "b055a5c6-a04e-4d1a-8524-001ad81bfb28",
                    "cc194892-92fa-4ce3-96ae-1f98bef8211c"
                  ]
                }
              ]
            ]
          },
          {
            "kind": "attributerule",
            "id": "purviewmetadatarole_builtin_data-curator:fabrikampurview",
            "name": "purviewmetadatarole_builtin_data-curator:fabrikampurview",
            "dnfCondition": [
              [
                {
                  "attributeName": "principal.microsoft.id",
                  "attributeValueIncludedIn": [
                    "2f656762-e440-4b62-9eb6-a991d17d64b0",
                    "649f56ab-2dd2-40de-a731-3d3f28e7af92",
                    "c29a5809-f9ec-49fd-b762-2d4d64abb93e",
                    "04314867-60a4-4e5a-ae16-8e5856f415d9",
                    "73fc02dc-becd-468b-a2a3-82238e722dae",
                    "517a27d2-39ba-4c91-a032-dd9ecf8ad6f1",
                    "6d563253-1d5b-48f2-baaa-5489f22ddce9"
                  ]
                },
                {
                  "fromRule": "purviewmetadatarole_builtin_data-curator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_data-curator"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_data-curator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_data-curator"
                },
                {
                  "attributeName": "principal.microsoft.groups",
                  "attributeValueIncludedIn": [
                    "b055a5c6-a04e-4d1a-8524-001ad81bfb28",
                    "cc194892-92fa-4ce3-96ae-1f98bef8211c",
                    "5046aba1-5b81-411c-8fec-b84600f3f08b"
                  ]
                }
              ]
            ]
          },
          {
            "kind": "attributerule",
            "id": "purviewmetadatarole_builtin_data-source-administrator:fabrikampurview",
            "name": "purviewmetadatarole_builtin_data-source-administrator:fabrikampurview",
            "dnfCondition": [
              [
                {
                  "attributeName": "principal.microsoft.id",
                  "attributeValueIncludedIn": [
                    "2f656762-e440-4b62-9eb6-a991d17d64b0",
                    "04314867-60a4-4e5a-ae16-8e5856f415d9",
                    "517a27d2-39ba-4c91-a032-dd9ecf8ad6f1",
                    "6d563253-1d5b-48f2-baaa-5489f22ddce9"
                  ]
                },
                {
                  "fromRule": "purviewmetadatarole_builtin_data-source-administrator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_data-source-administrator"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_data-source-administrator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_data-source-administrator"
                },
                {
                  "attributeName": "principal.microsoft.groups",
                  "attributeValueIncludedIn": [
                    "b055a5c6-a04e-4d1a-8524-001ad81bfb28",
                    "cc194892-92fa-4ce3-96ae-1f98bef8211c",
                    "d34eb741-be5e-4098-90d7-eca8d4a5153f",
                    "664ec992-9af0-4773-88f2-dc39edc46f6f",
                    "5046aba1-5b81-411c-8fec-b84600f3f08b"
                  ]
                }
              ]
            ]
          },
          {
            "kind": "attributerule",
            "id": "permission:fabrikampurview",
            "name": "permission:fabrikampurview",
            "dnfCondition": [
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_purview-reader:fabrikampurview",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_purview-reader:fabrikampurview"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_data-curator:fabrikampurview",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_data-curator:fabrikampurview"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_data-source-administrator:fabrikampurview",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_data-source-administrator:fabrikampurview"
                }
              ]
            ]
          }
        ],
        "collection": {
          "type": "CollectionReference",
          "referenceName": "fabrikampurview"
        }
      }
    },
    {
      "name": "policy_b2zpf1",
      "id": "12b0bb28-2acc-413e-8fe1-179ff9cc54c3",
      "version": 0,
      "properties": {
        "description": "",
        "decisionRules": [
          {
            "kind": "decisionrule",
            "effect": "Permit",
            "dnfCondition": [
              [
                {
                  "attributeName": "resource.purview.collection",
                  "attributeValueIncludes": "b2zpf1"
                },
                {
                  "fromRule": "permission:b2zpf1",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "permission:b2zpf1"
                }
              ]
            ]
          }
        ],
        "attributeRules": [
          {
            "kind": "attributerule",
            "id": "purviewmetadatarole_builtin_collection-administrator:b2zpf1",
            "name": "purviewmetadatarole_builtin_collection-administrator:b2zpf1",
            "dnfCondition": [
              [
                {
                  "attributeName": "principal.microsoft.id",
                  "attributeValueIncludedIn": [
                    "2f656762-e440-4b62-9eb6-a991d17d64b0"
                  ]
                },
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator:ukx7pq",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:ukx7pq"
                }
              ]
            ]
          },
          {
            "kind": "attributerule",
            "id": "permission:b2zpf1",
            "name": "permission:b2zpf1",
            "dnfCondition": [
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator:b2zpf1",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:b2zpf1"
                }
              ],
              [
                {
                  "fromRule": "permission:ukx7pq",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "permission:ukx7pq"
                }
              ]
            ]
          }
        ],
        "collection": {
          "type": "CollectionReference",
          "referenceName": "b2zpf1"
        },
        "parentCollectionName": "ukx7pq"
      }
    },
    {
      "name": "policy_7wte2n",
      "id": "a72084e4-ccab-4aec-a364-08ab001e4999",
      "version": 0,
      "properties": {
        "description": "",
        "decisionRules": [
          {
            "kind": "decisionrule",
            "effect": "Permit",
            "dnfCondition": [
              [
                {
                  "attributeName": "resource.purview.collection",
                  "attributeValueIncludes": "7wte2n"
                },
                {
                  "fromRule": "permission:7wte2n",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "permission:7wte2n"
                }
              ]
            ]
          }
        ],
        "attributeRules": [
          {
            "kind": "attributerule",
            "id": "purviewmetadatarole_builtin_collection-administrator:7wte2n",
            "name": "purviewmetadatarole_builtin_collection-administrator:7wte2n",
            "dnfCondition": [
              [
                {
                  "attributeName": "principal.microsoft.id",
                  "attributeValueIncludedIn": [
                    "2f656762-e440-4b62-9eb6-a991d17d64b0"
                  ]
                },
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator",
                  "attributeName": "derived.purview.role",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
                }
              ],
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator:ukx7pq",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:ukx7pq"
                }
              ]
            ]
          },
          {
            "kind": "attributerule",
            "id": "permission:7wte2n",
            "name": "permission:7wte2n",
            "dnfCondition": [
              [
                {
                  "fromRule": "purviewmetadatarole_builtin_collection-administrator:7wte2n",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:7wte2n"
                }
              ],
              [
                {
                  "fromRule": "permission:ukx7pq",
                  "attributeName": "derived.purview.permission",
                  "attributeValueIncludes": "permission:ukx7pq"
                }
              ]
            ]
          }
        ],
        "collection": {
          "type": "CollectionReference",
          "referenceName": "7wte2n"
        },
        "parentCollectionName": "ukx7pq"
      }
    }
  ]
}

取得選取的中繼資料原則

您可以藉由提供 {collectionName} 或 {PolicyID}，使用兩個 API 的其中一個來擷取特定集合的中繼資料原則 JSON 結構。

如下列兩節所述，這兩個 API 的用途相同，而且兩者的 JSON 輸出完全相同。

使用集合名稱取得集合的中繼資料原則

傳統 Microsoft Purview 治理入口網站：

GET https://{your_purview_account_name}.purview.azure.com/policystore/collections/{collectionName}/metadataPolicy?api-version=2021-07-01

新的 Microsoft Purview 入口網站：

GET https://api.purview-service.microsoft.com/policystore/collections/{collectionName}/metadataPolicy?api-version=2021-07-01

Microsoft Purview 帳戶名稱為 {your_purview_account_name}。將它取代為您的 Microsoft Purview 帳戶名稱。
在上一個 API 的 JSON 輸出「取得所有中繼資料原則」中，尋找下列區段：

{ 「type」：「CollectionReference」，「referenceName」：「7xkdg2」}
將 API URL 中的「{collectionName}」取代為「referenceName」：「{6-char-collection-name}」。例如，如果您的六個字元集合名稱是「7xkdg2」，則 API URL 會格式化為：

https://{your_purview_account_name}.purview.azure.com/policystore/collections/7xkdg2/metadataPolicy?api-version=2021-07-01

執行下列 API：

{
  "name": "policy_qu45fs",
  "id": "c6639bb2-9c41-4be0-912b-775750e725de",
  "version": 0,
  "properties": {
    "description": "",
    "decisionRules": [
      {
        "kind": "decisionrule",
        "effect": "Permit",
        "dnfCondition": [
          [
            {
              "attributeName": "resource.purview.collection",
              "attributeValueIncludes": "qu45fs"
            },
            {
              "fromRule": "permission:qu45fs",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "permission:qu45fs"
            }
          ]
        ]
      }
    ],
    "attributeRules": [
      {
        "kind": "attributerule",
        "id": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
        "name": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
        "dnfCondition": [
          [
            {
              "attributeName": "principal.microsoft.id",
              "attributeValueIncludedIn": [
                "2f656762-e440-4b62-9eb6-a991d17d64b0"
              ]
            },
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator",
              "attributeName": "derived.purview.role",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
            }
          ],
          [
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview"
            }
          ]
        ]
      },
      {
        "kind": "attributerule",
        "id": "permission:qu45fs",
        "name": "permission:qu45fs",
        "dnfCondition": [
          [
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:qu45fs"
            }
          ],
          [
            {
              "fromRule": "permission:fabrikampurview",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "permission:fabrikampurview"
            }
          ]
        ]
      }
    ],
    "collection": {
      "type": "CollectionReference",
      "referenceName": "qu45fs"
    },
    "parentCollectionName": "fabrikampurview"
  }
}

使用原則識別碼取得集合的中繼資料原則

傳統 Microsoft Purview 治理入口網站：

GET https://{your_purview_account_name}.purview.azure.com/policystore/metadataPolicies/{policyId}?api-version=2021-07-01

新的 Microsoft Purview 入口網站：

GET https://api.purview-service.microsoft.com/policystore/metadataPolicies/{policyId}?api-version=2021-07-01

Microsoft Purview 帳戶名稱為 {your_purview_account_name}。將它取代為您的 Microsoft Purview 帳戶名稱。
在上一個 API 的 JSON 輸出「取得所有中繼資料原則」中，尋找下列區段：

{....「name」：「policy_qu45fs」，「id」：「{policy-guid}」，「version」： N ....}
將 API URL 中的「{policyId}」取代為「id」值。例如，如果您的「{policy-guid}」為「c6639bb2-9c41-4be0-912b-775750e725de」，則 API URL 會格式化為：

HTTPs://{your_purview_account_name}.purview.azure.com/policystore/metadataPolicies/c6639bb2-9c41-4be0-912b-775750e725de?api-version=2021-07-01
現在，執行下列 API：

注意事項

此 API 呼叫和先前 API 呼叫的輸出相同。如先前所述，您可以選擇其中一個。

{
  "name": "policy_qu45fs",
  "id": "c6639bb2-9c41-4be0-912b-775750e725de",
  "version": 0,
  "properties": {
    "description": "",
    "decisionRules": [
      {
        "kind": "decisionrule",
        "effect": "Permit",
        "dnfCondition": [
          [
            {
              "attributeName": "resource.purview.collection",
              "attributeValueIncludes": "qu45fs"
            },
            {
              "fromRule": "permission:qu45fs",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "permission:qu45fs"
            }
          ]
        ]
      }
    ],
    "attributeRules": [
      {
        "kind": "attributerule",
        "id": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
        "name": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
        "dnfCondition": [
          [
            {
              "attributeName": "principal.microsoft.id",
              "attributeValueIncludedIn": [
                "2f656762-e440-4b62-9eb6-a991d17d64b0"
              ]
            },
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator",
              "attributeName": "derived.purview.role",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
            }
          ],
          [
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview"
            }
          ]
        ]
      },
      {
        "kind": "attributerule",
        "id": "permission:qu45fs",
        "name": "permission:qu45fs",
        "dnfCondition": [
          [
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:qu45fs"
            }
          ],
          [
            {
              "fromRule": "permission:fabrikampurview",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "permission:fabrikampurview"
            }
          ]
        ]
      }
    ],
    "collection": {
      "type": "CollectionReference",
      "referenceName": "qu45fs"
    },
    "parentCollectionName": "fabrikampurview"
  }
}

更新收集原則

PUT https://{your_purview_account_name}.purview.azure.com/policystore/metadataPolicies/{policyId}?api-version=2021-07-01

在本節中，您會從集合新增或移除使用者、群組或服務主體，以更新您在上一個步驟中取得的原則 JSON。然後使用 PUT REST 方法，將它推送至 Microsoft Purview 服務。

無論您要新增或移除使用者、群組或服務主體，您都會遵循相同的 API 程式。

在 JSON 的「attributeValueIncludedIn」陣列中提供使用者、群組或服務主體物件識別碼 {guid}。
搜尋上一個步驟中「attributeValueIncludedIn」陣列的 Get-Policy-by-ID API 的 JSON 輸出，並在陣列中新增或移除使用者、群組或服務主體物件識別碼。如果您不確定如何擷取使用者、群組或服務主體物件識別碼，請參閱 Get-AzureADUser。
這四個角色的 JSON 對應中有多個區段。針對集合管理員許可權角色，請使用識別碼稱為「purviewmetadatarole_builtin_collection-administrator」的區段。同樣地，針對其他角色使用對應的區段。
若要進一步瞭解新增/移除作業，請仔細檢查先前 API 的 JSON 輸出與下列輸出之間的差異。在下列輸出的 JSON 中，我們新增了使用者識別碼「3a3a3a3a-2c2c-4b4b-1c1c-2a3b4c5d6e7f」作為集合管理員。

{
  "name": "policy_qu45fs",
  "id": "c6639bb2-9c41-4be0-912b-775750e725de",
  "version": 0,
  "properties": {
    "description": "",
    "decisionRules": [
      {
        "kind": "decisionrule",
        "effect": "Permit",
        "dnfCondition": [
          [
            {
              "attributeName": "resource.purview.collection",
              "attributeValueIncludes": "qu45fs"
            },
            {
              "fromRule": "permission:qu45fs",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "permission:qu45fs"
            }
          ]
        ]
      }
    ],
    "attributeRules": [
      {
        "kind": "attributerule",
        "id": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
        "name": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
        "dnfCondition": [
          [
            {
              "attributeName": "principal.microsoft.id",
              "attributeValueIncludedIn": [
                "2f656762-e440-4b62-9eb6-a991d17d64b0",
                "3a3a3a3a-2c2c-4b4b-1c1c-2a3b4c5d6e7f"
              ]
            },
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator",
              "attributeName": "derived.purview.role",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator"
            }
          ],
          [
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:fabrikampurview"
            }
          ]
        ]
      },
      {
        "kind": "attributerule",
        "id": "permission:qu45fs",
        "name": "permission:qu45fs",
        "dnfCondition": [
          [
            {
              "fromRule": "purviewmetadatarole_builtin_collection-administrator:qu45fs",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "purviewmetadatarole_builtin_collection-administrator:qu45fs"
            }
          ],
          [
            {
              "fromRule": "permission:fabrikampurview",
              "attributeName": "derived.purview.permission",
              "attributeValueIncludes": "permission:fabrikampurview"
            }
          ]
        ]
      }
    ],
    "collection": {
      "type": "CollectionReference",
      "referenceName": "qu45fs"
    },
    "parentCollectionName": "fabrikampurview"
  }
}

新增根集合管理員角色

根據預設，建立 Microsoft Purview 帳戶的使用者是根集合管理員 (也就是集合階層最上層的系統管理員) 。不過，在某些情況下，組織可能會想要使用 API 來變更根集合管理員。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Purview/accounts/{accountName}/addRootCollectionAdmin?api-version=2021-07-01

若要執行上述命令，您只需要傳遞新的根集合管理員的物件識別碼。如先前所述，物件識別碼可以是任何使用者、群組或服務主體的識別碼。

{"objectId": "{guid}"}

注意事項

呼叫此 API 的使用者必須具有 Microsoft Purview 帳戶的擁有者或使用者帳戶和驗證 (UAA) 許可權，才能在帳戶上執行寫入動作。

其他資源

您可以選擇使用 PowerShell 公用程式來執行 Microsoft Purview REST API。您可以從PowerShell 資源庫立即安裝它。使用此公用程式，您可以執行所有相同的命令，但從 Windows PowerShell。

後續步驟

Purview-API-PowerShell

共用方式為

教學課程：使用 REST API 管理 Microsoft Purview 集合上的角色型存取控制

中繼資料原則 API 參考摘要

Microsoft Purview 目錄集合 API 參考摘要

原則 JSON 描述

從集合或角色新增或移除使用者

取得所有中繼資料角色

取得所有中繼資料原則

取得選取的中繼資料原則

使用集合名稱取得集合的中繼資料原則

使用原則識別碼取得集合的中繼資料原則

更新收集原則

新增根集合管理員角色

其他資源

後續步驟

意見反應

意見反應

其他資源