Microsoft Graph API-wijzigingsevenementen ontvangen via Azure Event Grid

Microsoft Graph API biedt wijzigingsmeldingen voor resources in Microsoft 365-services, waaronder Microsoft Entra ID, Teams, Outlook en OneDrive. Door je te abonneren op deze gebeurtenissen via Azure Event Grid, kun je event-gedreven applicaties bouwen die in realtime reageren op veranderingen in resources.

In dit artikel wordt uitgelegd hoe u:

  • Maak Microsoft Graph API-abonnementen die gebeurtenissen leveren aan azure Event Grid-partneronderwerpen.
  • Beheer de levenscyclus van abonnementen met automatische verlenging.
  • Leid evenementen naar meerdere bestemmingen door gebruik te maken van de filter- en routeringsmogelijkheden van Event Grid.

Azure Event Grid biedt verschillende voordelen ten opzichte van traditionele Microsoft Graph API-abonnementen op basis van webhook:

  • Vereenvoudigde routering: gebruik één Graph API-abonnement om gebeurtenissen naar meerdere bestemmingen te verzenden.
  • Geavanceerd filteren: specifieke gebeurtenistypen routeren naar verschillende toepassingen op basis van gebeurteniseigenschappen.
  • Standaardennaleving: Gebeurtenissen ontvangen in CloudEvents-indeling voor betere interoperabiliteit.
  • Betrouwbaarheid: een ingebouwde herhaallogica en dead-letter queues zorgen voor betrouwbare levering van gebeurtenissen.

Ondersteunde gebeurtenisbronnen

De volgende tabel geeft de gebeurtenisbronnen weer waarvoor je gebeurtenissen kunt verkrijgen via de Graph API. Voor de meeste bronnen ondersteunt de Graph API evenementen die hun aanmaak, update en verwijdering aankondigen. Voor gedetailleerde informatie over de bronnen die gebeurtenissen genereren voor gebeurtenisbronnen, zie ondersteunde bronnen van Microsoft Graph API wijzigingsmeldingen.

Microsoft-gebeurtenisbron Hulpmiddelen Beschikbare gebeurtenistypen
Microsoft Entra ID Gebruiker, groep Gebeurtenistypen voor Microsoft Entra-id
Microsoft Outlook Gebeurtenis (agendavergadering), Bericht (e-mail), Contactpersoon Microsoft Outlook-gebeurtenistypen
Microsoft Teams ChatMessage, CallRecord (vergadering) Microsoft Teams-gebeurtenistypen
OneDrive Schijfelement Microsoft OneDrive-gebeurtenissen
Microsoft SharePoint Lijst Microsoft SharePoint-gebeurtenissen
Te doen Taak uitvoeren Microsoft ToDo-gebeurtenissen
Beveiligingswaarschuwingen Alert Microsoft Beveiliging Alert-gebeurtenissen
Afdrukken in de cloud Printer, afdruktaakdefinitie Microsoft Cloud Printing-gebeurtenissen
Microsoft-gesprekken Gesprek Microsoft 365 Groepsgespreksevenementen

Maak een Microsoft Graph API-abonnement aan om te zorgen dat Graph API-gebeurtenissen naar een partnerthema kunnen stromen. Graph API maakt automatisch het partneronderwerp aan wanneer je het abonnement aanmaakt. Gebruik dat partneronderwerp om gebeurtenisabonnementen te maken om uw gebeurtenissen te verzenden naar een van de ondersteunde gebeurtenis-handlers die het beste voldoen aan uw vereisten om de gebeurtenissen te verwerken.

Belangrijk

Als u niet bekend bent met de functie Partnerevenementen , raadpleegt u het overzicht van partnerevenementen.

Waarom zou je je abonneren op evenementen vanuit Microsoft Graph API-bronnen via Event Grid?

Naast het abonneren op Microsoft Graph API-events via Event Grid, heb je ook andere opties om soortgelijke meldingen te ontvangen (geen gebeurtenissen). Gebruik Microsoft Graph API om gebeurtenissen aan Event Grid te leveren als u voldoet aan ten minste een van deze vereisten:

  • U ontwikkelt een gebeurtenisgestuurde oplossing die gebruikmaakt van gebeurtenissen van Microsoft Entra ID, Outlook of Teams om te reageren op resourcewijzigingen. U hebt het robuuste gebeurtenisgestuurde model nodig en de mogelijkheden voor publiceren/abonneren die Event Grid biedt. Zie Event Grid-concepten voor een overzicht van Event Grid.
  • Je wilt Event Grid gebruiken om evenementen naar meerdere bestemmingen te routeren met één Graph API-abonnement, en je wilt het beheren van meerdere Graph API-abonnementen vermijden.
  • U moet gebeurtenissen routeren naar verschillende downstreamtoepassingen, webhooks of Azure-services op basis van bepaalde eigenschappen in de gebeurtenis. U kunt bijvoorbeeld gebeurtenistypen routeren, zoals Microsoft.Graph.UserUpdated en Microsoft.Graph.UserDeleted, naar een gespecialiseerde toepassing die de onboarding en offboarding van gebruikers verwerkt. Mogelijk wilt u ook gebeurtenissen verzenden Microsoft.Graph.UserUpdated naar een andere toepassing waarmee bijvoorbeeld contactgegevens worden gesynchroniseerd. Je kunt dit bereiken door één Graph API-abonnement te gebruiken wanneer je Event Grid als notificatiebestemming gebruikt. Zie gebeurtenisfilters en gebeurtenis-handlers voor meer informatie.
  • Interoperabiliteit is belangrijk voor u. Je wilt gebeurtenissen op een standaardmanier doorsturen en afhandelen door gebruik te maken van de Cloud Native Computing Foundation (CNCF) CloudEvents-specificatiestandaard .
  • U waardeer de uitbreidbaarheidsondersteuning die CloudEvents biedt. Als u bijvoorbeeld gebeurtenissen in compatibele systemen wilt traceren, gebruikt u de CloudEvents-extensie gedistribueerde tracering. Meer informatie over CloudEvents-extensies.
  • Je gebruikt bewezen, event-gedreven benaderingen die de industrie hanteert.

Graph API-gebeurtenissen inschakelen om naar uw partneronderwerp te stromen

Vraag Microsoft Graph API om gebeurtenissen door te sturen naar een Event Grid-partneronderwerp door een Graph API-abonnement te maken met behulp van de Microsoft Graph API Software Development Kits (SDK's) en de stappen in de koppelingen naar voorbeelden in deze sectie te volgen. Zie Ondersteunde talen voor Microsoft Graph API SDK voor beschikbare SDK-ondersteuning.

Algemene vereisten

Voordat je je applicatie implementeert om Microsoft Graph API-abonnementen aan te maken en te vernieuwen, zorg ervoor dat je aan deze algemene vereisten voldoet:

U vindt andere vereisten die specifiek zijn voor de programmeertaal van keuze en de ontwikkelomgeving die u gebruikt in de koppelingen naar Microsoft Graph API-voorbeelden die in een volgende sectie worden gevonden.

Belangrijk

Hoewel gedetailleerde instructies voor het implementeren van je applicatie te vinden zijn in de sectie voorbeelden met gedetailleerde instructies, lees dan alle secties in dit artikel, want ze bevatten belangrijkere informatie over het doorsturen van Microsoft Graph API-gebeurtenissen via Event Grid.

Een Microsoft Graph API-abonnement maken

Wanneer je een Graph API-abonnement aanmaakt, maakt het systeem een partneronderwerp voor je aan. Je geeft de volgende informatie door in de notificationURL-parameter om het partneronderwerp aan te geven dat aangemaakt moet worden en gekoppeld aan het nieuwe Graph API-abonnement:

  • naam van partneronderwerp
  • Brongroepnaam voor het partneronderwerp
  • regio (locatie)
  • Azure-abonnement

Deze codevoorbeelden laten zien hoe u een Graph API-abonnement maakt. Ze bevatten voorbeelden voor het maken van een abonnement voor het ontvangen van gebeurtenissen van alle gebruikers in een Microsoft Entra ID-tenant wanneer ze worden gemaakt, bijgewerkt of verwijderd.

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: het soort resourcewijzigingen waarvoor u gebeurtenissen wilt ontvangen. Geldige waarden: Updated en Deleted (Created wordt niet ondersteund door de Graph API; raadpleeg de Graph API-documentatie voor meer details). U kunt een of meer van deze waarden opgeven, gescheiden door komma's.

  • notificationUrl: een URI die wordt gebruikt om het partneronderwerp te definiëren waarnaar gebeurtenissen worden verzonden. Het moet voldoen aan het volgende patroon: 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>. Om de locatie (ook bekend als Azure-regio) te krijgen, namevoer je het az account list-locations commando uit. Gebruik geen weergavenaam voor de locatie. Gebruik bijvoorbeeld niet West Central US. Gebruik in plaats daarvan westcentralus.

    az account list-locations

  • lifecycleNotificationUrl: een URI die wordt gebruikt om het partneronderwerp te definiëren waaraan microsoft.graph.subscriptionReauthorizationRequired gebeurtenissen worden gestuurd. Deze gebeurtenis geeft uw toepassing aan dat het Graph API-abonnement binnenkort verloopt. De URI volgt hetzelfde patroon als notificationUrl eerder beschreven als je Event Grid als bestemming voor levenscyclusgebeurtenissen gebruikt. In dat geval moet het partneronderwerp hetzelfde zijn als het onderwerp dat is opgegeven in notificationUrl.

  • resource: de bron die gebeurtenissen genereert die toestandswijzigingen aankondigen.

  • expirationDateTime: de vervaldatum waarop het abonnement afloopt en de stroom van gebeurtenissen stopt. Het moet voldoen aan het formaat dat is gespecificeerd in Request for Comments (RFC) 3339. Je moet een vervaldatum specificeren die binnen de maximaal toegestane abonnementsduur per type hulpbron valt.

  • clientState: gebruik deze optionele eigenschap om aanroepen naar je event handler-applicatie tijdens event delivery te verifiëren. Zie de eigenschappen van het Graph API-abonnement voor meer informatie.

Belangrijk

  • De naam van het partneronderwerp moet uniek zijn binnen dezelfde Azure-regio. Elke combinatie van tenanttoepassings-id's kan maximaal 10 unieke partneronderwerpen maken.

  • Houd rekening met de servicelimieten van bepaalde Graph API-resources bij het ontwikkelen van uw oplossing.

  • Bestaande Graph API-abonnementen zonder een lifecycleNotificationUrl eigenschap ontvangen geen levenscyclus-gebeurtenissen. Om de lifecycleNotificationUrl eigenschap toe te voegen, verwijder je het bestaande abonnement en maak je een nieuw abonnement aan dat de eigenschap tijdens het aanmaken van het abonnement specificeert.

Nadat u een Graph API-abonnement hebt gemaakt, hebt u een partneronderwerp gemaakt in Azure.

Een Microsoft Graph API-abonnement verlengen

Verleng het Graph API-abonnement voordat het verloopt om te voorkomen dat de stroom van gebeurtenissen wordt gestopt. Om het verlengingsproces te automatiseren, ondersteunt Microsoft Graph API levenscyclusmeldingen waarop applicaties zich kunnen abonneren. Momenteel ondersteunen alle typen Microsoft Graph API-bronnen het microsoft.graph.subscriptionReauthorizationRequired evenement, dat wordt verzonden wanneer een van de volgende voorwaarden zich voordoet:

  • De toegangstoken verloopt bijna af.
  • Het Graph API-abonnement loopt bijna af.
  • Een tenantbeheerder heeft de machtigingen van uw app ingetrokken om een resource te lezen.

Als het Graph API-abonnement niet wordt verlengd nadat het is verlopen, maakt u een nieuw Graph API-abonnement. Je kunt hetzelfde partnertopic gebruiken dat voor het verlopen abonnement werd gebruikt, zolang het abonnement minder dan 30 dagen geleden is verlopen. Als het Graph API-abonnement langer dan 30 dagen is verlopen, kunt u uw bestaande partneronderwerp niet opnieuw gebruiken. In dit geval moet je een andere partner-onderwerpnaam opgeven. U kunt ook het bestaande partneronderwerp verwijderen om een nieuw partneronderwerp te maken met dezelfde naam tijdens het maken van het Graph API-abonnement.

Een Microsoft Graph API-abonnement verlengen

Wanneer je applicatie een microsoft.graph.subscriptionReauthorizationRequired event ontvangt, zou het Graph API-abonnement moeten worden verlengd:

  1. Als je een clientsecret hebt toegevoegd in de clientState-property bij het aanmaken van het Graph API-abonnement, bevat het event dat clientsecret. Controleer of de clientState van de gebeurtenis overeenkomt met de waarde die is gebruikt bij het maken van het Graph API-abonnement.

  2. Zorg ervoor dat de app een geldig toegangstoken heeft om de volgende stap uit te voeren. De volgende voorbeelden met gedetailleerde instructies geven meer informatie.

  3. Roep een van de volgende twee API's aan. Als de API-aanroep slaagt, wordt de wijzigingsmeldingsstroom hervat.

    • Roep de /reauthorize actie aan om het abonnement opnieuw te autoriseren zonder de vervaldatum ervan uit te breiden.

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

    • Voer een reguliere actie 'verlengen' uit om het abonnement op hetzelfde moment opnieuw te autoriseren en te verlengen.

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

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

      Verlengen kan mislukken als de app niet langer gemachtigd is om toegang te krijgen tot de bron. De app moet dan mogelijk een nieuw toegangstoken aanvragen om een abonnement opnieuw te autoriseren.

Autorisatieproblemen vervangen niet de noodzaak om een abonnement te verlengen voordat het verloopt. De levenscyclus van toegangstokens en het verlopen van abonnementen zijn niet hetzelfde. Uw toegangstoken verloopt mogelijk voordat uw abonnement verloopt. Wees voorbereid om je endpoint regelmatig opnieuw te autoriseren om je toegangstoken te verversen. Wanneer u uw eindpunt opnieuw autoriseert, wordt uw abonnement niet verlengd. Als u uw abonnement verlengt, wordt uw eindpunt echter ook opnieuw geverifieerd.

Wanneer je je Graph API-abonnement verlengt of opnieuw autoriseert, gebruikt het hetzelfde partneronderwerp dat je hebt opgegeven bij het aanmaken van het abonnement.

Wanneer je een nieuwe vervaldatumDatumTijd opgeeft, zorg er dan voor dat deze minstens drie uur vanaf het huidige tijdstip is. Anders ontvangt microsoft.graph.subscriptionReauthorizationRequired uw toepassing mogelijk gebeurtenissen kort na verlenging.

Voor voorbeelden van hoe je je Graph API-abonnement opnieuw kunt autoriseren door gebruik te maken van een van de ondersteunde talen, zie abonnement herautoriseren verzoek.

Voor voorbeelden van hoe je je Graph API-abonnement kunt verlengen en opnieuw autoriseren door gebruik te maken van een van de ondersteunde talen, zie update-abonnementsverzoek.

Voorbeelden met gedetailleerde instructies

Microsoft Graph API-documentatie bevat codevoorbeelden met instructies voor:

  • Stel uw ontwikkelomgeving in met specifieke instructies op basis van de taal die u gebruikt. Instructies omvatten ook het verkrijgen van een Microsoft 365-tenant voor ontwikkelingsdoeleinden.
  • Maak een Graph API-abonnement aan. Om een abonnement te verlengen, roep je de Graph API aan door gebruik te maken van de codefragmenten in How to renew a Graph API subscription.
  • Haal verificatietokens op om deze te gebruiken bij het aanroepen van Microsoft Graph API.

Notitie

Je kunt je Graph API-abonnement aanmaken door gebruik te maken van de Microsoft Graph API Explorer. U moet de voorbeelden nog steeds gebruiken voor andere belangrijke aspecten van uw oplossing, zoals verificatie en ontvangst van gebeurtenissen.

Voorbeelden van webtoepassingen zijn beschikbaar voor de volgende talen:

  • C#-voorbeeld. Het is een up-to-date voorbeeld met informatie over het maken en verlengen van Graph API-abonnementen en begeleidt u bij een aantal stappen om de stroom van gebeurtenissen in te schakelen.
  • Java-voorbeeld
  • Node.js voorbeeld.

Belangrijk

Je moet het partneronderwerp activeren dat is gemaakt als deel van het aanmaken van je Graph API-abonnement. U moet ook een Event Grid-gebeurtenisabonnement maken voor uw webtoepassing om gebeurtenissen te ontvangen. Hiervoor gebruikt u de URL die is geconfigureerd in uw webtoepassing om gebeurtenissen te ontvangen als een webhookeindpunt in uw gebeurtenisabonnement.

Belangrijk

Hebt u voorbeeldcode nodig voor een andere taal of hebt u vragen? E-mail ask-graph-and-grid@microsoft.com.

Verwante inhoud

Om Microsoft Graph API-gebeurtenissen via Event Grid te ontvangen, voltooit u deze twee stappen:

  • Last updated on