Esercitazione: usare le API di Microsoft Purview per sfruttare i criteri nelle tue app

Tutte le app, incluse le app enterprise per intelligenza artificiale, gestiscono i dati sensibili che richiedono la protezione da perdite di dati, accessi non autorizzati e violazioni della conformità. Microsoft Purview criteri consentono alle organizzazioni di proteggere le informazioni riservate. Le app possono integrarsi con le API Microsoft Purview per garantire che i criteri di Microsoft Purview supportino il comportamento di sicurezza dell'app.

Questo articolo fornisce una guida dettagliata su come aggiungere le API di Microsoft Purview all'app aziendale esistente per usare i tuoi criteri. L'esempio usato in questo articolo è un'app GenAI, ma gli stessi concetti possono essere facilmente applicati alle app non di intelligenza artificiale. Al termine di questa procedura dettagliata, si comprenderà quanto segue:

• Quando e come chiamare le API Purview per un utente noto per un'attività eseguita nell'app.
• Valutare gli input utente e gli output dell'app (ad esempio, richieste e risposte di intelligenza artificiale o qualsiasi testo inviato dall'utente e contenuto generato) rispetto a tali criteri.
• Applicare le azioni dei criteri nell'app, ad esempio bloccare o mantenere aggiornate le modifiche ai criteri nel tenant.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Sottoscrizione Azure con Microsoft Purview configurata.

• Un'applicazione registrata in Microsoft Entra ID con le autorizzazioni appropriate.

• Conoscenza di base delle chiamate di Microsoft API Graph.

• Accesso agli input dell'utente e agli output dell'app da valutare(ad esempio, richieste e risposte in un'app GenAI o testo caricato/scaricato da un'app line-of-business).

• Per i test end-to-end, crea criteri nel portale di Microsoft Purview. Per altre informazioni sui criteri disponibili, vedere Usare Microsoft Purview per gestire la sicurezza e la conformità dei dati per le app di intelligenza artificiale registrate con Entra.

  Importante

  Per creare un criterio di prevenzione della perdita dei dati applicabile all'app registrata da Entra, è necessario usare il New-DlpComplianceRule cmdlet di PowerShell. Il Portale di Microsoft Purview attualmente non supporta la creazione di criteri di prevenzione della perdita dei dati per le applicazioni registrate da Entra. Per altre informazioni, vedere New-DlpComplianceRule.

Come iniziare a usare Microsoft Graph

Se non si ha familiarità con l'uso di Microsoft Graph, vedere Microsoft Graph Nozioni fondamentali.

I passaggi seguenti consentono di sperimentare l'API. Non usare questi passaggi per pianificare una distribuzione di produzione dell'applicazione.

1. Informazioni sulle API Microsoft Purview in Microsoft Graph per l'integrazione nell'app. Queste API sono descritte in dettaglio più avanti in questo articolo.

2. Chiedi al tuo amministratore Entra di registrare l'app in Entra. A seconda dei criteri dell'azienda, possono consentire la registrazione di un'app o potrebbe essere necessario seguire un processo di registrazione. Assicurarsi di rivolgersi all'amministratore di Entra per comprendere il processo da seguire per il tenant. Per ulteriori informazioni, vedi le seguenti risorse:

   • Registrare un'applicazione con Microsoft Identity Platform.
   • Microsoft Identity Platform esempi di codice per l'autenticazione e l'autorizzazione.
   • Panoramica dell'autenticazione e dell'autorizzazione di Microsoft Graph.
   • Creare applicazioni nell'ecosistema di Microsoft Entra ID.
   • Microsoft Entra ID Guida per sviluppatori di software indipendenti.

3. Configurare l'app con le autorizzazioni necessarie. Assicurarsi che l'app richieda queste autorizzazioni quando richiede il token da Microsoft Graph. Ad esempio, è possibile assegnare le Content.Process.User autorizzazioni e ProtectionScopes.Compute.User all'app. Per altre informazioni, vedere Informazioni di riferimento sulle autorizzazioni di Microsoft Graph e Autorizzazione di applicazioni, risorse e carichi di lavoro con Microsoft Entra ID.

4. Chiedi all'amministratore del tenant di configurare i criteri e le impostazioni di Microsoft Purview. Per altre informazioni, vedere Configurare Microsoft Purview soluzioni in Gestione del comportamento di sicurezza dei dati (DSPM) per l'intelligenza artificiale per applicazioni di intelligenza artificiale personalizzate. L'amministratore deve usare il New-DlpComplianceRule cmdlet di PowerShell per creare criteri di prevenzione della perdita dei dati per le app registrate da Entra. Il Portale di Microsoft Purview non supporta questo scenario.

5. Testare l'app. Per altre informazioni, vedere Come testare un'applicazione di intelligenza artificiale usando l'API Purview.

Panoramica dell'integrazione dell'API Microsoft Purview

L'applicazione esegue due chiamate API chiave per supportare i criteri di Microsoft Purview:

1. Compute protection scopes: determina quali attività dell'utente (uploadText, downloadText, uploadFile, downloadFile) richiedono una valutazione dei criteri per un utente specifico.
2. Process content: l'app invia un'attività di contenuto per la valutazione dei criteri e restituisce le azioni dei criteri che l'app deve applicare, ad esempio bloccando o rilevando modifiche ai criteri.

Le sezioni seguenti forniscono indicazioni dettagliate sull'implementazione, inclusi esempi di codice e come gestire le risposte.

Per una guida dettagliata a un'app demo che effettua queste chiamate API, consulta il video Microsoft Reactor.

Passaggio 1: Calcolare gli ambiti di protezione per l'utente

Il primo passaggio consiste nell'identificare quali criteri e restrizioni si applicano a un utente specifico in base alle attività che possono eseguire nell'applicazione, ad esempio caricare input/richieste di testo o scaricare risposte di intelligenza artificiale. Questa operazione viene chiamata calcolo dell'ambito di protezione dell'utente.

Gli ambiti di protezione sono un'astrazione dei criteri nel tenant che si applicano all'utente. Per qualsiasi utente e attività specificata eseguita nell'app, si vuole calcolare l'ambito di protezione. L'ambito di protezione indica l'azione che l'app deve eseguire successivamente, che può essere valutata e bloccata, valutata e non bloccata o non è necessaria alcuna valutazione.

Di seguito è riportato un esempio di richiesta 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"
      }
   ]
}

Nella chiamata precedente per calcolare l'ambito di protezione, è necessario includere le attività utente eseguite dall'utente nell'app. Le attività utente accettate includono:

• uploadText: gli utenti inviano input di testo all'app, ad esempio una richiesta inviata a un'intelligenza artificiale, un messaggio in un'app di chat o un testo incollato in un modulo.
• downloadText: output basato su testo che l'app restituisce all'utente (ad esempio, una risposta di intelligenza artificiale o un corpo del documento generato).
• uploadFile: l'utente invia un file all'app, ad esempio un file allegato a una richiesta di elaborazione.
• downloadFile: un file restituito dall'app all'utente, ad esempio un file generato dall'intelligenza artificiale o esportato da un'app line-of-business.

Per altre informazioni sulle attività utente, vedere valori userActivityTypes.

La chiamata per calcolare gli ambiti di protezione restituisce una raccolta di policyUserScopes. Di seguito è riportato un esempio di risposta con 2 ambiti di protezione.

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 che l'app analizzi questa risposta per determinare quale attività utente (ad esempio, uploadText) richiede la valutazione dei criteri sul contenuto inviato dall'utente o inviato all'utente.

Se l'insieme policyUserScopes restituito è vuoto: Nessun criterio si applica all'utente per l'attività utente. Quando non si applicano criteri a questo utente per questa attività, è consigliabile chiamare Attività contenuto per registrare le attività per la conformità di controllo e il rilevamento anomalie. È possibile impostare questa impostazione configurabile nell'app.

Se l'insieme policyUserScopes contiene ambiti: Quando vengono restituiti ambiti di protezione, l'app deve analizzare la risposta controllando i valori di activities e executionMode per ogni ambito di protezione. Nell'esempio precedente vengono restituiti 2 ambiti di protezione nella raccolta policyUserScopes.

executionMode consente di determinare quale restrizione si applica a un determinato utente per un'attività utente. L'elenco seguente mostra i valori validi per executionMode:

• evaluateOffline: significa che è possibile effettuare una chiamata asincrona per valutare il contenuto rispetto a un criterio quando si chiama processContent.
• evaluateInline: indica che il thread principale dell'app deve bloccarsi fino a quando la chiamata non viene restituita da processContent.

Per altre informazioni, vedere i valori di executionMode.

Indica activity l'attività utente a cui si applica l'ambito di protezione. È possibile che un oggetto activity venga ripetuto in più di 1 ambito di protezione. Si noti, ad esempio, nell'esempio precedente, che uploadText viene restituito in entrambi gli ambiti di protezione. In questo caso, l'app deve applicare l'ambito di protezione più restrittivo all'attività dell'utente.

L'esempio seguente mostra come l'app analizzerebbe la raccolta restituita policyUserScopes precedente:

1. Analizzando il primo ambito di protezione, vengono visualizzate le informazioni seguenti:
   • uploadText (o richieste inviate all'intelligenza artificiale) e downloadText (o risposte dall'IA) devono essere valutate offline.
2. Quando si analizza il secondo ambito di protezione, vengono visualizzate le informazioni seguenti:
   • uploadText (o i prompt inviati all'IA) devono essere valutati in linea.
3. Per qualsiasi altra attività utente (uploadFile, downloadFile), nessun ambito di protezione si applica a tali attività utente. Valutare la possibilità di chiamare l'attività Content come descritto in precedenza.

La logica che l'app deve implementare per queste diverse attività utente sono le seguenti:

Passaggio 2: Elaborare il contenuto

Successivamente, in base allo stato dell'ambito di protezione dell'utente, l'app potrebbe dover chiamare processContent.

Come descritto in precedenza, qualsiasi attività dell'utente in cui executionMode è stato evaluateInline o evaluateOffline richiede la chiamata a processContent.

Quando si effettua la chiamata, inviare il valore ETag che l'app ha memorizzato nella cache dalla chiamata a protectionScopes/compute nel passaggio 1 per determinare se sono state apportate modifiche ai criteri nel tenant. Invii il valore ETag nell'intestazione If-None-Match.

Di seguito è riportato un esempio di chiamata a 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" 
       }
    }
}

Di seguito è riportato un esempio di risposta da 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": []
}

Nell'esempio precedente sono necessarie due azioni che l'app deve eseguire:

1. Il processContentResponse contiene la proprietà protectionScopeState, impostata su modified. modified indica che i criteri nel tenant sono stati modificati. Poiché i criteri sono stati modificati, l'app deve prima chiamare protectionScopes/compute per ottenere i nuovi ambiti di protezione per l'utente, descritto nel passaggio 1. Assicurarsi di memorizzare nella cache il nuovo ETag valore.
2. Poiché la raccolta policyActions non è vuota, l'app deve esaminare ciascun action per determinare l'azione appropriata da intraprendere. In questo esempio, restrictAccess significa che l'app deve bloccare l'utente dall'azione richiesta. Se la policyActions raccolta in processContentResponse è vuota, l'app continuerà con l'attività richiesta. Se si creano agenti, l'agente deve anche bloccarsi prima di chiamare un altro agente quando action è impostato su restrictAccess.