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 w celu wykonywania operacji odświeżania modelu semantycznego przy użyciu interfejsu API REST odświeżania zestawu danych usługi 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 zapewnia 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
• GET odśwież szczegóły
• Anulowanie odświeżania

Uwaga

• Wcześniej rozszerzone odświeżanie było nazywane odświeżaniem asynchronicznym za pomocą interfejsu API REST. Jednak standardowe odświeżanie korzystające z interfejsu API REST odświeżania zestawu danych jest również uruchamiane asynchronicznie ze względu na jej nieodłączny charakter.
• Rozszerzone operacje odświeżania interfejsu API REST usługi Power BI nie są automatycznie odświeżane pamięci podręczne kafelków. Kafelek buforuje odświeżanie 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 grupy, zestawy danych i odświeżanie to kolekcje. Grupowanie, zestaw danych i odświeżanie to obiekty.

Wymagania

Do korzystania z interfejsu API REST potrzebne są następujące wymagania:

• Semantyczny model w usłudze Power BI Premium, Premium na użytkownika lub Power BI Embedded.
• Identyfikator grupy i identyfikator zestawu danych do użycia w adresie URL żądania.
• Dataset.ReadWrite.All zakres uprawnień.

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 identyfikatora Entra firmy Microsoft w nagłówku autoryzacji. Token musi spełniać następujące wymagania:

• Być tokenem użytkownika lub jednostką usługi aplikacji.
• Czy odbiorcy mają poprawnie ustawioną wartość https://api.powerbi.com.
• Być używane przez użytkownika lub aplikację, która ma wystarczające uprawnienia do modelu.

Uwaga

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. Nagłówek Location w odpowiedzi zawiera requestId. Ponieważ operacja jest asynchroniczna, aplikacja kliencka może rozłączyć się i użyć polecenia , requestId aby sprawdzić stan później, jeśli to konieczne.

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"
        }
    ]
}

Uwaga

Usługa akceptuje tylko jedną operację odświeżania naraz dla modelu. Jeśli istnieje bieżące uruchomione odświeżanie i zostanie przesłane inne żądanie, zostanie zwrócony 400 Bad Request kod stanu HTTP.

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.

Nazwisko	Typ	Domyślny	opis
type	Wyliczenie	automatic	Typ przetwarzania do wykonania. Typy są zgodne z typami poleceń odświeżania TMSL: full, , clearValues, calculatedataOnly, automatic, i defragment. Typ add nie jest obsługiwany.
commitMode	Wyliczenie	transactional	Określa, czy obiekty mają być zatwierdzane w partiach, czy tylko po zakończeniu. Tryby to transactional i partialBatch. W przypadku korzystania z partialBatch operacji 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ę za pomocą commitMode = transactionalpolecenia .
maxParallelism	Int	10	Określa maksymalną liczbę wątków, które mogą równolegle uruchamiać polecenia przetwarzania. Ta wartość jest zgodna z MaxParallelism właściwością, 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 obejmuje table przetwarzanie całej tabeli lub tablepartition podczas przetwarzania partycji. Jeśli nie określono żadnych obiektów, cały model zostanie odświeżyny.
applyRefreshPolicy	Wartość logiczna	true	Jeśli zdefiniowano zasady odświeżania przyrostowego, określi, czy zasady mają być stosowane. 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 parametr ma transactionalwartość , applyRefreshPolicy może mieć wartość true lub false. Jeśli commitMode parametr ma partialBatchwartość , applyRefreshPolicy nie true jest obsługiwany i applyRefreshPolicy musi być ustawiony na falsewartość .
effectiveDate	Data	Bieżąca data	Jeśli zastosowano zasady odświeżania przyrostowego, effectiveDate parametr zastępuje bieżącą datę. Jeśli nie zostanie określony, czasu UTC służy do określania bieżącego dnia.

Response

202 Accepted

Odpowiedź zawiera Location również pole nagłówka odpowiedzi, aby wskazać obiekt wywołujący operacji odświeżania, która została utworzona i zaakceptowana. Jest Location to lokalizacja nowego zasobu utworzonego żądania, który obejmuje requestId wymagane przez niektóre rozszerzone operacje odświeżania. Na przykład w poniższej odpowiedzi jest ostatnim identyfikatorem w odpowiedzi requestId87f31ef7-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 /refreshes

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",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Uwaga

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

Nazwisko	Pisz	Opis
requestId	Identyfikator GUID	Identyfikator żądania odświeżania. Należy requestId wykonać zapytanie o stan pojedynczej operacji odświeżania lub anulować operację odświeżania w toku.
refreshType	String	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	String	Data i godzina rozpoczęcia odświeżania.
endTime	String	Data i godzina zakończenia odświeżania.
status	String	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. Ten stan endTime jest pusty. Disabled wskazuje, że odświeżanie zostało wyłączone przez selektywne odświeżanie. Cancelled wskazuje, że odświeżanie zostało pomyślnie anulowane.
extendedStatus	String	Rozszerza właściwość, status aby uzyskać więcej informacji.

Uwaga

W usługach Azure Analysis Services ukończony status wynik to 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 $top parametru. 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 wartość 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"
        }
    ]
}

DELETE /refreshes/<requestId>

Aby anulować w toku rozszerzoną operację odświeżania, użyj czasownika DELETE w obiekcie odświeżania requestId, określając .

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

Rozważania i ograniczenia

Operacja odświeżania ma następujące zagadnienia i ograniczenia:

Standardowe operacje odświeżania

• Nie można anulować zaplanowanych ani na żądanie ręcznych odświeżeń modelu przy użyciu polecenia DELETE /refreshes/<requestId>.
• Zaplanowane i na żądanie ręczne odświeżanie modelu nie obsługują pobierania szczegółów operacji odświeżania przy użyciu polecenia GET /refreshes/<requestId>.
• Pobierz szczegóły i Anuluj to nowe operacje na potrzeby 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 lub przy użyciu programu PowerShell lub wystąpi awaria systemu, stan trwającej rozszerzonej operacji odświeżania pozostanie 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 wznowiona po upływie sześciu godzin, 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 jest eksmitowany z pamięci podczas operacji odświeżania, 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 Eksmisja 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 i 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 do największej liczby ponownych prób, które retryCount określają, lub rozszerzony limit czasu przetwarzania odświeżania 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 retryCount parametr. Pomyślne ukończenie odświeżania może przekroczyć pięć godzin, jeśli operacja początkowego odświeżania nie powiedzie się i retryCount określi 1 lub więcej.

Jeśli na przykład zażądasz operacji odświeżania za pomocą "retryCount": 1polecenia , 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:

1. Sklonuj lub pobierz repozytorium.
2. Otwórz rozwiązanie RestApiSample.
3. Znajdź wiersz client.BaseAddress = … i podaj podstawowy adres URL.

Przykładowy kod używa uwierzytelniania jednostki usługi.

Powiązana zawartość

• Interfejs API REST odświeżania zestawu danych usługi Power BI
• Korzystanie z interfejsów API REST usługi Power BI