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

Interfejs API programu Microsoft Graph udostępnia powiadomienia o zmianach dla zasobów w usługach platformy Microsoft 365, w tym microsoft Entra ID, Teams, Outlook i OneDrive. Subskrybując te zdarzenia przez Azure Event Grid, możesz tworzyć aplikacje oparte na zdarzeniach, które reagują na zmiany zasobów w czasie rzeczywistym.

W tym artykule wyjaśniono, jak:

  • Utwórz subskrypcje interfejsu API Microsoft Graph, które dostarczają zdarzenia do tematów partnerskich usługi Azure Event Grid.
  • Zarządzanie cyklami życia subskrypcji przy użyciu automatycznego odnawiania.
  • Trasowanie zdarzeń do wielu miejsc docelowych, korzystając z funkcji filtrowania i routingu Event Grid.

Usługa Azure Event Grid oferuje kilka zalet w porównaniu z tradycyjnymi subskrypcjami interfejsu API programu Microsoft Graph opartymi na elementach webhook:

  • Uproszczony routing: użyj pojedynczej subskrypcji interfejsu API programu Graph do wysyłania zdarzeń do wielu miejsc docelowych.
  • Zaawansowane filtrowanie: kierowanie określonych typów zdarzeń do różnych aplikacji na podstawie właściwości zdarzenia.
  • Zgodność ze standardami: odbieranie zdarzeń w formacie CloudEvents w celu lepszego współdziałania.
  • Niezawodność: Wbudowana logika ponawiania prób i kolejki wiadomości nie do dostarczenia zapewniają niezawodne dostarczanie zdarzeń.

Obsługiwane źródła zdarzeń

Poniższa tabela przedstawia źródła zdarzeń, dla których można uzyskać zdarzenia za pomocą interfejs Graph API. Dla większości zasobów interfejs Graph API obsługuje zdarzenia ogłaszające ich tworzenie, aktualizację i usuwanie. Szczegółowe informacje o zasobach, które generują zdarzenia dla źródeł zdarzeń, można znaleźć w artykule o powiadomieniach o zmianach wspieranych przez Microsoft interfejs Graph API.

Źródło zdarzeń firmy Microsoft Zasoby Dostępne typy zdarzeń
Microsoft Entra ID Użytkownik, grupa Typy zdarzeń Microsoft Entra ID
Microsoft Outlook Wydarzenie (spotkanie w kalendarzu), Wiadomość (e-mail), Kontakt Typy zdarzeń programu Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (spotkanie) Typy zdarzeń usługi Microsoft Teams
OneDrive Element dysku Zdarzenia usługi Microsoft OneDrive
Microsoft SharePoint Lista Zdarzenia programu Microsoft SharePoint
Do wykonania Zadanie do wykonania Zdarzenia Microsoft ToDo
Alerty zabezpieczeń Alarm Zdarzenia alertu zabezpieczeń firmy Microsoft
Drukowanie w chmurze Drukarka, Definicja zadania drukowania Zdarzenia drukowania w chmurze firmy Microsoft
Konwersacje firmy Microsoft Konwersacja Zdarzenia konwersacji grupowej platformy Microsoft 365

Utwórz subskrypcję Microsoft interfejs Graph API, aby umożliwić przepływ zdarzeń Microsoft interfejs Graph API do partnerskiego tematu. interfejs Graph API automatycznie tworzy temat partnera podczas tworzenia subskrypcji. Ten temat partnera umożliwia tworzenie subskrypcji zdarzeń w celu wysyłania zdarzeń do dowolnego z obsługiwanych programów obsługi zdarzeń spełniających najlepiej wymagania dotyczące przetwarzania zdarzeń.

Ważne

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

Dlaczego subskrybować wydarzenia ze źródeł Microsoft interfejs Graph API przez Event Grid?

Poza subskrypcją zdarzeń Microsoft interfejs Graph API przez Event Grid, masz też inne opcje otrzymywania podobnych powiadomień (nie zdarzeń). Użyj interfejsu API programu Microsoft Graph, aby dostarczać zdarzenia do usługi Event Grid, jeśli spełniasz co najmniej jedno z następujących wymagań:

  • Opracowujesz rozwiązanie sterowane zdarzeniami, które używa zdarzeń z identyfikatora Entra firmy Microsoft, programu Outlook lub usługi Teams w celu reagowania na zmiany zasobów. Potrzebujesz niezawodnego modelu opartego na zdarzeniach 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żywać Event Grid do kierowania zdarzeń do wielu miejsc docelowych za pomocą jednej subskrypcji interfejs Graph API i unikać zarządzania wieloma subskrypcjami interfejs Graph API.
  • Zdarzenia należy kierować do różnych aplikacji podrzędnych, elementów webhook lub usług platformy Azure na podstawie niektórych właściwości zdarzenia. Na przykład możesz chcieć kierować typy zdarzeń, takie jak Microsoft.Graph.UserUpdated 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żesz to osiągnąć, korzystając z jednej subskrypcji interfejs Graph API, gdy używasz Event Grid jako miejsca powiadomień. Aby uzyskać więcej informacji, zobacz filtrowanie zdarzeń i procedury obsługi zdarzeń.
  • Współdziałanie jest dla Ciebie ważne. Chcesz przekazywać i obsługiwać zdarzenia w standardowy sposób, korzystając ze standardowej specyfikacji CloudEvents Cloud Native Computing Foundation (CNCF).
  • Doceniasz obsługę rozszerzalności, którą zapewnia CloudEvents. Na przykład w celu śledzenia zdarzeń w zgodnych systemach użyj rozszerzenia CloudEvents Distributed Tracing. Dowiedz się więcej o rozszerzeniach CloudEvents.
  • Stosujesz sprawdzone, oparte na wydarzeniach podejścia, które branża stosuje.

Włącz zdarzenia API Graph, aby przepływały do tematu partnera

Poproś 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 (Software Development Kit) 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 zestawu SDK interfejsu API Microsoft Graph w celu sprawdzenia dostępnego wsparcia SDK.

Ogólne wymagania wstępne

Przed wdrożeniem aplikacji do tworzenia i odnawiania subskrypcji Microsoft interfejs Graph API, upewnij się, że spełniasz następujące ogólne wymagania:

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 można znaleźć w poniższej sekcji.

Ważne

Szczegółowe instrukcje implementacji aplikacji znajdują się w sekcji przykładowe z szczegółowymi instrukcjami, ale przeczytaj wszystkie sekcje tego artykułu, ponieważ zawierają one ważniejsze informacje dotyczące przekazywania zdarzeń Microsoft interfejs Graph API za pomocą Event Grid.

Jak utworzyć subskrypcję interfejsu API programu Microsoft Graph

Gdy tworzysz subskrypcję interfejs Graph API, system tworzy dla Ciebie temat partnerski. Przesyłasz następujące informacje do parametru notificationUrl, aby określić temat partnera do utworzenia i powiązania z nową subskrypcją interfejs Graph API:

  • nazwa tematu partnera
  • Nazwa grupy zasobów dla tematu partnerskiego
  • region (lokalizacja)
  • Subskrypcja platformy Azure

Te przykłady kodu pokazują, jak utworzyć subskrypcję interfejsu API programu Graph. Obejmują one przykłady tworzenia subskrypcji do odbierania zdarzeń od wszystkich użytkowników w dzierżawie Microsoft Entra ID, gdy są tworzone, aktualizowane lub usuwane.

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: rodzaj zmian zasobów, dla których chcesz odbierać zdarzenia. Poprawne wartości: Updated oraz Deleted (Created nie jest obsługiwane przez interfejs Graph API; sprawdź dokumentację interfejs Graph API po więcej szczegółów). 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>. Aby uzyskać lokalizację (znaną również jako region Azure), nameuruchom polecenieaz account list-locations. Nie używaj nazwy wyświetlanej lokalizacji. Na przykład nie używaj West Central US. Użycie w zamian parametru westcentralus.

    az account list-locations
    
  • lifecycleNotificationUrl: URI używane do definiowania tematu partnera, do którego microsoft.graph.subscriptionReauthorizationRequired wysyłane są zdarzenia. To zdarzenie informuje twoją aplikację, że subskrypcja interfejs Graph API wkrótce wygaśnie. URI podąża tym samym wzorcem co notificationUrl opisany wcześniej, jeśli używasz Event Grid jako miejsca docelowego dla 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 ogłaszające zmiany stanu.

  • expirationDateTime: czas wygaśnięcia, po którym subskrypcja wygasa, a przepływ zdarzeń się zatrzymuje. Musi być zgodny z formatem określonym w Request for Comments (RFC) 3339. Musisz określić czas wygaśnięcia, który mieści się w maksymalnej dozwolonej długości subskrypcji dla danego typu zasobu.

  • clientState: użyj tej opcjonalnej właściwości do weryfikowania wywołań kierowanych do aplikacji obsługującej zdarzenia 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 Graph bez właściwości lifecycleNotificationUrl nie otrzymują zdarzeń cyklu życia. Aby dodać właściwość lifecycleNotificationUrl, usuń istniejącą subskrypcję i utwórz nową, która określa tę właściwość podczas tworzenia subskrypcji.

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

Odnawianie subskrypcji interfejsu API programu Microsoft Graph

Odnów subskrypcję interfejsu interfejs Graph API zanim wygaśnie, żeby nie doszło do zatrzymania przepływu zdarzeń. Aby zautomatyzować proces odnowienia, Microsoft interfejs Graph API obsługuje powiadomienia o cyklu życia, na które aplikacje mogą się subskrybować. Obecnie wszystkie typy zasobów Microsoft interfejs Graph API obsługują microsoft.graph.subscriptionReauthorizationRequired to zdarzenie, które jest wysyłane, gdy wystąpi którykolwiek z następujących warunków:

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

Jeśli subskrypcja interfejsu API programu Graph nie zostanie odnowiona po wygaśnięciu, utwórz nową subskrypcję interfejsu API programu Graph. Możesz odnieść się do tego samego tematu partnerskiego, który był używany w wygasłej subskrypcji, o ile wygasła ona mniej niż 30 dni temu. Jeśli subskrypcja interfejs Graph API wygasła od ponad 30 dni, nie możesz ponownie użyć istniejącego tematu partnera. W takim przypadku musisz podać nazwę innego tematu partnerskiego. 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

Gdy Twoja aplikacja otrzyma zdarzeniemicrosoft.graph.subscriptionReauthorizationRequired, powinna odnowić subskrypcję interfejs Graph API:

  1. Jeśli podałeś sekret klienta w właściwości clientState podczas tworzenia subskrypcji interfejs Graph API, zdarzenie zawiera ten sekret klienta. 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. Nadchodząca sekcja z przykładami z szczegółowymi instrukcjami zawiera więcej informacji.

  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 wznowiony.

    • 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": "2026-09-30T11:00:00.0000000Z"
      }
      

      Odnawianie może się nie udać, jeśli aplikacja nie jest już autoryzowana do dostępu do zasobu. Aplikacja może wtedy potrzebować nowego tokena dostępu, aby ponownie autoryzować 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ą. Przygotuj się na regularne ponowne autoryzowanie swojego punktu końcowego, aby odświeżyć token dostępu. Ponowne uwierzytelnianie punktu końcowego nie odnawia subskrypcji. Jednak odnowienie subskrypcji również ponownie uwierzytelnia punkt końcowy.

Gdy odnawiasz lub ponownie autoryzujesz subskrypcję interfejs Graph API, używa ona tego samego tematu partnera, który określiłeś przy tworzeniu subskrypcji.

Gdy określasz nową wartość expirationDateTime, upewnij się, że przypada ona co najmniej trzy godziny od bieżącego momentu. W przeciwnym razie aplikacja może odbierać microsoft.graph.subscriptionReauthorizationRequired zdarzenia wkrótce po odnowieniu.

Przykłady dotyczące ponownego autoryzowania subskrypcji interfejs Graph API przy użyciu dowolnego z obsługiwanych języków można znaleźć w artykule o wniosek o ponowne autoryzowanie subskrypcji.

Przykłady odnawiania i ponownego autoryzowania subskrypcji interfejs Graph API przy użyciu dowolnego z obsługiwanych języków można znaleźć w artykule Update Subscription request.

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.
  • Stwórz subskrypcję interfejs Graph API. Aby odnowić subskrypcję, wywołaj interfejs Graph API, korzystając z fragmentów kodu w Jak odnowić subskrypcję interfejs Graph API.
  • Uzyskiwanie tokenów uwierzytelniania w celu ich używania podczas wywoływania interfejsu API programu Microsoft Graph.

Uwaga

Możesz utworzyć swoją subskrypcję interfejs Graph API, korzystając z Eksploratora Microsoft interfejs Graph API. Nadal powinno się korzystać z 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:

Ważne

Musisz aktywować temat partnera utworzony podczas tworzenia subskrypcji interfejsu API 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ń.

Ważne

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

Aby otrzymywać zdarzenia Microsoft interfejs Graph API przez Event Grid, wykonaj następujące dwa kroki: