Asynchrones Aktualisieren mit der REST-API
Mit jeder Programmiersprache, die REST-Aufrufe unterstützt, können Sie asynchrone Datenaktualisierungsvorgänge in Ihren Azure Analysis Services-Tabellenmodellen ausführen, einschließlich der Synchronisierung schreibgeschützter Replikate für die horizontale Abfrageskalierung.
Datenaktualisierungsvorgänge können abhängig von vielen 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). Diese Methoden können jedoch häufig unzuverlässige HTTP-Verbindungen mit langer Ausführungszeit erfordern.
Mithilfe der REST-API für Azure Analysis Services können Datenaktualisierungsvorgänge asynchron ausgeführt werden. Durch Verwendung der REST-API sind keine über Clientanwendungen hergestellten HTTP-Verbindungen mit langer Ausführungszeit erforderlich. Es gibt auch andere integrierte Features für die Zuverlässigkeit, z.B. automatische Wiederholungsversuche und in Batches verarbeitete Commits.
Basis-URL
Die Basis-URL weist das folgende Format auf:
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“. Der Servername lautet:
asazure://westus.asazure.windows.net/myserver
Die Basis-URL für diesen Servernamen lautet:
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:
- Alle Elemente, die mit s enden, sind als Sammlung definiert.
- Alle Elemente, die mit () enden, sind als Funktion definiert.
- Bei allen anderen Elementen handelt es sich um Ressourcen oder Objekte.
Sie können beispielsweise das POST-Verb für die Refreshes-Sammlung verwenden, um einen Aktualisierungsvorgang durchzuführen:
https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes
Authentifizierung
Alle Aufrufe müssen mit einem gültigen Microsoft Entra ID-Token (OAuth 2) im Autorisierungsheader authentifiziert werden und die folgenden Anforderungen erfüllen:
Das Token muss ein Benutzertoken oder ein Anwendungsdienstprinzipal sein.
Für das Token muss die Zielgruppe exakt auf
https://*.asazure.windows.netfestgelegt sein. Beachten Sie, dass*kein Platzhalter ist, und die Zielgruppe muss das*-Zeichen als Unterdomäne aufweisen. Benutzerdefinierte Zielgruppen, z. B.https://customersubdomain.asazure.windows.net, werden nicht unterstützt. Wenn Sie eine ungültige Zielgruppe angeben, tritt ein Authentifizierungsfehler auf.Der Benutzer oder die Anwendung muss für den Server oder das Modell über ausreichende Berechtigungen zum Ausführen des angeforderten Aufrufs verfügen. Die Berechtigungsebene wird durch Rollen innerhalb des Modells oder der Administratorengruppe auf dem Server bestimmt.
Wichtig
Derzeit sind Berechtigungen der Rolle Serveradministrator erforderlich.
POST /refreshes
Verwenden Sie zum Ausführen eines Aktualisierungsvorgangs das POST-Verb für die /refreshes-Sammlung, um der Sammlung ein neues Aktualisierungselement hinzuzufügen. Der Location-Header in der Antwort enthält die Aktualisierungs-ID. Die Clientanwendung kann die Verbindung trennen und den Status später überprüfen, falls erforderlich, da der Vorgang asynchron ist.
Für ein Modell kann nur jeweils ein Aktualisierungsvorgang ausgeführt werden. Wenn bei einem aktuell ausgeführten Aktualisierungsvorgang ein weiterer Aktualisierungsvorgang übertragen wird, wird der HTTP-Statuscode „409 Conflict“ zurückgegeben.
Die Text kann wie folgt aussehen:
{
"Type": "Full",
"CommitMode": "transactional",
"MaxParallelism": 2,
"RetryCount": 2,
"Objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Parameter
Der Standardwert wird angewendet, wenn der Parameter nicht angegeben ist.
| Name | Typ | Beschreibung | Standard |
|---|---|---|---|
Type |
Enum | Der auszuführende Verarbeitungstyp. Die Typen werden an die Typen des TMSL-Aktualisierungsbefehls angepasst: full, clearValues, calculate, dataOnly, automatic und defragment. Der Typ add wird nicht unterstützt. |
automatic |
CommitMode |
Enum | Bestimmt, ob Objekte in Batches oder nur zugesichert werden, wenn der gesamte Vorgang abgeschlossen ist. Folgende Modi sind verfügbar: transactional, partialBatch. |
transactional |
MaxParallelism |
Int | Dieser Wert legt die maximale Anzahl der Threads fest, für die Verarbeitungsbefehle parallel ausgeführt werden. Dieser Wert wird an die MaxParallelism-Eigenschaft angepasst, die im Sequence-Befehl (TMSL) oder mit anderen Methoden festgelegt werden kann. | 10 |
RetryCount |
Int | Gibt an, wie oft der Vorgang wiederholt wird, bevor ein Fehler auftritt. | 0 |
Objects |
Array | Ein Array von zu verarbeitenden Objekten. Jedes Objekt umfasst Folgendes: „table“ bei Verarbeitung der gesamten Tabelle oder „table“ und „partition“ bei Verarbeitung einer Partition. Wenn keine Objekte angegeben sind, wird das gesamte Modell aktualisiert. | Verarbeiten des gesamten Modells |
Das Angeben von partialBatch für CommitMode ist nützlich, wenn das erste Laden großer Datasets ausgeführt wird, was Stunden in Anspruch nehmen kann. 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).
Hinweis
Zum Zeitpunkt der Erstellung dieser Dokumentation entspricht die Batchgröße dem MaxParallelism-Wert – dieser Wert kann sich jedoch ändern.
Statuswerte
| Statuswert | Beschreibung |
|---|---|
notStarted |
Vorgang noch nicht gestartet. |
inProgress |
Vorgang wird ausgeführt. |
timedOut |
Timeout des Vorgangs basierend auf vom Benutzer angegebenen Timeout. |
cancelled |
Vorgang vom Benutzer oder System abgebrochen. |
failed |
Fehler bei dem Vorgang. |
succeeded |
Vorgang erfolgreich. |
GET /refreshes/<Aktualisierungs-ID>
Verwenden Sie zum Überprüfen des Status eines Aktualisierungsvorgangs das GET-Verb für die Aktualisierungs-ID. Es folgt ein Beispiel für den Antworttext. Wenn sich der Vorgang in Bearbeitung befindet, wird als Status inProgress zurückgegeben.
{
"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
Verwenden Sie zum Abrufen einer Liste der Aktualisierungsverlaufsdaten für ein Modell das GET-Verb für die /refreshes-Sammlung. Es folgt ein Beispiel für den Antworttext.
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.
[
{
"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/<Aktualisierungs-ID>
Verwenden Sie zum Abbrechen eines ausgeführten Aktualisierungsvorgangs das DELETE-Verb für die Aktualisierungs-ID.
POST /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. Der Location-Header in der Antwort enthält die ID des Synchronisierungsvorgangs.
GET /sync status
Verwenden Sie zum Überprüfen des Status eines Synchronisierungsvorgangs das GET-Verb, mit dem die Vorgangs-ID als Parameter übergeben wird. Es folgt ein Beispiel für den Antworttext:
{
"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:
- 0: Replikation. Datenbankdateien werden in einen Zielordner repliziert.
- 1: Aktivierung. Die Datenbank wird für schreibgeschützte Serverinstanzen aktiviert.
- 2: Abgeschlossen. Der Synchronisierungsvorgang wurde erfolgreich abgeschlossen.
- 3: Fehler. Beim Synchronisierungsvorgang sind Fehler aufgetreten.
- 4: Ausführung wird abgeschlossen. Der Synchronisierungsvorgang wurde abgeschlossen, es werden jedoch noch Bereinigungsschritte ausgeführt.
Codebeispiel
C#-Codebeispiel für Ihren Einstieg: RestApiSample auf GitHub.
So verwenden Sie das Codebeispiel
- Klonen Sie das Repository, oder laden Sie es herunter. Öffnen Sie die RestApiSample-Lösung.
- Suchen Sie die Zeile client.BaseAddress = und geben Sie Ihre Basis-URL an.
Das Codebeispiel verwendet die Dienstprinzipal-Authentifizierung.
Dienstprinzipal
Weitere Informationen finden Sie unter Erstellen eines Dienstprinzipals – Azure-Portal und Hinzufügen eines Dienstprinzipals zur Serveradministratorrolle, und befolgen Sie die Schritte zum Einrichten eines Dienstprinzipals und Zuweisen der erforderlichen Berechtigungen in Azure AS. Führen Sie anschließend die folgenden zusätzlichen Schritte aus:
- Suchen Sie im Codebeispiel nach string authority = …, und ersetzen Sie common durch die Mandanten-ID Ihrer Organisation.
- Fügen Sie eine Auskommentierung ein, bzw. heben Sie die Auskommentierung auf, damit die ClientCredential-Klasse zum Instanziieren des cred-Objekts verwendet wird. 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.
- Führen Sie das Beispiel aus.