Odświeżanie asynchroniczne za pomocą interfejsu API REST

Artykuł
10/24/2023

Korzystając z dowolnego języka programowania obsługującego wywołania REST, można wykonywać asynchroniczne operacje odświeżania danych na modelach tabelarycznych usług Azure Analysis Services. Obejmuje to synchronizację replik tylko do odczytu dla skalowania zapytań w poziomie.

Operacje odświeżania danych mogą zająć trochę czasu, w zależności od wielu czynników, takich jak ilość danych, poziom optymalizacji przy użyciu partycji itp. Te operacje tradycyjnie były wywoływane z istniejącymi metodami, takimi jak używanie modelu TOM (tabelarycznego modelu obiektów), poleceń cmdlet programu PowerShell lub TMSL (tabelaryczny język skryptowy modelu). Jednak te metody mogą wymagać często zawodnych, długotrwałych połączeń HTTP.

Interfejs API REST dla usług Azure Analysis Services umożliwia asynchroniczne wykonywanie operacji odświeżania danych. Korzystając z interfejsu API REST, długotrwałe połączenia HTTP z aplikacji klienckich nie są konieczne. Istnieją również inne wbudowane funkcje niezawodności, takie jak automatyczne ponawianie prób i zatwierdzenia wsadowe.

Podstawowy adres URL

Podstawowy adres URL ma następujący format:

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

Rozważmy na przykład model o nazwie AdventureWorks na serwerze o nazwie myserver, znajdującym się w regionie świadczenia usługi Azure Zachodnie stany USA. Nazwa serwera to:

asazure://westus.asazure.windows.net/myserver

Podstawowy adres URL dla tej nazwy serwera to:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

Przy użyciu podstawowego adresu URL zasoby i operacje można dołączać na podstawie następujących parametrów:

Diagram that shows asynchronous refresh logic.

Wszystko, co kończy się na s , to kolekcja.
Wszystko, co kończy się na () jest funkcją.
Wszystkie inne elementy to zasób/obiekt.

Na przykład możesz użyć czasownika POST w kolekcji Refreshes, aby wykonać operację odświeżania:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

Uwierzytelnianie

Wszystkie wywołania muszą być uwierzytelnione przy użyciu prawidłowego tokenu Identyfikator entra firmy Microsoft (OAuth 2) w nagłówku autoryzacji i muszą spełniać następujące wymagania:

Token musi być tokenem użytkownika lub jednostką usługi aplikacji.
Token musi mieć prawidłową grupę odbiorców ustawioną na https://*.asazure.windows.netwartość .
Użytkownik lub aplikacja musi mieć wystarczające uprawnienia na serwerze lub modelu, aby wykonać żądane wywołanie. Poziom uprawnień jest określany przez role w modelu lub grupie administracyjnej na serwerze.

Ważne

Obecnie niezbędne są uprawnienia roli administratora serwera.

POST /refreshes

Aby wykonać operację odświeżania, użyj czasownika POST w kolekcji /refreshes, aby dodać nowy element odświeżania do kolekcji. Nagłówek Location w odpowiedzi zawiera identyfikator odświeżania. Aplikacja kliencka może odłączyć się i sprawdzić stan później, jeśli jest to wymagane, ponieważ jest asynchroniczna.

Tylko jedna operacja odświeżania jest akceptowana naraz dla modelu. Jeśli jest bieżąca uruchomiona operacja odświeżania i zostanie przesłana inna operacja, zwracany jest kod stanu HTTP powodujący konflikt 409.

Treść może przypominać następujące elementy:

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Parametry

Określanie parametrów nie jest wymagane. Wartość domyślna jest stosowana.

Imię i nazwisko/nazwa	Pisz	Opis	Wartość domyślna
`Type`	Wyliczenie	Typ przetwarzania do wykonania. Typy są dopasowywane do typów poleceń odświeżania TMSL: full, clearValues, calculate, dataOnly, automatic i defragmentment. Dodawanie typu nie jest obsługiwane.	automatyczne
`CommitMode`	Wyliczenie	Określa, czy obiekty zostaną zatwierdzone w partiach lub tylko po zakończeniu. Tryby obejmują: domyślne, transakcyjne, częścioweBatch.	Transakcyjnych
`MaxParallelism`	Int	Ta wartość określa maksymalną liczbę wątków, na których mają być uruchamiane polecenia przetwarzania równolegle. Ta wartość jest zgodna z właściwością MaxParallelism, którą można ustawić w poleceniu sekwencji TMSL lub przy użyciu innych metod.	10
`RetryCount`	Int	Wskazuje liczbę ponownych prób wykonania operacji przed niepowodzeniem.	0
`Objects`	Tablica	Tablica obiektów do przetworzenia. Każdy obiekt zawiera: "tabela" podczas przetwarzania całej tabeli lub "tabeli" i "partycji" podczas przetwarzania partycji. Jeśli nie określono żadnych obiektów, cały model zostanie odświeżony.	Przetwarzanie całego modelu

Tryb CommitMode jest równy częścioweBatch. Jest on używany podczas początkowego ładowania dużych zestawów danych, które mogą potrwać kilka godzin. Jeśli operacja odświeżania zakończy się niepowodzeniem po pomyślnym zatwierdzeniu co najmniej jednej partii, zatwierdzone partie pozostaną zatwierdzone (nie zostanie wycofane pomyślnie zatwierdzone partie).

Uwaga

Podczas pisania rozmiar partii jest wartością MaxParallelism, ale ta wartość może ulec zmianie.

Wartości stanu

Wartość stanu	opis
`notStarted`	Operacja nie została jeszcze uruchomiona.
`inProgress`	Operacja w toku.
`timedOut`	Upłynął limit czasu operacji na podstawie limitu czasu określonego przez użytkownika.
`cancelled`	Operacja anulowana przez użytkownika lub system.
`failed`	Operacja nie powiodła się.
`succeeded`	Operacja powiodła się.

GET /refreshes/<refreshId>

Aby sprawdzić stan operacji odświeżania, użyj czasownika GET w identyfikatorze odświeżania. Oto przykład treści odpowiedzi. Jeśli operacja jest w toku, inProgress jest zwracana w stanie.

{
    "startTime": "2017-12-07T02:06:57.1838734Z",
    "endTime": "2017-12-07T02:07:00.4929675Z",
    "type": "full",
    "status": "succeeded",
    "currentRefreshType": "full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "succeeded"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "succeeded"
        }
    ]
}

GET /refreshes

Aby uzyskać listę historycznych operacji odświeżania dla modelu, użyj czasownika GET w kolekcji /refreshes. Oto przykład treści odpowiedzi.

Uwaga

Podczas zapisywania dane są przechowywane i zwracane w ciągu ostatnich 30 dni operacji odświeżania, ale ta liczba może ulec zmianie.

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>

Aby anulować operację odświeżania w toku, użyj czasownika DELETE w identyfikatorze odświeżania.

POST /sync

Po wykonaniu operacji odświeżania może być konieczne zsynchronizowanie nowych danych z replikami na potrzeby skalowania zapytań w poziomie. Aby wykonać operację synchronizacji dla modelu, użyj czasownika POST w funkcji /sync. Nagłówek Location w odpowiedzi zawiera identyfikator operacji synchronizacji.

GET /sync status

Aby sprawdzić stan operacji synchronizacji, użyj czasownika GET przekazującego identyfikator operacji jako parametr. Oto przykład treści odpowiedzi:

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

Wartości dla elementu syncstate:

0: Replikowanie. Pliki bazy danych są replikowane do folderu docelowego.
1: Ponowne wypełnianie. Baza danych jest ponownie wypełniania w wystąpieniach serwera tylko do odczytu.
2: Ukończono. Operacja synchronizacji została ukończona pomyślnie.
3: Niepowodzenie. Operacja synchronizacji nie powiodła się.
4: Finalizowanie. Operacja synchronizacji została ukończona, ale wykonuje kroki oczyszczania.

Przykładowy kod

Oto przykładowy kod w języku C#, aby rozpocząć pracę, restApiSample w witrynie GitHub.

Aby użyć przykładu kodu

Sklonuj lub pobierz repozytorium. Otwórz rozwiązanie RestApiSample.
Znajdź klienta wiersza . BaseAddress = ... i podaj podstawowy adres URL.

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

Jednostka usługi

Aby uzyskać więcej informacji na temat konfigurowania jednostki usługi i przypisywania niezbędnych uprawnień w usłudze Azure AS, zobacz Tworzenie jednostki usługi — witryna Azure Portal i Dodawanie jednostki usługi do roli administratora serwera. Po wykonaniu kroków wykonaj następujące dodatkowe kroki:

W przykładzie kodu znajdź urząd ciągu = ..., zastąp ciąg wspólny identyfikatorem dzierżawy organizacji.
Komentarz/usuń komentarz, aby klasa ClientCredential była używana do tworzenia wystąpienia obiektu cred. <Upewnij się, że dostęp do wartości Identyfikator> aplikacji i <Klucz> aplikacji jest uzyskiwany w bezpieczny sposób lub użyj uwierzytelniania opartego na certyfikatach dla jednostek usługi.
Uruchom przykład.

Zobacz też

Samples
Interfejs API REST

Share via