Obsługiwane opcje stronicowania, filtry i zapytania | Pojęcia dotyczące interfejsu API programu Graph
W tym temacie wymieniono opcje zapytania, filtrów i operacji stronicowania, korzystających z interfejsu API programu Graph usługi Azure Active Directory (AD). Końcowe części przedstawiono kilka przykładów typowych zapytania, które można wykonywać przy użyciu interfejsu API Azure AD Graph.
Ważne
Zdecydowanie zaleca się używanie Microsoft Graph zamiast interfejsu API Azure AD Graph dostęp do zasobów usługi Azure Active Directory. Nasze programistycznych teraz jest skoncentrowana na program Microsoft Graph i interfejsu API usługi Azure AD Graph planowane żadne rozszerzenia funkcjonalności. Istnieje bardzo ograniczoną liczbę scenariuszy, w których interfejsu API usługi Azure AD Graph nadal może być odpowiednie; Aby uzyskać więcej informacji, zobacz Microsoft Graph lub Azure AD Graph wpis w blogu w Centrum deweloperów pakietu Office.
Adresowanie
Zapytania poniżej wszystkich adresów dzierżawcy przy użyciu nazwy domeny. Można zastąpić contoso.com z jedną z nazw zarejestrowana domena Twojej dzierżawy, z Twojej dzierżawy Identyfikatora (GUID) lub z MyOrganization aliasu (na potrzeby delegowanej dostępu). W niektórych przypadkach można używać me alias. Aby uzyskać informacje na temat adresowania dzierżawy, zobacz Przegląd operacji.
Opcje zapytania obsługiwane
Wykres obsługuje następujące opcje zapytania: $filter, $orderby, rozwiń $, $top, i $format. Następujące opcje zapytania nie są obecnie obsługiwane: $count, $inlinecount, i $skip.
$filter
Do zapytań, które zawiera filtru, obowiązują następujące ograniczenia ogólne:
$filter nie można połączyć z wyrażenia $orderby.
Filtrowanie nie jest obsługiwane dla zapytań na DirectoryRole lub SubscribedSku obiektów katalogu.
Nie wszystkie właściwości obiektów katalogu obsługiwane mogą być używane w wyrażeniu filtru. Informacje o właściwościach można filtrować obsługiwanych typów, zobacz użytkownika, grupy, i skontaktuj się z.
Do wyrażenia filtru, obowiązują następujące ograniczenia:
Operatory logiczne: i i lub są obsługiwane. Na przykład:
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')Operatory porównania: eq (równy), ge (większe lub równe) i le (mniejsze niż lub równe) są obsługiwane.
StartsWith jest obsługiwana. Na przykład:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')wszelkie jest obsługiwana podczas wykonywania zapytań dotyczących właściwości wielowartościowych. Na przykład:
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')Operatory arytmetyczne: nieobsługiwane.
Funkcje: nieobsługiwane.
wartość null wartości nie są obsługiwane jako argumentu w wyrażeniach filtru. Na przykład nie można określić null wartości do filtrowania nie ustawiono właściwości.
Aby odfiltrować właściwości binarnej, takich jak issuerUserId w userIdentities, wartość musi być najpierw kodowanie base64 zanim będzie można ich użyć w ciągu $filter.
$orderby
$orderby sortowania obiektów zwracanych przez określony parametr. Przykład żądania przy użyciu opcji $orderby:
| Żądanie | Opis |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Zwraca listę użytkowników, uporządkowanych według nazwy wyświetlanej. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Zwraca listę najpierw 50 użytkowników, uporządkowanych według nazwy wyświetlanej. |
Do wyrażenia $orderby, obowiązują następujące ograniczenia:
Obecnie obsługiwane są dwa sortowania: DisplayName dla użytkownika i grupy obiekty i UserPrincipalName dla użytkownika obiektów. Domyślny porządek sortowania dla użytkowników jest UserPrincipalName.
Nie można łączyć $orderby za pomocą wyrażeń $filter.
Rozwiń węzeł $
$Rozwiń będzie zwracać obiekt i jego powiązane obiekty. Przykład żądań przy użyciu $rozwiń opcję:
| Żądanie | Opis |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Zwraca zarówno obiektu grupy, jak i jej elementów członkowskich. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Zwraca zarówno obiekt użytkownika, jak i jego bezpośrednich podwładnych. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Zwraca zarówno obiekt użytkownika, jak i jego menedżera. |
Następujące ograniczenia dotyczące $rozwiń wyrażeń:
- Maksymalna liczba zwracanych obiektów na żądanie wynosi 20.
$top
$top nie jest obsługiwana dla zapytań w DirectoryRole lub SubscribedSku obiektów katalogu.
Obsługę stronicowania
Można strony do przodu i do tyłu na wykresie. Odpowiedź, która zawiera wyników stronicowania będzie zawierać token Pomiń (odata.nextLink) umożliwiająca do pobrania następnej strony wyników. Ten token Pomiń można łączyć z poprzedniej strony = true zapytania argument strony z poprzednimi wersjami.
Wykonaj przykładowe żądanie przedstawiono stronicowania do przodu:
| Żądanie | Opis |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
$Skiptoken parametru z poprzedniej odpowiedzi jest dołączony i służy do pobrania następnej strony wyników. |
Następujące przykładowe żądanie przedstawiono wstecz stronicowania:
| Żądanie | Opis |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
$Skiptoken dołączono parametr z poprzedniej odpowiedzi. Gdy jest ona połączona z & poprzedniej strony = true parametru poprzedniej strony wyników zostaną pobrane. |
Następująca procedura przedstawia przepływ żądania/odpowiedzi stronę do przodu i do tyłu:
- Żądań w celu uzyskania listy użytkowników 10 pierwszych poza 15. Odpowiedź zawiera token Pomiń, aby wskazać na ostatniej stronie 10 użytkowników.
- Uzyskanie 5 użytkowników końcowych innego żądań które zawiera token Pomiń zwrócony z poprzedniej odpowiedzi.
- Na stronie do tyłu, żądanie przy użyciu tokenu Pomiń zwracane w kroku 1, a parametr & poprzedniej strony = true zostanie dodany do żądania.
- Odpowiedź zawiera poprzedniej strony (pierwszego) 10 użytkowników. W przypadku różnych, gdzie więcej strony są pozostawiane będzie zwracany nowy token skip. Ten nowy token Pomiń mogą być dodawane do żądania wraz z & poprzedniej strony = true stronę wstecz ponownie.
Do żądań stronicowanej, obowiązują następujące ograniczenia:
- Domyślny rozmiar strony to 100. Maksymalny rozmiar strony jest 999.
- Zapytania względem ról nie obsługują stronicowania. Obejmuje to odczytywanie obiektów roli się, jak również rolę elementów członkowskich.
- Wykaz, takie jak wyszukiwanie dla wszystkich użytkowników w dzierżawie zasobów (/użytkownicy), zapytania obsługują stronicowania. Na przykład:
https://graph.windows.net/contoso.com/users?api-version=1.6. Jednak wszystkich typów po zastosowaniu filtru Stronicowanie nie jest obsługiwane i zwracany jest tylko pierwszej strony wyników. - Stronicowanie nie jest obsługiwane dla łącza wyszukiwania, takie jak zapytań członków grupy. Na przykład:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Kolejność sortowania
- Zestaw wyników zapytania dla wszystkich użytkowników jest określona przez UserPrincipalName właściwości. Na przykład:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Zestaw wyników zapytania dla wszystkich innych zasobów najwyższego poziomu, takich jak grupy, kontakty, itp. jest określona przez objectId właściwości. Na przykład:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - Kolejność wyników zapytania innych niż dla zasobów najwyższego poziomu jest nieokreślony.
Typowe zapytania
W poniższych sekcjach przedstawiono kilka przykładów typowych zapytania, które można wykonywać za pomocą interfejsu API programu Graph.
Wykonywanie zapytania najwyższego poziomu
Następujące zapytania pokazują, jak uzyskać dostęp do zasobów najwyższego poziomu z interfejsu API programu Graph jako przykład dzierżawcy przy użyciu contoso.com. Należy pamiętać, że nagłówek uwierzytelnienia zawierające token elementu nośnego prawidłowy odebranych z usługi Azure AD będzie wymagane do wykonywania kwerend do dzierżawcy.
| Zasób najwyższego poziomu | Wyniki zapytania | Identyfikator URI (contoso.com) |
|---|---|---|
| Zasoby najwyższego poziomu | Zwraca listę URI najwyższego poziomu zasobów dla usług katalogowych (również wymienione poniżej) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Informacje o firmie | Zwraca firmy | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Kontakty | Informacje kontaktowe zwraca organizacji | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Zwraca informacje o użytkowniku | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Grupy | Zwraca grupowania danych | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Role katalogu | Zwraca wszystkie role aktywowanego katalogu w dzierżawie | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Zwraca subskrypcji dzierżawcy | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Metadanych katalogów | Zwraca dokument metadanych usługi, który opisuje modelu danych (czyli struktury i organizacji zasobów katalogu) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Inne operacje kwerend
W poniższej tabeli przedstawiono dodatkowe przykładowe zapytania interfejsu API programu Graph, używając contoso.com jako przykład dzierżawy.
| Operacji zapytania | Identyfikator URI (contoso.com) |
|---|---|
| Wyświetl listę wszystkich użytkowników i grup | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Pobrać poszczególnych użytkowników, określając identyfikator obiektu lub 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 |
| Żądanie i je filtrować użytkownika o nazwie wyświetlanej równa "Jan Nowak" | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Żądanie i filtrowania określonych użytkowników z imię równa "Jan" | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Filtr wartości imię i nazwisko. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Pobieranie pojedynczej grupy, określając identyfikator obiektu | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Pobrać menedżera użytkownika | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Pobieranie listy użytkownika bezpośrednich podwładnych | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Pobieranie listy łączy do użytkownika bezpośrednich podwładnych | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Pobieranie listy członkostwa grupy | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Pobieranie listy łączy do elementów członkowskich grupy. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Pobrać członkostwa grupy użytkownika (nie przechodnie) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Pobieranie listy grup, czy użytkownik jest członkiem (nie przechodnie) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Żądanie i je filtrować grupy o nazwie wyświetlanej > = "az" i < = "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Zwraca wszystkie lokalne konta użytkowników w dzierżawie usługi Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Zwracany lokalnego konta użytkownika o nazwie logowania "joe@example.com" z dzierżawy usługi 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 |
Uwaga: biały znak w ciągu zapytania powinien być zakodowane w adresie URL przed wysłaniem żądania. Na przykład następujące zapytanie ciągu https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, powinny być zakodowanych jako adres URL jako: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.