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
• Konfiguracja limitu czasu

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.

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,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

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.

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

Właściwości odpowiedzi

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

Operacja odświeżania może obejmować wiele prób, jeśli określono retryCount. Każda próba ma domyślny limit czasu 5 godzin, który można dostosować przy użyciu parametru timeout. Łączny czas trwania odświeżania, w tym ponownych prób, nie może przekraczać 24 godzin.

Jeśli retryCount określa liczbę, nowa operacja odświeżania rozpoczyna się od limitu czasu. Usługa ponawia próbę wykonania tej operacji, dopóki nie zakończy się powodzeniem, nie osiągnie limitu retryCount lub nie osiągnie maksymalnego 24-godzinnego limitu od pierwszej próby.

Można dostosować timeout, aby skrócić czas trwania odświeżania w celu szybszego wykrywania błędów lub rozszerzyć go poza domyślne 5 godzin w celu bardziej złożonych odświeżeń danych.

Podczas planowania odświeżania modelu semantycznego przy użyciu interfejsu API REST odświeżania zestawu danych należy wziąć pod uwagę limity czasu i parametr retryCount. Odświeżanie może przekroczyć limit czasu, jeśli początkowa próba zakończy się niepowodzeniem, a parametr retryCount ma wartość 1 lub więcej. Jeśli zażądasz odświeżenia za pomocą polecenia "retryCount": 1, a pierwsza próba zakończy się niepowodzeniem po 4 godzinach, rozpocznie się druga próba. Jeśli zakończy się to powodzeniem w ciągu 3 godzin, łączny czas odświeżania wynosi 7 godzin.

Jeśli operacje odświeżania regularnie kończą się niepowodzeniem, przekraczają 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ć parametr 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 swój podstawowy adres URL .

Przykładowy kod używa uwierzytelniania głównego użytkownika usługi.

Powiązana zawartość

• REST API odświeżania zestawu danych Power BI
• Użyj interfejsów API REST usługi Power BI