Lernprogramm – Verwenden von Microsoft Purview-APIs, um Ihre Richtlinien in Ihren Apps zu nutzen

Alle Apps, einschließlich Unternehmens-KI-Apps, behandeln vertrauliche Daten, die Schutz vor Datenlecks, unbefugtem Zugriff und Complianceverletzungen erfordern. Microsoft Purview Richtlinien helfen Organisationen beim Schutz vertraulicher Informationen. Ihre Apps können in die Microsoft Purview-APIs integriert werden, um sicherzustellen, dass Microsoft Purview Richtlinien den Sicherheitsstatus Ihrer App unterstützen.

Dieser Artikel enthält eine exemplarische Vorgehensweise zum Hinzufügen der Microsoft Purview-APIs zu Ihrer vorhandenen Unternehmens-App, um Ihre Richtlinien zu nutzen. Das in diesem Artikel verwendete Beispiel ist eine GenAI-App, aber dieselben Konzepte können problemlos auf Nicht-KI-Apps angewendet werden. Am Ende dieser Anleitung haben Sie Folgendes verstanden:

• Wann und wie Sie die Purview-APIs für einen bekannten Benutzer für eine Aktivität aufrufen, die sie in Ihrer App ausführen.
• Bewerten Sie Nutzereingaben und App-Ausgaben (z. B. Eingabeaufforderungen und KI-Antworten oder von Nutzern eingereichte Texte und generierte Inhalte) anhand dieser Richtlinien.
• Erzwingen Sie Richtlinienaktionen in Ihrer App, z. B. blockieren oder mit Richtlinienänderungen in Ihrem Mandanten auf dem laufenden halten.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

• Ein Azure-Abonnement, in dem Microsoft Purview konfiguriert ist.

• Eine anwendung, die in Microsoft Entra ID mit den entsprechenden Berechtigungen registriert ist.

• Grundlegende Vertrautheit mit Microsoft Graph-API-Aufrufen.

• Zugriff auf die Benutzereingaben und App-Ausgaben, die Sie auswerten möchten (z. B. Aufforderungen und Antworten in einer GenAI-App oder von einer Branchen-App hochgeladenen/heruntergeladenen Text).

• Erstellen Sie richtlinien für End-to-End-Tests in Ihrer Microsoft Purview-Portal. Weitere Informationen zu den verfügbaren Richtlinien finden Sie unter Verwenden von Microsoft Purview zum Verwalten von Datensicherheit und Compliance für Entra-registrierte KI-Apps.

  Important

  Um eine DLP-Richtlinie zu erstellen, die für Ihre entra-registrierte App gilt, müssen Sie das New-DlpComplianceRule PowerShell-Cmdlet verwenden. Die Microsoft Purview-Portal unterstützt derzeit nicht das Erstellen von DLP-Richtlinien für entra-registrierte Anwendungen. Weitere Informationen finden Sie unter "New-DlpComplianceRule".

Erste Schritte mit Microsoft Graph

Wenn Sie mit der Verwendung von Microsoft Graph völlig neu sind, lesen Sie Microsoft Graph Grundlagen.

Die folgenden Schritte helfen Ihnen beim Experimentieren mit der API. Führen Sie diese Schritte nicht aus, um eine Produktionsbereitstellung Ihrer Anwendung zu planen.

1. Erfahren Sie mehr über die Microsoft Purview-APIs in Microsoft Graph zur Integration in Ihre App. Diese APIs werden weiter unten in diesem Artikel ausführlich beschrieben.

2. Lassen Sie Ihren Entra-Administrator Ihre App in Entra registrieren. Je nach Richtlinie Ihres Unternehmens kann es sein, dass Sie eine App registrieren dürfen, oder dass Sie einen Registrierungsprozess durchlaufen müssen. Wenden Sie sich an Ihren Entra-Administrator, um den Prozess zu verstehen, dem Sie für Ihren Mandanten folgen müssen. Weitere Informationen finden Sie in den folgenden Ressourcen:

   • Registrieren einer Anwendung bei der Microsoft Identity Platform.
   • Microsoft Identity Platform Codebeispiele für Authentifizierung und Autorisierung.
   • Microsoft Graph Authentifizierungs- und Autorisierungsübersicht.
   • Einrichten von Anwendungen im Microsoft Entra ID Ökosystem.
   • Microsoft Entra ID Leitfaden für unabhängige Softwareentwickler.

3. Konfigurieren Sie Ihre App mit den erforderlichen Berechtigungen. Stellen Sie sicher, dass Ihre App diese Berechtigungen anfordert, wenn sie das Token von Microsoft Graph anfordert. Sie können Ihrer App beispielsweise die Berechtigungen Content.Process.User und ProtectionScopes.Compute.User zuweisen. Weitere Informationen finden Sie unter Microsoft Graph Berechtigungsreferenz und Autorisieren von Anwendungen, Ressourcen und Workloads mit Microsoft Entra ID.

4. Lassen Sie Ihren Mandantenadministrator Microsoft Purview Richtlinien und Einstellungen konfigurieren. Weitere Informationen finden Sie unter Konfigurieren von Microsoft-Purview-Lösungen in Data Security Posture Management (DSPM) für KI für benutzerdefinierte KI-Anwendungen. Ihr Administrator muss das New-DlpComplianceRule PowerShell-Cmdlet verwenden, um DLP-Richtlinien für Ihre entra-registrierten Apps zu erstellen. Dieses Szenario wird vom Microsoft Purview-Portal nicht unterstützt.

5. Testen Sie Ihre App. Weitere Informationen finden Sie unter Testen einer KI-Anwendung mithilfe der Purview-API.

Übersicht über die Microsoft Purview-API-Integration

Ihre Anwendung führt zwei wichtige API-Aufrufe aus, um Ihre Microsoft Purview-Richtlinien zu unterstützen:

1. Compute protection scopes: Bestimmt, welche Benutzeraktivitäten (uploadText, downloadText, uploadFile, downloadFile) eine Richtlinienauswertung für einen bestimmten Benutzer erfordern.
2. Process content: Ihre App sendet eine Inhaltsaktivität für die Richtlinienauswertung und gibt Richtlinienaktionen zurück, die Ihre App erzwingen muss (z. B. Blockieren oder Erkennen von Richtlinienänderungen).

In den folgenden Abschnitten finden Sie schrittweise Anleitungen zur Implementierung, einschließlich Codebeispielen und der Behandlung von Antworten.

Eine ausführliche exemplarische Vorgehensweise für eine Demo-App, die diese API-Aufrufe vorgibt, finden Sie im Video Microsoft Reaktor.

Schritt 1: Berechnen von Schutzbereichen für den Benutzer

Der erste Schritt besteht darin, zu identifizieren, welche Richtlinien und Einschränkungen für einen bestimmten Benutzer gelten, basierend auf den Aktivitäten, die sie in Ihrer Anwendung ausführen können (z. B. Hochladen von Texteingaben/Eingabeaufforderungen oder Herunterladen von KI-Antworten). Dies wird als Berechnung des Schutzumfangs des Benutzers bezeichnet.

Schutzbereiche sind eine Abstraktion von Richtlinien im Mandanten, die für den Benutzer gelten. Für jeden gegebenen Benutzer und jede Aktivität, die der Benutzer in Ihrer App ausführt, möchten Sie den Schutzbereich berechnen. Der Schutzumfang gibt an, welche Aktion die App als Nächstes ausführen soll: auswerten und blockieren, auswerten, aber nicht blockieren, oder keine Auswertung erforderlich.

Hier ist ein Beispiel für eine Anforderung an 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"
      }
   ]
}

Im vorherigen Aufruf zum Berechnen des Schutzbereichs müssen Sie die Benutzeraktivitäten einschließen, die der Benutzer in Ihrer App ausführt. Zu den akzeptierten Benutzeraktivitäten gehören:

• uploadText – Benutzer senden Texteingaben an die App (z. B. eine Aufforderung, die an eine KI gesendet wurde, eine Nachricht in einer Chat-App oder Text, der in ein Formular eingefügt wurde).
• downloadText – textbasierte Ausgabe, die die App an den Benutzer zurückgibt (z. B. eine KI-Antwort oder ein generierter Dokumenttext).
• uploadFile – Der Benutzer sendet eine Datei an die App (z. B. eine Datei, die an eine Aufforderung zur Verarbeitung angefügt ist).
• downloadFile - eine Datei, die von der App an den Benutzer zurückgegeben wird (z. B. eine Datei, die von KI generiert oder von einer Branchen-App exportiert wurde).

Weitere Informationen zu Benutzeraktivitäten finden Sie unter userActivityTypes-Werte.

Der Aufruf zum Berechnen der Schutzbereiche gibt eine Sammlung von policyUserScopes zurück. Hier ist ein Beispiel für eine Antwort mit 2 Schutzbereichen.

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

Es ist wichtig, dass Ihre App diese Antwort analysiert, um zu bestimmen, uploadTextwelche Benutzeraktivität (z. B. ) eine Richtlinienauswertung für die vom Benutzer übermittelten oder an den Benutzer gesendeten Inhalte erfordert.

Wenn die zurückgegebene policyUserScopes-Auflistung leer ist: Für die Benutzeraktivität gelten keine Richtlinien. Wenn für diesen Benutzer keine Richtlinien für diese Aktivität gelten, empfehlen wir, Inhaltsaktivitäten zum Protokollieren von Aktivitäten für die Compliance und Anomalieerkennung aufzurufen. Sie können dies zu einer konfigurierbaren Einstellung in Ihrer App machen.

Wenn die policyUserScopes-Sammlung Bereiche enthält: Wenn Schutzbereiche zurückgegeben werden, muss Ihre App die Antwort analysieren, indem sie für jeden Schutzbereich die Werte von activities und executionMode überprüft. Im vorherigen Beispiel werden 2 Schutzbereiche in der Sammlung policyUserScopes zurückgegeben.

executionMode hilft Ihnen zu bestimmen, welche Einschränkung für einen bestimmten Benutzer für eine Benutzeraktivität gilt. Die folgende Liste zeigt die gültigen Werte für executionMode:

• evaluateOffline: bedeutet, dass Sie beim Aufrufen processContenteinen asynchronen Aufruf ausführen können, um den Inhalt anhand einer Richtlinie auszuwerten.
• evaluateInline: bedeutet, dass der Hauptthread Ihrer App blockieren muss, bis der Aufruf von processContent zurückkehrt.

Weitere Informationen finden Sie unter executionMode-Werte.

Dies activity gibt die Benutzeraktivität an, auf die der Schutzbereich angewendet wird. Möglicherweise stellen Sie fest, dass ein activity Vorgang in mehr als 1 Schutzbereich wiederholt wird. Beachten Sie beispielsweise im vorherigen Beispiel, dass uploadText in beiden Schutzbereichen zurückgegeben wird. In diesem Fall muss Ihre App den restriktiveren Schutzbereich auf diese Benutzeraktivität anwenden.

Das folgende Beispiel zeigt, wie Ihre App die vorherige zurückgegebene policyUserScopes Sammlung analysiert:

1. Durch die Analyse des ersten Schutzbereichs werden die folgenden Informationen angezeigt:
   • uploadText (oder Aufforderungen, die an die KI gesendet werden) und downloadText (oder Antworten von KI) müssen offline ausgewertet werden.
2. Beim Analysieren des zweiten Schutzbereichs werden die folgenden Informationen angezeigt:
   • uploadText (oder an die KI gesendete Prompts) müssen direkt im Text ausgewertet werden.
3. Für alle anderen Benutzeraktivitäten (uploadFile, downloadFile), gelten keine Schutzbereiche für diese Benutzeraktivitäten. Erwägen Sie das Aufrufen von Inhaltsaktivitäten wie zuvor beschrieben.

Die Logik, die Ihre App für diese verschiedenen Benutzeraktivitäten implementieren muss, sind wie folgt:

Schritt 2: Verarbeiten von Inhalten

Als Nächstes muss Ihre App abhängig vom Status des Schutzbereichs des Benutzers möglicherweise processContent aufrufen.

Wie bereits beschrieben, müssen alle Benutzeraktivitäten, bei denen executionMode entweder evaluateInline oder evaluateOffline war, processContent aufrufen.

Wenn Sie den Aufruf tätigen, senden Sie den ETag-Wert, den Ihre App beim Aufruf von protectionScopes/compute in Schritt 1 zwischengespeichert hat, um zu ermitteln, ob Änderungen an Richtlinien in Ihrem Mandanten vorgenommen wurden. Sie senden den Wert ETag im If-None-Match-Header.

Hier ist ein Beispiel für einen Aufruf von 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" 
       }
    }
}

Hier ist ein Beispiel für eine Antwort von 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": []
}

Im vorherigen Beispiel gibt es zwei Aktionen, die Ihre App ausführen muss:

1. Das processContentResponse enthält die Eigenschaft protectionScopeState, die auf modified festgelegt ist. modified zeigt an, dass sich die Richtlinien im Mandanten geändert haben. Da sich die Richtlinien geändert haben, muss Ihre App zuerst aufrufen protectionScopes/compute , um die neuen Schutzbereiche für diesen Benutzer abzurufen, die in Schritt 1 beschrieben werden. Stellen Sie sicher, dass Sie den neuen ETag Wert zwischenspeichern.
2. Da die policyActions Sammlung nicht leer ist, muss Ihre App die einzelnen action Schritte durchlaufen, um die entsprechende Aktion zu ermitteln, die sie ausführen muss. In diesem Beispiel bedeutet dies, restrictAccess dass Ihre App den Benutzer von der angeforderten Aktion blockieren muss. Wenn die Sammlung in der policyActionsprocessContentResponse Datei leer war, würde Ihre App mit der angeforderten Aktivität fortfahren. Wenn Sie Agenten erstellen, muss der Agent auch blockieren, bevor ein anderer Agent aufgerufen wird, wenn die Einstellung action auf restrictAccess gesetzt ist.