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, till exempel automatiska återförsök och batchincheckningar.
Bas-URL
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:
- 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 exempelhttps://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 /refreshes
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. Platsrubriken i svaret innehåller uppdaterings-ID:t. 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 aktuell uppdateringsåtgärd som körs och en annan skickas returneras HTTP-statuskoden 409 Conflict.
Brödtexten kan likna följande:
{
"Type": "Full",
"CommitMode": "transactional",
"MaxParallelism": 2,
"RetryCount": 2,
"Objects": [
{
"table": "DimCustomer",
"partition": "DimCustomer"
},
{
"table": "DimDate"
}
]
}
Parametrar
Standardvärdet tillämpas om parametern inte har angetts.
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).
Kommentar
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.
Kommentar
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: Replikera. Databasfiler replikeras till en målmapp.
- 1: Uttorkande. Databasen extraheras på skrivskyddade serverinstanser.
- 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 utfö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
- Klona eller ladda ned lagringsplatsen. Öppna RestApiSample-lösningen.
- Hitta linjeklienten . BaseAddress = ... och ange din bas-URL.
Kodexemplet använder autentisering med tjänstens huvudnamn .
Tjänstens huvudnamn
Mer information finns i Skapa tjänstens huvudnamn – Azure Portal 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:
- I kodexemplet letar du reda på strängutfärdaren = ..., ersätter vanligt med organisationens klientorganisations-ID.
- 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.
- Kör exemplet.