Руководство. Использование API Microsoft Purview для использования политик в приложениях

Все приложения, включая корпоративные приложения ИИ, обрабатывают конфиденциальные данные, требующие защиты от утечки данных, несанкционированного доступа и нарушений соответствия требованиям. политики Microsoft Purview помогают организациям защищать конфиденциальную информацию. Приложения могут интегрироваться с API-интерфейсами Microsoft Purview, чтобы обеспечить поддержку политики безопасности вашего приложения Microsoft Purview.

В этой статье приведено пошаговое руководство по добавлению API-интерфейсов Microsoft Purview в существующее корпоративное приложение для использования политик. Пример, используемый в этой статье, — это приложение GenAI, но те же понятия можно легко применять к приложениям, отличным от ИИ. В конце этого пошагового руководства вы узнаете:

• Когда и как вызывать API Purview для известного пользователя для действия, выполняемого в приложении.
• Оцените входные данные пользователей и выходные данные приложения (например, запросы и ответы ИИ или любой отправленный пользователем текст и созданный контент) в отношении этих политик.
• Применяйте в своем приложении действия политики, например блокировку, и обеспечивайте актуальность с учетом изменений политики в вашем клиенте.

Необходимые условия

Прежде чем начать, убедитесь, что у вас есть следующее:

• Подписка Azure с настроенным Microsoft Purview.

• Приложение, зарегистрированное в Microsoft Entra ID с соответствующими разрешениями.

• Базовое знакомство с вызовами Microsoft API Graph.

• Доступ к входным данным пользователя и выходным данным приложения, которые вы хотите оценить (например, запросы и ответы в приложении GenAI или текст, загруженный или скачанный бизнес-приложением).

• Для сквозного тестирования создайте политики на портале Microsoft Purview. Дополнительные сведения о доступных политиках см. в статье Использование Microsoft Purview для управления безопасностью данных и соответствием требованиям для приложений ИИ, зарегистрированных в Entra.

  Important

  Чтобы создать политику защиты от потери данных, применяемую к вашему приложению, зарегистрированному в Microsoft Entra, необходимо использовать командлет PowerShell New-DlpComplianceRule. В настоящее время портал Microsoft Purview не поддерживает создание политик DLP для приложений, зарегистрированных в Microsoft Entra. Дополнительные сведения см. в статье New-DlpComplianceRule.

Начало работы с Microsoft Graph

Если вы совершенно не знакомы с использованием Microsoft Graph, ознакомьтесь с Microsoft Graph основами.

Следующие шаги помогут вам поэкспериментировать с API. Не используйте эти действия для планирования рабочего развертывания приложения.

1. Узнайте об API Microsoft Purview в Microsoft Graph, чтобы интегрировать их в свое приложение. Эти API подробно описаны в этой статье.

2. Попросите администратора Entra зарегистрировать ваше приложение в Entra. В зависимости от политики вашей компании они могут позволить зарегистрировать приложение или вам может потребоваться следовать процессу регистрации. Обязательно обратитесь к администратору Entra, чтобы понять процесс, который нужно выполнить для вашего клиента. Дополнительные сведения см. на следующих ресурсах:

   • Регистрирование приложения с помощью платформа удостоверений Майкрософт.
   • Примеры кода платформы удостоверений Майкрософт для аутентификации и авторизации.
   • Обзор проверки подлинности и авторизации в 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) для ИИ для пользовательских приложений ИИ. Администратор должен использовать командлет New-DlpComplianceRule PowerShell для создания политик защиты от потери данных (DLP) для ваших приложений, зарегистрированных в Microsoft Entra. Портал Microsoft Purview не поддерживает этот сценарий.

5. Тестирование приложения. Дополнительные сведения см. в статье "Тестирование приложения ИИ с помощью API Purview".

Обзор интеграции с API Microsoft Purview

Приложение выполняет два ключевых вызова API для поддержки политик Microsoft Purview:

1. Compute protection scopes: определяет, какие действия пользователя (uploadText, downloadText, uploadFile, downloadFile) требуют оценки политики для конкретного пользователя.
2. Process content: Ваше приложение отправляет событие, связанное с содержимым, для оценки политики и получает действия, предписанные политикой, которые оно обязано выполнять (например, блокировку или обнаружение изменений).

В следующих разделах приведены пошаговые инструкции по реализации, включая примеры кода и способы обработки ответов.

Подробное пошаговое руководство демонстрационного приложения, которое делает эти вызовы API, см. в видео Microsoft Reactor.

Шаг 1. Области защиты вычислений для пользователя

Первым шагом является определение политик и ограничений, применяемых к конкретному пользователю на основе действий, которые они могут выполнять в приложении (например, отправка текстовых и запросов или скачивание ответов ИИ). Это называется вычислением области защиты пользователя.

Области защиты — это абстрактное представление политик арендатора, применимых к пользователю. Для любого пользователя и действия, выполняемого в приложении, необходимо вычислить область защиты. Область применения защиты указывает, какое действие приложение должно выполнить далее: проверить и заблокировать, проверить и не блокировать либо проверка не требуется.

Ниже приведен пример запроса 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 — пользователи отправляют текстовые данные в приложение (например, запрос, отправленный в ИИ, сообщение в приложении чата или текст, вставленный в форму).
• downloadText — текстовый вывод, который приложение возвращает пользователю (например, ответ ИИ или сгенерированное содержимое документа).
• uploadFile — пользователь отправляет файл в приложение (например, файл, присоединенный к запросу на обработку).
• downloadFile — файл, возвращенный приложением пользователю (например, файл, созданный ИИ или экспортированный бизнес-приложением).

Дополнительные сведения о действиях пользователей см. в разделе "Значения 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 пуста: Политики не применяются к пользователю для действия пользователя. Если к этому пользователю не применяется ни одна политика для данного действия, мы рекомендуем вызвать Content activity для регистрации действий в целях аудита соответствия требованиям и обнаружения аномалий. Этот параметр можно настроить в приложении.

Если коллекция policyUserScopes содержит области: При возврате областей защиты приложение должно разобрать ответ, проверив значения activities и executionMode для каждой области защиты. В предыдущем примере в коллекции policyUserScopes возвращаются 2 области защиты.

executionMode помогает определить, какое ограничение применяется к конкретному пользователю для действия пользователя. В следующем списке показаны допустимые значения для executionMode:

• evaluateOffline: означает, что при вызове processContentможно выполнить асинхронный вызов для оценки содержимого по политике.
• evaluateInline: означает, что основной поток приложения должен быть заблокирован до тех пор, пока не будет получен возврат из processContent.

Дополнительные сведения см. в разделе "Значения executionMode".

activity указывает на действие пользователя, на которое распространяется область защиты. Вы можете обнаружить, что activity повторяется более чем в одной области защиты. Например, обратите внимание, что в предыдущем примере uploadText возвращается в обеих областях защиты. В этой ситуации приложение должно применять более ограничительную область защиты к этому действию пользователя.

В следующем примере показано, как приложение будет анализировать предыдущую возвращенную policyUserScopes коллекцию:

1. Анализируя первую область защиты, мы видим следующие сведения:
   • uploadText (или запросы, отправленные в ИИ) и downloadText (или ответы из ИИ) должны оцениваться в автономном режиме.
2. При анализе второй области защиты мы видим следующие сведения:
   • uploadText (или запросы, отправленные в искусственный интеллект) должны оцениваться непосредственно в тексте.
3. Для любой другой активности пользователя (uploadFile, downloadFileне применяются области защиты к этим действиям пользователей). Рассмотрите возможность вызова действия Content, как описано выше.

Логика, реализуемая приложением для этих различных действий пользователей, выглядит следующим образом:

Шаг 2: Обработка контента

Затем, в зависимости от состояния области защиты пользователя, вашему приложению может потребоваться вызвать processContent.

Как описано выше, при любых действиях пользователя, где executionMode был равен либо evaluateInline, либо evaluateOffline, необходимо вызывать processContent.

При выполнении вызова отправьте значение ETag, которое приложение сохранило в кэше после вызова protectionScopes/compute на шаге 1, чтобы определить, были ли внесены изменения в политики в вашем арендаторе. Вы отправляете значение ETag в заголовке If-None-Match.

Ниже приведен пример вызова 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 содержит свойство protectionScopeState, для которого задано значение modified. modified означает, что политики в арендаторе изменились. Поскольку политики изменились, ваше приложение должно сначала вызвать protectionScopes/compute, чтобы получить новые области защиты для этого пользователя, как описано в шаге 1. Убедитесь, что вы кэшируете новое ETag значение.
2. Так как коллекция policyActions не пуста, приложению нужно перебрать каждый action, чтобы определить, какое действие следует выполнить. В этом примере означает, restrictAccess что приложение должно заблокировать пользователя от запрошенного действия. Если коллекция policyActions в processContentResponse была пуста, ваше приложение продолжило бы выполнение запрошенного действия. Если вы создаете агентов, агент также должен блокировать выполнение перед вызовом другого агента, когда action имеет значение restrictAccess.