Tutorial - Use as APIs do Microsoft Purview para aproveitar as suas políticas nas suas aplicações

Todas as aplicações, incluindo aplicações de IA Empresarial, lidam com dados sensíveis que requerem proteção contra fugas de dados, acessos não autorizados e violações de conformidade. As políticas da Microsoft Purview ajudam as organizações a proteger informações sensíveis. As suas aplicações podem integrar-se com as APIs da Microsoft Purview para garantir que as políticas da Microsoft Purview apoiam a postura de segurança da sua aplicação.

Este artigo apresenta uma explicação de como pode adicionar as APIs Microsoft Purview à sua aplicação empresarial existente para tirar partido das suas políticas. O exemplo usado neste artigo é uma aplicação GenAI, mas os mesmos conceitos podem ser facilmente aplicados a aplicações não relacionadas com IA. No final deste walkthrough, vais perceber:

Quando e como chamar as APIs do Purview para um utilizador conhecido numa atividade que está a realizar na sua aplicação.
Avalie as entradas dos utilizadores e as saídas da aplicação (por exemplo, prompts e respostas de IA, ou qualquer texto e conteúdo gerado pelos utilizadores) em relação a essas políticas.
Implemente ações políticas na sua aplicação, como bloquear ou manter-se atualizado com as modificações da política no seu inquilino.

Note

Use as APIs do Microsoft Purview para enviar dados para o Microsoft Purview e suportar as políticas Purview associadas a esses dados. Não existem APIs disponíveis para extrair dados ou análises do Microsoft Purview.

Pré-requisitos

Antes de começar, certifique-se de que tem:

Uma subscrição do Azure com o Microsoft Purview configurado.
Uma aplicação registada no Microsoft Entra ID com as permissões apropriadas.
Familiaridade básica com chamadas à API do Microsoft Graph.
Acesso às entradas do utilizador e às saídas da aplicação que pretende avaliar (por exemplo, prompts e respostas numa aplicação GenAI, ou texto carregado/descarregado por uma aplicação de linha de negócio).
Para testes de ponta a ponta, crie políticas no seu portal do Microsoft Purview. Para mais informações sobre as políticas disponíveis, consulte Utilizar o Microsoft Purview para gerir a segurança e a conformidade dos dados para aplicações de IA registadas no Entra.

Importante

Para criar uma política DLP que se aplique à sua aplicação registada no Entra, deve usar o New-DlpComplianceRule cmdlet PowerShell. O portal do Microsoft Purview atualmente não suporta a criação de políticas DLP para aplicações registadas no Entra. Para mais informações, consulte New-DLPComplianceRule.

Como começar com o Microsoft Graph

Se és completamente novo no uso do Microsoft Graph, vê o Microsoft Graph Fundamentals.

Os passos seguintes ajudam-no a experimentar a API. Não use estes passos para planear uma implementação em produção da sua aplicação.

Saiba mais sobre as APIs Microsoft Purview no Microsoft Graph para integrar na sua aplicação. Estas APIs são descritas em detalhe mais adiante neste artigo.
Peça ao seu administrador do Entra para registar a sua aplicação no Entra. Dependendo da política da sua empresa, a sua empresa pode permitir-lhe registar uma aplicação ou poderá ter de seguir um processo de registo. Certifique-se de verificar com o administrador do Entra para compreender o processo a seguir para o seu inquilino. Para obter mais informações, consulte os seguintes recursos:
Configure a sua aplicação com as permissões necessárias. Certifique-se de que a sua aplicação pede estas permissões quando solicita o token ao Microsoft Graph. Por exemplo, pode atribuir permissões Content.Process.User e ProtectionScopes.Compute.User à sua aplicação. Para mais informações, consulte a referência de permissões do Microsoft Graph e Autorizar aplicações, recursos e cargas de trabalho com o Microsoft Entra ID.
Peça ao administrador do locatário para configurar as políticas e definições do Microsoft Purview. Para mais informações, consulte Configurar soluções Microsoft Purview em Gestão de Postura de Segurança de Dados (DSPM) para IA em aplicações de IA personalizadas. O seu administrador deve usar o New-DlpComplianceRule cmdlet PowerShell para criar políticas DLP para as suas aplicações registadas no Entra. O portal do Microsoft Purview não suporta este cenário.
Teste a aplicação. Para mais informações, veja Como testar uma aplicação de IA usando a API Purview.

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

A sua aplicação realiza duas chamadas API chave para suportar as suas políticas Microsoft Purview:

Compute protection scopes: Determina quais as atividades do utilizador (uploadText, downloadText, uploadFile, downloadFile) que exigem a avaliação de políticas para um determinado utilizador.
Process content: A sua aplicação envia uma atividade de conteúdo para avaliação de políticas e devolve ações de política que a sua aplicação deve aplicar (como bloquear ou detetar modificações de políticas).

As secções seguintes fornecem orientações passo a passo para a implementação, incluindo exemplos de código e como lidar com respostas.

Para uma explicação detalhada de uma aplicação de demonstração que faz estas chamadas API, veja o vídeo do Microsoft Reactor.

Passo 1: Calcular os escopos de proteção para o utilizador

O primeiro passo é identificar quais as políticas e restrições que se aplicam a um utilizador específico com base nas atividades que pode realizar na sua aplicação (como carregar texto/prompts ou descarregar respostas de IA). Isto chama-se calcular o âmbito de proteção do utilizador.

Os escopos de proteção são uma abstração das políticas do tenant que se aplicam ao utilizador. Para qualquer utilizador e atividade que esse utilizador realize na sua aplicação, deve calcular o âmbito de proteção. O âmbito de proteção indica a ação que a aplicação deve tomar a seguir, que pode ser avaliar e bloquear, avaliar e não bloquear, ou não ser necessária avaliação.

Note

Recomendamos que, imediatamente após a autenticação do utilizador, a sua aplicação chame os escopos de proteção de computação. Para chamar protectionScopes/compute, tem de ter o ID Entra do utilizador.

Se só tiveres o userPrincipalName do utilizador, usa o URL seguinte para recuperar o ID do objeto dele.

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

Aqui está um exemplo de um pedido a 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 âmbito de proteção, deve incluir as atividades que o utilizador está a realizar na sua aplicação. As atividades aceites dos utilizadores incluem:

uploadText - os utilizadores enviam introdução de texto para a aplicação (por exemplo, um prompt enviado para uma IA, uma mensagem numa aplicação de chat ou texto colado num formulário).
downloadText - saída baseada em texto que a aplicação devolve ao utilizador (por exemplo, uma resposta de IA ou o corpo de um documento gerado).
UploadFile - o utilizador submete um ficheiro à aplicação (por exemplo, um ficheiro anexado a um prompt para processamento).
downloadFile - um ficheiro devolvido pela aplicação ao utilizador (por exemplo, um ficheiro gerado por IA ou exportado por uma aplicação de negócio).

Para mais informações sobre as atividades dos utilizadores, consulte valores de userActivityTypes.

A chamada para calcular os âmbitos de proteção devolve uma coleção de policyUserScopes. Aqui está um exemplo de uma resposta com 2 âmbitos 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 a sua aplicação analise esta resposta para determinar qual atividade do utilizador (por exemplo, uploadText) requer uma avaliação de políticas sobre o conteúdo submetido ou enviado ao utilizador.

Se a coleção devolvida policyUserScopes estiver vazia: Nenhuma política se aplica ao utilizador relativamente à atividade do utilizador. Quando não se aplicam políticas a este utilizador para esta atividade, recomendamos chamar a Atividade de Conteúdo para registar atividades para auditoria de conformidade e deteção de anomalias. Podes tornar isto uma configuração configurável na tua aplicação.

Se a coleção policyUserScopes contiver âmbitos: Quando os escopos de proteção são devolvidos, a sua aplicação precisa de analisar a resposta inspecionando os valores de activities e executionMode para cada escopo de proteção. No exemplo anterior, são devolvidos 2 escopos de proteção na coleção policyUserScopes.

executionMode ajuda a determinar que restrição se aplica a um utilizador específico numa atividade do utilizador. A lista seguinte mostra os valores válidos para executionMode:

evaluateOffline: significa que pode efetuar uma chamada assíncrona para avaliar o conteúdo face a uma política quando chamar processContent.
evaluateInline: significa que o thread principal da sua aplicação deve bloquear até que a chamada retorne de processContent.

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

Sugestão

Se protectionScopes/compute sempre retorna âmbitos de proteção com o respetivo executionMode sempre igual a evaluateOffline, verifique se criou a sua política DLP utilizando o cmdlet do PowerShell New-DlpComplianceRule. Confirme que a política está listada e ativada nas políticas de Cobrança do DSPM>. Políticas criadas através da interface de utilizador do portal do Microsoft Purview não se aplicam a aplicações registadas no Entra.

Indica activity a atividade do utilizador a que o âmbito de proteção se aplica. Poderá verificar que um activity está repetido em mais do que um âmbito de proteção. Por exemplo, observe no exemplo anterior que uploadText é devolvido em ambos os escopos de proteção. Nesta situação, a sua aplicação deve aplicar o âmbito de proteção mais restritivo a essa atividade do utilizador.

O exemplo seguinte mostra como a sua aplicação analisaria a coleção devolvida policyUserScopes anteriormente:

Ao analisar o primeiro âmbito de proteção, vemos as seguintes informações:
- uploadText (ou pedidos enviados à IA) e downloadText (ou respostas da IA) devem ser avaliados offline.
Ao analisar o segundo telescópio de proteção, vemos a seguinte informação:
- uploadText (ou os prompts enviados à IA) devem ser avaliados em linha.
Para qualquer uma das outras atividades do utilizador (uploadFile, downloadFile), não se aplicam escopos de proteção a essas atividades do utilizador. Considere chamar a atividade de Conteúdo conforme descrito anteriormente.

A lógica que a sua aplicação deve implementar para estas diferentes atividades do utilizador é a seguinte:

Atividade do utilizador	Ação na sua aplicação
`uploadText`	Bloqueie o tópico principal ao chamar `processContent`.
`downloadText`	Faça uma chamada assíncrona ao ligar `processContent`.

Importante

Armazene o valor de ETag em cache: A chamada para protectionScopes/compute retorna um cabeçalho ETag que representa o estado atual dos escopos de proteção desse utilizador. A sua aplicação deve armazenar este valor em cache e enviá-lo juntamente com todas as chamadas para processContent.

Passo 2: Processar o conteúdo

De seguida, com base no estado do âmbito de proteção do utilizador, a sua aplicação pode precisar de chamar processContent.

Como descrito anteriormente, quaisquer atividades do utilizador em que o executionMode era evaluateInline ou evaluateOffline têm de chamar processContent.

Quando fizer a chamada, envie o valor ETag que a sua aplicação colocou em cache da chamada para protectionScopes/compute no Passo 1 para determinar se foram feitas alterações de política no seu tenant. Você envia o valor ETag no campo de cabeçalho If-None-Match.

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

Note

Diretrizes de implementação de conversas/tópicos:

Se a sua aplicação suportar múltiplas threads ou conversas (por exemplo, threads de chat numa aplicação de IA ou de mensagens), use uma única correlationId para cada thread.
Se mantiveres o contexto da conversa num determinado tópico, incrementa sequenceNumber para cada mensagem de utilizador (por exemplo, usa 0, 1, 2, e assim sucessivamente).

Aqui está um exemplo de 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 a sua aplicação deve tomar:

O processContentResponse contém a protectionScopeState propriedade que é definida como modified. modified indica que as políticas do inquilino mudaram. Como as políticas mudaram, a sua aplicação deve primeiro ligar protectionScopes/compute para obter os novos parâmetros de proteção para esse utilizador, o que é descrito no Passo 1. Certifique-se de que coloca em cache o novo valor ETag.
Como a policyActions coleção não está vazia, a sua aplicação precisa de passar por cada uma action para determinar a ação adequada que deve tomar. Neste exemplo, restrictAccess significa que a sua aplicação deve bloquear o utilizador da ação solicitada. Se a policyActions coleção no processContentResponse estivesse vazia, a tua aplicação continuaria com a atividade solicitada. Se estiver a construir agentes, o agente também deve bloquear antes de chamar outro agente quando o action estiver definido como restrictAccess.

Importante

Se já passaram 60 minutos desde a sua última chamada para processContent, recomendamos que ligue para os Compute Protection Scopes para detetar se alguma alteração de política feita no tenant se aplica agora ao utilizador. Se houver uma alteração que passe a aplicar-se ao utilizador, a chamada a protectionScopes/compute devolve um novo valor ETag, que deve ser colocado em cache na sua aplicação e utilizado ao chamar processContent.

Last updated on 2026-07-02

Tutorial - Use as APIs do Microsoft Purview para aproveitar as suas políticas nas suas aplicações

Pré-requisitos

Como começar com o Microsoft Graph

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

Passo 1: Calcular os escopos de proteção para o utilizador

Passo 2: Processar o conteúdo

Recursos adicionais