Příjem událostí změn rozhraní Microsoft Graph API prostřednictvím služby Azure Event Grid (Preview)

  • Článek

Tento článek popisuje postup přihlášení k odběru událostí publikovaných rozhraním Microsoft Graph API. Následující tabulka uvádí zdroje událostí, pro které jsou události dostupné prostřednictvím rozhraní Graph API. U většiny prostředků jsou podporovány události, které oznamují její vytvoření, aktualizaci a odstranění. Podrobné informace o prostředcích, pro které jsou vyvolány události pro zdroje událostí, naleznete v podporovaných prostředcích v oznámeních o změnách rozhraní Microsoft Graph API .

Důležité

Schopnost rozhraní Microsoft Graph API odesílat události do služby Azure Event Grid je aktuálně ve verzi Public Preview. Pokud máte dotazy nebo potřebujete podporu, pošlete nám e-mail na adresu ask-graph-and-grid@microsoft.com.

Zdroj událostí Microsoftu Dostupné typy událostí
Microsoft Entra ID Typy událostí Microsoft Entra
Microsoft Outlook Typy událostí Aplikace Microsoft Outlook
Konverzace skupin Microsoftu 365
Microsoft Teams Typy událostí Microsoft Teams
Microsoft SharePoint a OneDrive
Microsoft SharePoint
Výstrahy zabezpečení
Konverzace Microsoftu
Microsoft Universal Print

Důležité

Pokud funkci Partnerské události neznáte, podívejte se na přehled partnerských událostí.

Proč se mám přihlásit k odběru událostí ze zdrojů rozhraní Microsoft Graph API přes Event Grid?

Kromě možnosti přihlásit se k odběru událostí rozhraní Microsoft Graph API prostřednictvím Event Gridu máte další možnosti , prostřednictvím kterých můžete dostávat podobná oznámení (ne události). Pokud máte aspoň jeden z následujících požadavků, zvažte použití rozhraní Microsoft Graph API k doručování událostí do Event Gridu:

  • Vyvíjíte řešení řízené událostmi, které vyžaduje události z Microsoft Entra ID, Outlooku, Teams atd. k reakci na změny prostředků. Vyžadujete robustní model událostí a možnosti publikování a odběru, které event Grid poskytuje. Přehled služby Event Grid najdete v tématu Koncepty služby Event Grid.
  • Službu Event Grid chcete použít ke směrování událostí do více cílů pomocí jednoho předplatného rozhraní Graph API a chcete se vyhnout správě více předplatných rozhraní Graph API.
  • V závislosti na některých vlastnostech události v události musíte směrovat události do různých podřízených aplikací, webhooků nebo služeb Azure. Můžete například chtít směrovat typy událostí, například Microsoft.Graph.UserCreatedMicrosoft.Graph.UserDeleted do specializované aplikace, která zpracovává onboarding a odpojování uživatelů. Můžete také chtít odesílat Microsoft.Graph.UserUpdated události do jiné aplikace, která například synchronizuje informace o kontaktech. Toho můžete dosáhnout pomocí jednoho odběru rozhraní Graph API při použití Event Gridu jako cíle oznámení. Další informace najdete v tématu Filtrování událostí a obslužné rutiny událostí.
  • Interoperabilita je pro vás důležitá. Události chcete směrovat a zpracovávat standardním způsobem pomocí standardu specifikace CloudEvents SPOLEČNOSTI CNCF.
  • Líbí se vám podpora rozšiřitelnosti, kterou poskytuje CloudEvents. Pokud například chcete trasovat události napříč kompatibilními systémy, použijte rozšíření CloudEvents Distributed Tracing. Přečtěte si další informace o dalších rozšířeních CloudEvents.
  • Chcete použít osvědčené přístupy řízené událostmi, které obor přijal.

Povolení toku událostí rozhraní Graph API do partnerského tématu

Požádáte rozhraní Microsoft Graph API o předávání událostí do tématu partnera služby Event Grid vytvořením předplatného rozhraní Graph API pomocí sad SDK pro Microsoft Graph API a postupujte podle kroků v odkazech na ukázky uvedené v této části. Informace o podpoře dostupných sad SDK najdete v podporovaných jazycích sady Microsoft Graph API SDK .

Obecné požadavky

Před implementací aplikace byste měli splnit tyto obecné požadavky, abyste mohli vytvářet a obnovovat předplatná rozhraní Microsoft Graph API:

Další požadavky specifické pro programovací jazyk podle výběru a vývojové prostředí, které používáte, najdete v odkazech s ukázkami rozhraní Microsoft Graph API, které najdete v další části.

Důležité

Podrobné pokyny k implementaci aplikace najdete v ukázkách s podrobnými pokyny , měli byste si přečíst všechny části tohoto článku, protože obsahují další důležité informace související s předáváním událostí rozhraní Microsoft Graph API pomocí Event Gridu.

Vytvoření předplatného rozhraní Microsoft Graph API

Když vytvoříte předplatné rozhraní Graph API, vytvoří se pro vás partnerské téma. V oznámení parametru předáte následující informace a určíte, jaké téma partnera se má vytvořit a přidružit k novému předplatnému Rozhraní Graph API:

  • název tématu partnera
  • název skupiny prostředků, ve které se vytvoří téma partnera
  • oblast (umístění)
  • Předplatné Azure

Tyto ukázky kódu ukazují, jak vytvořit předplatné rozhraní Graph API. Zobrazují příklady vytvoření předplatného pro příjem událostí od všech uživatelů v tenantovi Microsoft Entra ID při jejich vytváření, aktualizaci nebo odstranění.

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: Druh změn prostředků, pro které chcete přijímat události. Platné hodnoty: Updated, Deleteda Created. Můžete zadat jednu nebo více těchto hodnot oddělených čárkami.
  • notificationUrl: Identifikátor URI sloužící k definování tématu partnera, do kterého se události odesílají. Musí odpovídat následujícímu vzoru: 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>. Umístění (označované také jako oblast Azure) name je možné získat spuštěním příkazu az account list-locations . Nepoužívejte zobrazovaný název umístění. Nepoužívejte například "USA – středozápad". Místo toho použijte westcentralus. 
      az account list-locations
  • lifecycleNotificationUrl: Identifikátor URI sloužící k definování tématu partnera, do kterého microsoft.graph.subscriptionReauthorizationRequiredse události odesílají. Tato událost signalizuje, že brzy vyprší platnost předplatného rozhraní Graph API. Identifikátor URI se řídí stejným vzorem jako notificationUrl popsaný výše, pokud používáte Event Grid jako cíl událostí životního cyklu. V takovém případě by mělo být téma partnera stejné jako téma zadané v notificationUrl.
  • prostředek: prostředek, který generuje události, které oznamují změny stavu.
  • expirationDateTime: čas vypršení platnosti, kdy vyprší platnost předplatného, a tok událostí se zastaví. Musí odpovídat formátu uvedenému v dokumentu RFC 3339. Musíte zadat dobu vypršení platnosti, která je v rámci maximální povolené délky předplatného pro jednotlivé typy prostředků.
  • stav klienta. Tato vlastnost je nepovinná. Používá se k ověření volání aplikace obslužné rutiny události během doručování událostí. Další informace najdete v tématu Vlastnosti předplatného rozhraní Graph API.

Důležité

  • Název tématu partnera musí být jedinečný ve stejné oblasti Azure. Každá kombinace ID aplikace tenanta může vytvořit až 10 jedinečných témat partnera.

  • Při vývoji řešení mějte na paměti určité limity služeb rozhraní Graph API.

  • Existující předplatná rozhraní Graph API bez lifecycleNotificationUrl vlastnosti neobdrží události životního cyklu. Pokud chcete přidat vlastnost lifecycleNotificationUrl, měli byste odstranit stávající předplatné a vytvořit nové předplatné určující vlastnost během vytváření předplatného.

Poznámka:

Pokud vaše aplikace použije hlavičku x-ms-enable-features s vaším požadavkem k vytvoření předplatného Graph API během privátní verze Preview, měli byste ji odebrat, protože už není potřeba.

Po vytvoření předplatného Graph API máte partnerské téma vytvořené v Azure.

Prodloužení předplatného rozhraní Microsoft Graph API

Předplatné rozhraní Graph API musí vaše aplikace prodloužit před vypršením jeho platnosti, aby se zabránilo zastavení toku událostí. Rozhraní Microsoft Graph API podporuje události oznámení o životním cyklu, ke kterým se vaše aplikace může přihlásit k odběru. V současné době podporují všechny typy prostředků microsoft.graph.subscriptionReauthorizationRequiredrozhraní Microsoft Graph API , které se odesílají, když dojde k některé z následujících podmínek:

  • Platnost přístupového tokenu brzy vyprší.
  • Platnost předplatného rozhraní Graph API brzy vyprší.
  • Správce tenanta odvolal oprávnění aplikace ke čtení prostředku.

Pokud jste předplatné rozhraní Graph API po vypršení platnosti neprodloužili, musíte vytvořit nové předplatné rozhraní Graph API. Můžete se podívat na stejné téma partnera, které jste použili ve svém předplatném, jehož platnost vypršela, pokud vypršela po dobu kratší než 30 dnů. Pokud vypršela platnost předplatného rozhraní Graph API déle než 30 dní, nemůžete znovu použít stávající téma partnera. V takovém případě budete muset zadat název jiného tématu partnera. Případně můžete odstranit stávající téma partnera a vytvořit nové téma partnera se stejným názvem při vytváření předplatného rozhraní Graph API.

Obnovení předplatného rozhraní Microsoft Graph API

Po přijetí microsoft.graph.subscriptionReauthorizationRequired události by vaše aplikace měla prodloužit předplatné rozhraní Graph API provedením těchto akcí:

  1. Pokud jste při vytváření odběru rozhraní Graph API zadali tajný klíč klienta do vlastnosti clientState , tajný klíč klienta zahrnutý do události. Ověřte, že hodnota clientState události odpovídá hodnotě použité při vytváření odběru rozhraní Graph API.

  2. Ujistěte se, že aplikace má platný přístupový token, abyste mohli provést další krok. Další informace najdete v následujících ukázkách s podrobnými pokyny .

  3. Volejte některé z následujících dvou rozhraní API. Pokud volání rozhraní API proběhne úspěšně, tok oznámení změn se obnoví.

    • /reauthorize Zavolejte akci, aby se předplatné znovu autorizovalo, aniž by se prodloužilo datum vypršení platnosti.

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

    • Proveďte běžnou akci pro obnovení a obnovení předplatného současně.

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

{
   "expirationDateTime": "2024-04-30T11:00:00.0000000Z"
}

      Obnovení může selhat, pokud už aplikace nemá oprávnění k přístupu k prostředku. Pak může být nutné, aby aplikace získala nový přístupový token pro úspěšné opětovné ověření předplatného.

Problémy s autorizací nenahrazovat potřebu prodloužení předplatného před vypršením jeho platnosti. Životní cyklus přístupových tokenů a vypršení platnosti předplatného nejsou stejné. Platnost přístupového tokenu může vypršet před vaším předplatným. Je důležité se připravit na pravidelné opětovné ověření koncového bodu za účelem aktualizace přístupového tokenu. Opětovné ověření koncového bodu neprodlouží vaše předplatné. Prodloužením platnosti předplatného se ale také znovu vytvoří koncový bod.

Při obnovování nebo opětovném ověření předplatného rozhraní Graph API se stejné téma partnera zadané při vytvoření předplatného použije.

Při zadávání nové hodnoty expirationDateTime musí být od aktuálního času nejméně tři hodiny. V opačném případě může vaše aplikace brzy po obnovení přijímat microsoft.graph.subscriptionReauthorizationRequired události.

Příklady opětovného ověření předplatného rozhraní Graph API pomocí libovolného podporovaného jazyka najdete v tématu o opětovném ověření předplatného.

Příklady obnovení a opětovného ověření předplatného rozhraní Graph API pomocí některého z podporovaných jazyků najdete v žádosti o aktualizaci předplatného.

Ukázky s podrobnými pokyny

Dokumentace k rozhraní Microsoft Graph API poskytuje ukázky kódu s pokyny pro:

  • Nastavte vývojové prostředí podle konkrétních pokynů podle jazyka, který používáte. Pokyny také zahrnují, jak získat tenanta Microsoftu 365 pro účely vývoje.
  • Vytvořte předplatná rozhraní Graph API. Pokud chcete předplatné prodloužit, můžete volat rozhraní Graph API pomocí fragmentů kódu v části Jak prodloužit předplatné rozhraní Graph API výše.
  • Získejte ověřovací tokeny, které je můžete použít při volání rozhraní Microsoft Graph API.

Poznámka:

Pomocí Průzkumníka rozhraní Microsoft Graph API je možné vytvořit předplatné rozhraní Graph API. Ukázky byste měli dál používat pro další důležité aspekty vašeho řešení, jako je ověřování a příjem událostí.

Ukázky webových aplikací jsou k dispozici pro následující jazyky:

  • Ukázka jazyka C#. Toto je aktuální ukázka, která obsahuje postup vytvoření a obnovení předplatných rozhraní Graph API a provede vás některými kroky, jak povolit tok událostí.
  • Ukázka Javy
    • GraphAPIController obsahuje ukázkový kód pro vytvoření, odstranění a obnovení předplatného rozhraní Graph API. Musí se používat společně s ukázkovou aplikací v Javě výše.
  • Ukázka NodeJS

Důležité

Musíte aktivovat téma partnera, které se vytvoří v rámci vytváření předplatného rozhraní Graph API. Abyste mohli přijímat události, musíte také vytvořit odběr událostí Event Gridu pro webovou aplikaci. K tomu použijete adresu URL nakonfigurovanou ve webové aplikaci k příjmu událostí jako koncový bod webhooku ve vašem odběru událostí. Další informace najdete v dalších krocích .

Důležité

Potřebujete ukázkový kód pro jiný jazyk nebo máte dotazy? Pošlete nám prosím e-mail na adresu ask-graph-and-grid@microsoft.com.

Další kroky

Podle pokynů v následujících dvou krocích dokončete nastavení pro příjem událostí rozhraní Microsoft Graph API pomocí Event Gridu:

Další užitečné odkazy: