Share via

A Microsoft Graph API változási eseményeinek fogadása az Azure Event Griden keresztül

  • Cikk

Ez a cikk a Microsoft Graph API által közzétett eseményekre való feliratkozás lépéseit ismerteti. Az alábbi táblázat felsorolja azokat az eseményforrásokat, amelyekhez az események a Graph API-n keresztül érhetők el. A legtöbb erőforrás esetében a létrehozást, frissítést és törlést bejelentő események támogatottak. Az eseményforrásokhoz létrehozott erőforrásokról a Microsoft Graph API által támogatott változásértesítések című témakörben talál részletes információt.

Microsoft eseményforrás Források Elérhető eseménytípusok
Microsoft Entra ID Felhasználó, csoport Microsoft Entra-eseménytípusok
Microsoft Outlook Esemény (naptárértekezlet), Üzenet (e-mail), Kapcsolatfelvétel Microsoft Outlook-eseménytípusok
Microsoft Teams ChatMessage, CallRecord (értekezlet) Microsoft Teams-eseménytípusok
OneDrive DriveItem Microsoft OneDrive-események
Microsoft SharePoint Lista Microsoft SharePoint-események
Teendő Feladat elvégzéséhez Microsoft ToDo-események
Biztonsági riasztások Éber Microsoft Security Alert-események
Felhőalapú nyomtatás Nyomtató, nyomtatási feladatdefiníció Microsoft Cloud Printing-események
Microsoft-beszélgetések Beszélgetés Microsoft 365 Csoportos beszélgetési események

Microsoft Graph API-előfizetést hoz létre, amely lehetővé teszi a Graph API-események partnertémakörbe való átvitelét. A partnertéma automatikusan létrejön Önnek a Graph API-előfizetés létrehozása során. Ezzel a partnertémával esemény-előfizetéseket hozhat létre, hogy az eseményeket a követelményeknek leginkább megfelelő támogatott eseménykezelőknek küldje el az események feldolgozásához.

Fontos

Ha nem ismeri a Partneresemények funkciót, tekintse meg a Partneresemények áttekintését.

Miért érdemes előfizetnem a Microsoft Graph API-forrásokból származó eseményekre az Event Griden keresztül?

AMellett, hogy feliratkozhat a Microsoft Graph API-eseményekre az Event Griden keresztül, más lehetőségek is rendelkezésre állnak, amelyeken keresztül hasonló értesítéseket kaphat (nem eseményeket). Ha rendelkezik legalább az alábbi követelmények valamelyikével, fontolja meg, hogy a Microsoft Graph API-val eseményeket kézbesítsen az Event Gridnek:

  • Olyan eseményvezérelt megoldást fejleszt, amely megköveteli, hogy a Microsoft Entra ID, az Outlook, a Teams stb. eseményei reagáljanak az erőforrás-változásokra. Az Event Grid által biztosított robusztus eseménymodellre és közzétételi előfizetési képességekre van szükség. Az Event Grid áttekintése: Event Grid-fogalmak.
  • Az Event Grid használatával több célhelyre szeretné irányítani az eseményeket egyetlen Graph API-előfizetés használatával, és nem szeretne több Graph API-előfizetést kezelni.
  • Az eseményeket különböző alárendelt alkalmazásokhoz, webhookokhoz vagy Azure-szolgáltatásokhoz kell irányítania az esemény egyes tulajdonságaitól függően. Előfordulhat például, hogy olyan eseménytípusokat szeretne irányítani, mint például Microsoft.Graph.UserCreatedMicrosoft.Graph.UserDeleted egy speciális alkalmazás, amely feldolgozza a felhasználók előkészítési és kiszállási folyamatait. Előfordulhat, hogy eseményeket is szeretne küldeni Microsoft.Graph.UserUpdated egy másik alkalmazásnak, amely például szinkronizálja a névjegyadatokat. Ezt egyetlen Graph API-előfizetéssel érheti el, ha az Event Gridet értesítési célként használja. További információ: eseményszűrés és eseménykezelők.
  • Az együttműködési képesség fontos Önnek. Az eseményeket szabványos módon szeretné továbbítani és kezelni a Cloud Native Computing Foundation (CNCF) CloudEvents specifikációs szabványával.
  • Önnek tetszik a CloudEvents által nyújtott bővíthetőségi támogatás. Ha például eseményeket szeretne nyomon követni a megfelelő rendszerek között, használja a CloudEvents Elosztott nyomkövetés bővítményt. További információ a CloudEvents további bővítményeiről.
  • Az iparág által alkalmazott bevált eseményvezérelt megközelítéseket szeretné használni.

A Graph API-események átvitelének engedélyezése a partnertémakörbe

Arra kéri a Microsoft Graph API-t, hogy továbbítsa az eseményeket egy Event Grid-partnertémakörbe, hozzon létre egy Graph API-előfizetést a Microsoft Graph API szoftverfejlesztői készletei (SDK-k) használatával, és kövesse az ebben a szakaszban megadott mintákra mutató hivatkozások lépéseit. Az elérhető SDK-támogatásért tekintse meg a Microsoft Graph API SDK támogatott nyelveit.

Általános előfeltételek

A Microsoft Graph API-előfizetések létrehozásához és megújításához az alkalmazás implementálása előtt meg kell felelnie ezeknek az általános előfeltételeknek:

A Microsoft Graph API-minták hivatkozásaiban megtalálja a választott programozási nyelvre és a fejlesztési környezetre vonatkozó egyéb előfeltételeket, amelyeket egy következő szakaszban talál.

Fontos

Bár az alkalmazás implementálására vonatkozó részletes utasításokat a minták tartalmazzák, a jelen cikk összes szakaszát el kell olvasnia, mivel ezek további, fontos információkat tartalmaznak a Microsoft Graph API-események Event Grid használatával történő továbbításáról.

Microsoft Graph API-előfizetés létrehozása

Graph API-előfizetés létrehozásakor létrejön egy partnertémakör. A paraméterértesítésben a következő információkat adja meg, hogy megadhatja, milyen partnertémakört szeretne létrehozni és társítani az új Graph API-előfizetéshez:

  • partnertémakör neve
  • erőforráscsoport neve, amelyben a partnertémakör létrejött
  • régió (hely)
  • Azure-előfizetés

Ezek a kódminták bemutatják, hogyan hozhat létre Graph API-előfizetést. Példákat mutatnak be arra, hogyan hozhat létre előfizetést, amely a Microsoft Entra ID-bérlő összes felhasználójától fogad eseményeket a létrehozásuk, frissítésük vagy törlésükkor.

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: azon erőforrásváltozások típusa, amelyekhez eseményeket szeretne fogadni. Érvényes értékek: Updated, Deletedés Created. Megadhat egy vagy több értéket vesszővel elválasztva.
  • notificationUrl: egy URI, amely meghatározza azt a partnertémakört, amelybe az eseményeket küldi. Ennek meg kell felelnie a következő mintának: 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>. A hely (más néven Azure-régió) name az az account list-locations parancs végrehajtásával szerezhető be. Ne használjon helymegjelenítési nevet. Például ne használja az USA nyugati középső régióját. A westcentralus használható helyette. 
      az account list-locations
  • lifecycleNotificationUrl: egy URI, amely meghatározza azt a partnertémakört, amelybe microsoft.graph.subscriptionReauthorizationRequiredaz eseményeket küldi. Ez az esemény azt jelzi az alkalmazásnak, hogy a Graph API-előfizetés hamarosan lejár. Az URI ugyanazt a mintát követi, mint a korábban ismertetett notificationUrl , ha az Event Gridet használja az életciklus-események célként. Ebben az esetben a partnertémakörnek meg kell egyeznie a notificationUrlben megadott témakörével.
  • erőforrás: az állapotváltozásokat bejelentő eseményeket létrehozó erőforrás.
  • expirationDateTime: az előfizetés lejárati ideje és az események folyamata leáll. Meg kell felelnie a 3339-ben megadott formátumnak. Olyan lejárati időt kell megadnia, amely az erőforrástípusonként megengedett maximális előfizetési hosszon belül van.
  • ügyfélállapot. Ez a tulajdonság opcionális. Ez az eseménykezelő alkalmazáshoz intézett hívások ellenőrzésére szolgál az eseménykézbesítés során. További információ: Graph API-előfizetés tulajdonságai.

Fontos

  • A partnertémakör nevének egyedinek kell lennie ugyanazon az Azure-régión belül. A bérlő-alkalmazásazonosító kombinációk legfeljebb 10 egyedi partnertémát hozhatnak létre.

  • Ügyeljen a Graph API-erőforrások bizonyos szolgáltatási korlátaira a megoldás fejlesztésekor.

  • A tulajdonság nélküli lifecycleNotificationUrl meglévő Graph API-előfizetések nem kapnak életciklus-eseményeket. Az életciklusNotificationUrl tulajdonság hozzáadásához törölnie kell a meglévő előfizetést, és létre kell hoznia egy új előfizetést, amely megadja a tulajdonságot az előfizetés létrehozása során.

A Graph API-előfizetés létrehozása után létrejön egy partnertémakör az Azure-ban.

Microsoft Graph API-előfizetés megújítása

Az alkalmazásnak meg kell újítania a Graph API-előfizetést, mielőtt lejár, hogy elkerülje az események áramlásának leállítását. A megújítási folyamat automatizálásához a Microsoft Graph API támogatja az életciklus-értesítések eseményeit , amelyekre az alkalmazás előfizethet. Jelenleg a Microsoft Graph API-erőforrások összes típusa támogatja a microsoft.graph.subscriptionReauthorizationRequiredkövetkező feltételek bármelyike esetén küldhető el:

  • A hozzáférési jogkivonat hamarosan lejár.
  • A Graph API-előfizetés hamarosan lejár.
  • A bérlői rendszergazda visszavonta az alkalmazás engedélyeit egy erőforrás olvasásához.

Ha nem újította meg a Graph API-előfizetést a lejárat után, létre kell hoznia egy új Graph API-előfizetést. A lejárt előfizetésben használt partnertémakörre is hivatkozhat, feltéve, hogy az 30 napnál rövidebb ideig lejárt. Ha a Graph API-előfizetés 30 napnál hosszabb ideig járt le, nem használhatja újra a meglévő partnertémakört. Ebben az esetben vagy meg kell adnia egy másik partnertémakör-nevet. Másik lehetőségként törölheti a meglévő partnertémakört, ha a Graph API-előfizetés létrehozásakor egy azonos nevű új partnertémakört hoz létre.

Microsoft Graph API-előfizetés megújítása

Az esemény fogadása microsoft.graph.subscriptionReauthorizationRequired után az alkalmazásnak meg kell újítania a Graph API-előfizetést az alábbi műveletek elvégzésével:

  1. Ha a Graph API-előfizetés létrehozásakor az ügyfélkulcsot a clientState tulajdonságban adta meg, az ügyfél titkos kódját az esemény tartalmazza. Ellenőrizze, hogy az esemény clientState értéke megegyezik-e a Graph API-előfizetés létrehozásakor használt értékkel.

  2. Győződjön meg arról, hogy az alkalmazás rendelkezik érvényes hozzáférési jogkivonattal a következő lépéshez. További információt a következő mintákban talál a részletes utasítások szakaszában.

  3. Hívja meg az alábbi két API egyikét. Ha az API-hívás sikeres, a változásértesítési folyamat folytatódik.

    • Hívja meg a /reauthorize műveletet az előfizetés újbóli létrehozásához a lejárati dátum meghosszabbítása nélkül.

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

    • Végezzen rendszeres "megújítási" műveletet az előfizetés egyidejű újrahitelesítéséhez és megújításához.

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

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

      A megújítás sikertelen lehet, ha az alkalmazás már nem jogosult az erőforráshoz való hozzáférésre. Előfordulhat, hogy az alkalmazásnak új hozzáférési jogkivonatot kell beszereznie az előfizetés sikeres újbóli létrehozásához.

Az engedélyezési kihívások nem helyettesítik az előfizetés megújításának szükségességét a lejárat előtt. A hozzáférési jogkivonatok és az előfizetés lejárati életciklusa nem azonos. Előfordulhat, hogy a hozzáférési jogkivonat az előfizetés előtt lejár. Fontos, hogy felkészüljön arra, hogy rendszeresen újrahitelesítse a végpontot a hozzáférési jogkivonat frissítéséhez. A végpont ismételt hitelesítése nem újítja meg az előfizetést. Az előfizetés megújítása azonban a végpontot is újrahitelesíti.

A Graph API-előfizetés megújítása és/vagy újrahitelesítése során ugyanaz a partnertémakör van megadva, amikor az előfizetés létrejött.

Új lejáratiDateTime megadásakor az aktuális időponttól számított legalább három órának kell lennie. Ellenkező esetben előfordulhat, hogy az alkalmazás nem sokkal a megújítás után eseményeket kap microsoft.graph.subscriptionReauthorizationRequired .

A Graph API-előfizetés bármely támogatott nyelv használatával történő újrahitelesítésére vonatkozó példákért tekintse meg az előfizetés újraauthorize kérését.

A Graph API-előfizetés bármely támogatott nyelv használatával történő megújításával és újbóli hitelesítésével kapcsolatos példákért tekintse meg az előfizetés frissítésére vonatkozó kérést.

Minták részletes útmutatással

A Microsoft Graph API dokumentációja kódmintákat tartalmaz a következőkhöz:

  • Állítsa be a fejlesztői környezetet a használt nyelvnek megfelelő konkrét utasításokkal. Az utasítások azt is tartalmazzák, hogyan szerezhet be Microsoft 365-bérlőt fejlesztési célokra.
  • Graph API-előfizetések létrehozása. Az előfizetés megújításához meghívhatja a Graph API-t a Graph API-előfizetés megújítása című témakör kódrészleteinek használatával.
  • Hitelesítési jogkivonatok lekérése a Microsoft Graph API meghívásához.

Feljegyzés

A Graph API-előfizetés a Microsoft Graph API Explorerrel hozható létre. A mintákat továbbra is érdemes használnia a megoldás egyéb fontos aspektusaihoz, például a hitelesítéshez és az események fogadásához.

A webalkalmazás-minták a következő nyelvekhez érhetők el:

  • C#-minta. Ez egy naprakész minta, amely bemutatja, hogyan hozhat létre és újíthat meg Graph API-előfizetéseket, és végigvezeti az események folyamatának engedélyezésének néhány lépésén.
  • Java-minta
    • A GraphAPIController mintakódot tartalmaz a Graph API-előfizetés létrehozásához, törléséhez és megújításához. A Java-mintaalkalmazással együtt kell használni.
  • NodeJS-minta.

Fontos

Aktiválnia kell a Graph API-előfizetés létrehozásakor létrehozott partnertémakört. Event Grid-esemény-előfizetést is létre kell hoznia a webalkalmazáshoz az események fogadásához. Ennek érdekében a webalkalmazásban konfigurált URL-cím használatával fogadhatja az eseményeket webhook-végpontként az esemény-előfizetésben. További információkért kövesse a következő lépéseket .

Fontos

Szüksége van mintakódra egy másik nyelvhez, vagy kérdése van? Kérjük, küldjön e-mailt a következő címre ask-graph-and-grid@microsoft.com: .

Következő lépések

A Microsoft Graph API-események Event Grid használatával történő fogadásához kövesse az alábbi két lépés utasításait:

Egyéb hasznos hivatkozások: