Table of contents

Podporované dotazy, filtrů a možností stránkování | Rozhraní Graph API konceptySupported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|Poslední aktualizace: 19. 6. 2018
|
1 Přispěvatel

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).This topic lists query options, filters, and paging operations that you can use with the Azure Active Directory (AD) Graph API.Koncová část uvádí některé příklady běžné dotazy, které můžete provádět s Azure AD Graph API.The final section gives some examples of common queries that you can perform with the 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.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for 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.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Adresování Addressing

Dotazy níže všechny adres klienta pomocí názvu domény.The queries below all address the tenant using a domain name.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).You can replace contoso.com with one of your tenant’s registered domain names, with your tenant's ID (GUID), or with the MyOrganization alias (for delegated access).V některých případech může být možné používat me alias.In some cases, you may be able to use the me alias.Informace o způsobech adres klienta najdete v tématu Operations přehled.For information about ways of addressing the tenant, see Operations overview.

Možnosti podporované dotazu Supported query options

Graf podporuje následující možnosti dotazu: $filter, $orderby, $expand, $top, a $format.The Graph supports the following query options: $filter, $orderby, $expand, $top, and $format.Následující možnosti dotazu nejsou aktuálně podporovány: $count, $inlinecount, a $skip.The following query options are not currently supported: $count, $inlinecount, and $skip.

$filter$filter

Na dotazy, které obsahují filtr platí tato obecná omezení:The following general restrictions apply to queries that contain a filter:

  • $filter nelze kombinovat s výrazy $orderby.$filter cannot be combined with $orderby expressions.

  • Filtrování není podporovaný pro dotazy na DirectoryRole nebo SubscribedSku objektů adresáře.Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

  • Ne všechny vlastnosti objektů podporované directory lze použít ve výrazu filtru.Not all properties of supported directory objects can be used in a filter expression.Informace o filtrování vlastnosti podporované typy najdete v tématu uživatele, skupiny, a kontaktujte.For information about filterable properties of supported types, see User, Group, and Contact.

Filtr výrazy platí následující omezení:The following restrictions apply to filter expressions:

  • Logické operátory: a a nebo jsou podporovány.Logical operators: and and or are supported.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')For example: 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.Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.

  • StartsWith je podporována.startswith is supported.Příklad: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')For example: 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.any is supported when querying multi-valued properties.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')For example: 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.Arithmetic operators: not supported.

  • Funkce: není podporováno.Functions: not supported.

  • Null hodnoty nejsou podporovány jako operand ve výrazech filtru.null values are not supported as an operand in filter expressions.Například nelze zadat null hodnotu pro filtrování pro vlastnosti nenastavené.For example, you cannot specify a null value to filter for unset properties.

  • 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.To filter on a binary property such as the issuerUserId in userIdentities, the value must first be base64 encoded before it can be used in the $filter string.

$orderby$orderby

$orderby bude seřadit zadaný parametr vrácených objektů.$orderby will sort the returned objects by the specified parameter.Příklad požadavky pomocí možnost $orderby:Example requests using the $orderby option:

PožadavekRequestPopisDescription
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Vrátí seznam seřazených podle jejich zobrazovaného jména uživatelů.Returns a list of users ordered by their display name.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6Vrátí seznam seřazených podle jejich zobrazovaného jména prvních 50 uživatelů.Returns a list of the first 50 users ordered by their display name.

$Orderby výrazy platí následující omezení:The following restrictions apply to $orderby expressions:

  • Dvě pořadí řazení se aktuálně podporují: DisplayName pro uživatele a skupiny objekty, a UserPrincipalName pro uživatele objekty.Two sort orders are currently supported: DisplayName for User and Group objects, and UserPrincipalName for User objects.Výchozí pořadí řazení pro uživatele, je UserPrincipalName.The default sort order for users is by UserPrincipalName.

  • $orderby nelze kombinovat s výrazy $filter.$orderby cannot be combined with $filter expressions.

$expand$expand

$, rozbalte položku se vrátí objekt a jeho propojené objekty.$expand will return an object and its linked objects.Příklad požadavky pomocí $rozbalte možnost:Example requests using the $expand option:

PožadavekRequestPopisDescription
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Vrátí objekt skupiny jak její členy.Returns both the group object as well as its members.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Vrátí objekt uživatele jak jeho přímé podřízené.Returns both the user object as well as its direct reports.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6Vrátí objekt uživatele jak jejího správce.Returns both the user object as well as its manager.

Následující omezení se vztahují na $rozbalte výrazů:The following restrictions apply to $expand expressions:

  • Maximální počet vrácených objektů pro žádost je 20.The maximum number of returned objects for a request is 20.

$top$top

$top není podporovaný pro dotazy na DirectoryRole nebo SubscribedSku objektů adresáře.$top is not supported for queries on DirectoryRole or SubscribedSku directory objects.

Podporu stránkování Paging support

V tomto grafu můžete stránkách vpřed a zpět.You can page forward and backward in the Graph.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ů.A response that contains paged results will include a skip token (odata.nextLink) that allows you to get the next page of results.Tento token skip je možné kombinovat s předchozí stránce = true dotaz argument zpětné stránky.This skip token can be combined with a previous-page=true query argument to page backwards.

Příklad žádost postupujte podle ukazuje stránkování dál:The follow example request demonstrates paging forward:

PožadavekRequestPopisDescription
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ů.The $skiptoken parameter from the previous response is included, and allows you to get the next page of results.

Požadavek následující příklad ukazuje zpátky stránkování:The following example request demonstrates paging backward:

PožadavekRequestPopisDescription
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í.The $skiptoken parameter from the previous response is included.Pokud je to kombinovat s & předchozí stránce = true bude načten parametr, předchozí stránky s výsledky.When this is combined with the &previous-page=true parameter, the previous page of results will be retrieved.

Následující kroky ukazují toku požadavků a odpovědí na stránkách vpřed a zpět:The following steps demonstrate the request/response flow to page forward and backward:

  1. Žádosti se získat seznam prvních 10 uživatelů mimo 15.A request is made to get a list of the first 10 users out of 15.Odpověď obsahuje token a přeskočit znamenat poslední stránce 10 uživatelů.The response contains a skip token to indicate the final page of 10 users.
  2. Poslední 5 uživatelů získáte jiné požadavku, obsahuje token přeskočit vrácená z předchozí odpovědi.To get the final 5 users, another request is made that contains the skip token returned from the previous response.
  3. 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.To page backward, a request is made using the skip token returned in step 1 and the parameter &previous-page=true is added to the request.
  4. Odpověď obsahuje předchozí stránce (první) 10 uživatelů.The response contains the previous (first) page of 10 users.V jiný scénář, kde jsou ponechána další stránky bude vrácen nový token přeskočit.In a different scenario where more pages are left, a new skip token would be returned.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.This new skip token can be added to the request along with &previous-page=true to page backward again.

Na stránkové požadavky platí následující omezení:The following restrictions apply to paged requests:

  • Výchozí velikost stránky je 100.The default page size is 100.Maximální velikost stránky je 999.The maximum page size is 999.
  • Dotazy na role nepodporují stránkování.Queries against roles do not support paging.To zahrnuje čtení objektů role sami a také role členy.This includes reading role objects themselves as well as role members.
  • Prostředek výpis, jako je hledání pro všechny uživatele v klientovi (/Users), dotazy podporují stránkování.Resource listing, such as a search for all users in a tenant (/users), queries do support paging.Příklad: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.However, across all types when a filter is applied, paging is not supported and only the first page of results is returned.
  • Stránkování nepodporuje hledání je odkaz, například pro dotazování na členy skupiny.Paging is not supported for link searches, such as for querying group members.Příklad: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.For example: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Pořadí řazení Sort order

  • Sada výsledků dotazu pro všechny uživatele je seřazené podle UserPrincipalName vlastnost.The result set of a query for all users is ordered by the UserPrincipalName property.Příklad: https://graph.windows.net/contoso.com/users?api-version=1.6.For example: 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.The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property.Příklad: https://graph.windows.net/contoso.com/groups?api-version=1.6.For example: 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.The order of the results of queries other than for top-level resources is indeterminate.

Běžné dotazy Common queries

Následující části vysvětlují několik příkladů běžných dotazů, které můžete provádět pomocí rozhraní Graph API.The following sections show some examples of common queries you can perform with the Graph API.

Dotaz na nejvyšší úrovni prostředkyQuerying top-level resources

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.The following queries demonstrate how to access top-level resources with the Graph API using contoso.com as the example tenant.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.Note that an Authorization header containing a valid bearer token received from Azure AD will be required to run queries against a tenant.

Nejvyšší úrovně prostředkůTop-Level ResourceVýsledky dotazuQuery ResultsIdentifikátor URI (contoso.com)URI (for contoso.com)
Nejvyšší úrovně prostředkyTop-level resourcesVrátí seznam URI nejvyšší úrovně prostředků pro directory services (také uvedené níže)Returns URI list of the top-level resources for directory services (also listed below)https://graph.windows.net/contoso.com?api-version=1.6
Informace o společnostiCompany informationVrátí společnosti informaceReturns company informationhttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
KontaktyContactsVrátí organizační kontaktní informaceReturns organizational contact informationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UživateléUsersVrátí informace o uživateliReturns user informationhttps://graph.windows.net/contoso.com/users?api-version=1.6
skupinyGroupsVrátí seskupení datReturns group datahttps://graph.windows.net/contoso.com/groups?api-version=1.6
Role adresářeDirectory RolesVrátí všechny role aktivovaný adresáře v klientoviReturns all activated directory roles in the tenanthttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusSubscribedSkusVrátí odběry klientaReturns the tenant's subscriptionshttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Metadat adresářeDirectory metadataVrátí Metadata dokument služby, který popisuje datový model (to znamená, struktura a organizace prostředky adresáře)Returns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Jiné operace dotazůOther query operations

Následující tabulka uvádí některé další příklad rozhraní Graph API dotazy pomocí contoso.com jako příklad klienta.The following table shows some additional example Graph API queries using contoso.com as the example tenant.

Operace dotazůQuery OperationIdentifikátor URI (contoso.com)URI (for contoso.com)
Zobrazí seznam všech uživatelů a skupinList all Users and Groupshttps://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živateleRetrieve individual User by specifying the objectId or userPrincipalNamehttps://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"Request and Filter for a user with displayName equal to “Jon 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"Request and Filter for specific users with firstName equal to “Jon”https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Filtr pro hodnoty givenName a příjmení.Filter for givenName and surname values.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 objectIdRetrieve individual group by specifying the objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Načtení správce uživateleRetrieve a user’s managerhttps://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
Načtení seznamu uživatele přímé podřízenéRetrieve a user’s direct reports listhttps://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éRetrieve a list of links to a user’s direct reportshttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
Načtení seznamu členství ve skupiněRetrieve membership list of a grouphttps://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6
Načtení seznamu odkazů na členy skupiny.Retrieve a list of links to the members of a group.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é)Retrieve a user’s group membership (not transitive)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é)Retrieve a list of the groups that the user is a member of (not transitive)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"Request and filter for groups with displayName >= "az" and <= "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 B2CReturn all local account users in an Azure Active Directory B2C tenanthttps://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 B2CReturn local account user with the sign-in name "joe@example.com" from an Azure Active Directory B2C tenanthttps://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.Note: White space in the query string should be URL-encoded before sending a request.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.For example, the following query string, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

Další zdroje informací Additional resources

© 2018 Microsoft