Microsoft Power BI — jak używać: integracje i raporty

Power BI REST API pozwala zarządzać zawartością usługi Power BI: zestawami danych, raportami, pulpitami nawigacyjnymi i obszarami roboczymi.^1,2 W tym artykule znajdziesz zasady uwierzytelniania, wysyłania żądań, odświeżania danych i automatyzacji raportowania. W pojemności współdzielonej można zainicjować najwyżej 8 odświeżeń zestawu danych dziennie; do limitu wliczają się odświeżenia zaplanowane³.

Czym jest Power BI API i jakie interfejsy obejmuje?

Power BI API to wspólna nazwa interfejsów programistycznych Power BI. REST API obsługuje operacje wykonywane przez żądania HTTP, a JavaScript API służy do pracy z treścią osadzoną w aplikacji. Interfejsy REST udostępniają punkty końcowe do osadzania treści, administrowania, ładu i obsługi zasobów użytkowników¹. Bazowy adres punktów końcowych Power BI REST API zawiera wersję 1.0: https://api.powerbi.com/v1.0/myorg⁴.

Według zestawienia Coupler.io Power BI REST API obejmuje 17 grup operacji². Taki podział ułatwia znalezienie punktu końcowego dla konkretnego zadania.

Jak rozpoznać przyczynę błędu zwróconego przez API?

Diagnozę błędu Power BI API zacznij od porównania odpowiedzi serwera z wysłanym żądaniem. Osobno sprawdź uwierzytelnienie, uprawnienia, adres zasobu i parametry operacji. HTTP 401 wskazuje na problem wymagający sprawdzenia uwierzytelnienia lub konfiguracji dostępu, a 403 może oznaczać brak uprawnień⁵.

• Status HTTP wskazuje kategorię błędu. Czytaj go razem z treścią odpowiedzi, nie tylko z komunikatem aplikacji.
• Żądanie API obejmuje metodę, adres, nagłówki i parametry. Porównaj je z wymaganiami punktu końcowego i sprawdź identyfikator zasobu.
• Tożsamość wywołująca określa zakres dostępu. Sprawdź, czy jej uwierzytelnienie i uprawnienia pozwalają wykonać operację na danym zasobie⁶.

Połączenie statusu i treści odpowiedzi z konfiguracją żądania pomaga ustalić przyczynę błędu. HTTP 400 oznacza nieprawidłowe żądanie, a 404 wskazuje, że serwer nie znalazł żądanego zasobu⁷.

Czym różni się REST API od JavaScript API?

Wybór interfejsu zależy od tego, gdzie chcesz wykonać operację: na zasobach usługi Power BI czy w osadzonym raporcie. W Power BI JavaScript API właściwość viewMode pozwala ustawić tryb raportu View albo Edit⁸.

Tabela porównuje interfejsy Power BI według sposobu użycia i przedmiotu operacji.

Dane w tabeli: 9

REST API wybierz do operacji na zasobach usługi. JavaScript API służy do sterowania treścią osadzoną w aplikacji internetowej.

Czym jest żądanie do Power BI API i od czego zależy jego wykonanie?

Żądanie do Power BI API wywołuje punkt końcowy usługi. Jego wykonanie zależy od metody HTTP, wskazanego zasobu, uwierzytelnienia i uprawnień wywołującego. Odpowiedź serwera zawiera status oraz, zależnie od operacji, dane albo komunikat błędu. Żądanie POST rozpoczynające odświeżanie zestawu danych może otrzymać odpowiedź HTTP 202 Accepted³.

Power BI ogranicza liczbę wywołań API przypadających na użytkownika w określonym przedziale czasu¹. Limit żądań to nie to samo co odmowa dostępu. Ponowienie wywołania nie nadaje uprawnień do zasobu⁶.

Jak wysłać żądanie do API i odczytać odpowiedź?

Żądanie wyślij do punktu końcowego właściwego dla danej operacji. Wynik odczytaj ze statusu HTTP i treści odpowiedzi. Na przykład GET /groups/{groupId}/reports/{reportId} pobiera raport z obszaru roboczego i przy powodzeniu zwraca HTTP 200 OK⁴.

• Metoda HTTP określa rodzaj operacji. Dobierz ją do punktu końcowego obsługującego wskazany zasób.
• Adres żądania identyfikuje operację i zasób. Umieść w nim wymagane identyfikatory oraz parametry.
• Odpowiedź API pokazuje wynik wywołania. Przeczytaj status, treść i nagłówki przed przetworzeniem danych albo ponowieniem żądania.

Status mówi, na jakim etapie jest operacja; treść i nagłówki uzupełniają ten obraz. HTTP 200 OK potwierdza powodzenie żądania. Kod 202 Accepted oznacza przyjęcie do przetwarzania, a nie zakończenie operacji⁷.

Jak skonfigurować uwierzytelnianie aplikacji?

Uwierzytelnianie aplikacji pozwala Power BI rozpoznać tożsamość wysyłającą żądanie. O wykonaniu operacji decydują również jej uprawnienia. Pobranie listy raportów z obszaru roboczego wymaga jednego z alternatywnych zakresów delegowanych: Report.Read.All lub Report.ReadWrite.All¹⁰.

• Tożsamość aplikacji wskazuje podmiot wywołujący API. Ustal ją przed konfiguracją dostępu do zasobów Power BI.
• Token dostępu jest poświadczeniem przesyłanym z żądaniem. Uzyskaj go dla właściwej tożsamości i dołącz do wywołania.
• Uprawnienia API określają operacje dostępne aplikacji. Dobierz je do planowanych wywołań i wskazanego zasobu.

Poprawne uwierzytelnienie identyfikuje aplikację, ale nie zastępuje uprawnienia do konkretnej operacji¹¹.

Jak wykonywać operacje na raportach, zestawach danych i obszarach roboczych?

Operacje na zasobach Power BI wykonuj przez punkt końcowy odpowiadający zasobowi i zamierzonej czynności. Dla /datasets/{datasetId}/refreshes metoda POST uruchamia odświeżenie, a GET pobiera jego historię¹².

• Raport wskaż jego identyfikatorem. Gdy wymaga tego operacja, podaj też identyfikator obszaru roboczego.
• Zestaw danych jest zasobem operacji dotyczących danych. Przed wysłaniem żądania sprawdź użyte identyfikatory.
• Obszar roboczy występuje w niektórych interfejsach Power BI API pod nazwą „grupa”¹. Odczytaj znaczenie parametru „group” w dokumentacji wybranego punktu końcowego.

Identyfikator musi pasować do zasobu i operacji. Pomylenie raportu, zestawu danych i obszaru roboczego skieruje żądanie w niewłaściwe miejsce. Ścieżka pobrania pojedynczego raportu wymaga dwóch różnych identyfikatorów: groupId wskazuje obszar roboczy, a reportId – raport⁴.

Jak odróżnić ograniczenie liczby żądań od braku uprawnień?

Przekroczenie limitu żądań Power BI API rozpoznasz po kodzie HTTP 429¹. Odmowę dostępu analizuj osobno, sprawdzając tożsamość i uprawnienia. Operacja Execute Queries ma limit 120 żądań zapytań na minutę na użytkownika, niezależnie od odpytywanego zestawu danych¹³.

• Status HTTP 429 oznacza ograniczenie liczby wywołań. Nie jest sygnałem do zmiany uprawnień aplikacji¹.
• Nagłówek Retry-After podaje czas oczekiwania po przekroczeniu limitu. Wstrzymaj kolejne żądanie na wskazany czas¹.
• Odmowa dostępu wymaga sprawdzenia tożsamości oraz uprawnień do operacji i zasobu. Samo odczekanie nie zmieni zakresu dostępu.

Przy obsłudze limitu kieruj się kodem odpowiedzi i nagłówkiem Retry-After. Przy odmowie dostępu sprawdzaj uprawnienia. Retry-After może zawierać nieujemną liczbę sekund oczekiwania albo datę w formacie HTTP¹⁴.

Pierwsze kroki z Power BI REST API: token, żądanie i połączenie

Pracę z Power BI REST API zacznij od przygotowania tożsamości wywołującej. Następnie uzyskaj token dostępu i wyślij żądanie do wybranego punktu końcowego. Token pozwala API rozpoznać wywołującego.

Punkt końcowy określa zasób i operację. Przed wywołaniem dobierz do niego metodę HTTP i wymagane parametry.

Połączenie jest gotowe, gdy aplikacja potrafi przesłać poświadczenie i odczytać odpowiedź API. Token, adres oraz metoda muszą pasować do tego samego wywołania.

Jak zacząć korzystać z REST API?

Najpierw wybierz operację Power BI REST API. Potem przygotuj dostęp i żądanie dla odpowiedniego punktu końcowego.

• Operacja API określa cel wywołania. Wybierz zasób i czynność, którą aplikacja ma na nim wykonać.
• Tożsamość wywołująca identyfikuje użytkownika lub aplikację. Sprawdź jej dostęp do wskazanego zasobu.
• Żądanie testowe pozwala sprawdzić połączenie. Wyślij je z odpowiednim poświadczeniem i odczytaj status odpowiedzi.

Poprawna odpowiedź potwierdza, że żądanie dotarło do punktu końcowego i zostało obsłużone¹⁵.

Jak uzyskać token dostępu?

Token dostępu uzyskaj dla tożsamości, która będzie wywoływać Power BI REST API. Żądania tego interfejsu można autoryzować tokenem dostępu aplikacji².

• Tożsamość aplikacji musi być przygotowana do uwierzytelniania. Jej poświadczeń użyj podczas uzyskiwania tokenu.
• Zakres dostępu powinien pasować do planowanej operacji. Dobierz uprawnienia aplikacji do zasobu, na którym ma działać¹⁵.
• Otrzymany token prześlij z żądaniem API. Nie umieszczaj go w publicznym kodzie ani w adresie żądania.

Token aplikacji identyfikuje wywołującego. Uprawnienia określają, jakie operacje ta tożsamość może wykonać.

Jak wywołać API?

Do wywołania Power BI REST API potrzebujesz adresu punktu końcowego, właściwej metody HTTP i poświadczenia przesłanego z żądaniem.

• Adres punktu końcowego wskazuje operację. Wstaw do niego identyfikatory zasobów wymagane przez tę operację.
• Metoda HTTP określa sposób wykonania operacji. Użyj metody przypisanej do wybranego punktu końcowego.
• Nagłówek autoryzacji przekazuje token dostępu. Dołącz go przed wysłaniem żądania.
• Odpowiedź API zawiera wynik wywołania. Przeczytaj status i treść, zanim aplikacja przetworzy zwrócone dane.

Praca nie kończy się na wysłaniu żądania. Trzeba jeszcze sprawdzić odpowiedź.

Czy Power BI może pobierać dane z zewnętrznego REST API?

Power BI Desktop może pobierać dane z zewnętrznego REST API. Wybór połączenia zależy od kierunku przepływu danych.

Tabela porównuje oba połączenia według wywołującego, celu i sposobu dostępu.

Dane w tabeli: 2

Źródło „Web” służy do wczytywania danych do Power BI Desktop, a Power BI REST API – do operacji w usłudze. Wybór zależy od tego, czy pobierasz dane do raportu, czy działasz na zasobie Power BI.

Przykłady operacji REST API: zestawy danych, odświeżanie i ograniczenia

Power BI REST API pozwala pobrać listę zestawów danych i skierować żądanie odświeżenia do wybranego zestawu. W obu operacjach zasób wskazuje identyfikator. Wywołujący potrzebuje też odpowiedniego dostępu.

Przy dodawaniu wierszy kontroluj liczbę wywołań, wielkość przesyłanych danych i kolejkę żądań. Poniższe zestawienie oddziela wartości ogólne od ograniczeń podanych dla pojedynczego zestawu danych.

Jak pobrać listę zestawów danych?

Listę zestawów danych Power BI pobierz żądaniem GET skierowanym do punktu końcowego zestawów danych.

• Zakres listy określa, skąd pobierasz zestawy danych. Jeśli operacja dotyczy zasobów obszaru roboczego, wybierz ten obszar¹⁵.
• Żądanie GET kierujesz do punktu końcowego listy zestawów danych. Dołącz poświadczenie tożsamości mającej dostęp do wybranego zakresu.
• Odpowiedź API wskazuje zasoby dostępne dla dalszych operacji. Odczytaj ją i zapisz identyfikator zestawu, który chcesz odświeżyć.

Identyfikator z odpowiedzi pozwala skierować kolejne żądanie do właściwego zestawu danych.

Jak uruchomić odświeżanie zestawu danych?

Odświeżanie zestawu danych Power BI uruchamia żądanie POST wysłane do punktu końcowego wybranego zestawu.

• Identyfikator zestawu danych wskazuje zasób do odświeżenia. Umieść go w żądaniu kierowanym do tego zestawu.
• Dostęp wywołującego sprawdź przed wysłaniem żądania. Tożsamość musi mieć uprawnienie do operacji na wskazanym zestawie.
• Odpowiedź na żądanie pokazuje wynik wywołania. Samo przyjęcie żądania nie oznacza zakończenia odświeżania.

Stan odświeżania oceniaj niezależnie od wyniku wysłania żądania POST.

Jakie ograniczenia trzeba uwzględnić przy wywołaniach API?

Planując wywołania Power BI REST API, uwzględnij limity żądań POST, wierszy, kolumn i kolejki. Poniższe wartości pochodzą z zestawienia Coupler.io i nie są potwierdzonymi oficjalnie limitami Power BI. Wartości dotyczące zestawu danych nie oznaczają limitu całej usługi.

Tabela zestawia podane wartości według jednostki i zakresu ograniczenia.

Dane w tabeli: 2

Osobno planuj wielkość pojedynczego żądania, tempo wysyłania i liczbę operacji oczekujących.

Automatyzacja raportowania przez REST API i przepływy danych

Power BI REST API automatyzuje powtarzalne operacje w usłudze. Przepływ danych przygotowuje natomiast dane pobrane z zewnętrznego źródła. REST API można użyć między innymi do wdrażania raportów, odświeżania zestawów danych i zarządzania obszarami roboczymi¹⁶.

Pobieranie danych z zewnętrznego API to inny proces niż zarządzanie zasobami Power BI. Coupler.io oferuje konektor JSON do połączenia REST API z Power BI oraz ponad 60 gotowych konektorów Power BI. To oferta dostawcy konektorów, nie funkcja Power BI REST API².

Po co automatyzować powtarzalne operacje w Power BI?

Automatyzacja ogranicza ręczną pracę przy powtarzalnych wdrożeniach raportów. W studium przypadku TechCorp Manufacturing proces obejmował działalność w 15 krajach i ponad 200 raportów aktualizowanych 1 raz w tygodniu. Autor studium podaje 67% krótszy czas wdrażania oraz 40% wzrost produktywności programistów. To wyniki opisanego przypadku, a nie gwarancja dla każdego wdrożenia API¹⁶.

Tabela porównuje czas cyklu wdrożenia i odsetek błędów w studium przypadku TechCorp Manufacturing przed automatyzacją i po niej.

Dane w tabeli: 16

Kontrola zgodności to osobny przykład. Opis platformy analitycznej dla ochrony zdrowia podaje 100% automatyzacji kontroli, 95% mniej problemów ze zgodnością i 2 mln USD rocznych oszczędności na kosztach zgodności¹⁶. Inny opis implementacji deklaruje 75% krótszy czas wdrażania i 90% mniej błędów. Tych wyników nie należy przenosić na każdy proces raportowy¹⁶.

Jak połączyć Power BI z zewnętrznym REST API w przepływie danych?

Przepływ danych Power BI może pobrać odpowiedź z zewnętrznego REST API i przekształcić ją w tabelę. Tabela staje się źródłem dla modelu danych. Sposób uwierzytelniania trzeba dopasować do wymagań zewnętrznego punktu końcowego.

• Punkt końcowy zewnętrznego API określa dane pobierane do przepływu. Ustal adres, wymagane parametry i format odpowiedzi.
• Poświadczenia źródła umożliwiają pobranie danych. Skonfiguruj je zgodnie z wymaganiami zewnętrznego API; nie umieszczaj sekretów w publicznym kodzie.
• Zapytanie przepływu danych przekształca odpowiedź API w kolumny i wiersze. Nadaj typy kolumnom używanym w modelu danych.
• Odświeżanie przepływu ponawia pobranie danych ze źródła. Sprawdź jego wynik, zanim oprzesz na danych raport.

Power BI REST API automatyzuje operacje w usłudze. Przepływ danych pobiera i przygotowuje dane z zewnętrznego API.

Architektura integracji: aplikacja, interfejs API i zasoby Power BI

Architektura integracji Power BI REST API obejmuje aplikację wysyłającą żądanie, interfejs usługi Power BI Service i zasób będący celem operacji. Aplikacja przekazuje żądanie, a odpowiedź API informuje ją o wyniku.

Żądania, odpowiedzi i dane Power BI REST API mogą być przetwarzane poza regionem macierzystym dzierżawy¹. Lokalizację przetwarzania warto więc uwzględnić przy ocenie przepływu danych w integracji.

• Aplikacja inicjuje operację na zasobie Power BI. Wysyła żądanie i przetwarza odpowiedź.
• Interfejs API pośredniczy między aplikacją a usługą Power BI. Punkt końcowy wskazuje operację do wykonania.
• Zasób Power BI jest przedmiotem operacji. Identyfikator w żądaniu wskazuje konkretny zasób w usłudze.

Projekt integracji powinien opisywać przepływ żądania, odpowiedzi i danych oraz miejsce ich przetwarzania.

Konfiguracja jednostki usługi do wywołań REST API

Jednostka usługi – service principal – jest tożsamością aplikacji wywołującej Power BI REST API bez działania w imieniu zalogowanego użytkownika. W tym trybie zakresy uprawnień API nie są wymagane. Uprawnieniami zarządza się w portalu administracyjnym Power BI¹.

Uprawnienia delegowane dotyczą żądań wykonywanych w kontekście użytkownika. W przypadku jednostki usługi oddziel zezwolenie na używanie API od dostępu do konkretnego obszaru roboczego.

Tabela porównuje uprawnienia delegowane i jednostkę usługi według tożsamości wywołującej oraz sposobu ustalania dostępu.

Jednostka usługi potrzebuje zarówno zezwolenia na wywołania aplikacji, jak i dostępu do zasobu objętego operacją.

Rejestracja aplikacji do integracji z Power BI

Rejestracja aplikacji w Azure Active Directory (Azure AD) jest wymagana do korzystania z Power BI REST API. Ustanawia ona uprawnienia dostępu do zasobów REST usługi Power BI¹. Zarejestrowana aplikacja otrzymuje tożsamość używaną przy uwierzytelnianiu wywołań.

Uprawnienia aplikacji dobierz do operacji planowanych w integracji. Konfiguracja musi uwzględniać osobno dostęp do interfejsu API i do konkretnego zasobu Power BI.

• Rejestracja aplikacji Azure AD tworzy tożsamość integracji. Jej identyfikator wskazuje aplikację podczas uwierzytelniania.
• Konfiguracja uprawnień określa operacje dostępne aplikacji. Dobór uprawnień powinien wynikać z punktów końcowych używanych przez integrację.
• Dostęp do zasobów Power BI obejmuje obszary robocze i inne zasoby objęte operacjami. Sama rejestracja aplikacji go nie nadaje.

Rejestracja przygotowuje tożsamość aplikacji. Uprawnienia i dostęp do zasobów określają, które wywołania może ona wykonać⁶.

Do czego służy API Power BI Embedded?

API Power BI Embedded służy do osadzania treści Power BI w aplikacji i obsługi interakcji z wyświetlanym raportem. Osadzanie oznacza wyświetlanie raportu wewnątrz własnej aplikacji, nie tylko w usłudze Power BI.

Zarządzanie pojemnościami Power BI Embedded to odrębna operacja obsługiwana przez interfejsy REST usługi Azure Resource Manager¹. Przy projektowaniu integracji rozdziel więc obsługę osadzonego raportu od zarządzania infrastrukturą, na której działa.

Ceny i warunki sprawdzone u źródeł: październik 2026.