Współpraca przez Microsoft Graph

Współpraca przez Microsoft Graph pozwala aplikacjom integrować się z danymi i usługami tej platformy.

Microsoft Graph jako interfejs dostępu do usług Microsoft 365

Microsoft Graph jest interfejsem programistycznym opartym na protokole HTTP, który pozwala aplikacjom korzystać z zasobów dostępnych w usługach Microsoft 365 i Microsoft Entra. Zamiast integrować osobno każdą usługę, program może wysyłać żądania do wspólnego punktu dostępu, najczęściej pod adresem https://graph.microsoft.com/v1.0. Graph udostępnia między innymi informacje o użytkownikach i grupach, pocztę Exchange Online, kalendarze, pliki przechowywane w OneDrive i SharePoint, zespoły oraz kanały Microsoft Teams, urządzenia i dane organizacyjne.

Odpowiedzi API są zazwyczaj zwracane w formacie JSON. Poszczególne zasoby mają adresowane ścieżki, takie jak /users, /groups, /me/messages, /me/events czy /me/drive/root/children. Żądanie może pobierać dane, tworzyć nowe obiekty, modyfikować istniejące albo je usuwać, zależnie od użytej metody HTTP i przyznanych uprawnień. Wersja v1.0 jest przeznaczona do stabilnych zastosowań produkcyjnych, natomiast beta służy do testowania funkcji, które mogą ulec zmianie.

Logowanie aplikacji i model uprawnień

Aplikacja korzystająca z Microsoft Graph musi zostać zarejestrowana w Microsoft Entra ID. Rejestracja określa identyfikator aplikacji, obsługiwane typy logowania, adresy przekierowania oraz wymagane uprawnienia. Dostęp jest realizowany przez Microsoft Identity Platform i protokół OAuth 2.0. Po prawidłowym uwierzytelnieniu aplikacja otrzymuje token dostępu, który przekazuje w nagłówku HTTP Authorization w postaci Bearer. Sam identyfikator aplikacji nie daje dostępu do danych.

Microsoft Graph rozróżnia uprawnienia delegowane i aplikacyjne. Uprawnienia delegowane działają w imieniu zalogowanego użytkownika, dlatego zakres danych zależy także od jego uprawnień. Uprawnienia aplikacyjne pozwalają aplikacji działać bez aktywnej sesji użytkownika, na przykład jako zadanie wykonywane automatycznie, ale zwykle wymagają zgody administratora dzierżawy. Przykładowe zakresy to User.Read, Mail.Read, Calendars.Read i Files.Read. Zakres powinien być możliwie wąski, ponieważ przyznanie Mail.ReadWrite lub uprawnień aplikacyjnych do wszystkich skrzynek oznacza znacznie szerszy dostęp niż samo odczytywanie profilu użytkownika.

W aplikacjach internetowych często stosuje się przepływ authorization code, a w zadaniach wykonywanych bez udziału użytkownika przepływ client credentials. Tokeny mają ograniczony czas ważności, dlatego program musi obsługiwać ich odświeżanie lub ponowne uzyskiwanie. Nie należy umieszczać sekretu klienta w kodzie aplikacji działającej na komputerze użytkownika. Błędny adres przekierowania, brak zgody administratora, niezgodny zakres lub użycie tokenu przeznaczonego dla innego zasobu powodują odpowiedzi HTTP z błędami uwierzytelniania albo autoryzacji.

Odczytywanie danych, stronicowanie i powiadomienia

Wynik zapytania do kolekcji może być podzielony na strony. W takim przypadku odpowiedź zawiera właściwość value oraz, gdy dostępne są kolejne elementy, pole @odata.nextLink. Aplikacja powinna korzystać z adresu podanego w nextLink, zamiast samodzielnie konstruować kolejny zakres danych. Parametry OData, między innymi $select, $filter, $orderby i $top, pozwalają ograniczyć liczbę zwracanych pól lub elementów. Nie każda kombinacja tych parametrów jest obsługiwana przez każdy zasób, dlatego zapytania trzeba sprawdzać w dokumentacji konkretnego punktu końcowego.

Do śledzenia zmian Graph udostępnia mechanizm delta query. Pierwsze zapytanie zwraca bieżący zestaw danych oraz odsyłacz @odata.deltaLink. Późniejsze wywołanie tego odsyłacza pozwala pobrać zmiany od poprzedniego odczytu, w tym informacje o usuniętych obiektach. Jest to inne działanie niż okresowe pobieranie całej kolekcji i może ograniczyć liczbę żądań. Do powiadomień o zmianach służą subskrypcje change notifications. Aplikacja przekazuje w nich między innymi typ zasobu, adres HTTPS do odbioru powiadomień oraz czas wygaśnięcia subskrypcji. Subskrypcje trzeba odnawiać, a odebrane powiadomienia należy weryfikować i obsługiwać idempotentnie, ponieważ samo powiadomienie nie zawsze zawiera pełny obiekt zmienionych danych.

Microsoft Graph stosuje ograniczenia liczby żądań. Przy przekroczeniu limitu usługa może zwrócić kod 429 Too Many Requests oraz nagłówek Retry-After. Klient powinien wtedy odczekać wskazany czas i ponowić żądanie, najlepiej z kontrolowanym opóźnieniem. Program powinien również rozróżniać błędy chwilowe, błędne dane wejściowe, brak uprawnień i brak zasobu. Automatyczne ponawianie każdego błędu może zwiększyć obciążenie usługi i utrudnić ustalenie rzeczywistej przyczyny problemu.

Znaczenie poprawnej konfiguracji na komputerze użytkownika

Integracja z Microsoft Graph może być używana przez aplikację uruchamianą w przeglądarce, program biurowy albo narzędzie zainstalowane lokalnie. Na działanie takiego programu wpływają między innymi poprawna data i godzina systemowa, dostęp do sieci, rozwiązywanie nazw DNS, konfiguracja serwera proxy oraz możliwość nawiązania połączenia TLS z usługą Microsoft. Nieprawidłowy zegar może powodować odrzucenie tokenu, a filtr sieciowy może blokować połączenie z domeną Graph mimo poprawnych danych logowania.

Diagnostyka powinna obejmować kod odpowiedzi HTTP, identyfikator żądania, adres użytego punktu końcowego i zakresy uprawnień, bez ujawniania tokenów dostępu ani sekretów aplikacji. Błąd 401 Unauthorized zwykle wskazuje na brak, wygaśnięcie lub nieprawidłowy token, natomiast 403 Forbidden oznacza zazwyczaj brak wymaganego uprawnienia albo zgody. Kod 404 Not Found może wynikać z nieistniejącego identyfikatora obiektu, niewłaściwego adresu lub braku widoczności zasobu dla danego kontekstu. Przy problemach z działaniem programu warto także sprawdzić, czy używana ścieżka należy do wersji v1.0, czy tylko do wersji beta.

Naprawa komputera wykorzystywanego do takiej pracy może obejmować sprawdzenie połączenia sieciowego, aktualizację systemu i przeglądarki, usunięcie uszkodzonej pamięci podręcznej aplikacji oraz weryfikację konfiguracji klienta. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, w tym diagnostyką problemów sprzętowych, które mogą uniemożliwiać prawidłowe korzystanie z aplikacji internetowych.