Ta emot Microsoft Graph-ändringsmeddelanden via Azure Event Grid (förhandsversion)

Artikel
10/18/2023

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 resurser för vilka händelser är tillgängliga via Graph API. För varje resurs stöds händelser för att skapa, uppdatera och ta bort tillståndsändringar.

Viktigt!

Microsoft Graph API:ets möjlighet att skicka händelser till Azure Event Grid är för närvarande i privat förhandsversion. Om du har frågor eller behöver support kan du skicka ett e-postmeddelande till oss på ask-graph-and-grid@microsoft.com.

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
Microsoft SharePoint och OneDrive	DriveItem
Microsoft SharePoint	Lista
Säkerhetsaviseringar	Alert
Microsoft-konversationer	Konversation

Viktigt!

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

Varför ska jag använda Microsoft Graph API som mål?

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ändelsemodellen och funktionerna för publicering och prenumeration 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 avstigning. 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 standard sätt med hjälp av CNCF:s CloudEvents-specifikationsstandard , som Event Grid uppfyller fullt ut.
Du gillar utökningsstöd som CloudEvents tillhandahåller. Om du till exempel vill spåra händelser i kompatibla system kan du använda 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.

Steg på hög nivå

Registrera Event Grid-resursprovidern med din Azure-prenumeration.
Ge partnern behörighet att skapa ett partnerämne i resursgruppen.
Aktivera händelser att flöda till ett partnerämne
Aktivera partnerämnet så att dina händelser börjar flöda till ditt partnerämne.
Prenumerera på händelser.

Registrera Event Grid-resursprovidern

Om du inte har använt Event Grid tidigare måste du registrera Event Grid-resursprovidern. Om du har använt Event Grid tidigare går du vidare till nästa avsnitt.

Gör följande i Azure-portalen:

Välj Prenumerationer på den vänstra menyn.
Välj den prenumeration som du vill använda för Event Grid i prenumerationslistan.
På sidan Prenumeration väljer du Resursprovidrar under Inställningar på den vänstra menyn.
Sök efter Microsoft.EventGrid och bekräfta att statusen inte är registrerad.
Välj Microsoft.EventGrid i providerlistan.
Välj Registrera i kommandofältet.
Uppdatera för att kontrollera att statusen för Microsoft.EventGrid har ändrats till Registrerad.

Auktorisera partner för att skapa ett partnerämne

Du måste ge ditt medgivande till partnern för att skapa partnerämnen i en resursgrupp som du anger. Den här auktoriseringen har en förfallotid. Det gäller för den tidsperiod som du anger mellan 1 och 365 dagar.

Viktigt!

För en större säkerhetsinställning anger du den minsta förfallotid som ger partnern tillräckligt med tid för att konfigurera dina händelser så att de flödar till Event Grid och etablerar ditt partnerämne. Din partner kommer inte att kunna skapa resurser (partnerämnen) i din Azure-prenumeration efter förfallotiden för auktoriseringen.

Kommentar

Event Grid började tillämpa auktoriseringskontroller för att skapa partnerämnen runt den 30 juni 2022.

Logga in på Azure-portalen.
I sökfältet längst upp anger du Partnerkonfigurationer och väljer Event Grid-partnerkonfigurationer under Tjänster i resultatet.
På sidan Konfigurationer av Event Grid-partner väljer du knappen Skapa Event Grid-partnerkonfiguration på sidan (eller) och väljer + Skapa i kommandofältet.
Gör följande på sidan Skapa partnerkonfiguration :
1. I avsnittet Projektinformation väljer du Azure-prenumerationenoch resursgruppen där du vill att partnern ska kunna skapa ett partnerämne.
2. I avsnittet Partnerauktoriseringar anger du en standardtid för förfallotid för partnerauktoriseringar som definierats i den här konfigurationen.
3. Om du vill ge din auktorisering för en partner att skapa partnerämnen i den angivna resursgruppen väljer du + Partnerauktoriseringslänk .
På sidan Lägg till partnerauktorisering för att skapa resurser visas en lista över verifierade partner. En verifierad partner är en partner vars identitet har verifierats av Microsoft. Följ de här stegen för att auktorisera Auth0 för att skapa ett partnerämne.
1. Välj den verifierade partnern (Auth0, SAP, Tribal Group eller Microsoft Graph API) i listan över verifierade partner.
2. Ange förfallotid för auktorisering.
3. välj Lägg till.
  
  Viktigt!
  
  Din partner kommer inte att kunna skapa resurser (partnerämnen) i din Azure-prenumeration efter förfallotiden för auktoriseringen.
På sidan Skapa partnerkonfiguration kontrollerar du att partnern har lagts till i listan över partnerauktorisering längst ned.
Välj Granska + skapa längst ned på sidan.
På sidan Granska granskar du alla inställningar och väljer sedan Skapa för att skapa partnerregistreringen.

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

Du begär att Microsoft Graph API skickar händelser genom att skapa en Graph API-prenumeration. När du skapar en Graph API-prenumeration bör http-begäran se ut som i följande exempel:

POST https://graph.microsoft.com/v1.0/subscriptions

x-ms-enable-features: EventGrid

Body:
{
    "changeType": "Updated,Deleted,Created",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2022-04-30T00:00:00Z",
    "clientState": "mysecret"
}

Här är några av nyckelhuvudena och nyttolastegenskaperna:

x-ms-enable-features: Rubrik som används för att ange din önskan att delta i förhandsgranskningsfunktionen för att skicka händelser till Azure Event Grid. Dess värde måste vara EventGrid. Det här huvudet måste inkluderas i begäran när du skapar en Microsoft Graph API-prenumeration.
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 överensstämmer 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
```
resurs: resursen som genererar händelser för att meddela tillståndsändringar.
expirationDateTime: förfallotiden då prenumerationen upphör att gälla och därmed stoppas händelseflödet. Den måste överensstämma med det format som anges i RFC 3339. Du måste ange en förfallotid som är inom den maximala prenumerationslängd som kan tillåtas för den resurstyp som används.
klienttillstånd. Ett värde som du anger när du skapar en Graph API-prenumeration. Mer information finns i Graph API-prenumerationsegenskaper.

Kommentar

Microsoft Graph API:s möjlighet att skicka händelser till Event Grid är endast tillgänglig i en specifik Graph API-miljö. Du måste uppdatera koden så att den använder följande Graph API-slutpunkt https://graph.microsoft.com/beta. Det är till exempel så här du kan ange slutpunkten på din graph-klient (com.microsoft.graph.requests.GraphServiceClient) med hjälp av Graph API Java SDK:

graphClient.setServiceRoot("https://graph.microsoft.com/beta");

Du kan skapa en Microsoft Graph API-prenumeration genom att följa anvisningarna i Webhook-exemplen för Microsoft Graph API som innehåller kodexempel för NodeJS, Java (Spring Boot) och .NET Core. Det finns ännu inga exempel för Python, Go och andra språk, men Graph SDK har stöd för att skapa Graph API-prenumerationer med hjälp av dessa programmeringsspråk.

Kommentar

Partnerämnesnamn måste vara unika 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.

Vad händer när du skapar en Microsoft Graph API-prenumeration?

När du skapar en Graph API-prenumeration med en notificationUrl bindning till Event Grid skapas ett partnerämne i din Azure-prenumeration. För det partneravsnittet konfigurerar du händelseprenumerationer så att de skickar 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.

Testa API:er med Graph Explorer

För snabba tester och för att lära känna API:et kan du använda Graph Explorer. För allt annat än tillfälliga tester eller utbildning bör du använda Microsoft Graph SDK:er.

Aktivera ett partnerämne

I sökfältet i Azure-portalen söker du efter och väljer Event Grid-partnerämnen.
På sidan Partnerämnen för Event Grid väljer du partnerämnet i listan.
Granska det aktiverade meddelandet och välj Aktivera på sidan eller i kommandofältet för att aktivera partnerämnet före den förfallotid som anges på sidan.
Bekräfta att aktiveringsstatusen är aktiverad och skapa sedan händelseprenumerationer för partnerämnet genom att välja + Händelseprenumeration i kommandofältet.

Skapa först en händelsehanterare som hanterar händelser från partnern. Skapa till exempel en händelsehubb, Service Bus-kö eller ämne eller en Azure-funktion. Skapa sedan en händelseprenumeration för partnerämnet med hjälp av händelsehanteraren som du skapade.

Skapa en händelsehanterare

För att testa ditt partnerämne behöver du en händelsehanterare. Gå till din Azure-prenumeration och starta en tjänst som stöds som händelsehanterare, till exempel en Azure-funktion. Ett exempel finns i Exempel på Loggboken i Event Grid som du kan använda som händelsehanterare via webhooks.

När du prenumererar på partneravsnittet får du information om var du vill att dina partnerhändelser ska levereras.

I Azure-portalen skriver du Event Grid-partnerämnen i sökrutan och väljer Event Grid-partnerämnen.
På sidan Partnerämnen för Event Grid väljer du partnerämnet i listan.
På sidan Event Grid-partnerämne för partnerämnet väljer du + Händelseprenumeration i kommandofältet.
Gör följande på sidan Skapa händelseprenumeration :
1. Ange ett namn för händelseprenumerationen.
2. För Filtrera till händelsetyper väljer du de typer av händelser som din prenumeration ska ta emot.
3. För Slutpunktstyp väljer du en Azure-tjänst (Azure-funktion, lagringsköer, händelsehubbar, Service Bus-kö, Service Bus-ämne, Hybrid Anslut ions osv.) eller webhook.
4. Klicka på länken Välj en slutpunkt. I det här exemplet ska vi använda Azure Event Hubs-mål eller slutpunkt.
5. På sidan Välj händelsehubb väljer du konfigurationer för slutpunkten och väljer sedan Bekräfta markering.
6. På sidan Skapa händelseprenumeration väljer du Skapa.