Condividi tramite

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

  • Articolo

Questo articolo descrive la procedura per sottoscrivere gli eventi pubblicati dall'API Microsoft Graph. La tabella seguente elenca le origini eventi per le quali gli eventi sono disponibili tramite l'API Graph. Per la maggior parte delle risorse, sono supportati gli eventi che ne annunciano la creazione, l'aggiornamento e l'eliminazione. Per informazioni dettagliate sulle risorse per cui vengono generati eventi per le origini eventi, vedi Risorse supportate dalle notifiche di modifica dell'API Microsoft Graph.

Origine evento Microsoft Risorse Tipi di evento disponibili
Microsoft Entra ID Utente, Gruppo Tipi di evento Microsoft Entra
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à Attività To Do Eventi di Microsoft ToDo
Avvisi di sicurezza Alert 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

Si crea una sottoscrizione dell'API Microsoft Graph per consentire agli eventi API Graph di passare a un argomento partner. L'argomento partner viene creato automaticamente durante la creazione della sottoscrizione dell'API Graph. Si usa l'argomento partner per creare sottoscrizioni di evento per inviare gli eventi a uno dei gestori eventi supportati che soddisfano meglio i requisiti per elaborare gli eventi.

Importante

Se non hai familiarità con la funzionalità Eventi partner, vedi Panoramica eventi partner.

Perché è consigliabile sottoscrivere eventi di origini dell'API Microsoft Graph tramite Griglia di eventi?

Oltre alla possibilità di sottoscrivere gli eventi dell'API Microsoft Graph tramite Griglia di eventi, hai a disposizione altre opzioni tramite cui ricevere notifiche simili (non eventi). Valuta l’uso dell'API Microsoft Graph per recapitare eventi a Griglia di eventi se possiedi almeno uno dei requisiti seguenti:

  • Stai sviluppando una soluzione guidata dagli eventi che richiede eventi di Microsoft Entra ID, Outlook, Teams e così via 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 Griglia di eventi per instradare gli eventi verso più destinazioni usando una singola sottoscrizione API Graph ed evitare di gestire più sottoscrizioni API Graph.
  • Hai bisogno di instradare gli eventi verso applicazioni downstream diverse, webhook o servizi di Azure a seconda di alcune delle proprietà dell'evento. Ad esempio, vuoi poter instradare tipi di evento come Microsoft.Graph.UserCreated 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 usando una singola sottoscrizione API Graph quando usi Griglia di eventi 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 usando lo standard delle specifiche Cloud Native Computing Foundation (CNCF) CloudEvents.
  • Ti piace il supporto dell'estendibilità fornito da CloudEvents. Ad esempio, vuoi tracciare eventi su più sistemi conformi e usare l'estensione CloudEvents Traccia distribuita. Altre informazioni sulle estensioni CloudEvents.
  • Vuoi usare gli approcci comprovati guidati dagli eventi adottati dal settore.

Abilitare eventi API Graph per passare all'argomento partner

Richiedi all'API Microsoft Graph di inoltrare gli eventi a un argomento partner di Griglia di eventi creando una sottoscrizione API Graph usando gli SDK (Software Development Kit) dell'API Microsoft Graph e seguendo la procedura disponibile 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

È necessario soddisfare questi prerequisiti generali per poter implementare l'applicazione e creare e rinnovare le sottoscrizioni dell'API Microsoft Graph:

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

Anche se le istruzioni dettagliate per implementare l'applicazione sono disponibili nella sezione degli esempi con istruzioni dettagliate, è consigliabile leggere tutte le sezioni di questo articolo in quanto contengono importanti informazioni aggiuntive in merito all'inoltro di eventi dell'API Microsoft Graph tramite Griglia di eventi.

Come creare una sottoscrizione dell'API Microsoft Graph

Quando crei una sottoscrizione dell'API Graph, viene creato automaticamente un argomento partner. Passi le informazioni seguenti nel parametro notificationUrl per specificare l'argomento partner da creare e associare alla nuova sottoscrizione dell'API Graph:

  • nome dell'argomento partner
  • nome del gruppo di risorse in cui viene creato l'argomento partner
  • area (posizione)
  • Sottoscrizione di Azure

Questi codici di esempio illustrano come creare una sottoscrizione dell'API Graph. Riportano esempi utili per la creazione di una sottoscrizione grazie alla quale ricevere eventi da tutti gli utenti di un tenant di Microsoft Entra ID quando questi vengono creati, aggiornati o eliminati.

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

{
    "changeType": "Updated,Deleted,Created",
    "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": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType: tipo di modifiche alle risorse per cui desideri ricevere eventi. Valori validi: Updated, Deleted e Created. 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>. La posizione (nota anche come area di Azure) name può essere ottenuta eseguendo il comando az account list-locations. Non usare il nome visualizzato di una posizione. Ad esempio, non usare Stati Uniti centro-occidentali. Utilizzare invece westcentralus. 
      az account list-locations
  • lifecycleNotificationUrl: URI usato per definire l'argomento partner a cui microsoft.graph.subscriptionReauthorizationRequiredvengono inviati gli eventi. Questo evento segnala all'applicazione che la sottoscrizione dell'API Graph scadrà a breve. L'URI segue lo stesso modello di notificationUrl descritto in precedenza, se si usa Griglia di eventi come destinazione per gli eventi del ciclo di vita. In tal caso, l'argomento partner deve essere uguale a quello specificato in notificationUrl.
  • risorsa: la risorsa che genera eventi che annunciano modifiche dello stato.
  • expirationDateTime: l'ora di scadenza in cui scade la sottoscrizione e in cui il flusso degli eventi si arresta. Deve essere conforme al formato specificato nella Richiesta di modifica (RFC) 3339. È necessario specificare un'ora di scadenza che rientri nella lunghezza massima consentita per ogni tipo di risorsa.
  • stato client. Questa proprietà è facoltativa. Viene usato per la verifica delle chiamate all'applicazione del gestore dell’evento durante il recapito 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 proprietà lifecycleNotificationUrl, è necessario eliminare la sottoscrizione esistente e creare una nuova sottoscrizione specificando la proprietà durante la creazione della sottoscrizione.

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

Rinnovare una sottoscrizione dell'API Microsoft Graph

L'applicazione deve rinnovare la sottoscrizione dell'API Graph prima della scadenza per evitare che si arresti il flusso di eventi. Per consentirti di automatizzare il processo di rinnovo, l'API Microsoft Graph supporta gli eventi di notifiche del ciclo di vita a cui l'applicazione può sottoscriversi. Attualmente, tutti i tipi di risorse dell'API Microsoft Graph supportano microsoft.graph.subscriptionReauthorizationRequired, il cui invio avviene quando si verifica una delle condizioni seguenti:

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

Non hai rinnovato la sottoscrizione dell'API Graph dopo la scadenza, ed è necessario creare una nuova sottoscrizione dell'API Graph. Puoi fare riferimento allo stesso argomento partner usato nella sottoscrizione scaduta, purché sia scaduta da 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 un altro nome argomento partner. 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

Dopo aver ricevuto un evento microsoft.graph.subscriptionReauthorizationRequired, l'applicazione deve rinnovare la sottoscrizione dell'API Graph eseguendo queste azioni:

  1. Se hai specificato un segreto client nella proprietà clientState quando hai creato la sottoscrizione dell'API Graph, tale segreto client sarà incluso nell'evento. 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. Per altre informazioni, vedi la sezione relativa agli esempi disponibili con istruzioni dettagliate.

  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": "2024-04-30T11:00:00.0000000Z"
}

      Il rinnovo potrebbe non andare a buon fine se l'app non è più autorizzata ad accedere alla risorsa. Per riautorizzare correttamente una sottoscrizione potrebbe quindi essere necessario che l'app ottenga un nuovo token di accesso.

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. È importante prepararsi a riautorizzare regolarmente l'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 si rinnova e/o si riautorizzare la sottoscrizione dell'API Graph, viene usato lo stesso argomento partner specificato al momento della creazione della sottoscrizione.

Quando si specifica una nuova expirationDateTime, deve essere almeno di tre ore successive dall'ora corrente. In caso contrario, l'applicazione potrebbe ricevere eventi microsoft.graph.subscriptionReauthorizationRequired subito dopo il rinnovo.

Per vedere esempi su come riautorizzare la sottoscrizione dell'API Graph usando uno dei linguaggi supportati, vedi Richiesta di riautorizzazione sottoscrizione.

Per vedere esempi su come rinnovare e riautorizzare la sottoscrizione dell'API Graph usando uno dei linguaggi supportati, vedi Richiesta di aggiornamento sottoscrizione.

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.
  • Creare sottoscrizioni dell'API Graph. Per rinnovare una sottoscrizione, puoi chiamare l'API Graph usando i frammenti di codice in Come rinnovare una sottoscrizione dell'API Graph.
  • Ottenere i token di autenticazione da usare quando si chiama l'API Microsoft Graph.

Nota

È possibile creare la sottoscrizione dell'API Graph usando Microsoft Graph API 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
  • Esempio NodeJS.

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. Passaggi successivi per altre informazioni.

Importante

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

Passaggi successivi

Segui le istruzioni nei due passaggi seguenti per completare la configurazione e ricevere eventi dell'API Microsoft Graph tramite Griglia di eventi:

Altri collegamenti utili: