教程 - 使用 Microsoft Purview API 在应用中利用你的策略

所有应用（包括企业 AI 应用）都处理需要保护的敏感数据，防止数据泄露、未经授权的访问和合规性违规。 Microsoft Purview策略可帮助组织保护敏感信息。 你的应用可以与Microsoft Purview API 集成，以确保Microsoft Purview策略支持应用的安全状况。

本文演示了如何将Microsoft Purview API 添加到现有企业应用以利用策略。 本文中使用的示例是 GenAI 应用，但同样的概念可以轻松应用于非 AI 应用。 在本演练结束时，你将了解：

  • 针对已知用户在您的应用中执行某项活动时，何时以及如何调用 Purview API。
  • 根据这些策略评估用户输入和应用输出（例如提示和 AI 响应或任何用户提交的文本和生成的内容）。
  • 在应用中强制执行策略操作，例如阻止操作，或与租户中的策略更改保持同步。

注释

使用Microsoft Purview API 将数据发送到Microsoft Purview并支持与该数据关联的 Purview 策略。 没有可用于从Microsoft Purview提取数据或分析的 API。

先决条件

在开始之前，请确保具备：

  • 已配置 Microsoft Purview 的 Azure 订阅。

  • 在Microsoft Entra ID中注册并具有相应权限的应用程序。

  • 基本熟悉Microsoft 图形 API调用。

  • 访问要评估的用户输入和应用输出（例如，GenAI 应用中的提示和响应，或业务线应用上传/下载的文本）。

  • 若要进行端到端测试，请在Microsoft Purview 门户中创建策略。 有关可用策略的详细信息，请参阅使用Microsoft Purview来管理 Entra 注册的 AI 应用的数据安全性和符合性。

    Important

    若要创建适用于 Entra 注册应用的 DLP 策略，必须使用 New-DlpComplianceRule PowerShell cmdlet。 Microsoft Purview 门户目前不支持为 Entra 注册的应用程序创建 DLP 策略。 有关详细信息，请参阅 New-DlpComplianceRule。

如何开始使用Microsoft Graph

如果你完全不熟悉使用Microsoft Graph，请参阅Microsoft Graph基础知识。

以下步骤可帮助你 试验 API。 不要使用这些步骤来计划应用程序的生产部署。

  1. 了解 Microsoft Graph 中的 Microsoft Purview API，以便将其集成到你的应用中。 本文稍后将详细介绍这些 API。

  2. 让 Entra 管理员在 Entra 中 注册应用 。 根据公司的策略，他们可能会让你注册应用，或者可能需要遵循注册过程。 请务必与 Entra 管理员联系，了解租户要遵循的过程。 有关详细信息，请参阅以下资源：

  3. 为您的应用配置所需权限。 确保你的应用在向 Microsoft Graph 请求令牌时申请这些权限。 例如，可以向应用分配 Content.Process.User 和 ProtectionScopes.Compute.User 权限。 有关详细信息，请参阅 Microsoft Graph 权限参考和 使用 Microsoft Entra ID 对应用程序、资源和工作负载进行授权。

  4. 让租户管理员配置Microsoft Purview策略和设置。 有关详细信息，请参阅在用于 AI 的数据安全态势管理 (DSPM) 中配置适用于自定义 AI 应用程序的 Microsoft Purview 解决方案。 管理员必须使用 New-DlpComplianceRule PowerShell cmdlet 为 Entra 注册的应用创建 DLP 策略。 Microsoft Purview 门户不支持此方案。

  5. 测试应用。 有关详细信息，请参阅 如何使用 Purview API 测试 AI 应用程序。

Microsoft Purview API 集成概述

应用程序执行两个关键 API 调用以支持Microsoft Purview策略：

  1. Compute protection scopes：确定哪些用户活动（uploadText、downloadText、uploadFile、downloadFile）需要对特定用户进行策略评估。
  2. Process content：应用发送用于策略评估的内容活动，并返回应用必须强制执行的策略操作（例如阻止或检测策略修改）。

以下部分提供了分步实现指南，包括代码示例以及如何处理响应。

有关进行这些 API 调用的演示应用的详细演练，请参阅 Microsoft Reactor 视频。

步骤 1：用户的计算保护范围

第一步是根据可在应用程序中执行的活动（例如上传文本输入/提示或下载 AI 响应）确定哪些策略和限制适用于特定用户。 这称为计算用户的保护范围。

保护范围是对租户中适用于用户的策略的抽象。 对于用户在应用中执行的任何给定用户和活动，需要计算保护范围。 保护范围指示应用接下来应采取的操作，该操作可以是“评估并阻止”“评估但不阻止”或“不需要评估”。

注释

我们建议，在用户完成身份验证后，您的应用立即调用 计算保护范围。 若要呼叫protectionScopes/compute，必须具有用户的Entra ID。

如果只有用户的 userPrincipalName，请使用以下 URL 检索其对象 ID。

GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}?$select=id

下面是向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 的集合。 下面是具有 2 个保护范围的响应示例。

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 集合为空： 对于用户活动，不会对用户应用任何策略。 如果此活动没有策略应用于此用户，我们建议调用 内容活动 来记录活动以记录审核合规性和异常情况检测。 可以在应用中将此设置为可配置的设置。

如果 policyUserScopes 集合包含作用域：返回保护作用域时，你的应用需要通过检查每个保护作用域的 activities 和 executionMode 的值来解析响应。 在前面的示例中，集合中 policyUserScopes 返回 2 个保护范围。

executionMode 可帮助你确定针对某项用户活动，特定用户适用的限制。 以下列表显示了以下项的有效值 executionMode：

  • evaluateOffline：表示可以进行异步调用，以在调用 processContent时根据策略评估内容。
  • evaluateInline：表示应用的主线程必须阻塞，直到对 processContent 的调用返回。

有关详细信息，请参阅 executionMode 值。

Tip

如果 protectionScopes/compute 始终返回保护范围，其 executionMode 始终等于 evaluateOffline，请验证你是否使用 New-DlpComplianceRule PowerShell cmdlet 创建了 DLP 策略。 确认在 DSPM > 收集策略中列出并启用该策略。 通过 Microsoft Purview 门户 UI 创建的策略不适用于 Entra 注册的应用程序。

activity 表示保护范围适用的用户活动。 你可能会发现，activity 在多个保护范围中重复出现。 例如，请注意，在前面的示例中，uploadText 在两个保护范围中都返回了。 在这种情况下，你的应用必须将限制性更高的保护范围应用于该用户活动。

以下示例演示如何应用分析上述返回 policyUserScopes 的集合：

  1. 通过分析第一个保护范围，可以看到以下信息：
    • uploadText（或发送给 AI 的提示）和 downloadText（或 AI 的响应）必须进行离线评估。
  2. 分析第二个保护范围时，会看到以下信息：
    • uploadText（或发送给 AI 的提示）必须以行内方式评估。
  3. 对于任何其他用户活动（uploadFile、downloadFile），这些用户活动不适用任何保护范围。 请考虑如前所述调用 Content 活动。

应用必须为这些不同的用户活动实现的逻辑如下所示：

用户活动 应用中的操作
uploadText 调用 processContent时阻止主线程。
downloadText 调用 processContent时进行异步调用。

Important

缓存 ETag 值：对 protectionScopes/compute 的调用会返回一个 ETag 标头，该标头表示该用户保护范围的当前状态。 应用必须缓存此值，并使用对 processContent 的所有调用发送该值。

步骤 2：处理内容

接下来，根据用户的保护范围状态，应用可能需要调用 processContent。

如前所述，任何其中 executionMode 为 evaluateInline 或 evaluateOffline 的用户活动都需要调用 processContent。

发出调用时，请发送你的应用在步骤 1 中调用 protectionScopes/compute 时缓存的 ETag 值，以确定你的租户中是否进行了策略修改。 您在 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" 
       }
    }
}

注释

对话/线程实现指南：

  • 如果您的应用程序支持多个线程或对话（例如 AI 应用或消息应用程序中的聊天线程），请为每个线程使用唯一的 correlationId。
  • 如果您在特定线程中维护会话上下文，则每条用户消息都将 sequenceNumber 递增一次（例如，依次使用 0、1、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 意味着你的应用必须阻止用户退出请求的操作。 如果 processContentResponse 中的 policyActions 集合为空，你的应用将继续执行所请求的活动。 如果您正在构建代理，当 action 设置为 restrictAccess 时，代理在调用另一个代理之前也必须先阻塞。

Important

如果距离上次调用 processContent 已过去 60 分钟，我们建议调用 计算保护作用域，以检测租户中所做的任何策略更改现在是否会应用于该用户。 如果某项更改现已适用于该用户，则调用 protectionScopes/compute 会返回一个新的 ETag 值，该值必须缓存在您的应用中，并在调用 processContent 时使用。

  • Last updated on