Desteklenen sorguları, filtreleri ve disk belleği seçenekleri | Grafik API'si kavramları
Bu konu, sorgu seçenekleri, filtreleri ve Azure Active Directory (AD) grafik API'si ile kullanabileceğiniz sayfalandırma işlemleri listeler. Son bölümü, Azure AD grafik API'si ile gerçekleştirebileceğiniz genel sorgular, bazı örnekler sağlar.
Ö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.
Adresleme
Aşağıda tüm sorguları bir etki alanı adını kullanarak Kiracı adres. Değiştirebileceğiniz contoso.com , kiracının kayıtlı etki alanı adlarını biriyle, kiracınıza ait kimlik (GUID) ile veya ile MyOrganization diğer ad (için temsilci erişimi). Bazı durumlarda kullanmanız mümkün olabilir me diğer adı. Kiracı adresleme yolları hakkında daha fazla bilgi için bkz: Operations genel bakış.
Desteklenen sorgu seçenekleri
Grafiği aşağıdaki sorgu seçeneklerini destekler: $filter, $orderby, $expand, $top, ve $format. Aşağıdaki sorgu seçenekleri şu anda desteklenmiyor: $count, $inlinecount, ve $skip.
$filter
Aşağıdaki genel kısıtlamalar bir filtre içeren sorguları için geçerlidir:
$filter, $orderby ifadelerle birleştirilemez.
Filtreleme desteklenmiyor sorgularında DirectoryRole veya SubscribedSku dizin nesneleri.
Desteklenen directory nesnelerinin tüm özelliklerini filtre ifadesinde kullanılabilir. Desteklenen türler filtrelenebilir özellikleri hakkında daha fazla bilgi için bkz: kullanıcı, grup, ve kişi.
Filtre ifadeleri için aşağıdaki kısıtlamalar geçerlidir:
Mantıksal işleçler: ve ve veya desteklenir. Örneğin:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')Karşılaştırma işleçleri: eq (eşit), ge (büyük veya eşittir) ve le (küçük veya eşittir) desteklenir.
startswith desteklenir. Örneğin:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')tüm birden çok değerli özellikleri sorgulanırken desteklenir. Örneğin:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')Aritmetik işleçler: desteklenmiyor.
İşlevler: desteklenmez.
null değerler filtre ifadeleri işlenen olarak desteklenmiyor. Örneğin, belirtemezsiniz bir null ayarlanmamış özellikler için filtrelemek için değer.
Bir ikili özellik gibi filtrelemek için issuerUserId içinde userIdentities, değerin ilk base64 ile kodlanmış $filter dizesinde kullanılabilmesi için önce olması gerekir.
$orderby
$orderby belirtilen parametresi tarafından döndürülen nesnelerin sıralanır. $Orderby seçeneği kullanılarak örnek istekleri:
| İstek | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Kullanıcıların kendi görünen ada göre sıralanmış bir listesini döndürür. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Görünen adına göre sıralanmış ilk 50 kullanıcıların bir listesini döndürür. |
$Orderby ifadeleri için aşağıdaki kısıtlamalar geçerlidir:
İki sıralamalar şu anda desteklenmiyor: DisplayName için kullanıcı ve grup nesneleri ve UserPrincipalName içinkullanıcı nesneleri. Kullanıcılar için varsayılan sıralama düzeni gereğidir UserPrincipalName.
$orderby $filter ifadelerle birleştirilemez.
$expand
$expand olacaktır ve onun bağlantılı nesneleri bir nesne döndürür. Kullanan $ örnek isteklerinin seçeneğini genişletin:
| İstek | Description |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Hem grup nesnesi, hem de üyeleri döndürür. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Hem kullanıcı nesnesi, hem de doğrudan raporlarının döndürür. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Hem kullanıcı nesnesi, hem de kendi Yöneticisi döndürür. |
Aşağıdaki kısıtlamalar uygulamak için $ ifadeleri genişletin:
- Bir istek için döndürülen nesnelerin sayısı 20'dir.
$top
$top desteklenmiyor sorgularında DirectoryRole veya SubscribedSku dizin nesneleri.
Sayfalama desteği
Grafikte ileriye ve geriye doğru sayfa. Disk belleğine alınan sonuçlarını içeren bir yanıt Atla belirteci içerir (odata.nextLink) sonraki sonuç sayfasını alma izin verir. Bu atlama belirteci ile birlikte kullanılabilir bir önceki sayfaya = true sorgu geriye doğru sayfa için bağımsız değişken.
İleri disk belleği izleyin örnek isteğini gösterir:
| İstek | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
$Skiptoken önceki yanıt parametresinden bulunur ve sonraki sonuç sayfasını almanızı sağlar. |
Aşağıdaki örnek isteği geriye doğru disk belleği gösterir:
| İstek | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
$Skiptoken önceki yanıt parametresinden eklenmiştir. Ne zaman bu birlikte ile & önceki sayfaya = true parametresi, önceki sayfaya sonuçlarının alınabilir. |
Aşağıdaki adımlarda, ileriye ve geriye doğru sayfa için istek/yanıt akışı gösterilmektedir:
- 15 dışında ilk 10 kullanıcıların listesini almak için bir istek yapılır. Yanıt 10 kullanıcı son sayfasında belirtmek için bir atlama belirteci içeriyor.
- Son 5 kullanıcıları almak için başka bir istek, yapılır alınan önceki yanıtta döndürülen Atla belirteç içerir.
- Geriye doğru sayfa için bir istek adım 1 ve parametre döndürülen Atla belirteci kullanılarak yapıldığında & önceki sayfaya = true isteği eklenir.
- Yanıt önceki (ilk) sayfanın 10 kullanıcıları içerir. Daha fazla sayfa burada bırakılır farklı bir senaryoda, yeni bir atlama belirteci döndürülür. Bu yeni atlama belirteci ile birlikte isteği eklenebilir & önceki sayfaya = true geriye doğru yeniden sayfası.
Disk belleğine alınan isteklerine aşağıdaki kısıtlamalar geçerlidir:
- Varsayılan sayfa boyutu 100'dür. Maksimum sayfa boyutunu 999'dur.
- Disk belleği rolleri sorguları desteklemez. Bu rolü nesnelerinin kendilerini yanı sıra rol okuma içerir üyeleri.
- Kaynak, bir kiracıdaki tüm kullanıcılar için bir arama gibi listeleme (/Users), sorguları, disk belleği destekler. Örneğin:
https://graph.windows.net/contoso.com/users?api-version=1.6. Ancak, tüm türleri arasında bir filtre uygulandığında, disk belleği desteklenmiyor ve sonuçları yalnızca ilk sayfasına döndürülür. - Disk belleği bağlantı arar gibi Grup üyeleri sorgulama için kullanılamaz. Örneğin:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Sıralama düzeni
- Tüm kullanıcılar için bir sorgu sonuç kümesini göre sıralanmış UserPrincipalName özelliği. Örneğin:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Gruplar, kişiler, vb. gibi üst düzey diğer tüm kaynaklar için bir sorgu sonuç kümesini göre sıralanmış objectID özelliği. Örneğin:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - Sorguların sonuçlarını dışında en üst düzey kaynaklar için belirsiz sırasıdır.
Genel sorgular
Aşağıdaki bölümlerde, grafik API'si ile gerçekleştirebileceğiniz genel sorgular bazı örnekler.
Üst düzey kaynaklarını sorgulama
Aşağıdaki sorgularda contoso.com örnek Kiracı olarak kullanarak grafik API'si ile en üst düzey kaynaklara erişmek nasıl ekleyebileceğiniz gösterilmektedir. Azure AD'den alınan geçerli taşıyıcı belirteci içeren bir Authorization Üstbilgisi Kiracı karşı sorguları çalıştırmak için gerekli olduğunu unutmayın.
| Üst düzey kaynak | Sorgu sonuçları | URI'sini (contoso.com) |
|---|---|---|
| Üst düzey kaynakları | (Ayrıca aşağıda listelenen) dizin hizmetleri için üst düzey kaynakları URI listesini döndürür | https://graph.windows.net/contoso.com?api-version=1.6 |
| Şirket bilgileri | Şirket bilgilerini döndürür | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Kişiler | Bilgi döndürür kuruluş başvurun | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Kullanıcı bilgilerini döndürür | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Gruplar | Veri döndürür grubu | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Dizin rolleri | Kiracısı'nda tüm etkinleştirilmiş dizin rollerini döndürür | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Kiracının abonelikleri döndürür | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Dizin meta verileri | Veri modeli (diğer bir deyişle, yapısı ve organizasyon dizin kaynakları) açıklayan bir hizmeti meta veri belgesi döndürür | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Diğer sorgu işlemleri
Aşağıdaki tabloda bazı ek örnek contoso.com örnek Kiracı olarak kullanarak grafik API'si sorguları gösterir.
| Sorgu işlemi | URI'sini (contoso.com) |
|---|---|
| Tüm kullanıcılar ve gruplar listesi | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Bireysel kullanıcı objectID veya userPrincipalName belirterek alma | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6 https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6 |
| İstek ve "Can Doe"nun eşit görünen adına sahip bir kullanıcı için filtre | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| İstek ve firstName "Can" eşit belirli kullanıcılarla Filtrele | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| GivenName ve Soyadı değerlerini filtreleyin. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Bireysel grup objectID belirterek alma | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Bir kullanıcının yöneticisinin alma | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Bir kullanıcının bağlı çalışanları listesini alma | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Bir kullanıcının bağlı çalışanları için bağlantıların listesini alma | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Bir grup üyeliği listesini alma | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Bir grubun üyelerini bağlantıların listesini alır. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Bir kullanıcının grup üyeliği (Geçişli değil) alma | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Kullanıcının (Geçişli değil) bir üyesi olduğunu gruplarının bir listesini alma | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| İstek ve displayName gruplarıyla Filtre > "az" = ve < = "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Tüm yerel hesap kullanıcılar bir Azure Active Directory B2C kiracınızda döndürür | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Dönüş yerel hesabı kullanıcıyla oturum açma adı "joe@example.com" bir Azure Active Directory B2C kiracısındaki | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Not: boşluk sorgu dizesinde olmalıdır URL kodlanmış bir isteği göndermeden önce. Örneğin, aşağıdaki dize, sorgu https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, URL kodlanmış olarak: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.