Tutorial – Usar Microsoft Purview APIs para aproveitar suas políticas em seus aplicativos

Todos os aplicativos, incluindo aplicativos de IA Empresarial, lidam com dados confidenciais que exigem proteção contra vazamentos de dados, acesso não autorizado e violações de conformidade. Microsoft Purview políticas ajudam as organizações a proteger informações confidenciais. Seus aplicativos podem se integrar às APIs de Microsoft Purview para garantir que as políticas de Microsoft Purview ofereçam suporte à postura de segurança do aplicativo.

Este artigo fornece um passo a passo de como você pode adicionar as APIs Microsoft Purview ao seu aplicativo empresarial existente para aproveitar suas políticas. O exemplo usado neste artigo é um aplicativo GenAI, mas os mesmos conceitos podem ser facilmente aplicados a aplicativos que não são de IA. No final deste passo a passo, você entenderá:

• Quando e como chamar as APIs do Purview para um usuário conhecido para uma atividade que ele está executando em seu aplicativo.
• Avalie as entradas do usuário e as saídas do aplicativo (por exemplo, prompts e respostas de IA ou qualquer texto enviado pelo usuário e conteúdo gerado) em relação a essas políticas.
• Imponha ações de política em seu aplicativo, como bloqueio ou atualização constante de acordo com as modificações de política em seu locatário.

Pré-requisitos

Antes de começar, verifique se você tem:

• Uma assinatura do Azure com o Microsoft Purview configurado.

• Um aplicativo registrado em Microsoft Entra ID com as permissões apropriadas.

• Familiaridade básica com as chamadas do Microsoft API do Graph.

• Acesso às entradas do usuário e às saídas do aplicativo que você deseja avaliar (por exemplo, comandos e respostas em um aplicativo de GenAI, ou texto carregado/baixado por um aplicativo de negócios).

• Para testes de ponta a ponta, crie políticas em seu portal do Microsoft Purview. Para obter mais informações sobre as políticas disponíveis, consulte Use Microsoft Purview para gerenciar a segurança de dados e a conformidade para aplicativos de IA registrados pela Entra.

  Importante

  Para criar uma política DLP que se aplique ao aplicativo registrado pela Entra, você deve usar o cmdlet do New-DlpComplianceRule PowerShell. O portal do Microsoft Purview atualmente não dá suporte à criação de políticas DLP para aplicativos registrados pela Entra. Para obter mais informações, consulte New-DlpComplianceRule.

Como começar a usar Microsoft Graph

Se você é totalmente novo em usar Microsoft Graph, consulte Microsoft Graph conceitos básicos.

As etapas a seguir ajudam você a experimentar a API. Não use essas etapas para planejar uma implantação de produção do aplicativo.

1. Saiba mais sobre as APIs de Microsoft Purview no Microsoft Graph para integrar ao seu aplicativo. Essas APIs são descritas em detalhes mais adiante neste artigo.

2. Faça com que o administrador do Entra registre seu aplicativo no Entra. Dependendo da política da sua empresa, eles podem permitir que você registre um aplicativo ou talvez seja necessário seguir um processo de registro. Verifique com o administrador do Entra para entender o processo a seguir para seu locatário. Para obter mais informações, consulte os seguintes recursos:

   • Registre um aplicativo na plataforma de identidade da Microsoft.
   • Exemplos de código da plataforma de identidade da Microsoft para autenticação e autorização.
   • Visão geral da autenticação e da autorização no Microsoft Graph.
   • Estabeleça aplicativos no ecossistema Microsoft Entra ID.
   • Guia Microsoft Entra ID para desenvolvedores de software independentes.

3. Configure seu aplicativo com as permissões necessárias. Verifique se o aplicativo solicita essas permissões quando solicita o token de Microsoft Graph. Por exemplo, você pode atribuir as permissões Content.Process.User e ProtectionScopes.Compute.User ao seu aplicativo. Para obter mais informações, consulte referência de permissões do Microsoft Graph e Autorizar aplicativos, recursos e cargas de trabalho com o Microsoft Entra ID.

4. Faça com que o administrador do locatário defina Microsoft Purview políticas e configurações. Para obter mais informações, consulte Configurar soluções de Microsoft Purview no DSPM (Gerenciamento de Postura de Segurança de Dados) para IA para aplicativos de IA personalizados. O administrador deve usar o cmdlet do New-DlpComplianceRule PowerShell para criar políticas DLP para seus aplicativos registrados pela Entra. O portal do Microsoft Purview não dá suporte a esse cenário.

5. Teste seu aplicativo. Para obter mais informações, consulte Como testar um aplicativo de IA usando a API do Purview.

visão geral da integração da API Microsoft Purview

Seu aplicativo executa duas chamadas principais de API para dar suporte às políticas de Microsoft Purview:

1. Compute protection scopes: determina quais atividades do usuário (uploadText, downloadText, uploadFile, downloadFile) exigem avaliação de política para um usuário específico.
2. Process content: seu aplicativo envia uma atividade de conteúdo para avaliação de política e retorna ações de política que seu aplicativo deve impor (como bloquear ou detectar modificações de política).

As seções a seguir fornecem diretrizes de implementação passo a passo, incluindo exemplos de código e como lidar com respostas.

Para obter um passo a passo detalhado de um aplicativo de demonstração que faz essas chamadas à API, consulte o vídeo Microsoft Reactor.

Etapa 1: Calcular os escopos de proteção para o usuário

A primeira etapa é identificar quais políticas e restrições se aplicam a um usuário específico com base nas atividades que podem ser executadas em seu aplicativo (como carregar entradas/prompts de texto ou baixar respostas de IA). Isso é chamado de computação do escopo de proteção do usuário.

Os escopos de proteção são uma abstração das políticas no locatário que se aplicam ao usuário. Para qualquer usuário e atividade que o usuário executa em seu aplicativo, você deseja calcular o escopo de proteção. O escopo de proteção indica a ação que o aplicativo deve executar em seguida: avaliar e bloquear, avaliar e não bloquear ou nenhuma avaliação é necessária.

Aqui está um exemplo de uma solicitação para 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"
      }
   ]
}

Na chamada anterior para calcular o escopo de proteção, você deve incluir as atividades do usuário que o usuário está executando em seu aplicativo. As atividades aceitas do usuário incluem:

• uploadText – os usuários enviam entrada de texto para o aplicativo (por exemplo, um prompt enviado para uma IA, uma mensagem em um aplicativo de chat ou texto colado em um formulário).
• downloadText – saída baseada em texto que o aplicativo retorna ao usuário (por exemplo, uma resposta de IA ou um corpo do documento gerado).
• uploadFile – o usuário envia um arquivo para o aplicativo (por exemplo, um arquivo anexado a um prompt de processamento).
• downloadFile - um arquivo retornado pelo aplicativo para o usuário (por exemplo, um arquivo gerado pela IA ou exportado por um aplicativo de linha de negócios).

Para obter mais informações sobre as atividades do usuário, consulte os valores userActivityTypes.

A chamada para calcular escopos de proteção retorna uma coleção de policyUserScopes. Aqui está um exemplo de uma resposta com dois escopos de proteção.

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": []
    }
  ]
}

É importante que seu aplicativo analise essa resposta para determinar qual atividade do usuário (por exemplo, uploadText) requer avaliação de política sobre o conteúdo enviado pelo usuário ou enviado ao usuário.

Se a coleção policyUserScopes retornada estiver vazia: Nenhuma política se aplica ao usuário para a atividade do usuário. Quando nenhuma política se aplica a esse usuário para essa atividade, recomendamos chamar a atividade de conteúdo para atividades de log para conformidade de auditoria e detecção de anomalias. Você pode fazer disso uma configuração configurável em seu aplicativo.

Se a coleção policyUserScopes contiver escopos: Quando os escopos de proteção forem retornados, seu aplicativo precisará analisar a resposta, inspecionando os valores de activities e executionMode para cada escopo de proteção. No exemplo anterior, dois escopos de proteção são retornados na coleção policyUserScopes.

executionMode ajuda a determinar qual restrição se aplica a um usuário específico para uma atividade de usuário. A lista a seguir mostra os valores válidos para executionMode:

• evaluateOffline: significa que você pode fazer uma chamada assíncrona para avaliar o conteúdo em relação a uma política ao chamar processContent.
• evaluateInline: significa que a thread principal do seu aplicativo deve bloquear até que a chamada retorne de processContent.

Para obter mais informações, consulte valores de executionMode.

Indica activity a atividade do usuário à qual o escopo de proteção se aplica. Você pode perceber que um activity se repete em mais de um escopo de proteção. Por exemplo, observe no exemplo anterior que uploadText é retornado em ambos os escopos de proteção. Nessa situação, seu aplicativo deve aplicar o escopo de proteção mais restritivo a essa atividade de usuário.

O exemplo a seguir mostra como seu aplicativo analisaria a coleção retornada policyUserScopes anterior:

1. Analisando o primeiro escopo de proteção, vemos as seguintes informações:
   • uploadText (ou prompts enviados à IA) e downloadText (ou respostas da IA) devem ser avaliados offline.
2. Ao analisar o segundo escopo de proteção, vemos as seguintes informações:
   • uploadText (ou prompts enviados à IA) devem ser avaliados em linha.
3. Para qualquer uma das outras atividades do usuário (uploadFile, downloadFile), nenhum escopo de proteção se aplica a essas atividades de usuário. Considere chamar a atividade Content conforme descrito anteriormente.

A lógica que seu aplicativo deve implementar para essas diferentes atividades do usuário é a seguinte:

Etapa 2: Processar conteúdo

Em seguida, com base no estado de escopo de proteção do usuário, seu aplicativo pode precisar chamar processContent.

Conforme descrito anteriormente, quaisquer atividades do usuário nas quais o executionMode era evaluateInline ou evaluateOffline devem chamar processContent.

Ao fazer a chamada, envie o valor ETag que seu aplicativo armazenou em cache da chamada para protectionScopes/compute na Etapa 1 para determinar se foram feitas modificações de política em seu locatário. Você envia o valor ETag no cabeçalho If-None-Match.

Aqui está um exemplo de uma chamada para 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" 
       }
    }
}

Aqui está um exemplo de uma resposta de 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": []
}

No exemplo anterior, há duas ações que seu aplicativo deve executar:

1. O processContentResponse contém a propriedade protectionScopeState, que está definida como modified. modified indica que as políticas no locatário foram alteradas. Como as políticas foram alteradas, seu aplicativo deve primeiro chamar protectionScopes/compute para obter os novos escopos de proteção para esse usuário, que é descrito na Etapa 1. Verifique se você armazena em cache o novo ETag valor.
2. Como a coleção policyActions não está vazia, seu aplicativo precisa percorrer cada action para determinar a ação apropriada a ser tomada. Neste exemplo, restrictAccess significa que seu aplicativo deve bloquear o usuário da ação solicitada. Se a coleção policyActions no processContentResponse estivesse vazia, seu aplicativo continuaria com a atividade solicitada. Se você estiver criando agentes, o agente também deverá bloquear antes de chamar outro agente quando action estiver definido como restrictAccess.