Ricevere eventi di modifica dell'API Microsoft Graph tramite Griglia di eventi di Azure

L'API Microsoft Graph fornisce notifiche di modifica per le risorse nei servizi di Microsoft 365, tra cui MICROSOFT Entra ID, Teams, Outlook e OneDrive. Iscrivendoti a questi eventi tramite Griglia di eventi di Azure, puoi costruire applicazioni orientate agli eventi che rispondono ai cambiamenti delle risorse in tempo reale.

Questo articolo spiega come:

  • Creare sottoscrizioni dell'API Microsoft Graph che inviano eventi agli argomenti partner di Griglia di eventi di Azure.
  • Gestire i cicli di vita delle sottoscrizioni con il rinnovo automatico.
  • Instradate gli eventi verso più destinazioni utilizzando le capacità di filtraggio e instradamento di Event Grid.

Griglia di eventi di Azure offre diversi vantaggi rispetto alle tradizionali sottoscrizioni dell'API Microsoft Graph basate sul webhook:

  • Routing semplificato: usare una singola sottoscrizione dell'API Graph per inviare eventi a più destinazioni.
  • Filtro avanzato: instradare tipi di evento specifici a applicazioni diverse in base alle proprietà degli eventi.
  • Conformità agli standard: ricevere eventi in formato CloudEvents per una migliore interoperabilità.
  • Affidabilità: la logica di ripetizione dei tentativi predefinita e le code di messaggi non recapitabili garantiscono un recapito affidabile degli eventi.

Fonti eventi supportate

La tabella seguente elenca le sorgenti di eventi per cui puoi ottenere eventi tramite API Graph. Per la maggior parte delle risorse, API Graph supporta eventi che ne annunciano la creazione, l'aggiornamento e la cancellazione. Per informazioni dettagliate sulle risorse che generano eventi per le sorgenti degli eventi, consulta le notifiche di modifica delle risorse supportate da Microsoft API Graph.

Origine evento Microsoft Risorse Tipi di evento disponibili
Microsoft Entra ID Utente, Gruppo Tipi di evento Microsoft Entra ID
Microsoft Outlook Evento (riunione del calendario), Messaggio (e-mail), Contatto Tipi di evento Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (riunione) Tipi di evento Microsoft Teams
OneDrive DriveItem Eventi di Microsoft OneDrive
Microsoft SharePoint Elenco Eventi di Microsoft SharePoint
Attività da svolgere Attività To Do Eventi di Microsoft ToDo
Avvisi di sicurezza avviso Eventi di avviso di sicurezza Microsoft
Stampa nel cloud Stampante, Definizione attività di stampa Eventi di Stampa Microsoft Cloud
Conversazioni Microsoft Conversazione Eventi di conversazione di gruppo di Microsoft 365

Creare una sottoscrizione dell'API Microsoft Graph per consentire agli eventi dell'API Graph di passare a un argomento partner. API Graph crea automaticamente l'argomento partner quando crei l'abbonamento. Usare l'argomento del partner per creare sottoscrizioni di eventi per inviare gli eventi a uno dei gestori eventi supportati che meglio rispondono ai tuoi requisiti per l'elaborazione degli eventi.

Importante

Se non si ha familiarità con la funzionalità Eventi partner , vedere Panoramica degli eventi dei partner.

Perché abbonarsi agli eventi dalle fonti Microsoft API Graph tramite Event Grid?

Oltre ad abbonarsi agli eventi Microsoft API Graph tramite Event Grid, hai altre opzioni per ricevere notifiche simili (non eventi). Usare l'API Microsoft Graph per recapitare eventi a Griglia di eventi se si soddisfa almeno uno di questi requisiti:

  • Si sta sviluppando una soluzione basata su eventi che usa eventi di Microsoft Entra ID, Outlook o Teams per reagire alle modifiche delle risorse. È necessario il modello affidabile basato su eventi e le funzionalità di pubblicazione-sottoscrizione fornite da Griglia di eventi. Per una panoramica di Griglia di eventi, vedi Concetti relativi a Griglia di eventi.
  • Vuoi usare Event Grid per instradare eventi verso più destinazioni usando un singolo abbonamento API Graph, e vuoi evitare di gestire più abbonamenti API Graph.
  • È necessario instradare gli eventi a diverse applicazioni downstream, webhook o servizi di Azure in base ad alcune proprietà nell'evento. Ad esempio, vuoi poter instradare tipi di evento come Microsoft.Graph.UserUpdated e Microsoft.Graph.UserDeleted verso un'applicazione specializzata che elabora l'onboarding e l'off-onboarding degli utenti. Potresti anche voler inviare eventi Microsoft.Graph.UserUpdated a un'altra applicazione che sincronizza le informazioni sui contatti, ad esempio. Puoi ottenere questo risultato utilizzando un singolo abbonamento API Graph quando usi Event Grid come destinazione di notifica. Per altre informazioni, vedi Filtro eventi e gestori degli eventi.
  • L'interoperabilità è importante per te. Vuoi inoltrare e gestire gli eventi in modo standard utilizzando lo standard di specifica CloudEvents della Cloud Native Computing Foundation (CNCF).
  • Apprezzi il supporto all'espandibilità fornito da CloudEvents. Ad esempio, per tracciare gli eventi tra sistemi conformi, usare l'estensione CloudEvents Distributed Tracing. Altre informazioni sulle estensioni CloudEvents.
  • Utilizzi approcci comprovati e basati sugli eventi che il settore adotta.

Abilitare eventi API Graph per passare all'argomento partner

Richiedere all'API Microsoft Graph di inoltrare gli eventi a un argomento partner di Griglia di eventi creando una sottoscrizione dell'API Graph usando Microsoft API Graph Software Development Kit (SDK) e seguendo i passaggi descritti nei collegamenti agli esempi forniti in questa sezione. Vedi Linguaggi supportati per l’SDK dell’API Microsoft Graph per il supporto SDK disponibile.

Prerequisiti generali

Prima di implementare la tua applicazione per creare e rinnovare gli abbonamenti Microsoft API Graph, assicurati di soddisfare questi prerequisiti generali:

Gli altri prerequisiti specifici per il linguaggio di programmazione scelto e l'ambiente di sviluppo usato sono indicati nei collegamenti agli esempi dell'API Microsoft Graph che si trovano in una delle sezioni successive.

Importante

Sebbene istruzioni dettagliate per implementare la tua applicazione si trovino nella sezione di esempi con istruzioni dettagliate, leggi tutte le sezioni di questo articolo perché contengono informazioni più importanti relative all'inoltro degli eventi Microsoft API Graph tramite Event Grid.

Come creare una sottoscrizione dell'API Microsoft Graph

Quando crei un abbonamento API Graph, il sistema crea un argomento partner per te. Passi le seguenti informazioni nel parametro notificationUrl per specificare l'argomento partner da creare e associare alla nuova iscrizione API Graph:

  • nome dell'argomento partner
  • Nome del gruppo di risorse per l'argomento partner
  • area (posizione)
  • Sottoscrizione di Azure

Questi esempi di codice illustrano come creare una sottoscrizione dell'API Graph. Includono esempi per la creazione di una sottoscrizione per ricevere eventi da tutti gli utenti in un tenant di Microsoft Entra ID al momento della creazione, dell'aggiornamento o dell'eliminazione.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2026-08-31T00:00:00Z",
    "clientState": "secretClientValue"
}

  • changeType: tipo di modifiche alle risorse per cui desideri ricevere eventi. Valori validi: Updated e Deleted (Created non è supportato da API Graph; consulta la documentazione di API Graph per maggiori dettagli). Puoi specificare uno o più di questi valori separati da virgole.

  • notificationUrl: URI usato per definire l'argomento partner a cui vengono inviati gli eventi. Deve essere conforme al modello seguente: EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>. Per ottenere la posizione (nota anche come regione Azure), nameesegui il az account list-locations comando. Non usare il nome visualizzato di una posizione. Ad esempio, non usare Stati Uniti centro-occidentali. Usare invece westcentralus.

    az account list-locations

  • lifecycleNotificationUrl: un URI usato per definire l'argomento partner a cui microsoft.graph.subscriptionReauthorizationRequired gli eventi vengono inviati. Questo evento segnala all'applicazione che la sottoscrizione dell'API Graph scadrà a breve. L'URI segue lo stesso schema descritto in precedenza da notificationUrl se usi Event Grid come destinazione per gli eventi del ciclo di vita. In tal caso, l'argomento partner deve essere uguale a quello specificato in notificationUrl.

  • resource: la risorsa che genera eventi che annunciano cambiamenti di stato.

  • expirationDateTime: il tempo di scadenza in cui l'abbonamento scade e il flusso degli eventi si interrompe. Deve conformarsi al formato specificato nella Request for Comments (RFC) 3339. Devi specificare un tempo di scadenza che rientri nella durata massima consentita per tipo di risorsa.

  • clientState: usa questa proprietà opzionale per verificare le chiamate all'applicazione del gestore eventi durante la consegna degli eventi. Per altre informazioni, vedi Proprietà delle sottoscrizioni API Graph.

Importante

  • Il nome dell'argomento partner deve essere univoco all'interno di una determinata area di Azure. Ogni combinazione ID applicazione-tenant può creare fino a 10 argomenti partner univoci.

  • Quando sviluppi la soluzione, tieni presente alcuni limiti del servizio delle risorse dell'API Graph.

  • Le sottoscrizioni dell'API Graph esistenti senza una proprietà lifecycleNotificationUrl non ricevono eventi del ciclo di vita. Per aggiungere la lifecycleNotificationUrl proprietà, elimina l'abbonamento esistente e crea un nuovo abbonamento che specifichi la proprietà durante la creazione dell'abbonamento.

Dopo aver creato una sottoscrizione dell'API Graph, sarà disponibile un argomento partner in Azure.

Rinnovare una sottoscrizione dell'API Microsoft Graph

Rinnovare la sottoscrizione dell'API Graph prima della scadenza per evitare di arrestare il flusso di eventi. Per aiutare ad automatizzare il processo di rinnovo, Microsoft API Graph supporta eventi di notifica del ciclo di vita a cui le applicazioni possono abbonarsi. Attualmente, tutti i tipi di risorse Microsoft API Graph supportano l'eventomicrosoft.graph.subscriptionReauthorizationRequired, che viene inviato quando si verificano le seguenti condizioni:

  • Il token di accesso sta per scadere.
  • L'abbonamento API Graph sta per scadere.
  • Un amministratore tenant ha revocato all’app le autorizzazioni per leggere una risorsa.

Se la sottoscrizione dell'API Graph non viene rinnovata dopo la scadenza, creare una nuova sottoscrizione dell'API Graph. Puoi fare riferimento allo stesso argomento partner usato nell'abbonamento scaduto purché sia scaduto per meno di 30 giorni. Se la sottoscrizione dell'API Graph è scaduta da più di 30 giorni, non è possibile riutilizzare l'argomento partner esistente. In questo caso, è necessario specificare il nome di un altro argomento associato. In alternativa, puoi eliminare l'argomento partner esistente e creare un nuovo argomento partner con lo stesso nome durante la creazione della sottoscrizione dell'API Graph.

Come rinnovare una sottoscrizione dell'API Microsoft Graph

Quando la tua applicazione riceve un microsoft.graph.subscriptionReauthorizationRequired evento, dovrebbe rinnovare l'abbonamento alla API Graph:

  1. Se hai fornito un client secret nella proprietà clientState quando hai creato la sottoscrizione API Graph, l'evento include quel client secret. Verifica che il clientState dell'evento corrisponda al valore usato durante la creazione della sottoscrizione dell'API Graph.

  2. Assicurati che l'app disponga di un token di accesso valido per eseguire il passaggio successivo. I prossimi esempi con la sezione delle istruzioni dettagliate forniscono ulteriori informazioni.

  3. Chiamare una delle due API seguenti. Se la chiamata API ha esito positivo, il flusso di notifica delle modifiche riprende.

    • Chiamare l'azione /reauthorize per riautorizzare la sottoscrizione senza estenderne la data di scadenza.

      POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize

    • Eseguire un'azione regolare di "rinnovo" per riautorizzare e rinnovare la sottoscrizione contemporaneamente.

      PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-Type: application/json

{
   "expirationDateTime": "2026-09-30T11:00:00.0000000Z"
}

      Il rinnovo potrebbe fallire se l'app non è più autorizzata ad accedere alla risorsa. L'app potrebbe quindi dover ottenere un nuovo token di accesso per riautorizzare un abbonamento.

I problemi di autorizzazione non sostituiscono la necessità di rinnovare una sottoscrizione prima della scadenza. I cicli di vita dei token di accesso e la scadenza della sottoscrizione non sono la stessa cosa. Il token di accesso potrebbe scadere prima della sottoscrizione. Preparati a riautorizzare regolarmente il tuo endpoint per aggiornare il token di accesso. La riautorizzazione dell'endpoint non rinnova la sottoscrizione. Tuttavia, il rinnovo della sottoscrizione riautorizzare anche l'endpoint.

Quando rinnovi o riautorizzi l'abbonamento API Graph, viene utilizzato lo stesso argomento partner che hai specificato quando hai creato l'abbonamento.

Quando specifichi una nuova data di scadenza, assicurati che sia almeno tre ore dal momento attuale. In caso contrario, l'applicazione potrebbe ricevere eventi microsoft.graph.subscriptionReauthorizationRequired subito dopo il rinnovo.

Per esempi su come riautorizzare il tuo abbonamento API Graph utilizzando una qualsiasi delle lingue supportate, vedi richiesta di riautorizzazione dell'abbonamento.

Per esempi su come rinnovare e riautorizzare il tuo abbonamento API Graph utilizzando una qualsiasi delle lingue supportate, vedi richiesta di aggiornamento di abbonamento.

Esempi con istruzioni dettagliate

La documentazione dell'API Microsoft Graph riporta esempi di codice con le istruzioni per:

  • Configurare l'ambiente di sviluppo con istruzioni specifiche in base al linguaggio usato. Le istruzioni includono anche indicazioni su come ottenere un tenant di Microsoft 365 a scopo di sviluppo.
  • Crea un abbonamento API Graph. Per rinnovare un abbonamento, chiama la API Graph utilizzando i frammenti di codice in Come rinnovare un abbonamento alla API Graph.
  • Ottenere i token di autenticazione da usare quando si chiama l'API Microsoft Graph.

Note

Puoi creare il tuo abbonamento API Graph utilizzando il Microsoft API Graph Explorer. È comunque consigliabile usare gli esempi per altri aspetti importanti della soluzione, come l'autenticazione e la ricezione di eventi.

Gli esempi di applicazioni Web sono disponibili per i linguaggi seguenti:

  • Esempio in C#. Si tratta di un esempio aggiornato che include le indicazioni per creare e rinnovare le sottoscrizioni dell'API Graph e illustra alcuni passaggi per abilitare il flusso di eventi.
  • Esempio Java
  • Node.js esempio.

Importante

È necessario attivare l'argomento partner creato come parte della creazione della sottoscrizione dell'API Graph. È inoltre necessario creare una sottoscrizione di eventi di Griglia di eventi nell’applicazione Web per ricevere eventi. A tale scopo, usa l'URL configurato nell'applicazione Web per ricevere eventi come endpoint webhook nella sottoscrizione di eventi.

Importante

Hai bisogno di codice di esempio per un altro linguaggio o hai domande? Indirizzo di posta elettronica ask-graph-and-grid@microsoft.com.

Contenuti correlati

Per ricevere eventi Microsoft API Graph tramite Event Grid, completare questi due passaggi:

  • Last updated on