Asynchroon vernieuwen met de REST API

  • Artikel

Met behulp van elke programmeertaal die REST-aanroepen ondersteunt, kunt u asynchrone bewerkingen voor het vernieuwen van gegevens uitvoeren op uw tabellaire Azure Analysis Services-modellen. Dit omvat synchronisatie van alleen-lezen replica's voor het uitschalen van query's.

Bewerkingen voor gegevensvernieuwing kunnen enige tijd duren, afhankelijk van een aantal factoren, waaronder gegevensvolume, optimalisatieniveau met behulp van partities, enzovoort. Deze bewerkingen worden traditioneel aangeroepen met bestaande methoden, zoals het gebruik van TOM (Tabular Object Model), PowerShell-cmdlets of TMSL (Tabular Model Scripting Language). Deze methoden kunnen echter vaak onbetrouwbare, langlopende HTTP-verbindingen vereisen.

Met de REST API voor Azure Analysis Services kunnen bewerkingen voor gegevensvernieuwing asynchroon worden uitgevoerd. Met behulp van de REST API zijn langlopende HTTP-verbindingen van clienttoepassingen niet nodig. Er zijn ook andere ingebouwde functies voor betrouwbaarheid, zoals automatische nieuwe pogingen en doorvoeringen in batches.

Basis-URL

De basis-URL volgt deze indeling:

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

Denk bijvoorbeeld aan een model met de naam AdventureWorks op een server met de naam myserver, die zich in de Azure-regio VS - west bevindt. De servernaam is:

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

De basis-URL voor deze servernaam is:

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

Met behulp van de basis-URL kunnen resources en bewerkingen worden toegevoegd op basis van de volgende parameters:

Diagram that shows asynchronous refresh logic.

  • Alles wat eindigt op s is een verzameling.
  • Alles wat eindigt op () is een functie.
  • Alles anders is een resource/object.

U kunt bijvoorbeeld de POST-bewerking voor de verzameling Vernieuwen gebruiken om een vernieuwingsbewerking uit te voeren:

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

Verificatie

Alle aanroepen moeten worden geverifieerd met een geldig Microsoft Entra ID-token (OAuth 2) in de autorisatieheader en moeten voldoen aan de volgende vereisten:

  • Het token moet een gebruikerstoken of een toepassingsservice-principal zijn.

  • Het token moet de juiste doelgroep hebben ingesteld op https://*.asazure.windows.net.

  • De gebruiker of toepassing moet over voldoende machtigingen beschikken op de server of het model om de aangevraagde aanroep uit te voeren. Het machtigingsniveau wordt bepaald door rollen binnen het model of de beheerdersgroep op de server.

    Belangrijk

    Momenteel zijn machtigingen voor de serverbeheerderrol nodig.

POST/vernieuwingen

Als u een vernieuwingsbewerking wilt uitvoeren, gebruikt u de POST-bewerking op de verzameling /refreshes om een nieuw vernieuwingsitem aan de verzameling toe te voegen. De locatieheader in het antwoord bevat de vernieuwings-id. De clienttoepassing kan de verbinding verbreken en de status later controleren, indien nodig, omdat deze asynchroon is.

Er wordt slechts één vernieuwingsbewerking tegelijk geaccepteerd voor een model. Als er een huidige actieve vernieuwingsbewerking is en er een andere wordt verzonden, wordt de HTTP-statuscode 409 Conflict geretourneerd.

De hoofdtekst kan er ongeveer als volgt uitzien:

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

Parameters

Het opgeven van parameters is niet vereist. De standaardwaarde wordt toegepast.

Naam Type Omschrijving Standaard
Type Enum Het type verwerking dat moet worden uitgevoerd. De typen zijn afgestemd op de opdrachttypen voor TMSL-vernieuwing: volledige, clearValues, calculate, dataOnly, automatic en defragmentatie. Het type toevoegen wordt niet ondersteund. automatisch
CommitMode Enum Bepaalt of objecten worden doorgevoerd in batches of alleen wanneer ze zijn voltooid. Modi zijn onder andere: standaard, transactioneel, partialBatch. Transactionele
MaxParallelism Int Deze waarde bepaalt het maximum aantal threads waarop verwerkingsopdrachten parallel moeten worden uitgevoerd. Deze waarde is uitgelijnd met de eigenschap MaxParallelism die kan worden ingesteld in de OPDRACHT TMSL Sequence of met andere methoden. 10
RetryCount Int Geeft het aantal keren aan dat de bewerking opnieuw wordt geprobeerd voordat de bewerking mislukt. 0
Objects Matrix Een matrix met objecten die moeten worden verwerkt. Elk object bevat: 'tabel' bij het verwerken van de hele tabel of 'tabel' en 'partitie' bij het verwerken van een partitie. Als er geen objecten zijn opgegeven, wordt het hele model vernieuwd. Het hele model verwerken

CommitMode is gelijk aan partialBatch. Deze wordt gebruikt bij het uitvoeren van een eerste belasting van grote gegevenssets die uren kunnen duren. Als de vernieuwingsbewerking mislukt nadat een of meer batches zijn doorgevoerd, blijven de vastgelegde batches doorgevoerd (de vastgelegde batches worden niet teruggedraaid).

Notitie

Op het moment van schrijven is de batchgrootte de waarde MaxParallelism, maar deze waarde kan veranderen.

Statuswaarden

Statuswaarde Omschrijving
notStarted De bewerking is nog niet gestart.
inProgress De bewerking wordt uitgevoerd.
timedOut Er is een time-out opgetreden voor de bewerking op basis van de door de gebruiker opgegeven time-out.
cancelled Bewerking geannuleerd door gebruiker of systeem.
failed Bewerking is mislukt.
succeeded De bewerking is voltooid.

GET /refreshes/<refreshId>

Als u de status van een vernieuwingsbewerking wilt controleren, gebruikt u de GET-bewerking voor de vernieuwings-id. Hier volgt een voorbeeld van de hoofdtekst van het antwoord. Als de bewerking wordt uitgevoerd, inProgress wordt deze geretourneerd in de 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/refreshes

Als u een lijst met historische vernieuwingsbewerkingen voor een model wilt ophalen, gebruikt u de GET-bewerking voor de verzameling /refreshes. Hier volgt een voorbeeld van de hoofdtekst van het antwoord.

Notitie

Op het moment van schrijven worden de laatste 30 dagen aan vernieuwingsbewerkingen opgeslagen en geretourneerd, maar dit nummer kan veranderen.

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

Als u een actieve vernieuwingsbewerking wilt annuleren, gebruikt u de bewerking DELETE op de vernieuwings-id.

POST /sync

Na het uitvoeren van vernieuwingsbewerkingen kan het nodig zijn om de nieuwe gegevens te synchroniseren met replica's voor het uitschalen van query's. Als u een synchronisatiebewerking voor een model wilt uitvoeren, gebruikt u de POST-bewerking voor de /sync-functie. De locatieheader in het antwoord bevat de synchronisatiebewerkings-id.

GET /sync-status

Als u de status van een synchronisatiebewerking wilt controleren, gebruikt u het GET-werkwoord dat de bewerkings-id doorgeeft als een parameter. Hier volgt een voorbeeld van de hoofdtekst van het antwoord:

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

Waarden voor syncstate:

  • 0: Repliceren. Databasebestanden worden gerepliceerd naar een doelmap.
  • 1: Reactiveren. De database wordt gerehydrateerd op alleen-lezenserverexemplaren.
  • 2: Voltooid. De synchronisatiebewerking is voltooid.
  • 3: Mislukt. De synchronisatiebewerking is mislukt.
  • 4: Voltooien. De synchronisatiebewerking is voltooid, maar voert opschoonstappen uit.

Voorbeeld van code

Hier volgt een C#-codevoorbeeld om aan de slag te gaan, RestApiSample op GitHub.

Het codevoorbeeld gebruiken

  1. Kloon of download de opslagplaats. Open de RestApiSample-oplossing.
  2. Zoek de regelclient . BaseAddress = ... en geef uw basis-URL op.

In het codevoorbeeld wordt verificatie van de service-principal gebruikt.

Service-principal

Zie Service-principal maken - Azure Portal en Voeg een service-principal toe aan de rol serverbeheerder voor meer informatie over het instellen van een service-principal en het toewijzen van de benodigde machtigingen in Azure AS. Nadat u de stappen hebt voltooid, voert u de volgende extra stappen uit:

  1. Zoek in het codevoorbeeld tekenreeksinstantie = ..., vervang deze door de tenant-id van uw organisatie.
  2. Opmerking/opmerking, zodat de klasse ClientCredential wordt gebruikt om het cred-object te instantiëren. Zorg ervoor dat de waarden voor de <app-id> en <app-sleutel> op een veilige manier worden geopend of dat verificatie op basis van certificaten voor service-principals wordt gebruikt.
  3. Voet het voorbeeld uit.

Zie ook

Voorbeelden
REST API