Självstudie – Använda Microsoft Purview API:er för att utnyttja dina principer i dina appar

Alla appar, inklusive Enterprise AI-appar, hanterar känsliga data som kräver skydd mot dataläckor, obehörig åtkomst och efterlevnadsöverträdelser. Microsoft Purview principer hjälper organisationer att skydda känslig information. Dina appar kan integreras med Microsoft Purview API:er för att säkerställa att Microsoft Purview principer stöder appens säkerhetsstatus.

Den här artikeln innehåller en genomgång av hur du kan lägga till Microsoft Purview API:er i din befintliga företagsapp för att utnyttja dina principer. Exemplet som används i den här artikeln är en GenAI-app, men samma begrepp kan enkelt tillämpas på appar som inte är AI-appar. I slutet av den här genomgången kommer du att förstå:

• När och hur du anropar Purview-API:er för en känd användare för en aktivitet som de utför i din app.
• Utvärdera användarindata och apputdata (till exempel frågor och AI-svar eller text som skickas av användaren och genererat innehåll) mot dessa principer.
• Tillämpa principåtgärder i din app, till exempel blockering eller att hålla den uppdaterad med principändringar i din klientorganisation.

Förutsättningar

Kontrollera att du har följande innan du börjar:

• En Azure prenumeration med Microsoft Purview konfigurerad.

• Ett program som är registrerat i Microsoft Entra ID med rätt behörigheter.

• Grundläggande kunskaper om Microsoft Graph API-anrop.

• Åtkomst till de användarindata och apputdata som du vill utvärdera (till exempel frågor och svar i en GenAI-app eller text som laddats upp/laddats ned av en verksamhetsspecifik app).

• Skapa principer i Microsoft Purview-portal för testning från slutpunkt till slutpunkt. Mer information om tillgängliga principer finns i Använda Microsoft Purview för att hantera datasäkerhet och efterlevnad för Entra-registrerade AI-appar.

  Important

  Om du vill skapa en DLP-princip som gäller för din Entra-registrerade app måste du använda PowerShell-cmdleten New-DlpComplianceRule . Microsoft Purview-portal stöder för närvarande inte att skapa DLP-principer för Entra-registrerade program. Mer information finns i New-DlpComplianceRule.

Så här kommer du igång med Microsoft Graph

Om du är helt ny på att använda Microsoft Graph kan du läsa Microsoft Graph Grunderna.

Följande steg hjälper dig att experimentera med API:et. Använd inte de här stegen för att planera en produktionsdistribution av ditt program.

1. Lär dig mer om Microsoft Purview API:er i Microsoft Graph för att integrera i din app. Dessa API:er beskrivs i detalj senare i den här artikeln.

2. Låt entra-administratören registrera din app i Entra. Beroende på företagets princip kan du registrera en app eller följa en registreringsprocess. Se till att stämma av med din Entra-administratör för att förstå vilken process du ska följa för din klientorganisation. Mer information finns i följande resurser:

   • Registrera ett program med Microsofts identitetsplattform.
   • Microsofts identitetsplattform – kodexempel för autentisering och auktorisering.
   • Översikt över autentisering och auktorisering i Microsoft Graph.
   • Upprätta program i Microsoft Entra ID ekosystemet.
   • Microsoft Entra ID Guide för oberoende programvaruutvecklare.

3. Konfigurera din app med de behörigheter som krävs. Kontrollera att appen begär dessa behörigheter när den begär token från Microsoft Graph. Du kan till exempel tilldela Content.Process.User och ProtectionScopes.Compute.User behörigheter till din app. Mer information finns i Microsoft Graph behörighetsreferens och Auktorisera program, resurser och arbetsbelastningar med Microsoft Entra ID.

4. Låt klientadministratören konfigurera Microsoft Purview principer och inställningar. Mer information finns i Konfigurera Microsoft Purview lösningar i Data Security Posture Management (DSPM) för AI för anpassade AI-program. Administratören måste använda PowerShell-cmdleten New-DlpComplianceRule för att skapa DLP-principer för dina Entra-registrerade appar. Microsoft Purview-portal stöder inte det här scenariot.

5. Testa din app. Mer information finns i Testa ett AI-program med purview-API:et.

översikt över Microsoft Purview API-integrering

Ditt program utför två viktiga API-anrop för att stödja dina Microsoft Purview principer:

1. Compute protection scopes: Avgör vilka användaraktiviteter (uploadText, downloadText, uploadFile, downloadFile) som kräver principutvärdering för en viss användare.
2. Process content: Din app skickar en innehållsaktivitet för principutvärdering och returnerar principåtgärder som din app måste framtvinga (till exempel blockering eller identifiering av principändringar).

Följande avsnitt innehåller stegvisa implementeringsvägledning, inklusive kodexempel och hur du hanterar svar.

En detaljerad genomgång av en demoapp som gör dessa API-anrop finns i videon Microsoft Reactor.

Steg 1: Beräkna skyddsomfång för användaren

Det första steget är att identifiera vilka principer och begränsningar som gäller för en specifik användare baserat på de aktiviteter som de kan utföra i ditt program (till exempel att ladda upp textindata/uppmaningar eller ladda ned AI-svar). Detta kallas för databehandling av användarens skyddsomfång.

Skyddsomfång är en abstraktion av de policyer i tenanten som gäller för användaren. För en viss användare och aktivitet som användaren utför i din app vill du beräkna skyddsomfånget. Skyddsomfånget anger vilken åtgärd appen ska vidta härnäst, som kan utvärderas och blockeras, utvärderas och inte blockeras eller ingen utvärdering behövs.

Här är ett exempel på en begäran till 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"
      }
   ]
}

I föregående anrop för att beräkna skyddsomfånget måste du inkludera de användaraktiviteter som användaren utför i din app. Godkända användaraktiviteter omfattar:

• uploadText – användare skickar textindata till appen (till exempel en uppmaning som skickas till en AI, ett meddelande i en chattapp eller text som klistras in i ett formulär).
• downloadText – textbaserade utdata som appen returnerar till användaren (till exempel ett AI-svar eller en genererad dokumenttext).
• uploadFile – användaren skickar en fil till appen (till exempel en fil som är kopplad till en uppmaning om bearbetning).
• downloadFile – en fil som returneras av appen till användaren (till exempel en fil som genereras av AI eller exporteras av en verksamhetsspecifik app).

Mer information om användaraktiviteter finns i userActivityTypes-värden.

Anropet för att beräkna skyddsomfång returnerar en samling med policyUserScopes. Här är ett exempel på ett svar med 2 skyddsområden.

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

Det är viktigt att appen parsar det här svaret för att avgöra vilken användaraktivitet (till exempel uploadText) som kräver principutvärdering av innehållet som skickas av eller skickas till användaren.

Om den returnerade policynUserScopes-samlingen är tom: Inga principer gäller för användaren för användaraktiviteten. När inga principer gäller för den här användaren för den här aktiviteten rekommenderar vi att du anropar innehållsaktivitet för att logga aktiviteter för granskningsefterlevnad och avvikelseidentifiering. Du kan göra detta till en konfigurerbar inställning i din app.

Om samlingen policyUserScopes innehåller omfattningar: När skyddsomfattningar returneras måste din app tolka svaret genom att granska värdena för activities och executionMode för varje skyddsomfattning. I föregående exempel returneras 2 skyddsomfång i samlingen policyUserScopes.

executionMode hjälper dig att avgöra vilken begränsning som gäller för en viss användare för en användaraktivitet. I följande lista visas giltiga värden för executionMode:

• evaluateOffline: innebär att du kan göra ett asynkront anrop för att utvärdera innehållet mot en princip när du anropar processContent.
• evaluateInline: innebär att appens huvudtråd måste blockeras tills anropet returneras från processContent.

Mer information finns i executionMode-värden.

activity Anger den användaraktivitet som skyddsomfånget gäller för. Du kanske upptäcker att en activity förekommer i fler än ett skyddsområde. Notera till exempel i det föregående exemplet att uploadText returneras i båda skyddsomfången. I det här fallet måste appen tillämpa det mer restriktiva skyddsomfånget på användaraktiviteten.

I följande exempel visas hur din app parsar den föregående returnerade policyUserScopes samlingen:

1. Genom att parsa det första skyddsomfånget ser vi följande information:
   • uploadText (eller uppmaningar som skickas till AI:n) och downloadText (eller svar från AI) måste utvärderas offline.
2. När vi parsar det andra skyddsomfånget ser vi följande information:
   • uploadText (eller prompter som skickas till AI:t) måste utvärderas direkt i texten.
3. För någon av de andra användaraktiviteterna (uploadFile, downloadFile) gäller inga skyddsomfattningar för dessa användaraktiviteter. Överväg att anropa Content activity så som beskrivits tidigare.

Logiken som appen måste implementera för dessa olika användaraktiviteter är följande:

Steg 2: Bearbeta innehåll

Sedan, baserat på användarens skyddsomfångstillstånd, kan din app behöva anropa processContent.

Som tidigare beskrivits måste alla användaraktiviteter där executionMode antingen var evaluateInline eller evaluateOffline anropa processContent.

När du gör anropet skickar du värdet ETag som appen cachade från anropet till protectionScopes/compute i steg 1 för att avgöra om ändringar i principer har gjorts i klientorganisationen. Du skickar ETag värdet i rubriken If-None-Match .

Här är ett exempel på ett anrop till 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" 
       }
    }
}

Här är ett exempel på ett svar från 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": []
}

I föregående exempel finns det två åtgärder som din app måste vidta:

1. processContentResponse Innehåller egenskapen protectionScopeState som är inställd på modified. modified indikerar att policyerna i klientorganisationen har ändrats. Eftersom principerna har ändrats måste appen först anropa protectionScopes/compute för att hämta de nya skyddsomfattningarna för den användaren, vilket beskrivs i steg 1. Se till att du cachelagr det nya ETag värdet.
2. Eftersom samlingen policyActions inte är tom måste appen gå igenom var och en action för att fastställa vilken åtgärd den måste vidta. I det här exemplet restrictAccess innebär det att appen måste blockera användaren från den begärda åtgärden. Om samlingen policyActions i processContentResponse var tom skulle din app fortsätta med den begärda aktiviteten. Om du bygger agenter måste agenten också blockera innan den anropar en annan agent när action är inställt på restrictAccess.