Támogatott lekérdezések, szűrők és lapozási beállítások |} Graph API fogalmak
Ez a témakör felsorolja a lekérdezési lehetőségek, szűrők és az Azure Active Directory (AD) Graph API-val használható lapozási műveletek. A végső szakaszban találhat néhány olyan gyakori lekérdezések hajthat végre az Azure AD Graph API-t.
Fontos
Határozottan javasoljuk, hogy használjon Microsoft Graph helyett az Azure AD Graph API Azure Active Directory-erőforrások eléréséhez. A fejlesztéshez most összpontosítani Microsoft Graph, és nincs további fejlesztések Azure AD Graph API tervbe van véve. Nagyon korlátozott számú forgatókönyvek, amelyek az Azure AD Graph API továbbra is megfelelő lehet; További információkért lásd: a Microsoft Graph vagy az Azure AD Graph blogbejegyzés az Office-fejlesztői központban.
Címzés
A lekérdezések alatti összes hárítsa el a bérlő tartománynévvel. Lecserélheti contoso.com valamelyik, a bérlő regisztrált tartománynév, a bérlő-azonosító (GUID) rendelkező, vagy a a MyOrganization alias (a delegált hozzáférést). Bizonyos esetekben bizonyára tudni használni a me alias. A bérlő címzési vonatkozó információkért lásd: áttekintése.
Támogatott lekérdezési lehetőségek
A grafikon támogatja a következő lekérdezési lehetőségek: $filter, $orderby, $expand argumentum, $top, és $format. A következő lekérdezési lehetőségek jelenleg nem támogatottak: $count, $inlinecount, és $skip.
$filter
Lekérdezések, amelyek tartalmaznak egy szűrőt a következő általános korlátozások vonatkoznak:
$filter, $orderby kifejezések nem kombinálható.
Szűrés nem támogatott a lekérdezések DirectoryRole vagy SubscribedSku címtárobjektumok.
A szűrőkifejezés nem támogatott directory-objektumok tulajdonságainak használható. További információ a támogatott típusok szűrhető tulajdonságairól: felhasználói, csoport, és forduljon.
A következő korlátozások vonatkoznak szűrőkifejezéseket:
Logikai operátorok: és és vagy támogatottak. Például így:
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')Összehasonlító operátorok: eq (egyenlő), ge (nagyobb vagy egyenlő), és le (kisebb vagy egyenlő, mint) használata támogatott.
megadott módon kezdődő esetén támogatott. Például így:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')bármely többértékű tulajdonságok lekérdezésekor támogatott. Például így:
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')Aritmetikai operátor: nem támogatott.
Funkciók: nem támogatott.
NULL értékek használata nem támogatott szűrőkifejezésekben operandusaként. Például nem adható meg egy null beállított tulajdonságok szűréshez értéket.
Bináris tulajdonsága szűréshez, mint a issuerUserId a userIdentities, értékét kell a base64 kódolású ahhoz, hogy a $filter karakterláncban kell használni.
$orderby
$orderby rendezze a visszaadott objektumok a megadott paraméterrel. Példa kérések a $orderby beállítás használatával:
| Kérelem | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
A felhasználók a megjelenített név szerint rendezett listáját adja vissza. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Az első 50 felhasználók megjelenítendő neve szerint rendezett listáját adja vissza. |
A következő korlátozások vonatkoznak a $orderby kifejezések:
Két a rendezési sorrend jelenleg támogatottak: DisplayName a felhasználói és csoport objektumokat, és UserPrincipalName a felhasználói objektumok. A felhasználók számára az alapértelmezett rendezési sorrend szerint van UserPrincipalName.
$orderby kifejezések $filter nem használható együtt.
Bontsa ki a $
$expand argumentum lesz az objektum, valamint azokat a csatolt objektumok. Példa kérelmek használatával az $ bontsa ki a beállítást:
| Kérelem | Description |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Mind a csoportházirend-objektum, valamint a tagot adja vissza. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Mind a felhasználói objektum, valamint a közvetlen beosztottak adja vissza. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Mind a felhasználói objektum, valamint a kezelő adja vissza. |
A következő korlátozások vonatkoznak $ bontsa ki a kifejezések:
- A visszaadott objektumok a kérelmek maximális száma: 20.
$top
$top nem támogatott a lekérdezések DirectoryRole vagy SubscribedSku címtárobjektumok.
Lapozás támogatása
A grafikonon is lapozhatunk előre és hátra. A lapozható eredmények tartalmazó válasz tartalmazza a kihagyási lexikális elem (odata.nextLink), amely lehetővé teszi, hogy a következő oldalra, beolvasása. A kihagyási lexikális elem kombinálható egy előző lapon = true argumentumának visszamenőleges lapon lekérdezése.
A következő példa egy kérelem bemutatja a lapozás előre:
| Kérelem | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
A $skiptoken paramétert az előző válaszban része, és lehetővé teszi a következő oldalra, beolvasása. |
A következő példa egy kérelem bemutatja a lapozás visszafelé:
| Kérelem | Description |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
A $skiptoken megtalálható az előző válaszban paramétert. Ha ezzel együtt a & előző lapon = true paramétert, az előző lapon, az eredmények lekérésének. |
A következő lépések azt mutatják be, a lapozhatunk előre és hátra a kérelem/válasz folyamata:
- A kérelem 15 kívül az első 10 felhasználók listáját. A válasz 10 olyan felhasználót utolsó lapján jelzéséhez skip jogkivonatot tartalmaz.
- Ahhoz, hogy az utolsó 5 felhasználók, egy másik kérelem, amely tartalmazza a skip jogkivonatot adott vissza az előző válaszban.
- Visszafelé lapra, a kérelem a skip jogkivonatot adott vissza az 1. lépés és a paraméter használatával & előző lapon = true hozzáadódik a kérelmet.
- A válasz az előző (első) oldalán látható 10 olyan felhasználót tartalmaz. Különböző forgatókönyvben, ahol több lapot megmaradnak egy új kihagyási lexikális elem vissza. Ez új kihagyási lexikális elem lehet hozzáadni a kérelmet, valamint & előző lapon = true újra visszafelé lapra.
Lapozható kérelmekre a következő korlátozások vonatkoznak:
- Az alapértelmezett oldal mérete 100. A maximális méretének 999 közötti érték.
- Szerepkörein lekérdezések nem támogatják a lapozás. Ez magában foglalja a szerepkör objektumok beolvasásakor magukat, valamint a szerepkör tagjai.
- Erőforrás listázása, például a bérlő összes felhasználója keresés (/Users), lekérdezések támogatják a lapozás. Például:
https://graph.windows.net/contoso.com/users?api-version=1.6. Azonban összes típusa a szűrő alkalmazása esetén nem támogatott a lapozás, és csak az első oldal eredményeket ad vissza. - Nem támogatott a lapozás hivatkozás keresésekhez, többek között csoporttagok lekérdezése. Például:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Rendezési sorrend
- Az eredménykészlet lekérdezés az összes felhasználó alapján van rendezve a UserPrincipalName tulajdonság. Például:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Az eredménykészlet a lekérdezés minden más legfelső szintű erőforrások, többek között a csoportok, névjegyek, stb. alapján van rendezve a objectId tulajdonság. Például:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - A lekérdezések eredményeit nem legfelső szintű erőforrások meghatározatlan.
Általános lekérdezések
A következő szakaszok bemutatják, néhány olyan gyakori lekérdezések Graph API-val végezheti el.
Legfelső szintű erőforrásainak lekérdezése
Az alábbi lekérdezéseket bemutatják, hogyan lehet contoso.com használja, mint a példa bérlő Graph API-val legfelső szintű erőforrások eléréséhez. Vegye figyelembe, hogy az Azure AD-ből kapott érvényes tulajdonosi jogkivonattal tartalmazó engedélyezési fejléc lesz szükség ahhoz, hogy egy bérlő lekérdezéseinek futtatásához.
| Legfelső szintű erőforrás | Lekérdezés eredményei | URI-JÁNAK (contoso.com) |
|---|---|---|
| Legfelső szintű erőforrások | A legfelső szintű erőforrások (is lenti) címtárszolgáltatás URI listáját adja vissza | https://graph.windows.net/contoso.com?api-version=1.6 |
| Vállalati adatok | A vállalati adatokat adja vissza | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Névjegyek | Szervezeti beolvasása kapcsolattartási adatok | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Felhasználói adatokat adja vissza. | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Csoportok | Értéket ad vissza adatokat csoport | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Directory szerepkörök | A bérlő adja vissza az összes aktivált directory szerepkör | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | A bérlői előfizetések adja vissza | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Directory metaadatok | A szolgáltatás metaadat-dokumentum, mely leírja az adatmodellbe (Ez azt jelenti, hogy a struktúra és a könyvtár-erőforrások) adja vissza | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Más lekérdezési műveletek
A következő táblázatban további példákat contoso.com használja, mint a példa bérlő Graph API-lekérdezések.
| Lekérdezési művelet | URI-JÁNAK (contoso.com) |
|---|---|
| Kilistázhatja az összes felhasználók és csoportok | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Egyéni felhasználói beolvasni a objectId vagy a userPrincipalName megadásával | 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 |
| Kérelem és a megjelenített egyenlő "Jon Doe" nevű felhasználó szűréséhez | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Kérése és Vezetéknév "Jon" egyenlő adott felhasználók szűrése | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Szűrés givenName és a Vezetéknév értékekre. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Egyéni csoport beolvasásához a objectId megadásával | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| A felhasználó kezelője beolvasása | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| A felhasználó közvetlen beosztottai listáját | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| A felhasználó közvetlen beosztottai mutató hivatkozások listájának beolvasása | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Egy csoport tagsági listájának beolvasása | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| A csoportnak a tagjai mutató hivatkozások listájának lekérésében. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| A felhasználó csoporttagsága (nem tranzitív) beolvasása | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| A csoportok, hogy a felhasználó tagja (nem tranzitív) listájának beolvasása | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Kérelem és a csoportok szolgáltatáskéréshez szűréséhez > = "az" és < = "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Az Azure Active Directory B2C-bérlő adja vissza az összes helyi fiókot használó felhasználók | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| A bejelentkezési névvel rendelkező visszatérési helyi fiók felhasználói "joe@example.com" az Azure Active Directory B2C-bérlő | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Megjegyzés:: szóköz, a lekérdezési karakterláncban kell URL-kódolású kérelem elküldése előtt. Például a következő lekérdezési karakterlánc, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, kell URL-cím kódolható: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.