Frågor, filter och alternativ för sidindelning som stöds | Graph API-begrepp
Det här avsnittet listar frågealternativ, filter och sidindelning åtgärder som du kan använda med Azure Active Directory (AD) Graph API. Den sista delen ger exempel på vanliga frågor som du kan utföra med Azure AD Graph API.
Viktigt
Vi rekommenderar starkt att du använder Microsoft Graph i stället för Azure AD Graph API för att komma åt resurser i Azure Active Directory. Vårt utvecklingsarbete är nu samlade på Microsoft Graph och inga fler förbättringar som planeras att Azure AD Graph API. Det finns ett begränsat antal scenarier som Azure AD Graph API kan fortfarande vara lämplig. Mer information finns i Microsoft Graph eller Azure AD Graph blogginlägget i Office Dev Center.
Adressering
Frågorna nedan alla hantera klienten med ett domännamn. Du kan ersätta contoso.com med ett registrerat domännamn för din klient, med din klient-ID (GUID) eller med den MyOrganization alias (för delegerad åtkomst). I vissa fall kan du använda den me alias. Information om olika sätt att adressera innehavaren finns Operationsöversikt.
Stöds frågealternativ
Diagrammet har stöd för följande frågealternativ: $filter, $orderby, $expand, $top, och $format. Följande fråga alternativ stöds inte för närvarande: $count, $inlinecount, och $skip.
$filter
Följande allmänna begränsningar gäller för frågor som innehåller ett filter:
$filter kan inte kombineras med $orderby uttryck.
Filtrering stöds inte för frågor på DirectoryRole eller SubscribedSku directory-objekt.
Inte alla egenskaper stöds katalogobjekt kan användas i ett filteruttryck. Information om filtrera egenskaper av typer som stöds finns i användare, grupp, och Kontakta.
Följande begränsningar gäller för filteruttryck:
Logiska operatorer: och och eller stöds. Exempelvis:
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')Jämförelseoperatorer: eq (lika med), ge (större än eller lika med), och le (mindre än eller lika med) stöds.
StartsWith stöds. Exempelvis:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')alla stöds när du frågar flera värden egenskaper. Exempelvis:
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')Aritmetiska operatorer: stöds inte.
Funktioner: stöds inte.
Null värden stöds inte som en operand i filteruttryck. Du kan till exempel ange en null värde att filtrera för att egenskaper.
Filtrera en binär egenskap som den issuerUserId i userIdentities, värdet måste först vara base64-kodade innan den kan användas i $filter-sträng.
$orderby
$orderby sorteras objekt som returneras av den angivna parametern. Exempel begäranden med alternativet $orderby:
| Begäran | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Returnerar en lista över användare sorterade efter deras visningsnamn. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Returnerar en lista över de första 50 användare sorterade efter deras visningsnamn. |
Följande begränsningar gäller för $orderby uttryck:
Två sorteringsordningar stöds för närvarande: DisplayName för användare och grupp objekt, och UserPrincipalName för användare objekt. Sorteringsordningen som standard för användare som är av UserPrincipalName.
$orderby kan inte kombineras med $filter uttryck.
$expand
$expand kan returnera ett objekt och dess länkade objekt. Exempel-begäranden som använder $Expandera alternativet:
| Begäran | Description |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Returnerar både gruppobjektet samt dess medlemmar. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Returnerar både användarobjektet samt dess direktrapporter. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Returnerar både användarobjektet samt dess manager. |
Följande begränsningar gäller för $Expandera uttryck:
- Det maximala antalet returnerade objekt för en begäran är 20.
$top
$top stöds inte för frågor på DirectoryRole eller SubscribedSku directory-objekt.
Stöd för sidindelning
Du kan bläddra framåt och bakåt i diagrammet. Ett svar som innehåller växlingsbara resultatet innehåller en skip-token (odata.nextLink) som gör det möjligt att hämta nästa sida i resultaten. Den här skip-token kan kombineras med en föregående sida = true fråga argumentet till sidan bakåtkompatibilitet.
Exempel följbegäran visar växling framåt:
| Begäran | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
Den $skiptoken parametern från föregående svar ingår, och du kan hämta nästa sida i resultaten. |
Följande exempelbegäran visar växling bakåt:
| Begäran | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
Den $skiptoken parametern från föregående svar ingår. När det kombineras med de & föregående sida = true parameter, föregående sida med resultat som ska hämtas. |
Följande steg visar begäranden/svar-flödet till framåt och bakåt:
- En begäran görs att hämta en lista över de första 10 användarna utanför 15. Svaret innehåller en skip-token för att ange den sista sidan i 10 användare.
- För att få de sista 5 användarna, en annan begäran görs som innehåller skip-token som returnerades från föregående svar.
- Om du vill bläddra bakåt en förfrågan görs med skip-token som returneras i steg 1 och parametern & föregående sida = true har lagts till i begäran.
- Svaret innehåller föregående (första) sida med 10 användare. I ett annat scenario där fler sidor lämnas, skulle en ny skip-token returneras. Den här nya skip-token kan läggas till begäran tillsammans med & föregående sida = true till sidan bakåt igen.
Följande begränsningar gäller för växlingsbara begäranden:
- Sidan standardstorleken är 100. Den maximala sidstorleken är 999.
- Frågor mot roller stöder inte sidindelning. Detta inkluderar läsning av rollen objekt själva samt rollen medlemmar.
- Resursen lista, till exempel en sökning efter alla användare i en klient (/Users), frågor stöder sidindelning. Till exempel:
https://graph.windows.net/contoso.com/users?api-version=1.6. Men för alla typer när ett filter används växling stöds inte och endast den första sidan av resultat returneras. - Sidindelning stöds inte för länken sökningar som för frågor gruppmedlemmar. Till exempel:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Sorteringsordningen
- Resultatet av en fråga för alla användare sorterade efter den UserPrincipalName egenskapen. Till exempel:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Resultatet av en fråga för alla andra översta resurser, till exempel grupper, kontakter, etc. sorterade efter den objectId egenskapen. Till exempel:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - Ordningen på resultatet av frågor är än för översta resurser obestämd.
Vanliga frågor
Följande avsnitt visar några exempel på vanliga frågor som du kan utföra med Graph API.
Förfrågan efter resurser på den översta nivån
Följande frågor visar hur du kommer åt resurser på den översta nivån med Graph-API med hjälp av contoso.com som exempel innehavare. Observera att ett Authorization-huvud som innehåller ett giltigt ägartoken som tas emot från Azure AD kommer att behöva köra frågor mot en klient.
| Översta resurs | Frågeresultat | URI: N (för contoso.com) |
|---|---|---|
| Översta resurser | Returnerar URI lista över de översta resurserna för directory services (även nedan) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Företagsinformation | Returnerar företagsinformation | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Kontakter | Returnerar organisationens kontaktinformation | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Användare | Returnerar information om användare | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Grupper | Returnerar gruppera data | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| I katalogen | Returnerar alla aktiverade directory roller i klienten | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Returnerar klientens prenumerationer | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Directory metadata | Returnerar ett tjänstdokument Metadata som beskriver datamodellen (det vill säga struktur och organisation för directory-resurser) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Andra frågeåtgärder
I följande tabell visas några ytterligare exempel Graph API-frågor med contoso.com som exempel innehavare.
| Frågeåtgärden | URI: N (för contoso.com) |
|---|---|
| Visa en lista över alla användare och grupper | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Hämta enskilda användare genom att ange objectId eller userPrincipalName | 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 |
| Begära och filtrera efter en användare med displayName som är lika med ”Jon Berg” | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Begära och filtrera efter specifika användare med förnamn som är lika med ”jan” | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtrera efter givenName och efternamn värden. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Hämta enskilda grupp genom att ange objekt-ID | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Hämta en användares chef | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Hämta en användares direktrapporter lista | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Hämta en lista med länkar till en användares direktrapporter | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Hämta listan över en grupp gruppmedlemskap | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Hämta en lista med länkar till medlemmar i en grupp. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Hämta en användares gruppmedlemskap (inte transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Hämta en lista över de grupper som användaren är medlem i (inte transitiva) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Begära och filtrera efter grupper med displayName > = ”az” och < = ”dz” | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Returnera alla användare för lokala konton i en Azure Active Directory B2C-klient | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Returnerade lokala användare med namnet inloggning ”joe@example.com” från en Azure Active Directory B2C-klient | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Obs: blanksteg i frågesträngen ska vara URL-kodade innan du skickar en begäran. Till exempel följande frågesträng, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, bör vara URL-kodade som: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.