Odbieranie zdarzeń zmiany interfejsu API programu Microsoft Graph za pośrednictwem usługi Azure Event Grid (wersja zapoznawcza)

  • Artykuł

W tym artykule opisano kroki subskrybowania zdarzeń publikowanych przez interfejs API programu Microsoft Graph. W poniższej tabeli wymieniono źródła zdarzeń, dla których zdarzenia są dostępne za pośrednictwem interfejsu API programu Graph. W przypadku większości zasobów obsługiwane są zdarzenia ogłaszające tworzenie, aktualizowanie i usuwanie. Aby uzyskać szczegółowe informacje o zasobach, dla których zdarzenia są zgłaszane dla źródeł zdarzeń, zobacz obsługiwane zasoby za pomocą powiadomień o zmianie interfejsu API programu Microsoft Graph.

Ważne

Możliwość wysyłania zdarzeń do usługi Azure Event Grid przez interfejs API programu Microsoft Graph jest obecnie dostępna w publicznej wersji zapoznawczej. Jeśli masz pytania lub potrzebujesz pomocy technicznej, wyślij nam wiadomość e-mail na adres ask-graph-and-grid@microsoft.com.

Źródło zdarzeń firmy Microsoft Dostępne typy zdarzeń
Identyfikator usługi Microsoft Entra Typy zdarzeń entra firmy Microsoft
Microsoft Outlook Typy zdarzeń programu Microsoft Outlook
Konwersacje grupowe platformy Microsoft 365
Microsoft Teams Typy zdarzeń usługi Microsoft Teams
Microsoft SharePoint i OneDrive
Microsoft SharePoint
Alerty zabezpieczeń
Konwersacje firmy Microsoft
Microsoft Universal Print

Ważne

Jeśli nie znasz funkcji Zdarzenia partnerskie, zobacz Omówienie zdarzeń partnerskich.

Dlaczego należy subskrybować zdarzenia ze źródeł interfejsu API programu Microsoft Graph za pośrednictwem usługi Event Grid?

Oprócz możliwości subskrybowania zdarzeń interfejsu API programu Microsoft Graph za pośrednictwem usługi Event Grid dostępne są inne opcje , za pomocą których można otrzymywać podobne powiadomienia (a nie zdarzenia). Rozważ użycie interfejsu API programu Microsoft Graph do dostarczania zdarzeń do usługi Event Grid, jeśli masz co najmniej jedno z następujących wymagań:

  • Opracowujesz rozwiązanie sterowane zdarzeniami, które wymaga zdarzeń z identyfikatora Entra firmy Microsoft, programu Outlook, aplikacji Teams itp., aby reagować na zmiany zasobów. Potrzebujesz niezawodnego modelu zdarzeń i możliwości publikowania subskrypcji oferowanych przez usługę Event Grid. Aby zapoznać się z omówieniem usługi Event Grid, zobacz Pojęcia dotyczące usługi Event Grid.
  • Chcesz użyć usługi Event Grid do kierowania zdarzeń do wielu miejsc docelowych przy użyciu jednej subskrypcji interfejsu API programu Graph i chcesz uniknąć zarządzania wieloma subskrypcjami interfejsu API programu Graph.
  • Należy kierować zdarzenia do różnych aplikacji podrzędnych, elementów webhook lub usług platformy Azure w zależności od niektórych właściwości zdarzenia. Na przykład możesz chcieć kierować typy zdarzeń, takie jak Microsoft.Graph.UserCreated i Microsoft.Graph.UserDeleted do wyspecjalizowanej aplikacji, która przetwarza dołączanie i odłączanie użytkowników. Możesz również wysłać Microsoft.Graph.UserUpdated zdarzenia do innej aplikacji, która synchronizuje informacje o kontaktach, na przykład. Można to osiągnąć przy użyciu pojedynczej subskrypcji interfejsu API programu Graph podczas korzystania z usługi Event Grid jako miejsca docelowego powiadomień. Aby uzyskać więcej informacji, zobacz filtrowanie zdarzeń i procedury obsługi zdarzeń.
  • Współdziałanie jest dla Ciebie ważne. Chcesz przekazywać zdarzenia i obsługiwać je w standardowy sposób przy użyciu standardu specyfikacji CloudEvents firmy CNCF.
  • Podoba Ci się obsługa rozszerzalności zapewniana przez usługę CloudEvents. Jeśli na przykład chcesz śledzić zdarzenia w zgodnych systemach, użyj rozszerzenia CloudEvents Distributed Tracing. Dowiedz się więcej o rozszerzeniach CloudEvents.
  • Chcesz użyć sprawdzonych podejść opartych na zdarzeniach przyjętych przez branżę.

Włączanie zdarzeń interfejsu API programu Graph w celu przepływu do tematu partnera

Poprosisz interfejs API programu Microsoft Graph o przekazywanie zdarzeń do tematu partnera usługi Event Grid, tworząc subskrypcję interfejsu API programu Graph przy użyciu zestawów SDK interfejsu API programu Microsoft Graph i wykonując kroki opisane w linkach do przykładów podanych w tej sekcji. Zobacz Obsługiwane języki dla zestawu SDK interfejsu API programu Microsoft Graph, aby uzyskać dostępną obsługę zestawu SDK.

Ogólne wymagania wstępne

Przed wdrożeniem aplikacji w celu utworzenia i odnowienia subskrypcji interfejsu API programu Microsoft Graph należy spełnić te ogólne wymagania wstępne:

W poniższej sekcji znajdziesz inne wymagania wstępne specyficzne dla wybranego języka programowania i środowiska programistycznego używanego w linkach przykładów interfejsu API programu Microsoft Graph.

Ważne

Szczegółowe instrukcje implementacji aplikacji znajdują się w sekcjach przykładów ze szczegółowymi instrukcjami , ale należy przeczytać wszystkie sekcje tego artykułu, ponieważ zawierają dodatkowe, ważne informacje dotyczące przekazywania zdarzeń interfejsu API programu Microsoft Graph przy użyciu usługi Event Grid.

Jak utworzyć subskrypcję interfejsu API programu Microsoft Graph

Podczas tworzenia subskrypcji interfejsu API programu Graph zostanie utworzony temat partnera. Aby określić temat partnera, który ma zostać utworzony i skojarzony z nową subskrypcją interfejsu API programu Graph, należy przekazać następujące informacje w elemencie notificationUrl parametrów:

  • nazwa tematu partnera
  • nazwa grupy zasobów, w której jest tworzony temat partnera
  • region (lokalizacja)
  • Subskrypcja platformy Azure

Te przykłady kodu pokazują, jak utworzyć subskrypcję interfejsu API programu Graph. Przedstawiają przykłady tworzenia subskrypcji w celu odbierania zdarzeń od wszystkich użytkowników w dzierżawie identyfikatora Entra firmy Microsoft podczas ich tworzenia, aktualizowania lub usuwania.

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: rodzaj zmian zasobów, dla których chcesz odbierać zdarzenia. Prawidłowe wartości: Updated, Deletedi Created. Można określić jedną lub więcej z tych wartości rozdzielonych przecinkami.
  • notificationUrl: identyfikator URI używany do definiowania tematu partnera, do którego są wysyłane zdarzenia. Musi być zgodny z następującym wzorcem: 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>. Lokalizację (znaną również jako region świadczenia usługi Azure) name można uzyskać, wykonując polecenie az account list-locations . Nie używaj nazwy wyświetlanej lokalizacji. Na przykład nie używaj "Zachodnio-środkowe stany USA". Użycie w zamian parametru westcentralus. 
      az account list-locations
  • lifecycleNotificationUrl: identyfikator URI używany do definiowania tematu partnera, do którego microsoft.graph.subscriptionReauthorizationRequiredsą wysyłane zdarzenia. To zdarzenie sygnalizuje, że subskrypcja interfejsu API programu Graph wkrótce wygaśnie. Identyfikator URI jest zgodny z tym samym wzorcem co element notificationUrl opisany powyżej, jeśli używasz usługi Event Grid jako miejsca docelowego do zdarzeń cyklu życia. W takim przypadku temat partnera powinien być taki sam jak temat określony w elemencie notificationUrl.
  • resource: zasób, który generuje zdarzenia, które ogłaszają zmiany stanu.
  • expirationDateTime: czas wygaśnięcia subskrypcji i zatrzymanie przepływu zdarzeń. Musi być zgodny z formatem określonym w specyfikacji RFC 3339. Musisz określić czas wygaśnięcia, który mieści się w zakresie maksymalnej długości subskrypcji dozwolonej dla typu zasobu.
  • stan klienta. Ta właściwość jest opcjonalna. Służy do weryfikacji wywołań aplikacji obsługi zdarzeń podczas dostarczania zdarzeń. Aby uzyskać więcej informacji, zobacz Właściwości subskrypcji interfejsu API programu Graph.

Ważne

  • Nazwa tematu partnera musi być unikatowa w tym samym regionie świadczenia usługi Azure. Każda kombinacja identyfikatora aplikacji dzierżawy może tworzyć maksymalnie 10 unikatowych tematów partnerów.

  • Podczas opracowywania rozwiązania należy pamiętać o pewnych limitach usługi interfejsu API programu Graph.

  • Istniejące subskrypcje interfejsu API programu Graph bez lifecycleNotificationUrl właściwości nie odbierają zdarzeń cyklu życia. Aby dodać właściwość lifecycleNotificationUrl, należy usunąć istniejącą subskrypcję i utworzyć nową subskrypcję określającą właściwość podczas tworzenia subskrypcji.

Uwaga

Jeśli aplikacja używa nagłówka x-ms-enable-features z żądaniem utworzenia subskrypcji interfejsu API programu Graph w prywatnej wersji zapoznawczej, usuń ją, ponieważ nie jest już potrzebna.

Po utworzeniu subskrypcji interfejsu API programu Graph masz temat partnera utworzony na platformie Azure.

Odnawianie subskrypcji interfejsu API programu Microsoft Graph

Subskrypcja interfejsu API programu Graph musi zostać odnowiona przez aplikację, zanim wygaśnie, aby uniknąć zatrzymania przepływu zdarzeń. Aby ułatwić automatyzację procesu odnawiania, interfejs API programu Microsoft Graph obsługuje zdarzenia powiadomień cyklu życia, do których aplikacja może subskrybować. Obecnie wszystkie typy zasobów interfejsu API programu Microsoft Graph obsługują microsoft.graph.subscriptionReauthorizationRequiredelement , który jest wysyłany, gdy wystąpi dowolny z następujących warunków:

  • Token dostępu wkrótce wygaśnie.
  • Subskrypcja interfejsu API programu Graph wkrótce wygaśnie.
  • Administrator dzierżawy odwołał uprawnienia aplikacji do odczytu zasobu.

Jeśli subskrypcja interfejsu API programu Graph nie została odnowiona po wygaśnięciu, musisz utworzyć nową subskrypcję interfejsu API programu Graph. Możesz odwołać się do tego samego tematu partnera, który był używany w wygasłej subskrypcji, o ile wygasł przez mniej niż 30 dni. Jeśli subskrypcja interfejsu API programu Graph wygasła przez ponad 30 dni, nie możesz ponownie użyć istniejącego tematu partnera. W takim przypadku należy określić inną nazwę tematu partnera. Alternatywnie możesz usunąć istniejący temat partnera, aby utworzyć nowy temat partnera o tej samej nazwie podczas tworzenia subskrypcji interfejsu API programu Graph.

Jak odnowić subskrypcję interfejsu API programu Microsoft Graph

Po otrzymaniu microsoft.graph.subscriptionReauthorizationRequired zdarzenia aplikacja powinna odnowić subskrypcję interfejsu API programu Graph, wykonując następujące akcje:

  1. Jeśli wpis tajny klienta został podany we właściwości clientState podczas tworzenia subskrypcji interfejsu API programu Graph, klucz tajny klienta dołączony do zdarzenia. Sprawdź, czy wartość clientState zdarzenia jest zgodna z wartością użytą podczas tworzenia subskrypcji interfejsu API programu Graph.

  2. Upewnij się, że aplikacja ma prawidłowy token dostępu, aby wykonać następny krok. Więcej informacji znajduje się w kolejnych przykładach z szczegółową sekcją instrukcji .

  3. Wywołaj jeden z następujących dwóch interfejsów API. Jeśli wywołanie interfejsu API powiedzie się, przepływ powiadomień o zmianie zostanie wznowione.

    • Wywołaj /reauthorize akcję, aby ponownie uwierzytelnić subskrypcję bez rozszerzania daty wygaśnięcia.

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

    • Wykonaj regularną akcję "odnów", aby ponownie uwierzytelnić i odnowić subskrypcję w tym samym czasie.

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

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

      Odnawianie może zakończyć się niepowodzeniem, jeśli aplikacja nie ma już autoryzacji dostępu do zasobu. Może to być konieczne, aby aplikacja uzyskała nowy token dostępu, aby pomyślnie ponownie uwierzytelnić subskrypcję.

Wyzwania związane z autoryzacją nie zastępują potrzeby odnowienia subskrypcji przed jej wygaśnięciem. Cykle życia tokenów dostępu i wygasania subskrypcji nie są takie same. Token dostępu może wygasnąć przed subskrypcją. Ważne jest, aby przygotować się do regularnego ponownego uwierzytelniania punktu końcowego w celu odświeżenia tokenu dostępu. Ponowne uwierzytelnianie punktu końcowego nie spowoduje odnowienia subskrypcji. Jednak odnowienie subskrypcji spowoduje również ponowne uwierzytelnienie punktu końcowego.

Podczas odnawiania i/lub ponownego uwierzytelniania subskrypcji interfejsu API programu Graph ten sam temat partnera określony podczas tworzenia subskrypcji jest używany.

Podczas określania nowej daty wygaśnięciaDateTime musi to być co najmniej trzy godziny od bieżącego czasu. W przeciwnym razie aplikacja może odbierać microsoft.graph.subscriptionReauthorizationRequired zdarzenia wkrótce po odnowieniu.

Przykłady dotyczące ponownego uwierzytelniania subskrypcji interfejsu API programu Graph przy użyciu dowolnego z obsługiwanych języków można znaleźć w temacie Żądanie ponownego uwierzytelniania subskrypcji.

Aby zapoznać się z przykładami dotyczącymi odnawiania i ponownego uwierzytelniania subskrypcji interfejsu API programu Graph przy użyciu dowolnego z obsługiwanych języków, zobacz żądanie aktualizacji subskrypcji.

Przykłady ze szczegółowymi instrukcjami

Dokumentacja interfejsu API programu Microsoft Graph zawiera przykłady kodu z instrukcjami:

  • Skonfiguruj środowisko deweloperskie z określonymi instrukcjami zgodnie z używanym językiem. Instrukcje obejmują również sposób uzyskiwania dzierżawy platformy Microsoft 365 na potrzeby programowania.
  • Tworzenie subskrypcji interfejsu API programu Graph. Aby odnowić subskrypcję, możesz wywołać interfejs API programu Graph przy użyciu fragmentów kodu w temacie Jak odnowić subskrypcję interfejsu API programu Graph powyżej.
  • Uzyskiwanie tokenów uwierzytelniania w celu ich używania podczas wywoływania interfejsu API programu Microsoft Graph.

Uwaga

Istnieje możliwość utworzenia subskrypcji interfejsu API programu Graph przy użyciu Eksploratora interfejsu API programu Microsoft Graph. Nadal należy używać przykładów dla innych ważnych aspektów rozwiązania, takich jak uwierzytelnianie i odbieranie zdarzeń.

Przykłady aplikacji internetowych są dostępne dla następujących języków:

  • Przykład języka C#. Jest to aktualny przykład, który zawiera sposób tworzenia i odnawiania subskrypcji interfejsu API programu Graph oraz przeprowadzi Cię przez niektóre kroki umożliwiające przepływ zdarzeń.
  • Przykład języka Java
    • Narzędzie GraphAPIController zawiera przykładowy kod umożliwiający tworzenie, usuwanie i odnawianie subskrypcji interfejsu API programu Graph. Należy go użyć wraz z przykładową aplikacją Java powyżej.
  • Przykład środowiska NodeJS.

Ważne

Musisz aktywować temat partnera utworzony w ramach tworzenia subskrypcji interfejsu API programu Graph. Należy również utworzyć subskrypcję zdarzeń usługi Event Grid w aplikacji internetowej w celu odbierania zdarzeń. W tym celu użyjesz adresu URL skonfigurowanego w aplikacji internetowej do odbierania zdarzeń jako punktu końcowego elementu webhook w ramach subskrypcji zdarzeń. Następne kroki , aby uzyskać więcej informacji.

Ważne

Czy potrzebujesz przykładowego kodu dla innego języka lub masz pytania? Wyślij nam wiadomość e-mail na adres ask-graph-and-grid@microsoft.com.

Następne kroki

Postępuj zgodnie z instrukcjami w następujących dwóch krokach, aby ukończyć konfigurowanie w celu odbierania zdarzeń interfejsu API programu Microsoft Graph przy użyciu usługi Event Grid:

Inne przydatne linki: