Gebeurtenissen van Microsoft Graph API-wijzigingen ontvangen via Azure Event Grid (preview)

  • Artikel

In dit artikel worden de stappen beschreven voor het abonneren op gebeurtenissen die zijn gepubliceerd door Microsoft Graph API. De volgende tabel bevat de gebeurtenisbronnen waarvoor gebeurtenissen beschikbaar zijn via Graph API. Voor de meeste resources worden gebeurtenissen die het maken, bijwerken en verwijderen aankondigen, ondersteund. Zie ondersteunde resources door wijzigingsmeldingen van Microsoft Graph API voor gedetailleerde informatie over de resources waarvoor gebeurtenissen worden gegenereerd voor gebeurtenisbronnen.

Belangrijk

De mogelijkheid van Microsoft Graph API om gebeurtenissen naar Azure Event Grid te verzenden, is momenteel beschikbaar als openbare preview. Als u vragen hebt of ondersteuning nodig hebt, kunt u ons een e-mail sturen naar ask-graph-and-grid@microsoft.com.

Microsoft-gebeurtenisbron Beschikbare gebeurtenistypen
Microsoft Entra ID Microsoft Entra-gebeurtenistypen
Microsoft Outlook Microsoft Outlook-gebeurtenistypen
Groepsgesprekken in Microsoft 365
Microsoft Teams Microsoft Teams-gebeurtenistypen
Microsoft SharePoint en OneDrive
Microsoft SharePoint
Beveiligingswaarschuwingen
Microsoft-gesprekken
Microsoft Universal Print

Belangrijk

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

Waarom moet ik me abonneren op gebeurtenissen van Microsoft Graph API-bronnen via Event Grid?

Naast de mogelijkheid om u te abonneren op Microsoft Graph API-gebeurtenissen via Event Grid, hebt u andere opties waarmee u vergelijkbare meldingen (niet gebeurtenissen) kunt ontvangen. Overweeg om Microsoft Graph API te gebruiken om gebeurtenissen aan Event Grid te leveren als u ten minste een van de volgende vereisten hebt:

  • U ontwikkelt een gebeurtenisgestuurde oplossing die gebeurtenissen vereist van Microsoft Entra ID, Outlook, Teams, enzovoort om te reageren op resourcewijzigingen. U hebt het robuuste gebeurtenismodel nodig en de mogelijkheden voor publiceren/abonneren die Event Grid biedt. Zie Event Grid-concepten voor een overzicht van Event Grid.
  • U wilt Event Grid gebruiken om gebeurtenissen naar meerdere bestemmingen te routeren met behulp van één Graph API-abonnement en u wilt voorkomen dat u meerdere Graph API-abonnementen beheert.
  • U moet gebeurtenissen routeren naar verschillende downstreamtoepassingen, webhooks of Azure-services, afhankelijk van een aantal eigenschappen in de gebeurtenis. U kunt bijvoorbeeld gebeurtenistypen routeren, zoals Microsoft.Graph.UserCreated en Microsoft.Graph.UserDeleted naar een gespecialiseerde toepassing die de onboarding en off-onboarding van gebruikers verwerkt. Mogelijk wilt u ook gebeurtenissen verzenden Microsoft.Graph.UserUpdated naar een andere toepassing waarmee bijvoorbeeld contactgegevens worden gesynchroniseerd. U kunt dit bereiken met behulp van één Graph API-abonnement wanneer u Event Grid gebruikt als een meldingsbestemming. Zie gebeurtenisfilters en gebeurtenis-handlers voor meer informatie.
  • Interoperabiliteit is belangrijk voor u. U wilt gebeurtenissen op een standaard manier doorsturen en afhandelen met behulp van de specificatiestandaard CloudEvents van CNCF.
  • U houdt van de uitbreidbaarheidsondersteuning die CloudEvents biedt. Als u bijvoorbeeld gebeurtenissen in compatibele systemen wilt traceren, gebruikt u gedistribueerde tracering van cloudEvents-extensies. Meer informatie over meer CloudEvents-extensies.
  • U wilt bewezen gebeurtenisgestuurde benaderingen gebruiken die door de branche worden gebruikt.

Graph API-gebeurtenissen inschakelen om naar uw partneronderwerp te stromen

U vraagt 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 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

U moet aan deze algemene vereisten voldoen voordat u uw toepassing implementeert om Microsoft Graph API-abonnementen te maken en te verlengen:

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

Belangrijk

Hoewel gedetailleerde instructies voor het implementeren van uw toepassing worden gevonden in de voorbeelden met gedetailleerde instructies , moet u alle secties in dit artikel lezen omdat deze aanvullende, belangrijke informatie bevatten met betrekking tot het doorsturen van Microsoft Graph API-gebeurtenissen met behulp van Event Grid.

Een Microsoft Graph API-abonnement maken

Wanneer u een Graph API-abonnement maakt, wordt er een partneronderwerp voor u gemaakt. U geeft de volgende informatie door in parameter notificationUrl om op te geven welk partneronderwerp moet worden gemaakt en gekoppeld aan het nieuwe Graph API-abonnement:

  • naam van partneronderwerp
  • resourcegroepnaam waarin het partneronderwerp wordt gemaakt
  • regio (locatie)
  • Azure-abonnement

Deze codevoorbeelden laten zien hoe u een Graph API-abonnement maakt. Ze tonen 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,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: het soort resourcewijzigingen waarvoor u gebeurtenissen wilt ontvangen. Geldige waarden: Updated, Deleteden Created. 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>. De locatie (ook wel Azure-regio genoemd) name kan worden verkregen door de opdracht az account list-locations uit te voeren. Gebruik geen weergavenaam voor de locatie. Gebruik bijvoorbeeld 'VS - west-centraal' niet. Gebruik in plaats daarvan westcentralus. 
      az account list-locations
  • lifecycleNotificationUrl: een URI die wordt gebruikt om het partneronderwerp te definiëren waarnaar microsoft.graph.subscriptionReauthorizationRequiredgebeurtenissen worden verzonden. Deze gebeurtenis geeft uw toepassing aan dat het Graph API-abonnement binnenkort verloopt. De URI volgt hetzelfde patroon als notificationUrl dat hierboven wordt beschreven als het gebruik van Event Grid als bestemming voor levenscyclus-gebeurtenissen. In dat geval moet het partneronderwerp hetzelfde zijn als het onderwerp dat is opgegeven in notificationUrl.
  • resource: de resource waarmee gebeurtenissen worden gegenereerd die statuswijzigingen aankondigen.
  • expirationDateTime: de vervaldatum waarop het abonnement verloopt en de stroom van gebeurtenissen stopt. Deze moet voldoen aan de indeling die is opgegeven in RFC 3339. U moet een verlooptijd opgeven die binnen de maximale toegestane abonnementslengte per resourcetype valt.
  • clientstatus. Deze eigenschap is optioneel. Deze wordt gebruikt voor verificatie van aanroepen naar uw gebeurtenis-handlertoepassing tijdens de levering van gebeurtenissen. 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. Als u de eigenschap lifecycleNotificationUrl wilt toevoegen, moet u het bestaande abonnement verwijderen en een nieuw abonnement maken waarin de eigenschap wordt opgegeven tijdens het maken van het abonnement.

Notitie

Als uw toepassing de header x-ms-enable-features met uw aanvraag gebruikt om een Graph API-abonnement te maken tijdens de privé-preview, moet u deze verwijderen omdat dit niet meer nodig is.

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

Een Microsoft Graph API-abonnement verlengen

Een Graph API-abonnement moet worden verlengd door uw toepassing voordat het verloopt om te voorkomen dat de stroom van gebeurtenissen wordt gestopt. Microsoft Graph API biedt ondersteuning voor gebeurtenissen voor levenscyclusmeldingen waarop uw toepassing zich kan abonneren om het verlengingsproces te automatiseren. Op dit moment ondersteunen alle typen Microsoft Graph API-resources de microsoft.graph.subscriptionReauthorizationRequired, die wordt verzonden wanneer een van de volgende voorwaarden zich voordoet:

  • Het toegangstoken staat op het punt om te verlopen.
  • Het Graph API-abonnement staat op het punt om te verlopen.
  • Een tenantbeheerder heeft de machtigingen van uw app ingetrokken om een resource te lezen.

Als u uw Graph API-abonnement niet hebt verlengd nadat het is verlopen, moet u een nieuw Graph API-abonnement maken. U kunt verwijzen naar hetzelfde partneronderwerp dat u hebt gebruikt in uw verlopen abonnement zolang het gedurende minder dan 30 dagen 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 u een andere partneronderwerpnaam 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 u een microsoft.graph.subscriptionReauthorizationRequired gebeurtenis ontvangt, moet uw toepassing het Graph API-abonnement verlengen door deze acties uit te voeren:

  1. Als u een clientgeheim hebt opgegeven in de eigenschap clientState toen u het Graph API-abonnement maakte, is dat clientgeheim opgenomen in de gebeurtenis. 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. Meer informatie vindt u in de komende voorbeelden met gedetailleerde instructies .

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

      Vernieuwen kan mislukken als de app niet langer gemachtigd is voor toegang tot de resource. Het kan vervolgens nodig zijn voor de app om een nieuw toegangstoken te verkrijgen 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 kan verlopen voordat uw abonnement verloopt. Het is belangrijk dat u voorbereid bent om uw eindpunt regelmatig opnieuw te autoriseren om uw toegangstoken te vernieuwen. Als u uw eindpunt opnieuw wilt autoriseren, wordt uw abonnement niet verlengd. Als u uw abonnement verlengt, wordt uw eindpunt echter ook opnieuw geverifieerd.

Bij het verlengen en/of opnieuw autoriseren van uw Graph API-abonnement wordt hetzelfde partneronderwerp opgegeven toen het abonnement werd gemaakt, gebruikt.

Wanneer u een nieuwe expirationDateTime opgeeft, moet deze ten minste drie uur vanaf de huidige tijd zijn. Anders ontvangt microsoft.graph.subscriptionReauthorizationRequired uw toepassing mogelijk gebeurtenissen kort na verlenging.

Zie de aanvraag voor opnieuwauthoriseren van uw Graph API-abonnement met behulp van een van de ondersteunde talen voor voorbeelden van het opnieuw autoriseren van abonnementen.

Zie Abonnementsaanvraag bijwerken voor voorbeelden over het verlengen en opnieuw autoriseren van uw Graph API-abonnement met behulp van een van de ondersteunde talen.

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. Als u een abonnement wilt verlengen, kunt u de Graph API aanroepen met behulp van de codefragmenten in Het hierboven verlengen van een Graph API-abonnement .
  • Haal verificatietokens op om deze te gebruiken bij het aanroepen van Microsoft Graph API.

Notitie

Het is mogelijk om uw Graph API-abonnement te maken met behulp 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. Dit 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
    • GraphAPIController bevat voorbeeldcode voor het maken, verwijderen en verlengen van een Graph API-abonnement. Deze moet samen met de Bovenstaande Java-voorbeeldtoepassing worden gebruikt.
  • NodeJS-voorbeeld.

Belangrijk

U moet het partneronderwerp activeren dat is gemaakt als onderdeel van het maken van uw 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. Volgende stappen voor meer informatie.

Belangrijk

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

Volgende stappen

Volg de instructies in de volgende twee stappen om de configuratie te voltooien voor het ontvangen van Microsoft Graph API-gebeurtenissen met behulp van Event Grid:

Andere nuttige koppelingen: