Ulepszone odświeżanie przy użyciu interfejsu API REST usługi Power BI
Możesz użyć dowolnego języka programowania, który obsługuje wywołania REST, aby przeprowadzać operacje odświeżania modelu semantycznego za pomocą interfejsu API REST do odświeżania zestawu danych Power BI.
Zoptymalizowane odświeżanie dla dużych i złożonych modeli partycjonowanych jest tradycyjnie wywoływane przy użyciu metod programowania korzystających z modelu TOM (tabelarycznego modelu obiektów), poleceń cmdlet programu PowerShell lub języka TMSL (tabelarycznego języka skryptowego modelu). Jednak te metody wymagają długotrwałych połączeń HTTP, które mogą być zawodne.
Interfejs API REST odświeżania zestawu danych usługi Power BI może wykonywać operacje odświeżania modelu asynchronicznie, więc długotrwałe połączenia HTTP z aplikacji klienckich nie są niezbędne. W porównaniu ze standardowymi operacjami odświeżania ulepszone odświeżanie za pomocą interfejsu API REST oferuje więcej opcji dostosowywania i następujące funkcje, które są przydatne w przypadku dużych modeli:
- Zatwierdzenia wsadowe
- Odświeżanie na poziomie tabeli i partycji
- Stosowanie zasad odświeżania przyrostowego
- odśwież szczegóły
GET - Anulowanie odświeżania
Notatka
- Wcześniej rozszerzone odświeżanie było nazywane asynchronicznym odświeżaniem z wykorzystaniem REST API. Jednak standardowe odświeżanie korzystające z interfejsu API REST zestawu danych również jest uruchamiane asynchronicznie ze względu na jego nieodłączny charakter.
- Rozszerzone operacje odświeżania interfejsu API REST usługi Power BI nie powodują automatycznego odświeżania pamięci podręcznych kafelków. Bufory kafelków są odświeżane tylko wtedy, gdy użytkownik uzyskuje dostęp do raportu.
Podstawowy adres URL
Podstawowy adres URL ma następujący format:
https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes
Zasoby i operacje można dołączać do podstawowego adresu URL na podstawie parametrów. Na poniższym diagramie grupyDatasetsi Refreshes to kolekcje . Grupa, Zestaw danych, i Odśwież są obiektami .
Wymagania
Do korzystania z interfejsu API REST potrzebne są następujące wymagania:
- Model semantyczny dla Power BI Premium, Premium na użytkownika lub Power BI Embedded.
- Identyfikator grupy i identyfikator zestawu danych do użycia w adresie URL żądania.
- Zakres uprawnień Dataset.ReadWrite.All.
Liczba odświeżeń jest ograniczona zgodnie z ogólnymi ograniczeniami dotyczącymi odświeżeń opartych na interfejsie API dla modeli Pro i Premium.
Uwierzytelnianie
Wszystkie wywołania muszą uwierzytelniać się przy użyciu prawidłowego tokenu OAuth 2 Microsoft Entra ID w nagłówku autoryzacyjnym. Token musi spełniać następujące wymagania:
- Bądź tokenem użytkownika lub głównym węzłem usługi aplikacji.
- Czy odbiorcy są poprawnie ustawieni na
https://api.powerbi.com? - Być używane przez użytkownika lub aplikację, która ma wystarczające uprawnienia do modelu.
Notatka
Modyfikacje interfejsu API REST nie zmieniają obecnie zdefiniowanych uprawnień dla odświeżeń modelu.
POST /refreshes
Aby przeprowadzić odświeżanie, użyj czasownika POST w kolekcji /refreshes, aby dodać nowy obiekt odświeżania do kolekcji. W odpowiedzi nagłówek Location zawiera requestId. Ponieważ operacja jest asynchroniczna, aplikacja kliencka może rozłączyć się i użyć requestId, aby później sprawdzić stan w razie potrzeby.
Poniższy kod przedstawia przykładowe żądanie:
POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes
Treść żądania może przypominać następujący przykład:
{
"type": "Full",
"commitMode": "transactional",
"maxParallelism": 2,
"retryCount": 2,
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Notatka
Usługa akceptuje tylko jedną operację odświeżania naraz dla modelu. Jeśli jest obecnie trwające odświeżanie i złożone zostanie inne żądanie, kod stanu HTTP 400 Bad Request zostanie zwrócony.
Parametry
Aby wykonać rozszerzoną operację odświeżania, należy określić co najmniej jeden parametr w treści żądania. Określone parametry mogą określać wartość domyślną lub opcjonalną. Gdy żądanie określa parametry, wszystkie inne parametry mają zastosowanie do operacji z ich wartościami domyślnymi. Jeśli żądanie nie określa żadnych parametrów, wszystkie parametry używają wartości domyślnych, a nastąpi standardowa operacja odświeżania.
| Nazwa | Typ | Domyślny | Opis |
|---|---|---|---|
type |
Wyliczenie | automatic |
Rodzaj przetwarzania, które należy wykonać. Typy są zgodne z typami poleceń odświeżania TMSL: full, clearValues, calculate, dataOnly, automatici defragment. Typ add nie jest obsługiwany. |
commitMode |
Wyliczenie | transactional |
Określa, czy obiekty mają być zatwierdzane w partiach, czy dopiero po zakończeniu. Tryby są transactional i partialBatch. W przypadku korzystania z partialBatch operacja odświeżania nie występuje w ramach jednej transakcji. Każde polecenie jest zatwierdzane indywidualnie. Jeśli wystąpi awaria, model może być pusty lub zawierać tylko podzbiór danych. Aby zabezpieczyć się przed awarią i zachować dane, które znajdowały się w modelu przed rozpoczęciem operacji, wykonaj operację przy użyciu commitMode = transactional. |
maxParallelism |
Int | 10 |
Określa maksymalną liczbę wątków, które mogą równolegle uruchamiać polecenia przetwarzania. Ta wartość jest zgodna z właściwością MaxParallelism, którą można ustawić w poleceniu TMSL Sequence lub przy użyciu innych metod. |
retryCount |
Int | 0 |
Liczba ponownych prób operacji przed niepowodzeniem. |
objects |
Tablica | Cały model | Tablica obiektów do przetworzenia. Każdy obiekt zawiera table podczas przetwarzania całej tabeli lub table i partition podczas przetwarzania partycji. Jeśli nie określono żadnych obiektów, cały model zostanie odświeżyny. |
applyRefreshPolicy |
Boolowski | true |
Jeśli zdefiniowano zasady odświeżania przyrostowego, określi, czy zasady mają być stosowane. Dostępne tryby to true lub false. Jeśli zasady nie są stosowane, cały proces pozostawia definicje partycji bez zmian i w pełni odświeża wszystkie partycje w tabeli. Jeśli commitMode jest transactional, applyRefreshPolicy można true lub false. Jeśli commitMode jest partialBatch, applyRefreshPolicy związane z true nie jest obsługiwane, a applyRefreshPolicy musi być ustawione na wartość false. |
effectiveDate |
Data | Bieżąca data | Jeśli zastosowano zasady odświeżania przyrostowego, parametr effectiveDate zastępuje bieżącą datę. Jeśli nie zostanie określony, bieżący dzień zostanie określony przy użyciu konfiguracji strefy czasowej w "Odśwież". |
Odpowiedź
202 Accepted
Odpowiedź zawiera również pole nagłówka odpowiedzi Location, aby wskazać wywołującego na operację odświeżania, która została utworzona i zaakceptowana.
Location to lokalizacja nowego zasobu utworzonego w wyniku żądania, który obejmuje requestId wymagane przez niektóre rozszerzone operacje odświeżania. Na przykład w następującej odpowiedzi requestId jest ostatnim identyfikatorem w odpowiedzi 87f31ef7-1e3a-4006-9b0b-191693e79e9e.
x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e
GET (żądanie HTTP) /refreshes (aktualizacje)
Użyj czasownika GET w kolekcji /refreshes, aby wyświetlić listę historycznych, bieżących i oczekujących operacji odświeżania.
Treść odpowiedzi może wyglądać podobnie do następującego przykładu:
[
{
"requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
"refreshType": "ViaEnhancedApi",
"startTime": "2020-12-07T02:06:57.1838734Z",
"endTime": "2020-12-07T02:07:00.4929675Z",
"status": "Completed",
"extendedStatus": "Completed"
},
{
"requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
"startTime": "2020-12-07T01:05:54.157324Z",
"refreshType": "ViaEnhancedApi",
"status": "Unknown"
}
{
"requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
"refreshType": "ViaEnhancedApi",
"startTime": "2020-12-07T01:05:54.157324Z",
"status": "Unknown",
"extendedStatus": "NotStarted"
}
]
Notatka
Usługa Power BI może usuwać żądania, jeśli w krótkim czasie istnieje zbyt wiele żądań. Usługa Power BI wykonuje odświeżanie, kolejkuje następne żądanie i usuwa wszystkie inne. Zgodnie z projektem nie można wykonywać zapytań o stan porzuconych żądań.
Właściwości odpowiedzi
| Nazwa | Typ | Opis |
|---|---|---|
requestId |
Guid | Identyfikator żądania odświeżania. Musisz użyć requestId, aby zapytać o status indywidualnej operacji odświeżania lub anulować operację odświeżania w toku. |
refreshType |
Struna |
OnDemand wskazuje, że odświeżanie zostało wyzwolone interaktywnie za pośrednictwem portalu usługi Power BI.Scheduled wskazuje, że harmonogram odświeżania modelu wyzwolił odświeżanie. ViaApi wskazuje, że wywołanie interfejsu API wyzwoliło odświeżanie. ViaEnhancedApi wskazuje, że wywołanie interfejsu API wyzwoliło rozszerzone odświeżanie. |
startTime |
Struna | Data i godzina rozpoczęcia odświeżania. |
endTime |
Struna | Data i godzina zakończenia odświeżania. |
status |
Struna |
Completed wskazuje, że operacja odświeżania została ukończona pomyślnie. Failed wskazuje, że operacja odświeżania nie powiodła się. Unknown wskazuje, że nie można określić stanu ukończenia. W przypadku tego stanu endTime jest pusta. Disabled wskazuje, że odświeżanie zostało wyłączone poprzez selektywne odświeżanie. Cancelled wskazuje, że odświeżanie zostało pomyślnie anulowane. |
extendedStatus |
Struna | Rozbudowuje właściwość status w celu dostarczenia większej ilości informacji. |
Notatka
W usługach Azure Analysis Services wynik status jest ukończony jako succeeded. W przypadku migracji rozwiązania azure Analysis Services do usługi Power BI może być konieczne zmodyfikowanie rozwiązań.
Ogranicz liczbę zwracanych operacji odświeżania
Interfejs API REST usługi Power BI obsługuje ograniczanie żądanej liczby wpisów w historii odświeżania przy użyciu opcjonalnego parametru $top. Jeśli nie zostanie określony, wartość domyślna to wszystkie dostępne wpisy.
GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}
GET /refreshes/<requestId>
Aby sprawdzić stan operacji odświeżania, użyj czasownika GET w obiekcie odświeżania, określając requestId. Jeśli operacja jest w toku, status zwraca InProgress, jak w następującej przykładowej treści odpowiedzi:
{
"startTime": "2020-12-07T02:06:57.1838734Z",
"endTime": "2020-12-07T02:07:00.4929675Z",
"type": "Full",
"status": "InProgress",
"currentRefreshType": "Full",
"objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer",
"status": "InProgress"
},
{
"table": "DimDate",
"partition": "DimDate",
"status": "InProgress"
}
]
}
USUŃ /refreshes/<identyfikator_żądania>
Aby anulować rozszerzoną operację odświeżania w toku, użyj polecenia DELETE w obiekcie odświeżania, określając requestId.
Na przykład
DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac
Zagadnienia i ograniczenia
Operacja odświeżania ma następujące zagadnienia i ograniczenia:
Standardowe operacje odświeżania
- Nie można anulować odświeżania modelu, zarówno zaplanowanego, jak i na żądanie, które zostało zainicjowane poprzez wybranie przycisku odświeżania w portalu za pomocą
DELETE /refreshes/<requestId>. - Zaplanowane odświeżenia modelu i te na żądanie, które zostały wyzwolone przez naciśnięcie przycisku odświeżania w portalu, nie obsługują uzyskiwania szczegółów operacji odświeżania przy użyciu
GET /refreshes/<requestId>. - "Pobierz szczegóły i Anuluj to nowe operacje dostępne tylko dla funkcji rozszerzonego odświeżania." Odświeżanie standardowe nie obsługuje tych operacji.
Power BI Embedded
Jeśli pojemność jest wstrzymana ręcznie w portalu usługi Power BI albo za pomocą programu PowerShell, lub wystąpi awaria systemu, status każdej trwającej rozszerzonej operacji odświeżania pozostaje InProgress przez maksymalnie sześć godzin. Jeśli pojemność zostanie wznowiona w ciągu sześciu godzin, operacja odświeżania zostanie wznowiona automatycznie. Jeśli pojemność zostanie przywrócona po więcej niż sześciu godzinach, operacja odświeżania może zwrócić błąd przekroczenia limitu czasu. Następnie należy ponownie uruchomić operację odświeżania.
Eksmisja modelu semantycznego
Usługa Power BI używa dynamicznego zarządzania pamięcią do optymalizacji pamięci pojemności. Jeśli model zostanie usunięty z pamięci podczas operacji odświeżania, możliwe, że może zostać zwrócony następujący błąd:
{
"messages": [
{
"code": "0xC11C0020",
"message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
"type": "Error"
}
]
}
Rozwiązaniem jest ponowne uruchomienie operacji odświeżania. Aby dowiedzieć się więcej na temat dynamicznego zarządzania pamięcią i eksmisji modelu, zobacz eksmisji modelu.
Limity czasu operacji odświeżania
Maksymalny czas dla pojedynczej operacji odświeżania wynosi pięć godzin. Jeśli operacja odświeżania nie zostanie pomyślnie ukończona w ramach pięciogodzinnego limitu, a retryCount nie zostanie określona lub zostanie określona jako 0 (wartość domyślna) w treści żądania, zostanie zwrócony błąd przekroczenia limitu czasu.
Jeśli retryCount określa 1 lub inną liczbę, zostanie uruchomiona nowa operacja odświeżania z pięciogodzinnym limitem. Jeśli ta operacja ponawiania nie powiedzie się, usługa będzie nadal ponawiać operację odświeżania aż do największej liczby ponownych prób określonej przez retryCount lub do zwiększonego limitu czasu przetwarzania odświeżania wynoszącego 24 godziny od początku pierwszego żądania odświeżania.
Podczas planowania rozszerzonego rozwiązania odświeżania modelu przy użyciu interfejsu API REST odświeżania zestawu danych należy wziąć pod uwagę te limity czasu i parametr retryCount. Zakończenie odświeżania może trwać ponad pięć godzin, gdy początkowa operacja odświeżania zakończy się niepowodzeniem i retryCount ustawia wartość na 1 lub więcej.
Jeśli na przykład zażądasz operacji odświeżania z "retryCount": 1, a początkowa operacja ponawiania nie powiedzie się cztery godziny od godziny rozpoczęcia, rozpocznie się druga operacja odświeżania dla tego żądania. Jeśli ta druga operacja odświeżania zakończy się powodzeniem w ciągu trzech godzin, łączny czas pomyślnego wykonania żądania odświeżania wynosi siedem godzin.
Jeśli operacje odświeżania regularnie kończą się niepowodzeniem, przekraczają pięciogodzinny limit czasu lub przekraczają żądany pomyślny czas operacji odświeżania, rozważ zmniejszenie ilości odświeżonych danych ze źródła danych. Odświeżanie można podzielić na wiele żądań, na przykład żądanie dla każdej tabeli. Można również określić partialBatch w parametrze commitMode.
Przykładowy kod
Aby zapoznać się z przykładem kodu w języku C#, zobacz RestApiSample w witrynie GitHub.
Aby użyć przykładowego kodu:
- Sklonuj lub pobierz repozytorium.
- Otwórz rozwiązanie RestApiSample.
- Znajdź wiersz
client.BaseAddress = …i podaj swój podstawowy adres URL .
Przykładowy kod używa uwierzytelniania głównego użytkownika usługi.