Microsoft Graph API — automatyzacja zadań w Microsoft 365

Zakładanie kont, przypisywanie licencji, porządkowanie skrzynek, raporty wykorzystania — większość powtarzalnej pracy administratora Microsoft 365 da się wykonać automatycznie przez Microsoft Graph API. Poniżej praktyczne wprowadzenie: jak się połączyć, od czego zacząć i na czym najłatwiej się potknąć.

Czym właściwie jest Graph

Microsoft Graph to jeden wspólny interfejs do danych z całego Microsoft 365. Zamiast osobnych narzędzi do Exchange, SharePoint, Teams i tożsamości, odpytujesz jeden adres i dostajesz JSON. Wszystko sprowadza się do wywołań w rodzaju:

GET  https://graph.microsoft.com/v1.0/users
GET  https://graph.microsoft.com/v1.0/users/jan.kowalski@firma.pl
POST https://graph.microsoft.com/v1.0/groups/{id}/members/$ref

Istnieją dwie wersje: v1.0 — stabilna, do zastosowań produkcyjnych, oraz beta — bogatsza, ale Microsoft może ją zmienić bez uprzedzenia. W skryptach, od których zależy praca firmy, trzymaj się v1.0.

Jak się uwierzytelnić

To miejsce, w którym najczęściej rodzi się zamieszanie. Są dwa modele:

Model	Kiedy stosować
Delegowany (w imieniu użytkownika)	Skrypt działa z uprawnieniami zalogowanej osoby. Do narzędzi uruchamianych ręcznie przez administratora.
Aplikacyjny (bez użytkownika)	Zadania w tle, harmonogramy, integracje serwerowe. Aplikacja ma własne uprawnienia, niezależne od kogokolwiek.

Do automatyzacji niemal zawsze chcesz modelu aplikacyjnego. Rejestrujesz aplikację w Microsoft Entra ID, nadajesz jej uprawnienia typu Application, zatwierdzasz je jako administrator i uwierzytelniasz się identyfikatorem dzierżawy, identyfikatorem aplikacji oraz sekretem lub certyfikatem.

Używaj certyfikatu zamiast sekretu. Sekret ma datę ważności i wygasa zwykle w najmniej dogodnym momencie — najczęściej w nocy, gdy przestaje działać synchronizacja, o której wszyscy zapomnieli. Certyfikat też wygasa, ale łatwiej objąć go kontrolą i rotacją. Niezależnie od wyboru: wpisz datę ważności do kalendarza w dniu, w którym tworzysz poświadczenie.

Zasada najmniejszych uprawnień

Przy nadawaniu uprawnień pokusa jest oczywista: zaznaczyć Directory.ReadWrite.All i mieć spokój. To zły pomysł — taka aplikacja może praktycznie wszystko w Twojej dzierżawie, a jej sekret leży w pliku konfiguracyjnym na serwerze.

• Potrzebujesz czytać listę użytkowników? User.Read.All, nie User.ReadWrite.All.
• Potrzebujesz jednej skrzynki? Ogranicz zakres dostępu do konkretnych skrzynek, zamiast dawać dostęp do wszystkich.
• Osobna rejestracja aplikacji dla każdej integracji — wtedy wyłączenie jednej nie kładzie pozostałych.

Od czego zacząć w praktyce

1. Raport wykorzystania licencji

Najprostszy start i od razu wymierna korzyść. Pobierasz listę użytkowników wraz z przypisanymi licencjami i datą ostatniego logowania. Wynik regularnie ujawnia licencje przypisane osobom, które nie zalogowały się od miesięcy — więcej o optymalizacji planów przy porównaniu planów Microsoft 365.

2. Onboarding pracownika

Jedno wywołanie tworzy konto, kolejne przypisuje licencję, następne dodaje do grup i zespołów. Zamiast dziesięciu kliknięć w kilku panelach — jeden skrypt z listą parametrów, wykonujący za każdym razem dokładnie to samo.

3. Offboarding

Zablokowanie logowania, unieważnienie sesji, konwersja skrzynki na współdzieloną, przekazanie plików z OneDrive, zwolnienie licencji. Procedurę opisaliśmy krok po kroku przy offboardingu w Microsoft 365 — Graph pozwala wykonać ją bezbłędnie i w tej samej kolejności za każdym razem.

4. Porządek w danych

Wyszukiwanie plików udostępnionych „wszystkim w organizacji”, list gości bez aktywności, zespołów Teams bez właściciela. To rzeczy, których nie widać w codziennej pracy, a które wychodzą boleśnie przy wdrożeniu Copilota — piszemy o tym w tekście o uprawnieniach przed wdrożeniem Copilota.

Pułapki, na które warto uważać

• Stronicowanie. Graph zwraca wyniki partiami. Jeżeli zignorujesz pole @odata.nextLink, dostaniesz pierwszych 100 rekordów i uznasz, że to wszystko. Klasyczne źródło raportów, które „się nie zgadzają”.
• Limity zapytań. Przy większej liczbie wywołań Graph zwróci kod 429 wraz z nagłówkiem Retry-After. Trzeba go uszanować i ponowić po wskazanym czasie, a nie odpytywać w pętli.
• Opóźnienie propagacji. Konto utworzone przed sekundą bywa jeszcze niewidoczne dla kolejnego wywołania. W skryptach onboardingowych planuj ponowienia.
• Uprawnienia delegowane a aplikacyjne. Ten sam endpoint zachowuje się inaczej w obu modelach. Większość błędów 403 bierze się z pomylenia typu uprawnienia, nie z jego braku.
• Filtrowanie po stronie serwera. Część zapytań wymaga nagłówka ConsistencyLevel: eventual wraz z parametrem $count. Bez tego filtr po prostu nie zadziała.

PowerShell czy własny kod

Moduły Microsoft Graph PowerShell wystarczą do zadań administracyjnych i raportów — są szybkie w napisaniu i czytelne dla kolejnej osoby. Gdy automatyzacja ma działać w tle, obsługiwać błędy, ponawiać i raportować, lepiej sprawdza się osobna usługa. My budujemy takie rozwiązania w Node.js z TypeScript — na tym stosie działa nasz portal B2B, korzystający z uwierzytelniania Entra ID.

Zanim wypuścisz to na produkcję

1. Przetestuj na osobnej dzierżawie testowej albo na koncie, którego skasowanie nikogo nie zaboli.
2. Operacje zapisujące uruchom najpierw w trybie „tylko podgląd”, wypisując, co skrypt zamierza zrobić.
3. Zapisuj logi — co, kiedy i z jakim skutkiem. Bez tego diagnoza po tygodniu jest niemożliwa.
4. Ustaw powiadomienie o niepowodzeniu. Cicho zepsuta automatyzacja jest gorsza od jej braku.
5. Wpisz do kalendarza datę wygaśnięcia poświadczeń.