Aggiornamento asincrono con l'API REST

  • Articolo

È possibile eseguire operazioni di aggiornamento asincrono dei dati sui modelli tabulari di Azure Analysis Services usando qualsiasi linguaggio di programmazione che supporta le chiamate REST. È inclusa la sincronizzazione delle repliche di sola lettura per la scalabilità orizzontale delle query.

Le operazioni di aggiornamento dei dati possono richiedere tempo a causa di fattori diversi tra cui volume dei dati, livello di ottimizzazione nell'uso delle partizioni e così via. Queste operazioni erano chiamate in genere con metodi esistenti come l'uso di TOM (Tabular Object Model), cmdlet di PowerShell o TMSL (Tabular Model Scripting Language). Tuttavia questi metodi possono richiedere spesso connessioni HTTP non affidabili e con esecuzione prolungata.

L'API REST per Azure Analysis Services consente di eseguire le operazioni di aggiornamento dei dati in modo asincrono. Se si usa l'API REST non sono necessarie connessioni HTTP con esecuzione prolungata dalle applicazioni client. Ci sono anche altre funzionalità integrate che garantiscono l'affidabilità, ad esempio i tentativi automatici e il commit in batch.

URL di base

L'URL di base presenta questo formato:

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

Si consideri ad esempio un modello denominato AdventureWorks in un server denominato myserver che si trova nell'area di Azure Stati Uniti occidentali. Il nome del server è:

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

L'URL di base per questo nome di server è:

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

Usando l'URL di base è possibile accodare risorse e operazioni in base ai parametri seguenti:

Diagram that shows asynchronous refresh logic.

  • Tutto ciò che termina con s è una raccolta.
  • Tutto ciò che termina con () è una funzione.
  • Tutto il resto è un oggetto/risorsa.

Ad esempio, è possibile usare il verbo POST sulla raccolta Refreshes per eseguire un'operazione di aggiornamento:

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

Autenticazione

Tutte le chiamate devono essere autenticate con un token di Microsoft Entra ID (OAuth 2) valido nell'intestazione di autorizzazione e devono soddisfare i requisiti seguenti:

  • Il token deve essere un token utente o un'entità servizio dell'applicazione.

  • Il token deve avere i destinatari corretti impostati su https://*.asazure.windows.net.

  • L'utente o l'applicazione deve avere autorizzazioni sufficienti per il server o il modello per poter effettuare la chiamata di richiesta. Il livello di autorizzazione è determinato dai ruoli all'interno del modello o del gruppo di amministrazione sul server.

    Importante

    Attualmente sono necessarie le autorizzazioni del ruolo amministratore del server.

POST /refreshes

Per eseguire un'operazione di aggiornamento, usare il verbo POST sulla raccolta /refreshes per aggiungere un nuovo elemento di aggiornamento alla raccolta. L'intestazione Location nella risposta include l'ID aggiornamento. L'applicazione client può disconnettersi e controllare lo stato in un secondo momento, se necessario, perché è asincrona.

Per un modello viene accettata una sola operazione di aggiornamento alla volta. Se un'operazione di aggiornamento è in esecuzione e ne viene inviata un'altra, viene restituito il codice di stato HTTP 409 - Conflitto.

Il corpo dovrebbe essere simile al seguente:

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

Parametri

Non è necessario specificare parametri. Viene applicato il valore predefinito.

Nome Tipo Descrizione Default
Type Enumerazione Il tipo di elaborazione da eseguire. I tipi sono allineati con i tipi del comando refresh di TMSL: full, clearValues, calculate, dataOnly, automatic e defragment. Il tipo add non è supportato. automatic
CommitMode Enumerazione Determina se verrà eseguito il commit degli oggetti in batch o solo al termine. Le modalità comprendono: default, transactional, partialBatch. transactional
MaxParallelism Int Questo valore determina il numero massimo di thread su cui eseguire i comandi di elaborazione in parallelo. Questo valore è allineato alla proprietà MaxParallelism che può essere impostata nel comando Sequence di TMSL o usando altri metodi. 10
RetryCount Int Indica il numero massimo di tentativi dell'operazione prima che venga considerata non riuscita. 0
Objects Matrice Una matrice di oggetti da elaborare. Ogni oggetto include: "table" quando viene elaborata un'intera tabella oppure "table" e "partition" quando viene elaborata una partizione. Se non viene specificato alcun oggetto, viene aggiornato l'intero modello. Elaborare l'intero modello

CommitMode equivale a partialBatch. Viene usato quando si esegue un caricamento iniziale di set di dati di grandi dimensioni che potrebbe richiedere ore. Se l'operazione di aggiornamento non riesce dopo l'avvenuto commit di uno o più batch, i batch il cui commit è riuscito rimarranno nello stato di commit (non sarà eseguito il rollback dei batch il cui commit è riuscito).

Nota

Al momento della stesura del presente testo, la dimensione del batch è il valore MaxParallelism, ma questo valore potrebbe cambiare.

Valori di stato

Valore di stato Descrizione
notStarted Operazione non ancora avviata.
inProgress Operazione in corso.
timedOut Si è verificato il timeout dell'operazione in base al timeout specifico dell'utente.
cancelled Operazione annullata dall'utente o dal sistema.
failed Operazione non riuscita.
succeeded Operazione riuscita.

GET /refreshes/<refreshId>

Per controllare lo stato di un'operazione di aggiornamento, usare il verbo GET sull'ID aggiornamento. Ecco un esempio del corpo della risposta. Se l'operazione è in corso, nello stato viene restituito inProgress.

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

Per ottenere un elenco delle operazioni di aggiornamento cronologiche per un modello, usare il verbo GET sulla raccolta /refreshes. Ecco un esempio del corpo della risposta.

Nota

Al momento della stesura del presente testo, vengono archiviati e restituiti gli ultimi 30 giorni di operazioni di aggiornamento, ma questo numero potrebbe cambiare.

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

Per annullare un'operazione di aggiornamento in corso, usare il verbo DELETE sull'ID aggiornamento.

POST /sync

Dopo aver eseguito operazioni di aggiornamento, potrebbe essere necessario sincronizzare i nuovi dati con le repliche per la scalabilità orizzontale delle query. Per eseguire un'operazione di sincronizzazione per un modello, usare il verbo POST sulla funzione /sync. L'intestazione Location nella risposta include l'ID dell'operazione di aggiornamento.

GET /sync status

Per controllare lo stato di un'operazione di sincronizzazione, usare il verbo GET passando l'ID operazione come parametro. Ecco un esempio del corpo della risposta:

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

Valori per syncstate:

  • 0: replica in corso. I file di database sono in fase di replica in una cartella di destinazione.
  • 1: riattivazione in corso. Il database è in fase di riattivazione su istanze del server di sola lettura.
  • 2: comokleto. L'operazione di sincronizzazione è stata completata correttamente.
  • 3: operazione non riuscita. L'operazione di sincronizzazione non è riuscita.
  • 4: finalizzazione in corso. L'operazione di sincronizzazione è stata completata ma è in corso la fase di pulizia.

Esempio di codice

Ecco un esempio di codice C# adatto per iniziare, RestApiSample su GitHub.

Per usare l'esempio di codice

  1. Clonare o scaricare il repository. Aprire la soluzione RestApiSample.
  2. Trovare la riga client.BaseAddress = … e fornire l'URL di base.

Il codice di esempio usa l'autenticazione basata su entità servizio.

Entità servizio

Vedere Creare un'entità servizio - Portale di Azure e Aggiungere un'entità servizio al ruolo di amministratore del server per altre informazioni su come configurare un'entità servizio e assegnare le autorizzazioni necessarie in Azure Analysis Services. Dopo aver completato i passaggi, eseguire i passaggi aggiuntivi seguenti:

  1. Nel codice di esempio, trovare string authority = …, sostituire common con l'ID tenant dell'organizzazione.
  2. Aggiungere o rimuovere il commento in modo che la classe ClientCredential venga usata per creare un'istanza dell'oggetto cred. Assicurarsi che l'accesso ai valori <App ID> e <App Key> venga eseguito in modo sicuro o usare l'autenticazione basata su certificato per le entità servizio.
  3. Eseguire l'esempio.

Vedi anche

Esempi
REST API