Asynchrones Aktualisieren mit der REST-APIAsynchronous refresh with the REST API

Durch Verwendung einer Programmiersprache, die REST-Aufrufe unterstützt, können Sie asynchrone Datenaktualisierungsvorgänge in Ihren tabellarischen Azure Analysis Services-Modellen durchführen.By using any programming language that supports REST calls, you can perform asynchronous data-refresh operations on your Azure Analysis Services tabular models. Dies schließt die Synchronisierung von schreibgeschützten Replikaten für die horizontale Skalierung von Abfragen ein.This includes synchronization of read-only replicas for query scale-out.

Datenaktualisierungsvorgänge können abhängig von verschiedenen Faktoren, z.B. dem Datenvolumen oder der Optimierungsebene mit Partitionen, einige Zeit in Anspruch nehmen. Diese Vorgänge werden üblicherweise mit vorhandenen Methoden aufgerufen, z.B. unter Verwendung von TOM (Tabellenobjektmodell), PowerShell-Cmdlets oder TMSL (Tabular Model Scripting Language).Data-refresh operations can take some time depending on a number of factors including data volume, level of optimization using partitions, etc. These operations have traditionally been invoked with existing methods such as using TOM (Tabular Object Model), PowerShell cmdlets, or TMSL (Tabular Model Scripting Language). Diese Methoden können jedoch häufig unzuverlässige HTTP-Verbindungen mit langer Ausführungszeit erfordern.However, these methods can require often unreliable, long-running HTTP connections.

Mithilfe der REST-API für Azure Analysis Services können Datenaktualisierungsvorgänge asynchron ausgeführt werden.The REST API for Azure Analysis Services enables data-refresh operations to be carried out asynchronously. Durch Verwendung der REST-API sind keine über Clientanwendungen hergestellten HTTP-Verbindungen mit langer Ausführungszeit erforderlich.By using the REST API, long-running HTTP connections from client applications aren't necessary. Es gibt auch andere integrierte Features für die Zuverlässigkeit, z.B. automatische Wiederholungsversuche und in Batches verarbeitete Commits.There are also other built-in features for reliability, such as auto retries and batched commits.

Basis-URLBase URL

Die Basis-URL weist das folgende Format auf:The base URL follows this format:

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

Angenommen, Sie verwenden ein Modell mit dem Namen „AdventureWorks“ auf dem Server „myserver“ in der Azure-Region „USA, Westen“.For example, consider a model named AdventureWorks on a server named myserver, located in the West US Azure region. Der Servername lautet:The server name is:

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

Die Basis-URL für diesen Servernamen lautet:The base URL for this server name is:

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

Durch Verwendung der Basis-URL können Ressourcen und Vorgänge mit den folgenden Parametern angefügt werden:By using the base URL, resources and operations can be appended based on the following parameters:

Asynchrone Aktualisierung

  • Alle Elemente, die mit s enden, sind als Sammlung definiert.Anything that ends in s is a collection.
  • Alle Elemente, die mit () enden, sind als Funktion definiert.Anything that ends with () is a function.
  • Bei allen anderen Elementen handelt es sich um Ressourcen oder Objekte.Anything else is a resource/object.

Sie können beispielsweise das POST-Verb für die Refreshes-Sammlung verwenden, um einen Aktualisierungsvorgang durchzuführen:For example, you can use the POST verb on the Refreshes collection to perform a refresh operation:

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

AuthentifizierungAuthentication

Alle Aufrufe müssen mit einem gültigen Azure Active Directory-Token (OAuth 2) im Autorisierungsheader authentifiziert werden und die folgenden Anforderungen erfüllen:All calls must be authenticated with a valid Azure Active Directory (OAuth 2) token in the Authorization header and must meet the following requirements:

  • Das Token muss ein Benutzertoken oder ein Anwendungsdienstprinzipal sein.The token must be either a user token or an application service principal.

  • Für das Token muss die richtige Zielgruppe auf https://*.asazure.windows.net festgelegt sein.The token must have the correct audience set to https://*.asazure.windows.net.

  • Der Benutzer oder die Anwendung muss für den Server oder das Modell über ausreichende Berechtigungen zum Ausführen des angeforderten Aufrufs verfügen.The user or application must have sufficient permissions on the server or model to make the requested call. Die Berechtigungsebene wird durch Rollen innerhalb des Modells oder der Administratorengruppe auf dem Server bestimmt.The permission level is determined by roles within the model or the admin group on the server.

    Wichtig

    Derzeit sind Berechtigungen der Rolle Serveradministrator erforderlich.Currently, server admin role permissions are necessary.

POST /refreshesPOST /refreshes

Verwenden Sie zum Ausführen eines Aktualisierungsvorgangs das POST-Verb für die /refreshes-Sammlung, um der Sammlung ein neues Aktualisierungselement hinzuzufügen.To perform a refresh operation, use the POST verb on the /refreshes collection to add a new refresh item to the collection. Der Location-Header in der Antwort enthält die Aktualisierungs-ID.The Location header in the response includes the refresh ID. Die Clientanwendung kann die Verbindung trennen und den Status gegebenenfalls später überprüfen, da die Aktualisierung asynchron ist.The client application can disconnect and check the status later if required because it is asynchronous.

Für ein Modell kann nur jeweils ein Aktualisierungsvorgang ausgeführt werden.Only one refresh operation is accepted at a time for a model. Wenn bei einem aktuell ausgeführten Aktualisierungsvorgang ein weiterer Aktualisierungsvorgang übertragen wird, wird der HTTP-Statuscode „409 Conflict“ zurückgegeben.If there's a current running refresh operation and another is submitted, the 409 Conflict HTTP status code is returned.

Die Text kann wie folgt aussehen:The body may resemble the following:

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

ParameterParameters

Es müssen keine Parameter angegeben werden.Specifying parameters is not required. Es wird jeweils der Standard angewendet.The default is applied.

NameName typeType BESCHREIBUNGDescription StandardDefault
Type EnumEnum Der auszuführende Verarbeitungstyp.The type of processing to perform. Die Typen werden an die TMSL-Typen des refresh-Befehls angepasst: full, clearValues, calculate, dataOnly, automatic und defragment.The types are aligned with the TMSL refresh command types: full, clearValues, calculate, dataOnly, automatic, and defragment. Der add-Typ wird nicht unterstützt.Add type is not supported. automaticautomatic
CommitMode EnumEnum Legt fest, ob für Objekte ein Commit in Batches oder erst nach Abschluss ausgeführt wird.Determines if objects will be committed in batches or only when complete. Folgende Modi sind verfügbar: default, transactional, partialBatch.Modes include: default, transactional, partialBatch. transactionaltransactional
MaxParallelism IntInt Dieser Wert legt die maximale Anzahl der Threads fest, für die Verarbeitungsbefehle parallel ausgeführt werden.This value determines the maximum number of threads on which to run processing commands in parallel. Dieser Wert wird an die MaxParallelism-Eigenschaft angepasst, die im Sequence-Befehl (TMSL) oder mit anderen Methoden festgelegt werden kann.This value aligned with the MaxParallelism property that can be set in the TMSL Sequence command or using other methods. 1010
RetryCount IntInt Gibt an, wie oft der Vorgang wiederholt wird, bevor ein Fehler auftritt.Indicates the number of times the operation will retry before failing. 00
Objects ArrayArray Ein Array von zu verarbeitenden Objekten.An array of objects to be processed. Jedes Objekt umfasst Folgendes: „table“ bei Verarbeitung der gesamten Tabelle oder „table“ und „partition“ bei Verarbeitung einer Partition.Each object includes: "table" when processing the entire table or "table" and "partition" when processing a partition. Wenn keine Objekte angegeben sind, wird das gesamte Modell aktualisiert.If no objects are specified, the whole model is refreshed. Verarbeiten des gesamten ModellsProcess the entire model

CommitMode entspricht partialBatch undCommitMode is equal to partialBatch. wird beim anfänglichen Laden umfangreicher DataSets verwendet, das Stunden dauern kann.It's used when doing an initial load of large datasets that could take hours. Wenn beim Aktualisierungsvorgang nach dem erfolgreichen Committen für einen oder mehrere Batches Fehler auftreten, bleiben die erfolgreich committeten Batches committet (erfolgreich committete Batches werden nicht zurückgesetzt).If the refresh operation fails after successfully committing one or more batches, the successfully committed batches will remain committed (it will not roll back successfully committed batches).

Hinweis

Zum Zeitpunkt der Erstellung dieser Dokumentation entspricht die Batchgröße dem MaxParallelism-Wert – dieser Wert kann sich jedoch ändern.At time of writing, the batch size is the MaxParallelism value, but this value could change.

StatuswerteStatus values

StatuswertStatus value BESCHREIBUNGDescription
notStarted Vorgang noch nicht gestartet.Operation not yet started.
inProgress Vorgang wird ausgeführt.Operation in progress.
timedOut Timeout des Vorgangs basierend auf vom Benutzer angegebenen Timeout.Operation timed out based on user specified timeout.
cancelled Vorgang vom Benutzer oder System abgebrochen.Operation canceled by user or system.
failed Fehler bei dem Vorgang.Operation failed.
succeeded Vorgang erfolgreich.Operation succeeded.

GET /refreshes/<refreshId>GET /refreshes/<refreshId>

Verwenden Sie zum Überprüfen des Status eines Aktualisierungsvorgangs das GET-Verb für die Aktualisierungs-ID.To check the status of a refresh operation, use the GET verb on the refresh ID. Es folgt ein Beispiel für den Antworttext.Here's an example of the response body. Wenn sich der Vorgang in Bearbeitung befindet, wird als Status inProgress zurückgegeben.If the operation is in progress, inProgress is returned in status.

{
    "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 /refreshesGET /refreshes

Verwenden Sie zum Abrufen einer Liste der Aktualisierungsverlaufsdaten für ein Modell das GET-Verb für die /refreshes-Sammlung.To get a list of historical refresh operations for a model, use the GET verb on the /refreshes collection. Es folgt ein Beispiel für den Antworttext.Here's an example of the response body.

Hinweis

Zum Zeitpunkt der Erstellung dieser Dokumentation werden die Aktualisierungsvorgänge der letzten 30 Tage gespeichert und zurückgegeben – diese Anzahl kann sich jedoch ändern.At time of writing, the last 30 days of refresh operations are stored and returned, but this number could change.

[
    {
        "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>DELETE /refreshes/<refreshId>

Verwenden Sie zum Abbrechen eines ausgeführten Aktualisierungsvorgangs das DELETE-Verb für die Aktualisierungs-ID.To cancel an in-progress refresh operation, use the DELETE verb on the refresh ID.

POST /syncPOST /sync

Nach dem Ausführen von Aktualisierungsvorgängen müssen die neuen Daten möglicherweise mit den Replikaten für die horizontale Skalierung von Abfragen synchronisiert werden. Verwenden Sie zum Ausführen eines Synchronisierungsvorgangs für ein Modell das POST-Verb für die /sync-Funktion.Having performed refresh operations, it may be necessary to synchronize the new data with replicas for query scale-out. To perform a synchronize operation for a model, use the POST verb on the /sync function. Der Location-Header in der Antwort enthält die ID des Synchronisierungsvorgangs.The Location header in the response includes the sync operation ID.

GET /sync statusGET /sync status

Verwenden Sie zum Überprüfen des Status eines Synchronisierungsvorgangs das GET-Verb, mit dem die Vorgangs-ID als Parameter übergeben wird.To check the status of a sync operation, use the GET verb passing the operation ID as a parameter. Es folgt ein Beispiel für den Antworttext:Here's an example of the response body:

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

Werte für syncstate:Values for syncstate:

  • 0: Replikation.0: Replicating. Datenbankdateien werden in einen Zielordner repliziert.Database files are being replicated to a target folder.
  • 1: Aktivierung.1: Rehydrating. Die Datenbank wird für schreibgeschützte Serverinstanzen aktiviert.The database is being rehydrated on read-only server instance(s).
  • 2: Abgeschlossen.2: Completed. Der Synchronisierungsvorgang wurde erfolgreich abgeschlossen.The sync operation completed successfully.
  • 3: Fehler.3: Failed. Beim Synchronisierungsvorgang sind Fehler aufgetreten.The sync operation failed.
  • 4: Ausführung wird abgeschlossen.4: Finalizing. Der Synchronisierungsvorgang wurde abgeschlossen, es werden jedoch noch Bereinigungsschritte ausgeführt.The sync operation has completed but is performing cleanup steps.

CodebeispielCode sample

C#-Codebeispiel für Ihren Einstieg: RestApiSample auf GitHub.Here's a C# code sample to get you started, RestApiSample on GitHub.

So verwenden Sie das CodebeispielTo use the code sample

  1. Klonen Sie das Repository, oder laden Sie es herunter.Clone or download the repo. Öffnen Sie die RestApiSample-Lösung.Open the RestApiSample solution.
  2. Suchen Sie die Zeile client.BaseAddress = … ,Find the line client.BaseAddress = … und geben Sie Ihre Basis-URL an.and provide your base URL.

Das Codebeispiel verwendet die Dienstprinzipal-Authentifizierung.The code sample uses service principal authentication.

DienstprinzipalService principal

Weitere Informationen zum Einrichten eines Dienstprinzipals und Zuweisen der erforderlichen Berechtigungen in Azure finden Sie unter Erstellen eines Dienstprinzipals – Azure-Portals und Hinzufügen eines Dienstprinzipals zur Serveradministratorrolle.See Create service principal - Azure portal and Add a service principal to the server administrator role for more info on how to set up a service principal and assign the necessary permissions in Azure AS. Führen Sie nach Abschluss dieser Schritte die folgenden zusätzlichen Schritte aus:Once you've completed the steps, complete the following additional steps:

  1. Suchen Sie im Codebeispiel nach string authority = … , und ersetzen Sie common durch die Mandanten-ID Ihrer Organisation.In the code sample, find string authority = …, replace common with your organization's tenant ID.
  2. Fügen Sie eine Auskommentierung ein, bzw. heben Sie die Auskommentierung auf, damit die ClientCredential-Klasse zum Instanziieren des cred-Objekts verwendet wird.Comment/uncomment so the ClientCredential class is used to instantiate the cred object. Stellen Sie sicher, dass auf die Werte <App ID> und <App Key> auf sichere Weise zugegriffen wird, oder verwenden Sie die zertifikatbasierte Authentifizierung für Dienstprinzipale.Ensure the <App ID> and <App Key> values are accessed in a secure way or use certificate-based authentication for service principals.
  3. Führen Sie das Beispiel aus.Run the sample.

Weitere InformationenSee also

Beispiele Samples
REST-APIREST API