Podporované dotazy, filtrů a možností stránkování | Rozhraní Graph API koncepty
Toto téma uvádí možnosti dotazu, filtrů a stránkovací operace, které může používat pro rozhraní Graph API Azure Active Directory (AD). Koncová část uvádí některé příklady běžné dotazy, které můžete provádět s Azure AD Graph API.
Důležité
Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory. Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API. Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center.
Adresování
Dotazy níže všechny adres klienta pomocí názvu domény. Můžete nahradit contoso.com s jedním z vašeho klienta registrovaných doménách, s ID vašeho klienta (GUID) nebo pomocí MyOrganization alias (pro delegovaný přístup). V některých případech může být možné používat me alias. Informace o způsobech adres klienta najdete v tématu Operations přehled.
Možnosti podporované dotazu
Graf podporuje následující možnosti dotazu: $filter, $orderby, $expand, $top, a $format. Následující možnosti dotazu nejsou aktuálně podporovány: $count, $inlinecount, a $skip.
$filter
Na dotazy, které obsahují filtr platí tato obecná omezení:
$filter nelze kombinovat s výrazy $orderby.
Filtrování není podporovaný pro dotazy na DirectoryRole nebo SubscribedSku objektů adresáře.
Ne všechny vlastnosti objektů podporované directory lze použít ve výrazu filtru. Informace o filtrování vlastnosti podporované typy najdete v tématu uživatele, skupiny, a kontaktujte.
Filtr výrazy platí následující omezení:
Logické operátory: a a nebo jsou podporovány. Příklad:
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')Operátory porovnání: eq (rovná), ge (větší než nebo rovno), a le (je menší než nebo rovno) jsou podporovány.
StartsWith je podporována. Příklad:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')všechny je podporován při dotazování více hodnot vlastnosti. Příklad:
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')Aritmetické operátory: není podporováno.
Funkce: není podporováno.
Null hodnoty nejsou podporovány jako operand ve výrazech filtru. Například nelze zadat null hodnotu pro filtrování pro vlastnosti nenastavené.
Chcete-li filtrovat na binární vlastnosti, jako issuerUserId v userIdentities, hodnota musí být nejprve před použitím v řetězci $filter kódováním base64.
$orderby
$orderby bude seřadit zadaný parametr vrácených objektů. Příklad požadavky pomocí možnost $orderby:
| Požadavek | Popis |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Vrátí seznam seřazených podle jejich zobrazovaného jména uživatelů. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Vrátí seznam seřazených podle jejich zobrazovaného jména prvních 50 uživatelů. |
$Orderby výrazy platí následující omezení:
Dvě pořadí řazení se aktuálně podporují: DisplayName pro uživatele a skupiny objekty, a UserPrincipalName pro uživatele objekty. Výchozí pořadí řazení pro uživatele, je UserPrincipalName.
$orderby nelze kombinovat s výrazy $filter.
$expand
$, rozbalte položku se vrátí objekt a jeho propojené objekty. Příklad požadavky pomocí $rozbalte možnost:
| Požadavek | Popis |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Vrátí objekt skupiny jak její členy. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Vrátí objekt uživatele jak jeho přímé podřízené. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Vrátí objekt uživatele jak jejího správce. |
Následující omezení se vztahují na $rozbalte výrazů:
- Maximální počet vrácených objektů pro žádost je 20.
$top
$top není podporovaný pro dotazy na DirectoryRole nebo SubscribedSku objektů adresáře.
Podporu stránkování
V tomto grafu můžete stránkách vpřed a zpět. Odpověď obsahující stránkových výsledků bude obsahovat token přeskočit (odata.nextLink), které umožňuje získat další stránky výsledků. Tento token skip je možné kombinovat s předchozí stránce = true dotaz argument zpětné stránky.
Příklad žádost postupujte podle ukazuje stránkování dál:
| Požadavek | Popis |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
$Skiptoken parametr z předchozí odpovědi je součástí a umožňuje získat další stránky výsledků. |
Požadavek následující příklad ukazuje zpátky stránkování:
| Požadavek | Popis |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
$Skiptoken parametr z předchozí odpovědi je součástí. Pokud je to kombinovat s & předchozí stránce = true bude načten parametr, předchozí stránky s výsledky. |
Následující kroky ukazují toku požadavků a odpovědí na stránkách vpřed a zpět:
- Žádosti se získat seznam prvních 10 uživatelů mimo 15. Odpověď obsahuje token a přeskočit znamenat poslední stránce 10 uživatelů.
- Poslední 5 uživatelů získáte jiné požadavku, obsahuje token přeskočit vrácená z předchozí odpovědi.
- Na stránku zpátky, je zaslán požadavek pomocí tokenu přeskočit, vrátí se v kroku 1 a parametr & předchozí stránce = true se přidá k požadavku.
- Odpověď obsahuje předchozí stránce (první) 10 uživatelů. V jiný scénář, kde jsou ponechána další stránky bude vrácen nový token přeskočit. Tento nový token přeskočit lze přidat na žádost o spolu s & předchozí stránce = true na stránku zpátky znovu.
Na stránkové požadavky platí následující omezení:
- Výchozí velikost stránky je 100. Maximální velikost stránky je 999.
- Dotazy na role nepodporují stránkování. To zahrnuje čtení objektů role sami a také role členy.
- Prostředek výpis, jako je hledání pro všechny uživatele v klientovi (/Users), dotazy podporují stránkování. Příklad:
https://graph.windows.net/contoso.com/users?api-version=1.6. Ale všech typů při se filtr použije, stránkování není podporována a je vrácen pouze první stránky s výsledky. - Stránkování nepodporuje hledání je odkaz, například pro dotazování na členy skupiny. Příklad:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Pořadí řazení
- Sada výsledků dotazu pro všechny uživatele je seřazené podle UserPrincipalName vlastnost. Příklad:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Sada výsledků dotazu pro všechny ostatní prostředky nejvyšší úrovně, jako jsou skupiny, kontakty, atd. je seřazené podle objectId vlastnost. Příklad:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - Pořadí výsledky dotazů jiné než pro prostředky nejvyšší úrovně je neurčitou.
Běžné dotazy
Následující části vysvětlují několik příkladů běžných dotazů, které můžete provádět pomocí rozhraní Graph API.
Dotaz na nejvyšší úrovni prostředky
Následující dotazy ukazují, jak získat přístup k prostředkům nejvyšší úrovně s použitím contoso.com jako příklad klienta rozhraní Graph API. Všimněte si, že hlavičku autorizace obsahující platné nosný token přijatého z Azure AD bude nutné ke spouštění dotazů na klienta.
| Nejvyšší úrovně prostředků | Výsledky dotazu | Identifikátor URI (contoso.com) |
|---|---|---|
| Nejvyšší úrovně prostředky | Vrátí seznam URI nejvyšší úrovně prostředků pro directory services (také uvedené níže) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Informace o společnosti | Vrátí společnosti informace | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Kontakty | Vrátí organizační kontaktní informace | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Uživatelé | Vrátí informace o uživateli | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| skupiny | Vrátí seskupení dat | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Role adresáře | Vrátí všechny role aktivovaný adresáře v klientovi | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Vrátí odběry klienta | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Metadat adresáře | Vrátí Metadata dokument služby, který popisuje datový model (to znamená, struktura a organizace prostředky adresáře) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Jiné operace dotazů
Následující tabulka uvádí některé další příklad rozhraní Graph API dotazy pomocí contoso.com jako příklad klienta.
| Operace dotazů | Identifikátor URI (contoso.com) |
|---|---|
| Zobrazí seznam všech uživatelů a skupin | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Zadáním objectId nebo userPrincipalName načíst jednotlivé uživatele | 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 |
| Vyžádat a filtrování pro uživatele se zobrazovaným názvem rovno "Jan Doe" | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Vyžádat a filtrování pro konkrétní uživatele s firstName rovno "Jan" | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtr pro hodnoty givenName a příjmení. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Načtení jednotlivé skupiny zadáním objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Načtení správce uživatele | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Načtení seznamu uživatele přímé podřízené | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Načtení seznamu odkazů na uživatele přímé podřízené | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Načtení seznamu členství ve skupině | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Načtení seznamu odkazů na členy skupiny. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Načíst uživatele členství ve skupině (není přenositelné) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Načtení seznamu skupin, že uživatel je členem skupiny (není přenositelné) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Vyžádat a filtrování pro skupiny se zobrazovaným názvem > = "az" a < = "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Vrátí všechny místní účet uživatele v klienta služby Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Návratový místní účet uživatele s názvem přihlášení "joe@example.com" z tenanta služby Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Poznámka:: prázdné znaky v řetězci dotazu by měla být kódovaná adresou URL před odesláním požadavku. Například následující dotaz řetězci https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, by měl být kódovaná v řetězci URL jako: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.