Dela via

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

  • Artikel

I den här artikeln beskrivs steg för att prenumerera på händelser som publicerats av Microsoft Graph API. I följande tabell visas de händelsekällor för vilka händelser är tillgängliga via Graph API. För de flesta resurser stöds händelser som meddelar dess skapande, uppdatering och borttagning. Detaljerad information om de resurser för vilka händelser genereras för händelsekällor finns i Resurser som stöds av Microsoft Graph API:s ändringsaviseringar .

Microsoft-händelsekälla Resurser Tillgängliga händelsetyper
Microsoft Entra ID Användare, grupp Microsoft Entra-händelsetyper
Microsoft Outlook Händelse (kalendermöte), Meddelande (e-post), Kontakt Händelsetyper för Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (möte) Händelsetyper för Microsoft Teams
OneDrive DriveItem Microsoft OneDrive-händelser
Microsoft SharePoint Lista Microsoft SharePoint-händelser
Att göra Att göra-uppgift Microsoft ToDo-händelser
Säkerhetsaviseringar Alert 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

Du skapar 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. Partnerämnet skapas automatiskt åt dig som en del av skapandet av Graph API-prenumerationen. Du använder 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 ska jag prenumerera på händelser från Microsoft Graph API-källor via Event Grid?

Förutom möjligheten att prenumerera på Microsoft Graph API-händelser via Event Grid har du andra alternativ där du kan ta emot liknande meddelanden (inte händelser). Överväg att använda Microsoft Graph API för att leverera händelser till Event Grid om du har minst ett av följande krav:

  • Du utvecklar en händelsedriven lösning som kräver att händelser från Microsoft Entra ID, Outlook, Teams osv. reagerar 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 mål med 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 beroende på några av egenskaperna i händelsen. Du kanske till exempel vill dirigera händelsetyper som Microsoft.Graph.UserCreated 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å det med hjälp av en enda Graph API-prenumeration när du använder Event Grid som meddelandemål. 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 med cloudevents-specifikationsstandarden CloudEvents (Cloud Native Computing Foundation).
  • Du gillar 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 fler CloudEvents-tillägg.
  • Du vill använda beprövade händelsedrivna metoder som används av branschen.

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

Du 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

Du bör uppfylla dessa allmänna krav innan du implementerar ditt program för att skapa och förnya Microsoft Graph API-prenumerationer:

  • Bekanta dig med de övergripande stegen för att prenumerera på partnerhändelser. Som beskrivs i den artikeln bör du följa anvisningarna i innan du skapar en Graph API-prenumeration:

  • Ha en fungerande kunskap om Microsoft Graph API-meddelanden. Som en del av din inlärning kan du använda Graph API Explorer för att skapa Graph API-prenumerationer.

  • Förstå begrepp för partnerhändelser.

  • Identifiera den Microsoft Graph API-resurs som du vill ta emot ändringshändelser för systemtillstånd från. Mer information finns i Meddelanden om ändring av Microsoft Graph API. Om du till exempel vill spåra ändringar för användare i Microsoft Entra-ID bör du använda användarresursen. Använd grupp för att spåra ändringar i användargrupper.

  • Ha ett klientadministratörskonto på en Microsoft 365-klientorganisation. Du kan skaffa en utvecklingsklientorganisation kostnadsfritt genom att gå med i Microsoft 365 Developer Program.

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!

Detaljerade instruktioner för att implementera ditt program finns i exemplen med detaljerade instruktioner , men du bör läsa alla avsnitt i den här artikeln eftersom de innehåller ytterligare viktig information som rör 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 skapas ett partnerämne åt dig. Du skickar följande information i parametermeddelandeUrl för att ange vilket partnerämne som ska skapas och associeras till den nya Graph API-prenumerationen:

  • partnerämnesnamn
  • resursgruppsnamn där partnerämnet skapas
  • region (plats)
  • Azure-prenumeration

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

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: den typ av resursändringar som du vill ta emot händelser för. Giltiga värden: Updated, Deletedoch Created. 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>. Platsen (kallas även Azure-region) name kan hämtas genom att köra kommandot az account list-locations . Använd inte ett platsvisningsnamn. Använd till exempel inte USA, västra centrala. 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.subscriptionReauthorizationRequiredhä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 beskrev tidigare om du använder Event Grid som mål för livscykelhändelser. I så fall bör partnerämnet vara detsamma som det som anges i notificationUrl.
  • resurs: resursen som genererar händelser som meddelar tillståndsändringar.
  • expirationDateTime: förfallotiden då prenumerationen upphör att gälla och händelseflödet stoppas. Det måste överensstämma med det format som anges i RFC (Request for Change) 3339. Du måste ange en förfallotid som är inom den maximala tillåtna prenumerationslängden per resurstyp.
  • klienttillstånd. Den här egenskapen är valfri. Den används för verifiering av anrop till ditt händelsehanterarprogram under händelseleveransen. 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. Om du vill lägga till egenskapen lifecycleNotificationUrl bör du ta bort den befintliga prenumerationen och skapa en ny prenumeration som anger egenskapen när prenumerationen skapas.

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

Förnya en Microsoft Graph API-prenumeration

Ditt program måste 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 dig att automatisera förnyelseprocessen stöder Microsoft Graph API händelser för livscykelmeddelanden som ditt program kan prenumerera på. För närvarande stöder microsoft.graph.subscriptionReauthorizationRequiredalla typer av Microsoft Graph API-resurser , som skickas när något av följande villkor inträffar:

  • Åtkomsttoken håller på att upphöra att gälla.
  • Graph API-prenumerationen håller på att upphöra att gälla.
  • En klientadministratör har återkallat appens behörighet att läsa en resurs.

Om du inte har förnyat din Graph API-prenumeration när den har upphört att gälla måste du skapa en ny Graph API-prenumeration. Du kan referera till samma partnerämne som du använde i din utgångna prenumeration så länge den har upphört att gälla 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 måste du antingen 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 du får en microsoft.graph.subscriptionReauthorizationRequired händelse bör programmet förnya Graph API-prenumerationen genom att utföra följande åtgärder:

  1. Om du angav en klienthemlighet i egenskapen clientState när du skapade Graph API-prenumerationen, ingår klienthemligheten i händelsen. 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. Mer information finns i de kommande exemplen med detaljerade anvisningar .

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

      Förnyelsen kan misslyckas om appen inte längre har behörighet att komma åt resursen. Det kan sedan vara nödvändigt för appen att hämta en ny åtkomsttoken för att kunna auktorisera en prenumeration igen.

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. Det är viktigt att vara beredd på att regelbundet auktorisera din slutpunkt igen för att uppdatera din åtkomsttoken. Om du auktoriserar din slutpunkt förnyas inte din prenumeration. Men om du förnyar prenumerationen auktoriseras slutpunkten igen.

När du förnyar och/eller omauktoriserar din Graph API-prenumeration används samma partnerämne som angavs när prenumerationen skapades.

När du anger en ny expirationDateTime måste det vara minst tre timmar från den aktuella tiden. Annars kan ditt program ta emot microsoft.graph.subscriptionReauthorizationRequired händelser strax efter förnyelsen.

Exempel på hur du auktoriserar din Graph API-prenumeration igen med något av de språk som stöds finns i begäran om omauktorisering av prenumeration.

Exempel på hur du förnyar och auktoriserar din Graph API-prenumeration igen med något av de språk som stöds finns i uppdatera prenumerationsbegä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 omfattar även hur du hämtar en Microsoft 365-klientorganisation i utvecklingssyfte.
  • Skapa en Graph API-prenumeration. Om du vill förnya en prenumeration kan du anropa Graph API med hjälp av kodfragmenten i Så här förnyar du en 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 med hjälp av 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
  • NodeJS-exempel.

Viktigt!

Du måste aktivera ditt partnerämne som skapas som en del av skapandet av Graph API-prenumerationen. Du måste också skapa en Event Grid-händelseprenumeration på din webbapp för att ta emot händelser. Därför använder du url:en som konfigurerats i webbappen för att ta emot händelser som en webhook-slutpunkt i din händelseprenumeration. Nästa steg för mer information.

Viktigt!

Behöver du exempelkod för ett annat språk eller har du frågor? Skicka ett e-postmeddelande till oss på ask-graph-and-grid@microsoft.com.

Nästa steg

Följ anvisningarna i följande två steg för att slutföra konfigurationen för att ta emot Microsoft Graph API-händelser med Event Grid:

Andra användbara länkar: