İşlemleri genel bakış | Grafik API'si kavramları

  • Makale

Azure Active Directory (AD) grafik API'si okumak ve kullanıcılar, gruplar ve kişiler Kiracı gibi nesneleri değiştirmek için kullanabileceğiniz bir OData 3.0 uyumlu hizmetidir. Azure AD Graph API HTTP isteklerine hizmet kullanarak işlemleri gerçekleştirmek için gönderdiğiniz REST uç noktalarını kullanıma sunar. Aşağıdaki bölümler biçimi istekleri ve yanıtları okumak ve dizin kaynaklarının yazma, dizin işlevleri veya eylemleri arayın veya dizin sorguları gerçekleştirmek için grafik API'sini kullandığınızda beklenmesi gerekenler hakkında genel bilgi sağlar. Belirli işlemlerini directory kaynakları gerçekleştirme hakkında daha ayrıntılı bilgi için uygun operations konusuna bakın Azure AD Graph API Başvurusu.

Önemli

Kullanmanız önerilir Microsoft Graph Azure Active Directory kaynaklara erişmek için Azure AD Graph API yerine. Geliştirme çalışmalarımızı artık Microsoft Graph yoğunlaşmıştır ve herhangi bir geliştirme için Azure AD Graph API planlanmaktadır. Senaryolar için Azure AD Graph API hala uygun olabilir, çok sınırlı sayıda vardır; Daha fazla bilgi için bkz: Microsoft Graph veya Azure AD grafik Office Geliştirici Merkezi blog postasına.

Grafik API'si için başarılı bir istek için geçerli bir uç noktası ele alınması gereken ve düzgün biçimlendirilmiş, diğer bir deyişle, tüm gerekli üstbilgileri içermelidir ve gerekirse, istek gövdesindeki bir JSON yükü. İsteği yapan uygulama istek tarafından hedeflenen kaynaklara erişmek için yetkili olup kanıtlar Azure AD'den alınan bir belirteç eklemeniz gerekir. Uygulama Graph API öğesinden alınan yanıtları işleyen kurabilmesi gerekir.

Bu konudaki bölümlerden isteklerin ve yanıtların grafik API'si ile kullanılan biçim anlamanıza yardımcı olur.

Kimlik doğrulama ve yetkilendirme

Her istek grafik API'si için Azure Active bağlı Directory tarafından verilmiş bir taşıyıcı belirteç olması gerekir. Belirteç taşır bilgilerini uygulamanızı, oturum açmış kullanıcı (durumunda izinlere temsilci), kimlik doğrulama ve uygulamanızın dizininde işlemleri gerçekleştirme yetkisi. Bu belirteç içinde taşınan yetkilendirme isteği üstbilgisi. (Belirteç okumanızdır kısaltılmıştır) örneğin:

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Grafik API'si OAuth 2.0 izin kapsamları belirtecinde dayalı yetkilendirme gerçekleştirir. Gösteren grafik API'si izin kapsamları hakkında daha fazla bilgi için bkz: grafik API'si izin kapsamları.

Azure AD ile kimlik doğrulaması ve grafik API'sini çağırmak, uygulamanız için sırayla kiracınıza ekleyin ve Windows Azure Active Directory için izinler (OAuth 2.0 izin kapsamları) gerektirecek şekilde yapılandırmanız gerekir. Ekleme ve bir uygulama yapılandırma hakkında daha fazla bilgi için bkz: Azure Active Directory Tümleştirme uygulamalarla.

Azure AD OAuth 2.0 kimlik doğrulama protokolünü kullanır. Desteklenen akışları dahil olmak üzere Azure AD'de OAuth 2.0 hakkında daha fazla bilgi edinin ve erişim belirteçleri OAuth 2.0 Azure AD'de.

Uç nokta adresleme

Grafik API'si ile işlemlerini gerçekleştirmek için desteklenen bir yöntemle HTTP istekleri göndermek - genellikle GET, POST, düzeltme eki, PUT veya--hedefler hizmeti, bir kaynak koleksiyonu, tek başına bir kaynak, bir gezinti özelliği, kaynağın bir uç nokta silme veya işlev veya hizmet tarafından kullanıma sunulan eylem. Uç noktaları URL'ler olarak ifade edilir.

Graph API uç noktası temel biçimini açıklanmaktadır:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Aşağıdaki bileşenler URL oluşturan:

Not: Bazı durumlarda, kaynak koleksiyonları okunurken filtre, sıralama ve sonuç kümesi sayfa isteği OData sorgu parametrelerini eklenebilir. Daha fazla bilgi için bkz: OData sorgu parametrelerini bölümüne bakın.

Kiracı tanımlayıcı {tenant_id}

Bir isteğin hedef Kiracı dört yollardan birini belirtebilirsiniz:

  • Kiracı tarafından nesne kimliği. Kiracı oluşturulduğunda atanan GUID. Bu bulunabilir objectID özelliği TenantDetail nesnesi. Aşağıdaki URL'yi Kiracı nesne kimliği'ni kullanarak kullanıcıların kaynak koleksiyonu adres gösterilmektedir:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • (Kayıtlı) etki alanı adı ile doğrulandı. Kiracı için kayıtlı etki alanı adlarından biri. Bunlar bulunabilir verifiedDomains özelliği TenantDetail nesnesi. Aşağıdaki URL'yi, contoso.com etki alanı olan bir kiracı kullanıcılar kaynak koleksiyonu adres gösterilmektedir:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Kullanarak myOrganization diğer. Bu diğer adı, yalnızca OAuth yetkilendirme kodu verme türü (3 bacaklı) kimlik doğrulaması kullanırken kullanılabilir; diğer bir deyişle, bir temsilci izni kapsamı kullanırken. Diğer ad büyük küçük harfe duyarlı değil. Nesne kimliği veya Kiracı etki alanı URL'deki değiştirir. Diğer ad kullanıldığında grafik API'si isteğe bağlı belirteci sunulan talepler Kiracı türetir. Aşağıdaki URL, bu diğer adı kullanarak bir kiracı kullanıcılar kaynak koleksiyonu adres gösterilmektedir:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Kullanarak me diğer. Bu diğer adı, yalnızca OAuth yetkilendirme kodu verme türü (3 bacaklı) kimlik doğrulaması kullanırken kullanılabilir; diğer bir deyişle, bir temsilci izni kapsamı kullanırken. Diğer ad büyük küçük harfe duyarlı değil. Nesne kimliği veya Kiracı etki alanı URL'deki değiştirir. Diğer ad kullanıldığında grafik API'si isteğe bağlı belirteci sunulan talepler kullanıcı türetir. Bu diğer adı kullanarak oturum açmış kullanıcı gidermek için aşağıdaki URL'si:
    https://graph.windows.net/me?api-version=1.6.

Not: kullandığınız me yalnızca oturum açmış kullanıcıya karşı hedef işlemleri için diğer ad. Daha fazla bilgi için bkz: imzalandı bileşenini kullanıcı işlemleri.

Kaynak yolu {resource_path}

Belirttiğiniz {resource_path} farklı olup olmadığını, hedeflediğiniz bağlı olarak kaynak koleksiyonu, tek başına bir kaynak, bir kaynağın bir gezinti özelliği, bir işlev veya eylem kullanıma sunulan Kiracı'ya da bir işlevi veya eylem kullanıma sunulan bir kaynakta.

Hedef Yol Açıklama
Service Metadata /$metadata Hizmet meta veri belgesi döndürür. Contoso.com Kiracı kullanarak aşağıdaki örnek hedefleri hizmeti meta verileri:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Not: kimlik doğrulaması hizmeti meta verileri okumak gerekli değildir.
Kaynak koleksiyonu /{resource_collection} Kullanıcılar veya gruplar, Kiracı gibi bir kaynak koleksiyonu hedefler. Bu yol, koleksiyondaki ve kaynakların, Kiracı içinde yeni bir kaynak oluşturmak için kaynak türüne bağlı olarak okumak için kullanabilirsiniz. Çoğu durumda okuma tarafından döndürülen sonuç kümesi ek, sipariş, filtre uygulamak veya sonuçları sayfası için sorgu parametreleri ekleyerek iyileştirilmiştir. Aşağıdaki örnekte, kullanıcı koleksiyonu hedefleyen:
https://graph.windows.net/myorganization/users?api-version=1.6
Tek kaynak /{resource_collection}/{resource_id} Bir Kiracı Kullanıcı, kuruluş kişi veya grup gibi belirli kaynak hedefler. Çoğu kaynaklar için resource_id nesne kimliğidir. Bazı kaynaklar ek tanımlayıcıları izin ver; Örneğin, kullanıcıların kullanıcı asıl adı (UPN) belirtilebilir. Kaynak bağlı olarak bu yol bildirilen özelliklerini değiştirmek için ya da kaynak silmek için kaynak bildirilen özelliklerini almak için kullanabilirsiniz. Aşağıdaki örnek kullanıcı hedefler john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Gezinti özelliği (nesne) /{resource_collection}/{resource_id}/{property_name} Bir kullanıcının yöneticisinin veya grup üyeliklerini veya bir grubun üyeleri gibi belirli bir kaynak Gezinti özelliğinin hedefler. Nesne ya da hedef gezinti özelliği tarafından başvurulan nesneleri döndürmek için bu yolu kullanabilirsiniz. Aşağıdaki örnek yöneticisinin hedefler john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Not: adresleme bu form yalnızca okuma için kullanılabilir.
Gezinti özelliği (Bağlantılar) /{resource_collection}/{resource_id}/$links/{property_name} Bir kullanıcının yöneticisinin veya grup üyeliklerini veya bir grubun üyeleri gibi belirli bir kaynak Gezinti özelliğinin hedefler. Bu formun adresleme, hem okuma hem de bir gezinti özelliği değiştirmek için kullanabilirsiniz. Üzerinde okuma, özelliği tarafından başvurulan bir veya daha fazla bağlantı yanıt gövdesi olarak döndürülür. Yazma üzerinde nesneleri istek gövdesindeki bir veya daha fazla bağlantılar olarak belirtilir. Aşağıdaki örnekte yönetici özelliği hedefler john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
İşlevler veya Kiracı'kullanıma sunulan eylemleri /{function_name} Bir işlev veya Kiracı sunulan eylem hedefler. İşlevler ve Eylemler tipik olarak bir POST isteği ile çağrılır ve bir istek gövdesi içerebilir. Aşağıdaki örnek hedefleri isMemberOf işlevi:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
İşlevler veya bir kaynakta sunulan eylemler. /{resource_collection}/{resource_id}/{function_name} Bir işlev veya bir kaynakta sunulan eylem hedefler. İşlevler ve Eylemler tipik olarak bir POST isteği ile çağrılır ve bir istek gövdesi içerebilir. Aşağıdaki örnek hedefleri getMemberGroups işlevi:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Grafik API'si sürümü {api-version}

Kullandığınız api-version sorgu grafik API'si bir işlem için belirli bir sürümünü hedefleyecek şekilde parametresi. Bu parametre gereklidir.

Değeri api-version parametresi şunlardan biri olabilir:

  • "beta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

Örneğin aşağıdaki URL'yi sürüm 1.6 grafik API'sini kullanarak kullanıcı koleksiyonu hedefleyen:

https://graph.windows.net/myorganization/users?api-version=1.6

Sürümleri ve sürümler arasında özellik değişiklikleri hakkında daha fazla bilgi için bkz: sürüm.

OData sorgu parametrelerini

Çoğu durumda kaynaklar koleksiyonu okurken, sıralama ve filtreleyebilirsiniz sonuç isteğinizi OData sorgu parametrelerini ekleyerek kümesini sayfa.

Grafik API'si aşağıdaki Odata sorgu parametrelerini destekler:

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken ve önceki sayfaya

Bkz: desteklenen sorguları, filtreleri ve disk belleği seçenekleri desteklenen OData hakkında daha fazla bilgi için sorgu parametreleri ve kendi sınırlamalarını grafik API'si.

İstek ve yanıt üstbilgileri

Aşağıdaki tablo, grafik API'si ile isteklerinde kullanılan ortak HTTP üst bilgilerini gösterir. Kapsamlı olacak şekilde tasarlanmamıştır.

İstek üstbilgisi Description
Yetkilendirme Gerekli. Azure Active Directory tarafından verilmiş bir taşıyıcı belirteç. Bkz: kimlik doğrulama ve yetkilendirme daha fazla bilgi için bu konudaki.
İçerik türü İstek gövdesinde mevcut ise gereklidir. İstek gövdesindeki içerik medya türü. Uygulama/json kullanın. Parametreleri medya türüyle dahil edilebilir.
Not: uygulama/atom + xml ve uygulama/xml (bağlantılar için) desteklenir, ancak her ikisi de performans nedenleriyle önerilmez ve çünkü XML gelecekteki bir sürümde kullanım dışı kalacaktır desteği.
Content-Length İstek gövdesinde mevcut ise gereklidir. İstek bayt cinsinden uzunluğu.

Aşağıdaki tabloda yanıtları grafik API'si tarafından döndürülen ortak HTTP üst bilgilerini gösterir. Kapsamlı olacak şekilde tasarlanmamıştır.

Yanıt üst bilgisi Description
İçerik türü Yanıt gövdesi içeriği medya türü. Varsayılan application/json şeklindedir. Kullanıcı küçük resim fotoğrafı istekleri varsayılan görüntü/jpeg döndürüyor.
Konum Yeni bir kaynak (nesne) dizinde oluşturmak POST isteklerini yanıtlar döndürdü. Yeni oluşturulan kaynak URI içeriyor.
ocp-aad-diagnostics-server-name İstenen işlem gerçekleştirilen sunucu tanımlayıcısı.
ocp-aad-oturum-anahtar Geçerli oturumu dizin hizmetiyle tanımlayan anahtar.

En azından her istek için şunları öneririz:

  1. Doğru zaman damgası isteği gönderimi olarak oturum açın.
  2. Gönderme ve oturum client-request-id.
  3. HTTP yanıt kodunu oturum ve request-id.

Bu tür günlükleri bilgileri sağlayarak Yardım veya destek için söylediğinizde sorunlarını giderme Microsoft yardımcı olur.

İstek ve yanıt gövdesi

İstek gövdelerine POST, düzeltme eki ve PUT isteklerini JSON veya XML yükleri gönderilebilir. Sunucu yanıtlarını JSON veya XML yükleri döndürülebilir. Kullanarak istek gövdelerine yükü belirtebilirsiniz Content-Type istek üstbilgisi ve kullanarak yanıtlarındaki Accept istek üstbilgisi.

Grafik API'si ile JSON yükü istekleri ve yanıtları kullanmak önerilir. Performansı artırmak için her ikisini de budur ve XML gelecekteki bir sürümde kullanım dışı kalacaktır.

Gelişmiş Özellikler

Önceki bölümlerde ele alınan temel isteklerin ve yanıtların grafik API'si ile biçimlendirme. Daha gelişmiş özellikleri ek sorgu dizesi parametreleri ekleyebilir veya önemli ölçüde farklı istek ve yanıt gövdesi daha önce bu konuda tartışılan temel işlemleri daha vardır.

Bu özellikler şunlardır:

  • Toplu işleme: grafik API'sini destekleyen toplu işleme. Toplu olarak istekleri gönderirken gidiş dönüş ağ yükünü ve işlemlerinizi daha hızlı tamamlamak yardımcı azaltır sunucusuna azaltır. Toplu işleme grafik API'si hakkında daha fazla bilgi için bkz: toplu işleme.
  • Fark sorgu: grafik API'sini destekleyen fark sorgular gerçekleştirme. Fark sorgu, farklı zamanlarda verilen istekler arasında bir kiracı belirli varlıklar için değişiklikleri iade olanak sağlar. Bu özellik genellikle yerel bir depo Kiracı değişiklikleri ile eşitlemek için kullanılır. Grafik API'si ile fark sorgu hakkında daha fazla bilgi için bkz: fark sorgu.

Ek kaynaklar