Udostępnij za pośrednictwem

Przegląd operacji | Pojęcia dotyczące interfejsu API programu Graph

  • Artykuł

Interfejsu API programu Graph usługi Azure Active Directory (AD) jest usługą zgodne OData 3.0, która służy do odczytywania i modyfikowania obiektów, takich jak użytkownicy, grupy i kontakty w dzierżawie. Azure AD Graph API przedstawia punkty końcowe REST, które wysyłają żądania HTTP w celu wykonywania operacji przy użyciu usługi. Poniższe sekcje zawierają ogólne informacje o sposobie format żądania i czego oczekiwać w odpowiedzi, korzystając z interfejsu API programu Graph do odczytu i zapisu zasobów katalogu, wywołanie funkcji katalogu lub akcje lub wykonywać zapytania względem katalogu. Aby uzyskać szczegółowe informacje dotyczące wykonywania określonych operacji katalogu zasobów, zobacz temat odpowiednie działania w dokumentacja 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.

Pomyślne żądania interfejsu API programu Graph muszą być kierowane do prawidłowy punkt końcowy i być prawidłowo sformatowaną, oznacza to, musi zawierać wszystkie wymagane nagłówki i w razie potrzeby ładunek JSON w treści żądania. Aplikacji w żądaniu skierowanym musi zawierać token z usługi Azure AD, gdy okaże się, czy jest autoryzowany dostęp do zasobów docelowych przez żądanie. Aplikacja musi mieć możliwość obsługi odpowiedzi z interfejsu API programu Graph.

Sekcje w tym temacie pomoże zrozumieć, format żądania i odpowiedzi używane z interfejsu API programu Graph.

Uwierzytelnianie i autoryzacja

Każde żądanie do interfejsu API programu Graph musi mieć tokenu elementu nośnego wystawione przez usługi Azure Active Directory dołączony. Token posiada informacje o aplikacji, zalogowanego użytkownika (w przypadku delegowane uprawnienia), uwierzytelniania i operacji na katalogu, w którym aplikacja jest autoryzowany do wykonania. Token ten jest przenoszona w autoryzacji nagłówka żądania. Na przykład (token została skrócona do skrócenia):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Interfejsu API programu Graph wykonuje autoryzacji na podstawie zakresów uprawnień OAuth 2.0 jest obecny w tokenie. Aby uzyskać więcej informacji o zakresach uprawnienia, które ujawnia interfejsu API programu Graph, zobacz zakresy uprawnień interfejsu API Graph.

Aby aplikacji w celu uwierzytelniania za pomocą usługi Azure AD i wywołania interfejsu API programu Graph należy dodać go do dzierżawy i skonfigurować go do wymagają uprawnień (zakresy uprawnień uwierzytelniania OAuth 2.0) dla systemu Windows Azure Active Directory. Aby uzyskać informacje o dodawaniu i konfigurowaniu aplikacji, zobacz integracji aplikacji z usługą Azure Active Directory.

Usługi Azure AD korzysta z protokołu uwierzytelniania OAuth 2.0. Możesz dowiedzieć się więcej o OAuth 2.0 w usłudze Azure AD, w tym obsługiwanych przepływów i dostęp do tokenów w OAuth 2.0 w usłudze Azure AD.

Adresowanie punktu końcowego

Do wykonania operacji związanych z interfejsu API programu Graph, można wysyłania żądań HTTP za pomocą obsługiwanej metody — zwykle GET, POST, poprawka, PUT i usuwania — do punktu końcowego, który jest przeznaczony dla usługi, kolekcji zasobów, pojedynczego zasobu, właściwość nawigacji zasobu, lub Funkcja lub akcji udostępnianych przez usługę. Punkty końcowe są wyrażane jako adresów URL.

Poniżej opisano podstawowy format punkt końcowy interfejsu API programu Graph:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Adres URL składają się następujące składniki:

Uwaga: W niektórych przypadkach podczas odczytu kolekcji zasobów, można dodać parametry zapytania OData na żądanie do filtrowania, kolejność i strony zestawu wyników. Aby uzyskać więcej informacji, zobacz parametry zapytania OData w tym temacie.

Identyfikator dzierżawy {tenant_id}

Możesz określić dzierżawy docelowych żądania w jednej z czterech metod:

  • Identyfikator obiektu przez dzierżawcę. Identyfikator GUID, który został przypisany podczas tworzenia dzierżawcy. Znajdują się w objectId właściwość TenantDetail obiektu. Następujący adres URL pokazano, jak adres kolekcji zasobów użytkowników przy użyciu Identyfikatora obiektu dzierżawy:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Przez zweryfikować nazwy domeny (zarejestrowanym). Jedną z nazw domen, które są zarejestrowane dla dzierżawcy. Są one dostępne w verifiedDomains właściwość TenantDetail obiektu. Następujący adres URL pokazano, jak adres kolekcji zasobów użytkownicy dzierżawy, który ma domeny contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Za pomocą myOrganization alias. Ten alias jest dostępna tylko w przypadku korzystania z uwierzytelniania (bokami 3) typ kodu autoryzacji OAuth oznacza to gdy przy użyciu zakresu uprawnień delegowanych. Alias nie jest uwzględniana wielkość liter. Zastępuje obiekt domeny Identyfikatora lub dzierżawy w adresie URL. W przypadku alias interfejsu API programu Graph pochodną dzierżawcy oświadczenia w tokenie dołączony do żądania. Następujący adres URL pokazano, jak adres kolekcji zasobów użytkowników dzierżawcy, za pomocą tego aliasu:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Za pomocą me alias. Ten alias jest dostępna tylko w przypadku korzystania z uwierzytelniania (bokami 3) typ kodu autoryzacji OAuth oznacza to gdy przy użyciu zakresu uprawnień delegowanych. Alias nie jest uwzględniana wielkość liter. Zastępuje obiekt domeny Identyfikatora lub dzierżawy w adresie URL. W przypadku alias interfejsu API programu Graph pochodną użytkownika oświadczenia w tokenie dołączony do żądania. Następujący adres URL do rozwiązania zalogowanego użytkownika, korzystając z tego aliasu:
    https://graph.windows.net/me?api-version=1.6.

Uwaga: możesz użyć me alias wyłącznie do operacji docelowych dla zalogowanego użytkownika. Aby uzyskać więcej informacji, zobacz podpisany w operacji użytkownika.

Ścieżka zasobu {resource_path}

Należy określić {resource_path} inaczej w zależności od tego, czy ma być przeznaczona dla kolekcji zasobów, pojedynczego zasobu, właściwość nawigacji zasobu, funkcji lub akcji udostępniane w ramach dzierżawy lub funkcji lub akcji widoczne w zasobie.

Cel Ścieżka Objaśnienie
Metadane usługi /$metadata Zwraca dokument metadanych usługi. Następujące przykładowe elementy docelowe metadane usługi przy użyciu dzierżawy contoso.com:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Uwaga: niezbędne móc odczytać metadane usługi jest bez uwierzytelniania.
Kolekcja zasobów /{resource_collection} Dotyczy kolekcji zasobów, takich jak użytkownicy i grupy w dzierżawie. Można użyć tej ścieżki do odczytu zasobów w kolekcji i w zależności od typu zasobu, aby utworzyć nowy zasób w dzierżawie. W wielu przypadkach zestaw wyników zwrócony przez odczytu można dodatkowo oczyszczeniu przez dodanie parametrów zapytania do filtru, kolejności, lub strony wyników. Poniższy przykład dotyczy kolekcji użytkowników:
https://graph.windows.net/myorganization/users?api-version=1.6
Pojedynczy zasób /{resource_collection}/{resource_id} Dotyczy konkretnego zasobu w dzierżawie, takich jak użytkownika, skontaktuj się z organizacyjnej lub grupy. Dla większości zasobów resource_id jest identyfikatora obiektu. Zezwalaj na niektóre zasoby dodatkowe specyfikatory; na przykład użytkowników można również określić za główna nazwa użytkownika (UPN). W zależności od tego zasobu można użyć tej ścieżki uzyskanie zadeklarowane właściwości zasobów, aby zmodyfikować jego właściwości zadeklarowane lub usunąć zasób. Poniższy przykład jest przeznaczony dla użytkownika john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Właściwość nawigacji (obiekty) /{resource_collection}/{resource_id}/{property_name} Dotyczy określonego zasobu, takiego jak Menedżer użytkownika lub członkostwa w grupach lub członkowie grupy właściwości nawigacji. Ta ścieżka umożliwia zwracać obiekty, które odwołuje się właściwość nawigacji docelowej. Poniższy przykład dotyczy Menedżera john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Uwaga: Ten formularz adresowania jest dostępna tylko dla operacji odczytu.
Właściwość nawigacji (linki) /{resource_collection}/{resource_id}/$links/{property_name} Dotyczy określonego zasobu, takiego jak Menedżer użytkownika lub członkostwa w grupach lub członkowie grupy właściwości nawigacji. Ten formularz adresowania służy do odczytu i modyfikowania właściwości nawigacji. Podczas operacji odczytu obiekt odwołuje się właściwość są zwracane jako co najmniej jednego łącza w treści odpowiedzi. Na zapisy obiekty są określone jako co najmniej jednego łącza w treści żądania. Poniższy przykład dotyczy Menedżer właściwości john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funkcje lub akcje udostępniane w ramach dzierżawy /{function_name} Dotyczy funkcji lub akcji narażone dzierżawcy. Funkcje i działania zwykle są wywoływane z żądania POST i mogą obejmować treści żądania. Następujące przykładowe elementy docelowe isMemberOf funkcji:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funkcje lub akcje widoczne w zasobie. /{resource_collection}/{resource_id}/{function_name} Dotyczy funkcji lub akcji widoczne w zasobie. Funkcje i działania zwykle są wywoływane z żądania POST i mogą obejmować treści żądania. Następujące przykładowe elementy docelowe getMemberGroups funkcji:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Wersja interfejsu API Graph {wersja interfejsu api}

Możesz użyć api-version parametr pod kątem określonej wersji interfejsu API programu Graph dla operacji zapytania. Ten parametr jest wymagany.

Wartość api-version parametr może być jedną z następujących czynności:

  • "beta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

Na przykład następujący adres URL jest przeznaczony dla kolekcji użytkowników przy użyciu interfejsu API programu Graph w wersji 1.6:

https://graph.windows.net/myorganization/users?api-version=1.6

Aby uzyskać więcej informacji o wersji i zmiany funkcji między wersjami, zobacz Versioning.

Parametry zapytania OData

W wielu przypadkach podczas odczytu kolekcji zasobów, można filtrować, sortować i strony zestawu dołączając parametry zapytania OData do żądania wyników.

Interfejsu API programu Graph obsługuje następujące parametry zapytania Odata:

  • $filter
  • $batch
  • Rozwiń węzeł $
  • $orderby
  • $top
  • $skiptoken i poprzedniej strony

Zobacz obsługiwane zapytania, filtrów i opcji stronicowania uzyskać więcej informacji o obsługiwanych OData zapytania parametrów i ich ograniczenia interfejsu API programu Graph.

Nagłówki żądania i odpowiedzi

W poniższej tabeli przedstawiono typowe nagłówki HTTP używana w żądaniach z interfejsu API programu Graph. Nie oznacza pełne.

Nagłówek żądania Opis
Autoryzacja Wymagane. Token elementu nośnego wystawione przez usługi Azure Active Directory. Zobacz uwierzytelniania i autoryzacji w tym temacie, aby uzyskać więcej informacji.
Typ zawartości Wymagane, jeśli treść żądania jest obecny. Typ multimediów zawartości w treści żądania. Użyj application/json. Parametry mogą być dołączone do typu nośnika.
Uwaga: application/atom + xml i aplikacja/xml (dla łącza) są obsługiwane, ale nie są zalecane zarówno ze względu na wydajność i dlatego obsługa XML zostaną wycofane w przyszłej wersji.
Content-Length. Wymagane, jeśli treść żądania jest obecny. Długość żądania w bajtach.

W poniższej tabeli przedstawiono typowe nagłówki HTTP zwrócona w odpowiedzi przez interfejsu API programu Graph. Nie oznacza pełne.

Nagłówek odpowiedzi Opis
Typ zawartości Typ multimediów zawartości w treści odpowiedzi. Wartość domyślna to application/json. Żądania dla miniatury zdjęcia użytkownika zwracają image/jpeg domyślnie.
Lokalizacja Zwracany w odpowiedzi na żądania POST służące do tworzenia nowego zasobu (obiekt) w katalogu. Zawiera identyfikator URI nowo utworzonego zasobu.
ocp-aad-diagnostics-server-name Identyfikator serwera, który wykonać żądanej operacji.
OCP-aad klucza sesji Klucz, który identyfikuje bieżącej sesji przy użyciu funkcji usługi katalogowej.

Co najmniej firma Microsoft zaleca, wykonaj następujące czynności dla każdego żądania:

  1. Zaloguj się sygnaturę czasową dokładne przesłanie żądania.
  2. Wysyłanie i dziennika client-request-id.
  3. Kod odpowiedzi HTTP logowania i request-id.

Udostępnia informacje w tych dziennikach pomoże rozwiązywania problemów, gdy poprosić o pomoc lub pomocy technicznej firmy Microsoft.

Treść żądania i odpowiedzi

Treść żądania dla żądania POST, poprawki i PUT mogą być wysyłane w formacie JSON lub XML. Odpowiedzi serwera może być zwracany w formacie JSON lub XML. Można określić ładunku w treści żądania przy użyciu Content-Type nagłówek żądania i odpowiedzi przy użyciu Accept nagłówek żądania.

Zdecydowanie zaleca się używanie ładunek JSON w żądań i odpowiedzi z interfejsu API programu Graph. Jest to zarówno ze względu na wydajność i dlatego XML zostaną wycofane w przyszłej wersji.

Funkcje zaawansowane

Poprzednich sekcjach omówiono formatowania podstawowe żądań i odpowiedzi z interfejsu API programu Graph. Bardziej zaawansowane funkcje mogą dodawać parametrów ciągu zapytania dodatkowe lub mają różne żądania i treści odpowiedzi niż podstawowe operacje omówionych wcześniej w tym temacie.

Te funkcje obejmują:

  • Przetwarzanie wsadowe: interfejs API programu Graph obsługuje przetwarzanie wsadowe. Wysyłania żądań w partiach zmniejsza liczbę rund do serwera, co zmniejsza obciążenie sieci i pomaga w operacji ukończone szybciej. Aby uzyskać więcej informacji na temat przetwarzania wsadowego z interfejsu API programu Graph, zobacz przetwarzanie wsadowe.
  • Zapytanie różnicowej: interfejs API programu Graph obsługuje wykonywanie kwerend różnicowej. Różnicowa zapytania można zwrócić zmiany do konkretnych obiektów w dzierżawie między żądaniami wydane w różnym czasie. Ta funkcja jest często używana do synchronizacji z lokalnego magazynu ze zmianami w ramach dzierżawy. Aby uzyskać więcej informacji na temat różnicowej zapytanie z interfejsu API programu Graph, zobacz różnicowej zapytania.

Dodatkowe zasoby