Ta emot ändringshändelser för Microsoft Graph API via Azure Event Grid

Microsoft Graph API tillhandahåller ändringsmeddelanden för resurser i Microsoft 365-tjänster, inklusive Microsoft Entra-ID, Teams, Outlook och OneDrive. Genom att prenumerera på dessa händelser via Azure Event Grid kan du bygga händelsedrivna applikationer som svarar på resursförändringar i realtid.

Den här artikeln beskriver hur du:

  • Skapa Microsoft Graph API-prenumerationer som levererar händelser till Azure Event Grid-partnerämnen.
  • Hantera prenumerationslivscykler med automatisk förnyelse.
  • Dirigera händelser till flera destinationer genom att använda Event Grids filtrerings- och routingfunktioner.

Azure Event Grid har flera fördelar jämfört med traditionella webhook-baserade Microsoft Graph API-prenumerationer:

  • Förenklad routning: Använd en enda Graph API-prenumeration för att skicka händelser till flera mål.
  • Avancerad filtrering: Dirigera specifika händelsetyper till olika program baserat på händelseegenskaper.
  • Standardefterlevnad: Ta emot händelser i CloudEvents-format för bättre samverkan.
  • Tillförlitlighet: Inbyggd logik för återförsök och dödbrevköer säkerställer tillförlitlig leverans av händelser.

Händelsekällor som stöds

Följande tabell listar de händelsekällor för vilka du kan få händelser via Graph API. För de flesta resurser stödjer Graph API händelser som meddelar deras skapande, uppdatering och borttagning. För detaljerad information om de resurser som utlöser händelser för händelsekällor, se resurser som stöds av ändringsmeddelanden i Microsoft Graph API.

Microsoft-händelsekälla Resurser Tillgängliga händelsetyper
Microsoft Entra ID Användare, grupp Händelsetyper för Microsoft Entra-ID
Outlook Händelse (kalendermöte), Meddelande (e-post), Kontakt Händelsetyper för Outlook
Microsoft Teams ChatMessage, CallRecord (möte) Händelsetyper för Microsoft Teams
OneDrive DriveItem (på engelska) Microsoft OneDrive-händelser
Microsoft SharePoint Lista Microsoft SharePoint-händelser
Att göra Att göra-uppgift Microsoft ToDo-händelser
Säkerhetsaviseringar avisering Händelser i Microsoft Security Alert
Utskrift i molnet Skrivar- och utskriftsaktivitetsdefinition Microsoft Cloud Printing-händelser
Microsoft-konversationer Konversation Gruppkonversationshändelser för Microsoft 365

Skapa en Microsoft Graph API-prenumeration för att göra det möjligt för Graph API-händelser att flöda in i ett partnerämne. Graph API skapar automatiskt partnerämnet när du skapar prenumerationen. Använd det partneravsnittet för att skapa händelseprenumerationer för att skicka dina händelser till någon av de händelsehanterare som stöds och som bäst uppfyller dina krav för att bearbeta händelserna.

Viktigt!

Om du inte är bekant med funktionen Partnerhändelser kan du läsa Översikt över partnerhändelser.

Varför prenumerera på händelser från Microsoft Graph API-källor via Event Grid?

Förutom att prenumerera på Microsoft Graph API-händelser via Event Grid har du andra alternativ för att få liknande notiser (inte händelser). Använd Microsoft Graph API för att leverera händelser till Event Grid om du uppfyller minst ett av följande krav:

  • Du utvecklar en händelsedriven lösning som använder händelser från Microsoft Entra-ID, Outlook eller Teams för att reagera på resursändringar. Du behöver den robusta händelsedrivna modellen och funktionerna publish-subscribe som Event Grid tillhandahåller. En översikt över Event Grid finns i Event Grid-begrepp.
  • Du vill använda Event Grid för att dirigera händelser till flera destinationer genom att använda en enda Graph API-prenumeration, och du vill undvika att hantera flera Graph API-prenumerationer.
  • Du måste dirigera händelser till olika underordnade program, webhooks eller Azure-tjänster baserat på vissa egenskaper i händelsen. Du kanske till exempel vill dirigera händelsetyper som Microsoft.Graph.UserUpdated och Microsoft.Graph.UserDeleted till ett specialiserat program som bearbetar användarnas registrering och off-boarding. Du kanske också vill skicka Microsoft.Graph.UserUpdated händelser till ett annat program som synkroniserar kontaktinformation, till exempel. Du kan uppnå detta genom att använda en enda Graph API-prenumeration när du använder Event Grid som notifikationsdestination. Mer information finns i händelsefiltrering och händelsehanterare.
  • Samverkan är viktig för dig. Du vill vidarebefordra och hantera händelser på ett standardiserat sätt genom att använda Cloud Native Computing Foundation (CNCF) CloudEvents-specifikationsstandarden.
  • Du värdesätter det utökningsstöd som CloudEvents tillhandahåller. Om du till exempel vill spåra händelser i kompatibla system använder du CloudEvents-tillägget Distribuerad spårning. Läs mer om CloudEvents-tillägg.
  • Du använder beprövade, händelsedrivna metoder som branschen använder.

Aktivera Graph API-händelser för att flöda till ditt partnerämne

Begär att Microsoft Graph API vidarebefordrar händelser till ett Event Grid-partnerämne genom att skapa en Graph API-prenumeration med hjälp av Microsoft Graph API Software Development Kits (SDK:er) och följa stegen i länkarna till exemplen i det här avsnittet. Se Språk som stöds för Microsoft Graph API SDK för tillgänglig SDK-support.

Allmänna krav

Innan du implementerar din applikation för att skapa och förnya Microsoft Graph API-prenumerationer, se till att du uppfyller dessa allmänna förutsättningar:

Du hittar andra krav som är specifika för valfritt programmeringsspråk och den utvecklingsmiljö som du använder i Microsoft Graph API-exempellänkarna som finns i ett kommande avsnitt.

Viktigt!

Även om detaljerade instruktioner för att implementera din applikation finns i avsnittet om exempel med detaljerade instruktioner, läs alla avsnitt i denna artikel eftersom de innehåller viktigare information om vidarebefordran av Microsoft Graph API-händelser med Event Grid.

Så här skapar du en Microsoft Graph API-prenumeration

När du skapar en Graph API-prenumeration skapar systemet ett partnerämne åt dig. Du skickar följande information i notificationUrl-parametern för att specificera partnerämnet som ska skapas och associeras med den nya Graph API-prenumerationen:

  • partnerämnesnamn
  • Resursgruppsnamn för partnerämnet
  • region (lokalisering)
  • Azure-prenumeration

Dessa kodexempel visar hur du skapar en Graph API-prenumeration. De innehåller exempel på hur du skapar en prenumeration för att ta emot händelser från alla användare i en Microsoft Entra-ID-klient när de skapas, uppdateras eller tas bort.

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: den typ av resursändringar som du vill ta emot händelser för. Giltiga värden: Updated och Deleted (Created stöds inte av Graph API; se Graph API-dokumentationen för mer information). Du kan ange ett eller flera av dessa värden avgränsade med kommatecken.

  • notificationUrl: en URI som används för att definiera partnerämnet som händelser skickas till. Den måste överensstämma med följande mönster: 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>. För att hämta platsen (även kallad Azure-region) name, kör kommandot az account list-locations. Använd inte ett platsvisningsnamn. Använd till exempel inte västra centrala USA. Använd westcentralus i stället.

    az account list-locations

  • lifecycleNotificationUrl: en URI som används för att definiera partnerämnet som microsoft.graph.subscriptionReauthorizationRequired händelser skickas till. Den här händelsen signalerar ditt program att Graph API-prenumerationen snart upphör att gälla. URI:n följer samma mönster som notificationUrl som beskrivits tidigare om du använder Event Grid som destination för livscykelhändelser. I så fall bör partnerämnet vara detsamma som det som anges i notificationUrl.

  • resource: resursen som genererar händelser som meddelar tillståndsförändringar.

  • expirationDateTime: utgångstiden då prenumerationen löper ut och händelseflödet upphör. Den måste följa formatet som anges i Request for Comments (RFC) 3339. Du måste ange en utgångstid som ligger inom den maximala prenumerationstiden per resurstyp.

  • clientState: använd denna valfria egenskap för att verifiera anrop till din event handler-applikation under händelseleverans. Mer information finns i Graph API-prenumerationsegenskaper.

Viktigt!

  • Partnerämnesnamnet måste vara unikt i samma Azure-region. Varje kombination av klientprogram-ID kan skapa upp till 10 unika partnerämnen.

  • Tänk på vissa Graph API-resursers tjänstgränser när du utvecklar din lösning.

  • Befintliga Graph API-prenumerationer utan en lifecycleNotificationUrl egenskap tar inte emot livscykelhändelser. För att lägga till lifecycleNotificationUrl egenskapen, ta bort den befintliga prenumerationen och skapa en ny prenumeration som specificerar egenskapen vid prenumerationsskapandet.

När du har skapat en Graph API-prenumeration har du skapat ett partnerämne i Azure.

Förnya en Microsoft Graph API-prenumeration

Förnya Graph API-prenumerationen innan den upphör att gälla för att undvika att stoppa händelseflödet. För att hjälpa till att automatisera förnyelseprocessen stöder Microsoft Graph API livscykelnotiser som applikationer kan prenumerera på. För närvarande stödjer alla typer av Microsoft Graph API-resurser händelsenmicrosoft.graph.subscriptionReauthorizationRequired, som skickas när något av följande villkor inträffar:

  • Åtkomsttoken är på väg att gå ut.
  • Graph API-prenumerationen är på väg att gå ut.
  • En klientadministratör har återkallat appens behörighet att läsa en resurs.

Om Graph API-prenumerationen inte förnyas när den har upphört att gälla skapar du en ny Graph API-prenumeration. Du kan hänvisa till samma partnerämne som används i den utgångna prenumerationen så länge den har gått ut i mindre än 30 dagar. Om Graph API-prenumerationen har upphört att gälla i mer än 30 dagar kan du inte återanvända ditt befintliga partnerämne. I det här fallet behöver du ange ett annat partnerämnesnamn. Du kan också ta bort det befintliga partneravsnittet för att skapa ett nytt partnerämne med samma namn när Graph API-prenumerationen skapas.

Så här förnyar du en Microsoft Graph API-prenumeration

När din applikation får en microsoft.graph.subscriptionReauthorizationRequired händelse ska den förnya Graph API-prenumerationen:

  1. Om du tillhandgav en klienthemlighet i clientState-egenskapen när du skapade Graph API-prenumerationen, inkluderar händelsen den klienthemligheten. Kontrollera att händelsens clientState matchar det värde som användes när du skapade Graph API-prenumerationen.

  2. Kontrollera att appen har en giltig åtkomsttoken för att ta nästa steg. Avsnittet om kommande exempel med detaljerade instruktioner ger mer information.

  3. Anropa någon av följande två API:er. Om API-anropet lyckas återupptas flödet för ändringsmeddelande.

    • Anropa åtgärden /reauthorize för att auktorisera prenumerationen igen utan att förlänga dess förfallodatum.

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

    • Utför en vanlig "förnya"-åtgärd för att auktorisera och förnya prenumerationen på samma gång.

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

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

      Förnyelsen kan misslyckas om appen inte längre är auktoriserad att komma åt resursen. Appen kan då behöva skaffa en ny åtkomsttoken för att återauktorisera en prenumeration.

Auktoriseringsutmaningar ersätter inte behovet av att förnya en prenumeration innan den upphör att gälla. Livscykeln för åtkomsttoken och prenumerationens giltighetstid är inte desamma. Din åtkomsttoken kan upphöra att gälla innan prenumerationen. Var beredd på att regelbundet auktorisera din endpoint för att uppdatera din åtkomsttoken. Att auktorisera om din ändpunkt förnyar inte din prenumeration. Genom att förnya prenumerationen återauktoriseras din slutpunkt.

När du förnyar eller auktoriserar din prenumeration på Graph API på nytt använder den samma partnerämne som du angav när du skapade prenumerationen.

När du anger en ny utgångsdatumTid, se till att det är minst tre timmar från den aktuella tiden. Annars kan ditt program ta emot microsoft.graph.subscriptionReauthorizationRequired händelser strax efter förnyelsen.

För exempel på hur du kan återauktorisera din Graph API-prenumeration genom att använda något av de stödda språken, se prenumerationsbegäran om återauktorisation.

För exempel på hur du förnyar och återauktoriserar ditt Graph API-abonnemang genom att använda något av de stödda språken, se uppdateringsprenumerationsbegäran.

Exempel med detaljerade instruktioner

Dokumentation om Microsoft Graph API innehåller kodexempel med instruktioner för att:

  • Konfigurera utvecklingsmiljön med specifika instruktioner beroende på vilket språk du använder. Anvisningarna täcker också hur du får en Microsoft 365-klientorganisation för utvecklingssyfte.
  • Skapa en Graph API-prenumeration. För att förnya en prenumeration, anropa Graph API genom att använda kodbitarna i How to renew a Graph API-prenumeration.
  • Hämta autentiseringstoken för att använda dem när du anropar Microsoft Graph API.

Kommentar

Du kan skapa din Graph API-prenumeration genom att använda Microsoft Graph API Explorer. Du bör fortfarande använda exemplen för andra viktiga aspekter av din lösning, till exempel autentisering och mottagande av händelser.

Webbprogramexempel är tillgängliga för följande språk:

  • C#-exempel. Det är ett uppdaterat exempel som innehåller hur du skapar och förnyar Graph API-prenumerationer och vägleder dig genom några av stegen för att aktivera händelseflödet.
  • Java-exempel
  • Node.js exempel.

Viktigt!

Du måste aktivera ditt partnertopic som skapas som en del av prenumerationen på Graph API. Du måste också skapa en Event Grid-händelseprenumeration på din webbapp för att ta emot händelser. För detta ändamål använder du URL:en som konfigurerats i din webbapplikation för att ta emot händelser som webhook-slutpunkt i din evenemangsprenumeration.

Viktigt!

Behöver du exempelkod för ett annat språk eller har du frågor? E-post ask-graph-and-grid@microsoft.com.

Relaterat innehåll

För att ta emot Microsoft Graph API-händelser via Event Grid, utför dessa två steg:

  • Last updated on