Wykonywanie zapytań względem programu Microsoft Graph przy użyciu interfejsu REST

  • 3 min

Microsoft Graph to internetowy interfejs API RESTful, który umożliwia dostęp do zasobów usługi Microsoft Cloud. Po zarejestrowaniu aplikacji i pobraniu tokenów uwierzytelniania dla użytkownika lub usługi możesz wysyłać żądania do interfejsu API programu Microsoft Graph.

Interfejs API programu Microsoft Graph definiuje większość swoich zasobów, metod i wyliczenia w przestrzeni microsoft.graphnazw OData w metadanych programu Microsoft Graph. Kilka zestawów interfejsu API jest zdefiniowanych w swoich przestrzeniach nazw podrzędnych, takich jak interfejs API rekordów wywołań, który definiuje zasoby, takie jak callRecord w elem.microsoft.graph.callRecords

Jeśli nie określono jawnie w odpowiednim temacie, przyjmij typy, metody i wyliczenia są częścią microsoft.graph przestrzeni nazw.

Wywoływanie metody interfejsu API REST

Aby odczytać lub zapisać w zasobie, takim jak użytkownik lub wiadomość e-mail, skonstruuj żądanie, które wygląda podobnie do następującego przykładu:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Składniki żądania obejmują:

  • {HTTP method} - Metoda HTTP używana w żądaniu do programu Microsoft Graph.
  • {version} — Wersja interfejsu API programu Microsoft Graph używana przez aplikację.
  • {resource} — Zasób w programie Microsoft Graph, do którego się odwołujesz.
  • {query-parameters} - Opcjonalne opcje zapytania OData lub parametry metody REST, które dostosują odpowiedź.

Po wykonaniu żądania zostanie zwrócona odpowiedź zawierająca następujące elementy:

  • Kod stanu — kod stanu HTTP wskazujący powodzenie lub niepowodzenie.
  • Komunikat odpowiedzi — żądane dane lub wynik operacji. Komunikat odpowiedzi może być pusty dla niektórych operacji.
  • nextLink — Jeśli żądanie zwraca wiele danych, musisz stronicować je przy użyciu adresu URL zwróconego w @odata.nextLinkpliku .

Metody HTTP

Program Microsoft Graph używa metody HTTP w żądaniu, aby określić, co robi twoje żądanie. Interfejs API obsługuje następujące metody.

Metoda opis
GET Odczytywanie danych z zasobu.
POST Utwórz nowy zasób lub wykonaj akcję.
PATCH Zaktualizuj zasób przy użyciu nowych wartości.
ODŁÓŻ Zastąp zasób nowym.
DELETE Usuń zasób.
  • W przypadku metod GET CRUD i DELETE, nie jest wymagana żadna treść żądania.
  • Metody POST, PATCHi PUT wymagają treści żądania określonej w formacie JSON, która zawiera dodatkowe informacje. Takie jak wartości właściwości zasobu.

Wersja

Program Microsoft Graph obecnie obsługuje dwie wersje: v1.0 i beta.

  • v1.0 zawiera ogólnie dostępne interfejsy API. Użyj wersji 1.0 dla wszystkich aplikacji produkcyjnych.
  • beta zawiera interfejsy API, które są obecnie dostępne w wersji zapoznawczej. Ze względu na to, że możemy wprowadzić zmiany powodujące niezgodność w naszych interfejsach API w wersji beta, zalecamy używanie wersji beta tylko do testowania aplikacji, które są opracowywane; Nie używaj interfejsów API w wersji beta w aplikacjach produkcyjnych.

Zasób

Zasób może być jednostką lub typem złożonym, często zdefiniowanym za pomocą właściwości. Jednostki różnią się od typów złożonych, zawsze uwzględniając właściwość id .

Adres URL zawiera zasób, z którym korzystasz w żądaniu, taki jak me, użytkownik, grupa, dysk i witryna. Często zasoby najwyższego poziomu obejmują również relacje, których można użyć do uzyskiwania dostępu do innych zasobów, takich jak me/messages lub me/drive. Możesz również wchodzić w interakcje z zasobami przy użyciu metod, na przykład w celu wysłania wiadomości e-mail, użyj polecenia me/sendMail.

Każdy zasób może wymagać różnych uprawnień dostępu do niego. Aby utworzyć lub zaktualizować zasób, często potrzebny jest wyższy poziom uprawnień, niż go odczytać. Aby uzyskać szczegółowe informacje o wymaganych uprawnieniach, zobacz temat referencyjny metody.

Parametry zapytań

Parametry zapytania mogą być opcjami zapytania systemowego OData lub innymi ciągami akceptowanymi przez metodę w celu dostosowania odpowiedzi.

Możesz użyć opcjonalnych opcji zapytania systemu OData, aby uwzględnić więcej lub mniej właściwości niż domyślna odpowiedź. Odpowiedź można filtrować pod kątem elementów pasujących do zapytania niestandardowego lub podać inne parametry dla metody.

Na przykład dodanie następującego filter parametru ogranicza komunikaty zwracane z właściwością emailAddress jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Inne zasoby

Poniżej znajdują się linki do niektórych narzędzi, których można użyć do kompilowania i testowania żądań przy użyciu interfejsów API programu Microsoft Graph.