Azure Event Grid aracılığıyla Microsoft Graph API değişiklik olaylarını alma (önizleme)

  • Makale

Bu makalede, Microsoft Graph API tarafından yayımlanan olaylara abone olma adımları açıklanmaktadır. Aşağıdaki tabloda, Graph API aracılığıyla olayların kullanılabildiği olay kaynakları listelenir. Çoğu kaynak için, oluşturulması, güncelleştirilip silinmesini duyuran olaylar desteklenir. Olay kaynakları için olayların oluşturulduğu kaynaklar hakkında ayrıntılı bilgi için bkz . Microsoft Graph API değişiklik bildirimleri tarafından desteklenen kaynaklar.

Önemli

Microsoft Graph API'lerinin Azure Event Grid'e olay gönderme özelliği şu anda genel önizleme aşamasındadır. Sorularınız varsa veya desteğe ihtiyacınız varsa adresinden bize ask-graph-and-grid@microsoft.come-posta gönderin.

Microsoft olay kaynağı Kullanılabilir olay türleri
Microsoft Entra Kimliği Microsoft Entra olay türleri
Microsoft Outlook Microsoft Outlook olay türleri
Microsoft 365 grup konuşmaları
Microsoft Teams Microsoft Teams olay türleri
Microsoft SharePoint ve OneDrive
Microsoft SharePoint
Güvenlik uyarıları
Microsoft Konuşmaları
Microsoft Universal Print

Önemli

İş Ortağı Olayları özelliğini bilmiyorsanız bkz. İş Ortağı Olaylarına genel bakış.

Event Grid aracılığıyla Neden Microsoft Graph API kaynaklarından olaylara abone yapmalıyım?

Event Grid aracılığıyla Microsoft Graph API olaylarına abone olma özelliğinin yanı sıra, benzer bildirimleri (olayları değil) alabileceğiniz başka seçenekleriniz de vardır. Aşağıdaki gereksinimlerden en az birine sahipseniz Olayları Event Grid'e teslim etmek için Microsoft Graph API'sini kullanmayı göz önünde bulundurun:

  • Kaynak değişikliklerine tepki vermek için Microsoft Entra ID, Outlook, Teams vb. olaylarını gerektiren olay odaklı bir çözüm geliştirıyorsunuz. Event Grid'in sağladığı güçlü olay modeline ve yayımlama-abone olma özelliklerine ihtiyacınız vardır. Event Grid'e genel bakış için bkz . Event Grid kavramları.
  • Tek bir Graph API aboneliği kullanarak olayları birden çok hedefe yönlendirmek için Event Grid kullanmak ve birden çok Graph API aboneliğini yönetmekten kaçınmak istiyorsunuz.
  • Olaydaki bazı özelliklere bağlı olarak olayları farklı aşağı akış uygulamalarına, web kancalarına veya Azure hizmetlerine yönlendirmeniz gerekir. Örneğin, ve gibi Microsoft.Graph.UserCreated olay türlerini kullanıcıların ekleme ve Microsoft.Graph.UserDeleted çıkarma işlemlerini işleyen özel bir uygulamaya yönlendirmek isteyebilirsiniz. Örneğin, kişi bilgilerini eşitleyen başka bir uygulamaya da olay göndermek Microsoft.Graph.UserUpdated isteyebilirsiniz. Event Grid'i bildirim hedefi olarak kullanırken tek bir Graph API aboneliği kullanarak bunu başarabilirsiniz. Daha fazla bilgi için bkz . olay filtreleme ve olay işleyicileri.
  • Birlikte çalışabilirlik sizin için önemlidir. CNCF'nin CloudEvents belirtim standardını kullanarak olayları standart bir şekilde iletmek ve işlemek istiyorsunuz.
  • CloudEvents'in sağladığı genişletilebilirlik desteğini seviyorsunuz. Örneğin, olayları uyumlu sistemlerde izlemek istiyorsanız CloudEvents Uzantısı Dağıtılmış İzleme'yi kullanın. Daha fazla CloudEvents uzantısı hakkında daha fazla bilgi edinin.
  • Sektör tarafından benimsenen kanıtlanmış olay odaklı yaklaşımları kullanmak istiyorsunuz.

Graph API olaylarının iş ortağı konunuza akışını etkinleştirme

Microsoft Graph API SDK'larını kullanarak bir Graph API aboneliği oluşturarak ve bu bölümde sağlanan örneklerin bağlantılarındaki adımları izleyerek Microsoft Graph API'sinin olayları event Grid iş ortağı konusuna iletmesini istiyorsunuz. Kullanılabilir SDK desteği için bkz . Microsoft Graph API SDK'sı için desteklenen diller.

Genel önkoşullar

Microsoft Graph API aboneliklerini oluşturmak ve yenilemek için uygulamanızı uygulamadan önce şu genel önkoşulları karşılamanız gerekir:

Tercih ettiğiniz programlama diline ve kullandığınız geliştirme ortamına özgü diğer önkoşulları, gelecek bölümde bulunan Microsoft Graph API örnekleri bağlantılarında bulabilirsiniz.

Önemli

Uygulamanızı uygulamaya yönelik ayrıntılı yönergeler ayrıntılı yönergeler içeren örneklerde bulunurken, Event Grid kullanarak Microsoft Graph API olaylarını iletmeyle ilgili ek, önemli bilgiler içerdiğinden bu makaledeki tüm bölümleri okumanız gerekir.

Microsoft Graph API aboneliği oluşturma

Graph API aboneliği oluşturduğunuzda, sizin için bir iş ortağı konusu oluşturulur. Yeni Graph API aboneliğinin oluşturulacağı ve ilişkilendirileceği iş ortağı konusunu belirtmek için notificationUrl parametresine aşağıdaki bilgileri geçirirsiniz:

  • iş ortağı konu adı
  • iş ortağı konusunun oluşturulduğu kaynak grubu adı
  • bölge (konum)
  • Azure aboneliği

Bu kod örnekleri, Graph API aboneliğinin nasıl oluşturulacağını gösterir. Microsoft Entra ID kiracısında oluşturulan, güncelleştirilen veya silinen tüm kullanıcılardan olay almak için abonelik oluşturmaya yönelik örnekler gösterir.

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: olaylarını almak istediğiniz kaynak türü değişir. Geçerli değerler: Updated, Deletedve Created. Bu değerlerden birini veya daha fazlasını virgülle ayırarak belirtebilirsiniz.
  • notificationUrl: olayların gönderildiği iş ortağı konusunu tanımlamak için kullanılan bir URI. Aşağıdaki desene uygun olmalıdır: 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>. Konum (Azure bölgesi olarak da bilinir) name az account list-locations komutu yürütülerek elde edilebilir. Konum görünen adı kullanmayın. Örneğin, "Orta Batı ABD" kullanmayın. Bunun yerine westcentralus kullanın. 
      az account list-locations
  • lifecycleNotificationUrl: olayların gönderildiği iş ortağı konusunu tanımlamak için microsoft.graph.subscriptionReauthorizationRequiredkullanılan bir URI. Bu olay, uygulamanıza Graph API aboneliğinin süresinin yakında dolduğunu bildirir. URI, Event Grid'i yaşam döngüsü olaylarının hedefi olarak kullanıyorsa yukarıda açıklanan notificationUrl ile aynı deseni izler. Bu durumda, iş ortağı konusu notificationUrl'da belirtilen konu ile aynı olmalıdır.
  • resource: Durum değişikliklerini duyuran olaylar oluşturan kaynak.
  • expirationDateTime: Aboneliğin sona erme zamanı ve olayların akışı durduruluyor. RFC 3339'da belirtilen biçime uygun olmalıdır. Kaynak türü başına izin verilen abonelik uzunluğu üst sınırı içinde bir süre sonu belirtmelisiniz.
  • istemci durumu. Bu özellik isteğe bağlıdır. Olay teslimi sırasında olay işleyicisi uygulamanıza yapılan çağrıların doğrulanması için kullanılır. Daha fazla bilgi için bkz . Graph API aboneliği özellikleri.

Önemli

  • İş ortağı konu adı aynı Azure bölgesinde benzersiz olmalıdır. Her kiracı-uygulama kimliği bileşimi en fazla 10 benzersiz iş ortağı konusu oluşturabilir.

  • Çözümünüzü geliştirirken belirli Graph API kaynaklarının hizmet sınırlarına dikkat edin.

  • Özelliği olmayan lifecycleNotificationUrl mevcut Graph API abonelikleri yaşam döngüsü olaylarını almaz. lifecycleNotificationUrl özelliğini eklemek için mevcut aboneliği silmeniz ve abonelik oluşturma sırasında özelliği belirten yeni bir abonelik oluşturmanız gerekir.

Dekont

Uygulamanız özel önizleme sırasında Graph API aboneliği oluşturma isteğinizle birlikte üst bilgiyi kullanıyorsa, artık gerekli olmadığından bu aboneliği x-ms-enable-features kaldırmanız gerekir.

Graph API aboneliği oluşturduktan sonra Azure'da oluşturulmuş bir iş ortağı konusuna sahipsiniz.

Microsoft Graph API aboneliğini yenileme

Olay akışının durdurulmasını önlemek için bir Graph API aboneliğinin süresi dolmadan önce uygulamanız tarafından yenilenmesi gerekir. Microsoft Graph API, yenileme işlemini otomatikleştirmenize yardımcı olmak için uygulamanızın abone olabileceği yaşam döngüsü bildirimleri olaylarını destekler. Şu anda tüm Microsoft Graph API kaynakları türü, aşağıdaki koşullardan herhangi biri oluştuğunda gönderilen öğesini destekler microsoft.graph.subscriptionReauthorizationRequired:

  • Erişim belirtecinin süresi dolmak üzere.
  • Graph API aboneliğinin süresi dolmak üzere.
  • Kiracı yöneticisi, uygulamanızın kaynak okuma izinlerini iptal etti.

Süresi dolduktan sonra Graph API aboneliğinizi yenilemediyseniz yeni bir Graph API aboneliği oluşturmanız gerekir. Süresi 30 günden kısa olduğu sürece süresi dolan aboneliğinizde kullandığınız iş ortağı konusuna başvurabilirsiniz. Graph API aboneliğinin süresi 30 günden uzun süre dolduysa mevcut iş ortağı konunuzu yeniden kullanamazsınız. Bu durumda, başka bir iş ortağı konu adı belirtmeniz gerekir. Alternatif olarak, Graph API aboneliği oluşturma sırasında aynı ada sahip yeni bir iş ortağı konusu oluşturmak için mevcut iş ortağı konusunu silebilirsiniz.

Microsoft Graph API aboneliğini yenileme

Bir microsoft.graph.subscriptionReauthorizationRequired olay aldıktan sonra uygulamanız şu eylemleri gerçekleştirerek Graph API aboneliğini yenilemelidir:

  1. Graph API aboneliğini oluştururken clientState özelliğinde bir istemci gizli dizisi sağladıysanız, içindeki bu istemci gizli dizisi olaya dahil edilir. Olayın clientState değerinin Graph API aboneliğini oluştururken kullanılan değerle eşleşdiğini doğrulayın.

  2. Uygulamanın bir sonraki adıma geçmek için geçerli bir erişim belirtecine sahip olduğundan emin olun. Ayrıntılı yönergeler bölümüyle birlikte gelecek örneklerde daha fazla bilgi sağlanmıştır.

  3. Aşağıdaki iki API'den birini çağırın. API çağrısı başarılı olursa değişiklik bildirimi akışı devam eder.

    • Aboneliği son /reauthorize kullanma tarihini uzatmadan yeniden yetkilendirmek için eylemi çağırın.

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

    • Aboneliği aynı anda yeniden yetkilendirmek ve yenilemek için düzenli bir "yenileme" eylemi gerçekleştirin.

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

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

      Uygulama artık kaynağa erişim yetkisine sahip değilse yenileme başarısız olabilir. Daha sonra uygulamanın bir aboneliği başarıyla yeniden yetkilendirmesi için yeni bir erişim belirteci alması gerekebilir.

Yetkilendirme sınamaları, süresi dolmadan önce aboneliği yenileme gereksiniminin yerini değiştirmez. Erişim belirteçlerinin yaşam döngüleri ve abonelik süre sonu aynı değildir. Erişim belirtecinizin süresi aboneliğinizden önce dolabilir. Erişim belirtecinizi yenilemek için uç noktanızı düzenli olarak yeniden yetkilendirmeye hazırlıklı olmak önemlidir. Uç noktanızın yeniden yetkilendirilmesi aboneliğinizi yenilemez. Ancak aboneliğinizi yenilemek de uç noktanızı yeniden yetkilendirir.

Graph API aboneliğinizi yeniler ve/veya yeniden yetkilendirirken, abonelik oluşturulurken belirtilen iş ortağı konusu kullanılır.

Yeni bir expirationDateTime belirtirken, geçerli saatten itibaren en az üç saat olmalıdır. Aksi takdirde, uygulamanız yenilemeden kısa süre sonra olayları alabilir microsoft.graph.subscriptionReauthorizationRequired .

Desteklenen dillerden herhangi birini kullanarak Graph API aboneliğinizi yeniden yetkilendirme hakkında örnekler için bkz . Aboneliği yeniden yetkilendirme isteği.

Desteklenen dillerden birini kullanarak Graph API aboneliğinizi yenileme ve yeniden yetkilendirme hakkında örnekler için bkz . abonelik isteğini güncelleştirme..

Ayrıntılı yönergeler içeren örnekler

Microsoft Graph API belgeleri, şu yönergeleri içeren kod örnekleri sağlar:

  • Kullandığınız dile göre belirli yönergelerle geliştirme ortamınızı ayarlayın. Yönergeler, geliştirme amacıyla Bir Microsoft 365 kiracısı edinmeyi de içerir.
  • Graph API abonelikleri oluşturun. Aboneliği yenilemek için yukarıdaki Graph API aboneliğini yenileme başlığı altında yer alan kod parçacıklarını kullanarak Graph API'sini çağırabilirsiniz.
  • Microsoft Graph API'sini çağırırken kullanmak için kimlik doğrulama belirteçlerini alın.

Dekont

Microsoft Graph API Gezgini'ni kullanarak Graph API aboneliğinizi oluşturabilirsiniz. Yine de kimlik doğrulaması ve alma olayları gibi çözümünüzün diğer önemli yönleri için örnekleri kullanmanız gerekir.

Web uygulaması örnekleri aşağıdaki diller için kullanılabilir:

  • C# örneği. Bu, Graph API aboneliklerini oluşturma ve yenilemeyi içeren ve olay akışını etkinleştirme adımlarından bazılarında size yol gösteren güncel bir örnektir.
  • Java örneği
    • GraphAPIController , Graph API aboneliği oluşturmak, silmek ve yenilemek için örnek kod içerir. Yukarıdaki Java örnek uygulamasıyla birlikte kullanılmalıdır.
  • NodeJS örneği.

Önemli

Graph API aboneliği oluşturma işleminizin bir parçası olarak oluşturulan iş ortağı konunuzu etkinleştirmeniz gerekir. Ayrıca, olayları almak için web uygulamanıza bir Event Grid olay aboneliği oluşturmanız gerekir. Bu amaçla, olayları olay aboneliğinizde web kancası uç noktası olarak almak için web uygulamanızda yapılandırılan URL'yi kullanırsınız. Daha fazla bilgi için sonraki adımlar .

Önemli

Başka bir dil için örnek koda mı ihtiyacınız var yoksa sorularınız mı var? Lütfen adresinden bize ask-graph-and-grid@microsoft.come-posta gönderin.

Sonraki adımlar

Event Grid kullanarak Microsoft Graph API olaylarını alma kurulumunu tamamlamak için aşağıdaki iki adımda yer alan yönergeleri izleyin:

Diğer yararlı bağlantılar: