Dela via

Asynkron uppdatering med REST API

Genom att använda alla programmeringsspråk som stöder REST-anrop kan du utföra asynkrona datauppdateringsåtgärder på dina Azure Analysis Services-tabellmodeller, inklusive synkronisering av skrivskyddade repliker för utskalning av frågor.

Datauppdateringsåtgärder kan ta lite tid beroende på många faktorer, inklusive datavolym, optimeringsnivå med partitioner osv. Traditionellt har dessa åtgärder anropats med befintliga metoder som att använda TOM (tabellobjektmodell), PowerShell-cmdletar eller TMSL (skriptspråk för tabellmodell). Dessa metoder kan dock kräva ofta otillförlitliga, långvariga HTTP-anslutningar.

REST-API:et för Azure Analysis Services gör att datauppdateringsåtgärder kan utföras asynkront. Med hjälp av REST-API:et behövs inte långvariga HTTP-anslutningar från klientprogram. Det finns också andra inbyggda funktioner för tillförlitlighet, såsom automatiska återförsök och batchcommits.

Bas-webbadress

Bas-URL:en följer det här formatet:

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

Tänk dig till exempel en modell med namnet AdventureWorks på en server med namnet myserver, som finns i Azure-regionen USA, västra. Servernamnet är:

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

Bas-URL:en för det här servernamnet är:

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

Med hjälp av bas-URL:en kan resurser och åtgärder läggas till baserat på följande parametrar:

Diagram som visar asynkron uppdateringslogik.

  • Allt som slutar i s är en samling.
  • Allt som slutar med () är en funktion.
  • Allt annat är en resurs/ett objekt.

Du kan till exempel använda POST-verbet i samlingen Uppdaterar för att utföra en uppdateringsåtgärd:

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

Autentisering

Alla anrop måste autentiseras med en giltig OAuth 2-token (Microsoft Entra ID) i auktoriseringshuvudet och måste uppfylla följande krav:

  • Token måste vara antingen en användartoken eller ett huvudnamn för programtjänsten.

  • Token måste ha målgruppen inställd på exakt https://*.asazure.windows.net. Observera att * det inte är en platshållare eller ett jokertecken och att målgruppen * måste ha tecknet som underdomän. Anpassade målgrupper, till exempel https://customersubdomain.asazure.windows.net, stöds inte. Om du anger en ogiltig målgrupp resulterar det i autentiseringsfel.

  • Användaren eller programmet måste ha tillräcklig behörighet på servern eller modellen för att kunna göra det begärda anropet. Behörighetsnivån bestäms av roller i modellen eller administratörsgruppen på servern.

    Viktigt!

    För närvarande krävs behörigheter för serveradministratörsrollen .

POST /uppdateringar

Om du vill utföra en uppdateringsåtgärd använder du POST-verbet i samlingen /refreshes för att lägga till ett nytt uppdateringsobjekt i samlingen. Location-rubriken i svaret innehåller uppdaterings-ID:n. Klientprogrammet kan koppla från och kontrollera statusen senare om det behövs eftersom det är asynkront.

Endast en uppdateringsåtgärd godkänns i taget för en modell. Om det finns en pågående uppdateringsprocess och en annan skickas in returneras HTTP-statuskoden 409 Conflict.

Texten kan likna följande:

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

Parameterar

Standardvärdet tillämpas om parametern inte har angetts.

Namn Typ Beskrivning Förinställning
Type Räkna upp Vilken typ av bearbetning som ska utföras. Typerna är anpassade till TMSL-uppdateringskommandotyperna : full, clearValues, calculate, dataOnly, automaticoch defragment. add typ stöds inte. automatic
CommitMode Räkna upp Avgör om objekt genomförs i batchar eller endast genomförs när hela operationen är slutförd. Tillgängliga lägen är: transactional, partialBatch. transactional
MaxParallelism Int Det här värdet avgör det maximala antalet trådar som bearbetningskommandon ska köras parallellt på. Det här värdet överensstämmer med egenskapen MaxParallelism som kan anges i TMSL-sekvenskommandot eller med hjälp av andra metoder. 10
RetryCount Int Anger hur många gånger åtgärden försöker igen innan den misslyckas. 0
Objects Array En matris med objekt som ska bearbetas. Varje objekt innehåller: "table" när du bearbetar hela tabellen eller "tabellen" och "partitionen" när du bearbetar en partition. Om inga objekt anges uppdateras hela modellen. Bearbeta hela modellen

Det är användbart att partialBatch ange för CommitMode när du utför en första inläsning av stora datamängder som kan ta timmar. Om uppdateringsåtgärden misslyckas efter att en eller flera batchar har utförts förblir de batchar som har checkats in kvar (de återställs inte korrekt bekräftade batchar).

Anmärkning

I skrivande stund är batchstorleken MaxParallelism-värdet, men det här värdet kan ändras.

Statusvärden

Statusvärde Beskrivning
notStarted Åtgärden har inte startats ännu.
inProgress Åtgärden pågår.
timedOut Tidsgränsen för åtgärden uppnåddes baserat på användarens angivna tidsgräns.
cancelled Åtgärden avbröts av användare eller system.
failed Åtgärden misslyckades.
succeeded Åtgärden lyckades.

GET /refreshes/<refreshId>

Om du vill kontrollera status för en uppdateringsåtgärd använder du GET-verbet på uppdaterings-ID:t. Här är ett exempel på svarstexten. Om åtgärden pågår inProgress returneras i 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

Om du vill hämta en lista över historiska uppdateringsåtgärder för en modell använder du GET-verbet i samlingen /refreshes. Här är ett exempel på svarstexten.

Anmärkning

I skrivande stund lagras och returneras de senaste 30 dagarnas uppdateringsåtgärder, men det här antalet kan ändras.

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

Om du vill avbryta en pågående uppdateringsåtgärd använder du DELETE-verbet på uppdaterings-ID:t.

POST /sync

Efter att ha utfört uppdateringsåtgärder kan det vara nödvändigt att synkronisera nya data med repliker för utskalning av frågor. Om du vill utföra en synkroniseringsåtgärd för en modell använder du POST-verbet på funktionen /sync. Platsrubriken i svaret innehåller synkroniseringsåtgärds-ID:t.

GET/sync-status

Om du vill kontrollera statusen för en synkroniseringsåtgärd använder du GET-verbet som skickar åtgärds-ID:t som en parameter. Här är ett exempel på svarstexten:

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

Värden för syncstate:

  • 0: Kopierar. Databasfiler replikeras till en målmapp.
  • 1: Återfuktande. Databasen återställs på skrivskyddad(e) serverinstans(er).
  • 2: Slutförd. Synkroniseringsåtgärden har slutförts.
  • 3: Det gick inte. Synkroniseringsåtgärden misslyckades.
  • 4: Slutför. Synkroniseringsåtgärden har slutförts men genomför rensningssteg.

Kodexempel

Här är ett C#-kodexempel för att komma igång, RestApiSample på GitHub.

Så här använder du kodexemplet

  1. Klona eller ladda ned lagringsplatsen. Öppna RestApiSample-lösningen.
  2. Hitta raden client.BaseAddress = ... och ange din bas-URL.

Kodexemplet använder autentisering med tjänstehuvudman.

Service Principal

Mer information finns i Skapa tjänstens huvudnamn – Azure-portalen och Lägg till ett huvudnamn för tjänsten till serveradministratörsrollen och följ stegen för hur du konfigurerar ett huvudnamn för tjänsten och tilldelar nödvändiga behörigheter i Azure AS. Slutför sedan följande extra steg:

  1. I kodexemplet, hitta string authority = ... och ersätt common med din organisations klientorganisations-ID.
  2. Kommentera/avkommentera så klassen ClientCredential används för att instansiera det autentiseringsbara objektet. <Se till att app-ID> och <appnyckelvärden> nås på ett säkert sätt eller använd certifikatbaserad autentisering för tjänstens huvudnamn.
  3. Utför exemplet.

Se även

Exempel
REST-API

  • Last updated on