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

Korzystając z dowolnego języka programowania obsługującego wywołania REST, można wykonywać asynchroniczne operacje odświeżania danych w modelach tabelarycznych usług Azure Analysis Services, w tym synchronizację replik tylko do odczytu na potrzeby 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. Tradycyjnie te operacje zostały wywołane przy użyciu istniejących metod, takich jak używanie modelu TOM (tabelarycznego modelu obiektów), poleceń cmdlet programu PowerShell lub TMSL (tabelaryczny język skryptów 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 zwiększające niezawodność, takie jak automatyczne ponowne próby i partiowe zatwierdzenia.

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:

• 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 Microsoft Entra ID (OAuth 2) w nagłówku autoryzacji i muszą spełniać następujące wymagania:

• Token musi być tokenem użytkownika lub głównym kontem usługi aplikacji.

• Token musi mieć ustawioną wartość dokładnie na https://*.asazure.windows.net. Należy pamiętać, że * nie jest symbolem zastępczym ani symbolem wieloznacznym, a odbiorcy muszą mieć * znak jako poddomenę. Niestandardowe grupy odbiorców, takie jak https://customersubdomain.asazure.windows.net, nie są obsługiwane. Określenie nieprawidłowych odbiorców powoduje niepowodzenie uwierzytelniania.

• 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 konieczne, ponieważ jest asynchroniczna.

Tylko jedna operacja odświeżania jest akceptowana naraz dla modelu. Jeśli jest uruchomiona operacja odświeżania i zostanie przesłana inna operacja, zwracany jest kod stanu HTTP 409 - Konflikt.

Treść główna może przypominać następujące:

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

Parametry

Wartość domyślna jest stosowana, jeśli parametr nie jest określony.

Wskazanie partialBatch dla CommitMode jest przydatne podczas wstępnego ł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, pomyślnie zatwierdzone partie pozostaną w mocy i nie zostaną wycofane.

Wartości stanu

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 statusie.

{
    "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 (żądanie HTTP) /refreshes (aktualizacje)

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

[
    {
        "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 w celu zwiększenia skali przetwarzania zapytań. 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: Nawadnianie. 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 nadal wykonuje kroki oczyszczania.

Przykład kodu

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

Aby użyć przykładu kodu

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

Przykładowy kod używa uwierzytelniania service principal.

główna usługa

Aby uzyskać więcej informacji, zobacz Tworzenie jednostki usługi — witryna Azure Portal i Dodawanie jednostki usługi do roli administratora serwera , a następnie postępuj zgodnie z instrukcjami dotyczącymi konfigurowania jednostki usługi i przypisywania niezbędnych uprawnień w usłudze Azure AS. Następnie wykonaj następujące dodatkowe kroki:

1. W przykładzie kodu znajdź string authority = ..., zastąp ciąg wspólny identyfikatorem dzierżawcy Twojej organizacji.
2. Zakomentuj/odkomentuj, aby klasa ClientCredential była używana do utworzenia obiektu cred. Upewnij się, że wartości <Identyfikator aplikacji> i <Klucz aplikacji> są uzyskiwane w bezpieczny sposób lub użyj uwierzytelniania opartego na certyfikatach dla podmiotów usługi.
3. Uruchom przykład.

Zobacz także

Próbki
REST API