Query's, filters en opties voor paginering ondersteund | Graph API-concepten
Dit onderwerp worden de query-opties, filters en paginering bewerkingen die u met de Azure Active Directory (AD) Graph API gebruiken kunt. De laatste sectie vindt u enkele voorbeelden van algemene query's die u met de Azure AD Graph API uitvoeren kunt.
Belangrijk
Wordt aangeraden dat u Microsoft Graph in plaats van Azure AD Graph API voor toegang tot Azure Active Directory-resources. Ontwikkeling van onze producten nu concentreren zich bij Microsoft Graph en geen verdere verbeteringen zijn gepland voor Azure AD Graph API. Er zijn een zeer beperkt aantal scenario's waarvoor Azure AD Graph API nog steeds mogelijk geschikt; Zie voor meer informatie de Microsoft Graph of de Azure AD Graph blogbericht in het Office-ontwikkelaarscentrum.
Addressing
De query's onder alle omgaan met de tenant met een domeinnaam. U kunt vervangen contoso.com met een van de geregistreerde domeinnamen van uw tenant, met uw tenant-ID (GUID) of met de MyOrganization alias (voor gedelegeerde toegang). In sommige gevallen kunt u mogelijk gebruik van de me alias. Zie voor meer informatie over de manieren voor het oplossen van de tenant van overzicht van bewerkingen.
Ondersteunde query-opties
De grafiek ondersteunt de volgende queryopties: $filter, $orderby, $expand-, $top, en $format. De volgende queryopties worden momenteel niet ondersteund: $count, $inlinecount, en $skip.
$filter
De volgende algemene beperkingen zijn van toepassing op query's met een filter:
$filter kan niet worden gecombineerd met $orderby expressies.
Filteren wordt niet ondersteund voor query's op DirectoryRole of SubscribedSku directory-objecten.
Niet alle eigenschappen van de ondersteunde directory-objecten kunnen worden gebruikt in een filterexpressie. Zie voor meer informatie over Filterbaar eigenschappen van de ondersteunde typen gebruiker, groep, en Contact.
De volgende beperkingen zijn van toepassing op filterexpressies:
Logische operators: en en of worden ondersteund. Bijvoorbeeld:
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')Vergelijkingsoperators: eq (gelijk aan) ge (groter dan of gelijk zijn aan), en RP (kleiner dan of gelijk aan) worden ondersteund.
StartsWith wordt ondersteund. Bijvoorbeeld:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')alle wordt ondersteund bij het opvragen van eigenschappen met meerdere waarden. Bijvoorbeeld:
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')Rekenkundige operatoren: niet ondersteund.
Functies: niet ondersteund.
Null waarden worden niet ondersteund als een operand in filterexpressies. Bijvoorbeeld, u niet opgeven een null waarde voor het filteren van eigenschappen niet in.
Om te filteren op een binaire eigenschap, zoals de issuerUserId in userIdentities, de waarde moet eerst base64-gecodeerd voordat deze kan worden gebruikt in de tekenreeks $filter.
$orderby
$orderby, worden de geretourneerde objecten gesorteerd op de opgegeven parameter. Voorbeeld aanvragen met de optie $orderby:
| Aanvraag | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Retourneert een lijst met gebruikers die zijn geordend op hun weergavenaam. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Retourneert een lijst van de eerste 50 gebruikers hun weergavenaam geordend. |
De volgende beperkingen zijn van toepassing op $orderby expressies:
Twee sorteervolgorde worden momenteel ondersteund: DisplayName voor gebruiker en groep objecten, en UserPrincipalName voor gebruiker objecten. De standaardsorteervolgorde voor gebruikers is door UserPrincipalName.
$orderby kan niet worden gecombineerd met $filter expressies.
$expand-
$expand-wordt een object en de gekoppelde objecten retourneren. Voorbeeld aanvragen met de volgende $expand-optie:
| Aanvraag | Description |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Retourneert zowel het groepsobject als leden. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Zowel het gebruikersobject als de directe ondergeschikten retourneert. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Retourneert zowel het gebruikersobject als de manager. |
De volgende beperkingen gelden voor $ expressies uit te vouwen:
- Het maximum aantal geretourneerde objecten voor een aanvraag is 20.
$top
$top wordt niet ondersteund voor query's op DirectoryRole of SubscribedSku directory-objecten.
Ondersteuning voor paginering
U kunt voorwaarts en achterwaarts pagina in de grafiek. Een antwoord met pagina's met zoekresultaten bevat een skip-token (odata.nextLink) waarmee u de volgende pagina van de resultaten ophalen. Dit token overslaan kan worden gecombineerd met een vorige pagina = true argument voor de pagina achterwaarts zoeken.
De volgaanvraag voorbeeld demonstreert paging doorsturen:
| Aanvraag | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
De $skiptoken parameter van het vorige antwoord is opgenomen en kunt u downloaden van de volgende pagina van de resultaten. |
Het volgende voorbeeld van de aanvraag wordt getoond hoe achterwaarts paging:
| Aanvraag | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
De $skiptoken parameter van het vorige antwoord is opgenomen. Wanneer dit wordt gecombineerd met de & vorige pagina = true parameter, de vorige pagina van de resultaten worden opgehaald. |
De volgende stappen laten zien dat de aanvraag/antwoord-stroom naar pagina voorwaarts en achterwaarts:
- Een aanvraag wordt gedaan voor een lijst van de eerste 10 gebruikers buiten 15. Het antwoord bevat een token overslaan om aan te geven van de laatste pagina van 10 gebruikers.
- Als u de laatste 5 gebruikers, een andere aanvraag wordt doorgevoerd die de skip-token geretourneerd van het vorige antwoord bevat.
- Pagina achteruit, een aanvraag wordt gedaan met behulp van het overslaan token geretourneerd in stap 1 en de parameter & vorige pagina = true wordt toegevoegd aan de aanvraag.
- Het antwoord bevat de vorige pagina (eerste) 10 gebruikers. In een ander scenario waar meer pagina's worden gehandhaafd, wordt een nieuw skip-token geretourneerd. Deze nieuwe skip-token kan worden toegevoegd aan de aanvraag samen met & vorige pagina = true naar vorige pagina opnieuw.
De volgende beperkingen zijn van toepassing op wisselbare aanvragen:
- Grootte van de pagina is 100. De maximale paginagrootte is 999.
- Query's voor rollen bieden geen ondersteuning voor paginering. Dit omvat lezen van objecten van de rol zelf, evenals een rol leden.
- Resource op te nemen, zoals een zoekopdracht voor alle gebruikers in een tenant (/Users), query's bieden ondersteuning voor paginering. Bijvoorbeeld:
https://graph.windows.net/contoso.com/users?api-version=1.6. Echter alle typen wanneer een filter wordt toegepast, paginering niet wordt ondersteund en wordt alleen de eerste pagina van de resultaten geretourneerd. - Paginering wordt niet ondersteund voor koppeling zoekacties, zoals query's groepsleden. Bijvoorbeeld:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Sorteervolgorde
- De resultatenset van een query voor alle gebruikers die is besteld op het UserPrincipalName eigenschap. Bijvoorbeeld:
https://graph.windows.net/contoso.com/users?api-version=1.6. - De resultatenset van een query voor alle andere op het hoogste niveau resources, zoals groepen, contactpersonen, enz. is besteld op het objectId eigenschap. Bijvoorbeeld:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - De volgorde van de resultaten van query's is anders dan voor resources op het hoogste niveau onbepaald.
Algemene query 's
De volgende secties ziet enkele voorbeelden van algemene query's die u met de Graph API uitvoeren kunt.
Uitvoeren van query's op het hoogste niveau resources
De volgende query's laten zien hoe u toegang krijgen tot bronnen op het hoogste niveau met de Graph API met behulp van contoso.com als voorbeeld van de tenant. Houd er rekening mee dat een autorisatie-header met een geldige bearer-token ontvangen van Azure AD moeten worden query's uitvoeren op een tenant.
| Op het hoogste niveau Resource | Queryresultaten | De URI (voor contoso.com) |
|---|---|---|
| Bronnen op het hoogste niveau | Retourneert de lijst URI van de bronnen op het hoogste niveau voor directoryservices (ook Zie hieronder) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Bedrijfsgegevens | Retourneert de bedrijfsgegevens | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Contactpersonen | Retourneert organisatie contactgegevens | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Retourneert informatie over de gebruiker | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Groepen | Retourneert groeperen gegevens | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Directory-functies | Retourneert alle geactiveerde directory rollen in de tenant | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Retourneert de tenant-abonnementen | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Directory-metagegevens | Retourneert een servicedocument metagegevens die worden beschreven van het gegevensmodel (dat wil zeggen, structuur en organisatie van directory-bronnen) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Andere querybewerkingen
De volgende tabel bevat aanvullende voorbeelden Graph API query's op basis van contoso.com als voorbeeld van de tenant.
| Querybewerking | De URI (voor contoso.com) |
|---|---|
| Lijst van alle gebruikers en groepen | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Afzonderlijke gebruiker ophalen door de object-id of userPrincipalName te geven | 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 |
| Vragen en te filteren op een gebruiker met de weergavenaam is gelijk aan 'Jan de Vries' | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Vragen en te filteren op specifieke gebruikers met firstName gelijk aan "Jan" | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Voornaam en achternaam waarden filteren. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Afzonderlijke groep door op te geven van de object-id ophalen | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Ophalen van de manager van een gebruiker | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Een gebruiker directe ondergeschikten lijst ophalen | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Een lijst met koppelingen naar een gebruiker directe ondergeschikten ophalen | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| De lidmaatschapslijst van een groep ophalen | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Een lijst met koppelingen naar de leden van een groep ophalen. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Lidmaatschap van een gebruiker (niet-transitieve) niet ophalen | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Een lijst van de groepen waarvan de gebruiker een lid (niet-transitieve) is ophalen | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Vragen en te filteren voor groepen met weergavenaam > = 'az' en < = 'dz' | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Alle gebruikers van het lokale account in een Azure Active Directory B2C-tenant retourneren | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Gebruiker Return lokale account met de naam 'joe@example.com' van een Azure Active Directory B2C-tenant | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Opmerking: witruimte in de query-tekenreeks moet URL-codering voordat een aanvraag wordt verzonden. Bijvoorbeeld de volgende tekenreeks, query https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, moet URL-codering: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.