教學 - 使用 Microsoft Purview API 來善用你的應用程式中的政策

所有應用程式，包括企業 AI 應用程式，都處理需要防範資料外洩、未經授權存取及合規違規的敏感資料。 Microsoft Purview 政策協助組織保護敏感資訊。 您的應用程式可以整合 Microsoft Purview API，確保 Microsoft Purview 政策能支援您的應用程式安全防護。

本文將詳細說明如何將 Microsoft Purview API 加入現有企業應用程式，以善用你的政策。 本文舉例為生成式 AI 應用程式，但相同的概念也很容易套用到非 AI 應用程式上。 在這次攻略結束時，你會明白：

• 何時以及如何為已知使用者呼叫 Purview API，針對他們在應用程式中執行的活動。
• 根據這些政策評估使用者輸入與應用程式輸出（例如提示與 AI 回應，或任何用戶提交的文字與生成內容）。
• 在你的應用程式中執行政策操作，例如封鎖或保持租戶的政策修改與最新。

先決條件

在開始之前，請確保您擁有：

• 已設定 Microsoft Purview 的 Azure 訂用帳戶。

• 一個以 Microsoft Entra ID 註冊並擁有適當權限的應用程式。

• 對 Microsoft 圖形 API 呼叫有基本熟悉。

• 存取你想評估的使用者輸入與應用程式輸出（例如生成式 AI 應用程式中的提示與回應，或是業務線上應用程式上傳/下載的文字）。

• 端對端測試時，請在您的 Microsoft Purview 入口網站 建立政策。 欲了解更多可用政策資訊，請參閱使用 Microsoft Purview 管理 Entra 註冊 AI 應用程式的資料安全與合規。

  Important

  要建立適用於你 Entra 註冊應用程式的 DLP 政策，你必須使用 New-DlpComplianceRule PowerShell 指令檔。 Microsoft Purview 入口網站 目前不支援為 Entra 註冊應用程式建立 DLP 政策。 欲了解更多資訊，請參閱 New-DlpComplianceRule。

如何開始使用 Microsoft Graph

如果你完全是 Microsoft Graph 的新手，請參考 Microsoft Graph 基礎。

以下步驟幫助你 嘗試 使用 API。 不要用這些步驟來規劃應用程式的生產部署。

1. 了解 Microsoft Graph 中的 Microsoft Purview API，以將其整合至您的應用程式。 這些 API 將在本文後面詳細說明。

2. 請你的 Entra 管理員幫你在 Entra 裡註冊你的應用程式 。 根據你公司的政策，他們可能會讓你註冊應用程式，或者你可能需要遵循註冊流程。 務必向你的 Entra 管理員確認，了解租戶該遵循的流程。 如需詳細資訊，請參閱下列資源：

   • 向 Microsoft 身分識別平台 註冊應用程式。
   • Microsoft 身分識別平台 驗證與授權程式碼範例。
   • Microsoft Graph 認證與授權概述。
   • 在 Microsoft Entra ID 生態系統中建立應用程式。
   • Microsoft Entra ID 獨立軟體開發者指南。

3. 請用所需的權限設定你的應用程式。 請確保您的應用程式在向 Microsoft Graph 要求權杖時，一併要求這些權限。 例如，你可以為你的應用程式分配 Content.Process.User 和 ProtectionScopes.Compute.User 權限。 欲了解更多資訊，請參閱 Microsoft Graph 權限參考和 使用 Microsoft Entra ID 授權應用程式、資源和工作負載。

4. 請你的租戶管理員設定 Microsoft Purview 的政策和設定。 欲了解更多資訊，請參閱「配置 Microsoft Purview 解決方案於資料安全態勢管理（DSPM）中的人工智慧，用於客製化 AI 應用。 你的管理員必須使用 New-DlpComplianceRule PowerShell 指令檔來為你的 Entra 註冊應用程式建立 DLP 政策。 Microsoft Purview 入口網站 不支援此情境。

5. 測試您的應用程式。 欲了解更多資訊，請參閱 如何使用 Purview API 測試 AI 應用程式。

Microsoft Purview API 整合概覽

您的應用程式會執行兩個關鍵的 API 呼叫來支援您的 Microsoft Purview 政策：

1. Compute protection scopes： 決定哪些使用者活動（上傳文字、下載文字、上傳檔案、下載檔案）需要針對特定使用者進行政策評估。
2. Process content： 您的應用程式會傳送一項內容活動以供政策評估，並回傳應用程式必須執行的政策行動（例如封鎖或偵測政策變更）。

以下章節提供逐步實作指引，包括程式碼範例及回應處理方式。

想詳細了解一個能呼叫這些 API 的示範應用程式，請參考 Microsoft Reactor 影片。

步驟 1：為使用者計算保護範圍

第一步是根據使用者在應用程式中能執行的活動（例如上傳文字輸入/提示或下載 AI 回應）來識別適用哪些政策和限制。 這稱為計算使用者的保護範圍。

保護範圍是租戶內套用至使用者之原則的抽象化呈現。 對於任何特定使用者及其在應用程式中執行的活動，你要計算保護範圍。 保護範圍指示應用程式接下來應該採取的行動，可以是評估並封鎖、評估但不封鎖，或是不需要評估。

以下是傳送至 protectionScopes/compute 的請求範例。

POST https://graph.microsoft.com/v1.0/users/7c1f8f10-cba8-4a8d-9449-db4b876d1ef70/dataSecurityAndGovernance/protectionScopes/compute
Content-type: application/json

{
   "activities": "uploadText,downloadText",
   "locations": [
      {
         "@odata.type": "microsoft.graph.policyLocationApplication",
         "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
      }
   ]
}

在前述計算保護範圍的呼叫中，您必須包含使用者在應用程式中執行的活動。 允許的使用者活動包括：

• uploadText - 使用者將文字輸入傳送給應用程式（例如發送給 AI 的提示、聊天應用程式中的訊息，或貼上到表單中的文字）。
• downloadText - 應用程式傳回給使用者的文字型輸出（例如 AI 回應或產生的文件本文）。
• uploadFile - 使用者向應用程式提交檔案（例如附加於處理提示的檔案）。
• downloadFile - 應用程式回傳給使用者的檔案（例如由 AI 產生或由業務應用匯出的檔案）。

欲了解更多使用者活動資訊，請參閱 userActivityTypes 值。

計算保護範圍的呼叫會回傳一組 policyUserScopes。 這裡有一個有兩個保護鏡的回應範例。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.policyUserScope)",
  "value": [
    {
      "activities": "uploadText,downloadText",
      "executionMode": "evaluateOffline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    },
    {
      "activities": "uploadText",
      "executionMode": "evaluateInline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    }
  ]
}

應用程式解析此回應以判斷哪些使用者活動（例如 uploadText）需要對提交或發送給使用者的內容進行政策評估非常重要。

如果回傳的 policyUserScopes 集合為空： 使用者的活動不會適用任何政策。 當此使用者的這項活動沒有任何適用的原則時，我們建議呼叫 Content activity 來記錄活動，以供稽核合規和異常偵測之用。 你可以在應用程式中設定這個設定。

如果 policyUserScopes 集合包含 scope：當保護範圍被回傳時，應用程式需要透過檢查每個保護範圍的activitiesexecutionMode值來解析回應。 在前述範例中，policyUserScopes 集合中會傳回 2 個保護範圍。

executionMode 可協助您判斷某位特定使用者在某項使用者活動中適用的限制。 以下列表顯示 的 executionMode有效值：

• evaluateOffline：表示您可以在呼叫 processContent 時，發出非同步呼叫，根據原則評估內容。
• evaluateInline： 表示你的應用程式主執行緒必須阻塞，直到呼叫從 processContent返回。

如需詳細資訊，請參閱 executionMode 的值。

activity 表示保護範圍適用的使用者活動。 你可能會發現 activity 在多個保護範圍內重複出現。 例如，請注意，在前面的範例中，uploadText 會在兩個保護範圍中都被傳回。 在這種情況下，你的應用程式必須對該使用者的行為套用更嚴格的保護範圍。

以下範例展示了你的應用程式如何解析前一個回傳 policyUserScopes 的集合：

1. 透過解析第一個保護範圍，我們看到以下資訊：
   • uploadText（或傳送給 AI 的提示詞）以及 downloadText（或 AI 的回應）都必須以離線方式評估。
2. 解析第二個保護範圍時，我們看到以下資訊：
   • uploadText（或傳送給 AI 的提示詞）必須以內嵌方式評估。
3. 對於其他任何使用者活動（uploadFile， downloadFile），這些使用者活動都不適用保護範圍。 請考慮如前所述呼叫內容活動。

你的應用程式必須為這些不同使用者活動實作的邏輯如下：

步驟二：內容處理

接著，根據使用者的保護範圍狀態，你的應用程式可能需要呼叫 processContent。

如前所述，在任何使用者活動中，若 executionMode 為 evaluateInline 或 evaluateOffline，則必須呼叫 processContent。

當你打電話時，先把應用程式從通話中快取的值傳送 ETag 到 protectionScopes/compute 步驟 1 中，以確認租戶是否有做政策修改。 你要在 If-None-Match 標頭中傳送 ETag 值。

以下是一個對 processContent 的呼叫範例。

POST https://graph.microsoft.com/v1.0/me/dataSecurityAndGovernance/processContent
Content-Type: application/json

{
    "contentToProcess": {
       "contentEntries": [
          {
             "@odata.type": "microsoft.graph.processConversationMetadata",
             "identifier": "07785517-9081-4fe7-a9dc-85bcdf5e9075",
             "content": {
                "@odata.type": "microsoft.graph.textContent", 
                "data": "Write an acceptance letter for Alex Wilber with Credit card number 4532667785213500, ssn: 120-98-1437 at One Microsoft Way, Redmond, WA 98052"
             },
             "name":"PC Purview API Explorer message",
             "correlationId": "d63eafd2-e3a9-4c1a-b726-a2e9b9d9580d",
             "sequenceNumber": 0, 
             "isTruncated": false,
             "createdDateTime": "2025-05-27T17:23:20",
             "modifiedDateTime": "2025-05-27T17:23:20"
          }
       ],
       "activityMetadata": { 
          "activity": "uploadText"
       },
       "deviceMetadata": {
          "deviceType": "Unmanaged",
          "operatingSystemSpecifications": {
             "operatingSystemPlatform": "Windows 11",
             "operatingSystemVersion": "10.0.26100.0" 
          },
          "ipAddress": "127.0.0.1"
       },
       "protectedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2",
          "applicationLocation":{
             "@odata.type": "microsoft.graph.policyLocationApplication",
             "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
          }
       },
       "integratedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2" 
       }
    }
}

以下是來自 processContent的回應範例。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.processContentResponse",
  "protectionScopeState": "modified",
  "policyActions": [
    {
      "@odata.type": "#microsoft.graph.restrictAccessAction",
      "action": "restrictAccess",
      "restrictionAction": "block"
    }
  ],
  "processingErrors": []
}

在前面的例子中，你的應用程式必須採取兩個步驟：

1. processContentResponse 包含設為 modified 的 protectionScopeState 屬性。 modified 表示租戶的政策已變更。 由於政策已變更，您的應用程式必須先呼叫 protectionScopes/compute 以取得該使用者的新保護範圍，如步驟 1 所述。 請確保快取新的 ETag 值。
2. 因為集合 policyActions 不是空的，你的應用程式需要逐一步驟檢視 action ，判斷必須採取的適當行動。 在此範例中， restrictAccess 表示你的應用程式必須阻擋使用者執行該請求的動作。 如果 policyActions 集合 processContentResponse 是空的，你的應用程式會繼續執行被要求的活動。 如果你正在建置代理，當 action 設為 restrictAccess 時，代理在呼叫另一個代理之前也必須先進入阻塞狀態。