Opanowanie uwierzytelniania aplikacji (app-only) dla interfejsów API Microsoft Viva

By Mirko Peters · 2026-08-28

Automatically translated with AI from the original post. Read the English original

Titelbild: Mastering App-Only Authentication for Microsoft Viva APIs

Jeśli kiedykolwiek traciłeś godziny na walkę z uporczywymi błędami „Unauthorized” lub „Forbidden” podczas budowania zautomatyzowanych skryptów utrzymaniowych dla Microsoft Viva, nie jesteś w tym sam. Zbyt wiele nowoczesnych wdrożeń Microsoft 365 utyka na etapie „włącz i miej nadzieję, że użytkownicy sami sobie poradzą”. Aby osiągnąć prawdziwą skalowalność operacyjną, właściciele platform i administratorzy muszą odejść od interfejsu administracyjnego i zanurzyć się w interfejsy API. Automatyzacja bez udziału użytkownika wymaga jednak solidnego podejścia do uwierzytelniania opartego wyłącznie na aplikacji, precyzyjnej obsługi żądań oraz dobrze zaprojektowanej struktury ładunku danych. Ten przewodnik pokaże, jak skonfigurować bezpieczne jednostki usługi z poświadczeniami w postaci certyfikatów przechowywanych w usłudze Azure Key Vault, jak żądać dokładnie tych zakresów specyficznych dla zasobów, które są potrzebne w Twoim środowisku, oraz jak obsługiwać oświadczenia tokenów jak doświadczony deweloper.

Aby zgłębić te strategie architektoniczne i posłuchać historii wdrożeń z życia wziętych, koniecznie posłuchaj naszego towarzyszącego odcinka podcastu: Automate Viva Connections, Topics, Learning, and News. A teraz przejdźmy przez dokładny plan działania, potrzebny do pokonania przeszkód w automatyzacji Viva.

Przełamywanie bariery uwierzytelniania

Najczęstszym punktem tarcia podczas budowania skryptów automatyzacji jest odpowiedź „Unauthorized”, mimo że masz pewność, iż postępowałeś zgodnie z oficjalną dokumentacją. Rzeczywistość jest taka, że ekosystem Microsoft Viva obejmuje kombinację punktów końcowych Microsoft Graph i punktów końcowych specyficznych dla produktów, a ich zakresy uprawnień mogą się znacząco różnić.

Aby zbudować minimalną, bezpieczną i w pełni opartą wyłącznie na aplikacji konfigurację, powinieneś przestrzegać ścisłych zasad tożsamości:

Zarejestruj dedykowaną aplikację w Entra ID, która będzie pełnić rolę jednostki usługi.
Zawsze preferuj poświadczenia w postaci certyfikatów przechowywane w usłudze Azure Key Vault zamiast statycznych, podatnych na ataki kluczy tajnych klienta.
Przyznawaj wyłącznie wymagane uprawnienia aplikacji. Na przykład Viva Topics zazwyczaj wymaga uprawnienia Topics.ReadWrite.All; Viva Learning wymaga uprawnień LearningContent.ReadWrite.All oraz LearningProvider.ReadWrite.All; a Connections lub wiadomości w SharePoint w dużym stopniu opierają się na uprawnieniu Sites.ReadWrite.All wraz z uprawnieniami do docelowych witryn.
Upewnij się, że wyraźnie udzielono zgody administratora na żądane zakresy.
Uwzględnij zasady dostępu warunkowego, wykluczając jednostkę usługi lub tworząc dedykowane zasady, które bezpiecznie zezwalają na nieinteraktywne jednostki usługi pochodzące z zaufanych sieci automatyzacji.
Podczas żądania tokenów żądaj zakresu /.default dokładnie dla zasobu, który zamierzasz wywołać. Nigdy nie używaj ponownie ogólnego tokenu Graph wobec natywnego dla produktu punktu końcowego zasobu.

Jeśli napotkasz przeszkodę, przejdź przez krótką listę kontrolną diagnostyki uwierzytelniania. Sprawdź, czy oświadczenie audience w tokenie odpowiada zamierzonemu punktowi końcowemu, upewnij się, że używasz uprawnień aplikacji zamiast delegowanych, potwierdź, że zgoda rzeczywiście została zastosowana, sprawdź, czy certyfikat jest ważny i objęty alertem o rotacji, oraz zapisuj oświadczenia tokenów przy każdym wykonaniu.

Wiedza niestandardowa: automatyzacja Viva Topics

Częstym scenariuszem awarii podczas pracy z Viva Topics jest otrzymanie pomyślnej odpowiedzi 201 Created z interfejsu API, mimo że temat nigdy nie pojawia się w interfejsie użytkownika. Prawie zawsze wynika to z brakujących wymaganych pól, nieprawidłowego stanu publikacji pozostawionego w trybie wersji roboczej lub metadanych, które są po prostu zbyt ubogie.

Ładunek musi zawierać kluczowe elementy, takie jak jasny tytuł, szczegółowe podsumowanie lub opis, nazwy alternatywne lub akronimy, wiarygodne odwołania wskazujące na pliki, strony lub osoby, wyznaczony stan „published” (opublikowany) oraz przypisanych właścicieli lub ekspertów, którzy nadadzą tematowi wiarygodność organizacyjną.

Aby skalować to rozwiązanie w sposób wydajny, przyjrzyj się zewnętrznym źródłom prawdy, takim jak firmowa wiki, listy SharePoint czy rejestry projektów, i przekształć te dane w uporządkowany JSON. Wdróż strategię grupowania żądań z kontrolowanym poziomem równoległości, zawsze respektując odpowiedzi HTTP 429 (limit żądań) poprzez uwzględnianie nagłówka Retry-After. Zapewnij idempotentność, wykonując upsert rekordów na podstawie zewnętrznego klucza, aby zapobiec duplikatom, i zawsze wykonuj końcowe zapytanie weryfikacyjne, które potwierdzi, że temat rzeczywiście przeszedł przez proces publikacji.

Najlepsze praktyki operacyjne w zarządzaniu wiedzą

Podczas uruchamiania zautomatyzowanych zadań publikacji niezwykle ważne jest solidne logowanie. Zawsze rejestruj przychodzące żądania wraz z odpowiadającymi im identyfikatorami korelacji odpowiedzi. Traktuj każdy kod stanu 4xx jako problem z walidacją danych lub uprawnień, natomiast błędy 5xx oraz limity żądań 429 kieruj do dedykowanej kolejki ponowień z wykładniczym opóźnieniem (exponential backoff).

Od silosów LMS do Viva Learning

Organizacje często mają problem z treściami szkoleniowymi rozproszonymi w różnych systemach. Głównym celem automatyzacji Viva Learning jest zbiorcza publikacja zewnętrznych kursów, dzięki czemu pracownicy mogą wyszukiwać wszystko w jednym miejscu: bezpośrednio w Viva.

Aby zapewnić bezproblemową integrację, ładunek learningContent musi zawierać stabilny identyfikator externalId, czytelny tytuł, opisowe streszczenie, działający adres webUrl, prawidłowy adres thumbnailUrl, czas trwania zapisany w formacie ISO 8601, istotne umiejętności lub tagi oraz poprawny język regionalny (locale). Mapowanie eksportów CSV z dotychczasowego systemu LMS (Learning Management System) na ściśle zwalidowany JSON jest absolutnie konieczne.

Twój potok grupowania, niezależnie od tego, czy zostanie napisany w PowerShell, czy wdrożony jako Azure Function, powinien importować dane źródłowe, weryfikować wymagane kolumny, budować ładunki JSON z wbudowanymi zabezpieczeniami przed pustymi wartościami, wykonywać żądania POST z odpowiednimi tokenami oraz wprowadzać wyliczane interwały oczekiwania i kroki wykładniczego opóźnienia. Zawsze zapisuj niepomyślne kody stanu HTTP wraz z numerami wierszy i przyczynami, aby zbudować zautomatyzowaną listę ponowień do naprawy.

Automatyzacja aktualności Viva Connections

Ręczne wpisy komunikacyjne często przegapiają kluczowe okna publikacji, nie docierają do właściwych grup odbiorców lub zawodzą z powodu nieprawidłowych ładunków JSON. Przejście na programowe generowanie kart pozwala dostarczać ukierunkowane aktualności z absolutną niezawodnością.

Wiarygodny wpis z aktualnościami wymaga powiązanego tytułu i streszczenia, jawnie zdefiniowanego autora, odbiorców przekazanych jako tablica identyfikatorów grup Microsoft Entra ID, zweryfikowanego adresu URL obrazu, linków głębokich, które otwierają się bezpośrednio w aplikacji Teams, oraz skonfigurowanych priorytetów i dat wygaśnięcia. Upewnij się, że wszystkie nazwy właściwości mają poprawny zapis camelCase i są walidowane przed wysłaniem.

Dostarczaj te zasoby na dużą skalę, planując publikacje zgodnie z lokalnymi strefami czasowymi regionów i grupując partie według docelowych odbiorców. Analizuj treść odpowiedzi o błędach, gdy wystąpią wyjątki 400 bad request, aby szybko je naprawić i ponownie wysłać. Prowadź szczegółową telemetrię obejmującą identyfikatory wpisów, liczebność odbiorców i statusy dostarczenia.

Wzorce gotowe do środowiska produkcyjnego

Budowa odpornej automatyzacji wymaga stosowania wzorców inżynierskich klasy enterprise. Nigdy nie polegaj na ręcznym uruchamianiu skryptów na lokalnym komputerze. Zamiast tego twórz, testuj i wdrażaj potoki automatyzacji przy użyciu GitHub Actions lub Azure DevOps. Wszystkie sekrety operacyjne przechowuj bezpiecznie w odwołaniach do Azure Key Vault, zamiast wpisywać je na sztywno w skryptach.

Obserwowalność ma kluczowe znaczenie. Zintegruj zadania automatyzacji z Application Insights lub Log Analytics, aby śledzić udane wykonania, skoki opóźnień i zdarzenia ograniczania przepustowości (throttling). Wdrażaj algorytmy wykładniczego opóźnienia z losowym jitterem, konsekwentnie respektuj nagłówki Retry-After i stosuj klucze idempotentności, aby ponowienie nieudanego zadania nigdy nie powodowało tworzenia zduplikowanej treści.

Pułapki i szybkie rozwiązania

Nawet doświadczeni inżynierowie potrafią natknąć się na subtelne wymagania API. Oto, jak szybko rozwiązać najczęstsze pułapki automatyzacji:

Otrzymywanie błędów 401 lub 403 mimo poprawnego kodu zwykle oznacza, że odbiorca tokenu (audience) nie odpowiada docelowemu zasobowi API. Zawsze żądaj świeżego tokenu przygotowanego dla konkretnego punktu końcowego, który wywołujesz.
Jeśli temat został poprawnie utworzony, ale nie pojawia się w interfejsie użytkownika, sprawdź właściwość state, aby upewnić się, że jest oznaczona jako opublikowana, a nie pozostaje w stanie szkicu, oraz upewnij się, że metadane nie są zbyt ubogie.
Treści szkoleniowe, które się przesyłają, a potem tajemniczo znikają, zwykle mają niezgodność typów danych albo brakujące wymagane pola w ładunku schematu.
Wpisy aktualności w usłudze Connections, które nie pojawiają się w serwisie, często mają właściwość audience sformatowaną niepoprawnie jako ciąg znaków zamiast tablicy albo zawierają nieprawidłowe linki do obrazów i zbyt długie streszczenia.
Losowe błędy występujące przy masowym uruchamianiu zadań są wyraźnym sygnałem, że przekraczasz limity żądań. Zmniejsz rozmiar wsadów i wprowadź właściwe procedury ponawiania z rosnącym opóźnieniem (backoff).

Wskaźniki KPI potwierdzające skuteczność

Aby uzasadnić nakład pracy inżynierskiej włożony w automatyzację platformy Microsoft Viva, musisz śledzić jasno określone wskaźniki KPI. Mierz czas od momentu wygenerowania pliku CSV do publikacji treści na żywo. Monitoruj odsetek udanych wywołań na sto wywołań API w każdej z poszczególnych funkcji, obserwuj wskaźniki błędów ograniczania przepustowości 429 i 5xx przed i po wdrożeniu procedur backoff, oceniaj pokrycie tematów, obliczając procent projektów firmowych i skrótów, dla których istnieją aktywne tematy na żywo, porównuj kompletność katalogu szkoleń z danymi głównymi w systemie LMS oraz mierz wskaźniki dostarczania Viva Connections, w tym procent publikacji na czas i łączny zasięg odbiorców.

Szybki start (w tym tygodniu)

Jeśli jesteś gotowy podjąć działania w tym tygodniu, postępuj zgodnie z tym prostym planem wdrożenia:

Utwórz dedykowaną jednostkę usługi (service principal) opartą na certyfikacie, przydziel absolutnie minimalne wymagane uprawnienia aplikacji i zapewnij wyraźną zgodę administratora.
Uruchom lekką funkcję Azure Functions lub lokalny skrypt automatyzacji w PowerShell, skonfigurowany tak, aby bezpiecznie pobierał sekrety z Azure Key Vault.
Zautomatyzuj jeden przepływ pracy od początku do końca – na przykład publikację partii dwudziestu pięciu tematów Viva Topics wraz z obsługą błędów, ponawianiem prób i kontrolami po weryfikacji.
Zintegruj logowanie i zbuduj podstawowy pulpit monitorowania w Application Insights.
Udokumentuj runbook operacyjny, określ kontakty do wsparcia i zaplanuj uruchamianie zautomatyzowanych zadań bez nadzoru.

Odchodząc od ręcznego wprowadzania danych na rzecz solidnej automatyzacji API opartej na bezpiecznym uwierzytelnianiu aplikacji, możesz przekształcić swoje środowisko Microsoft Viva w żywą, dynamiczną platformę korporacyjną. Więcej szczegółowych omówień, wskazówek eksperckich i analiz architektury znajdziesz w pełnym odcinku podcastu Automate Viva Connections, Topics, Learning, and News!