Aggiornamento asincrono con l'API REST

Articolo
07/12/2024

Usando qualsiasi linguaggio di programmazione che supporta le chiamate REST, è possibile eseguire operazioni asincrone di aggiornamento dei dati nei modelli tabulari di Azure Analysis Services, inclusa la sincronizzazione di repliche di sola lettura per la scalabilità orizzontale delle query.

Le operazioni di aggiornamento dei dati possono richiedere tempo a causa di molti fattori 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:

Diagramma che mostra la logica di aggiornamento asincrona.

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 il gruppo di destinatari impostato esattamente su https://*.asazure.windows.net. Si noti che * non è un segnaposto o un carattere jolly e il gruppo di destinatari deve avere il carattere * come sottodominio. I gruppi di destinatari personalizzati, ad esempio https://customersubdomain.asazure.windows.net, non sono supportati. Se si specifica un gruppo di destinatari non valido, si verifica un errore di autenticazione.
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

Il valore predefinito viene applicato se il parametro non è specificato.

Nome	Tipo	Descrizione	Default
`Type`	Enumerazione	Il tipo di elaborazione da eseguire. I tipi sono allineati ai tipi di comando di aggiornamento TMSL: `full`, `clearValues`, `calculate`,`dataOnly`, `automatic`, e `defragment`. Il tipo `add` non è supportato.	`automatic`
`CommitMode`	Enumerazione	Determina se gli oggetti vengono sottoposti a commit in batch o sottoposti a commit solo al completamento dell'intera operazione. Le modalità includono: `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 di tentativi dell'operazione prima dell'esito negativo.	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

Specificare partialBatch per CommitMode è utile quando si esegue un caricamento iniziale di set di dati di grandi dimensioni che potrebbero 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

Clonare o scaricare il repository. Aprire la soluzione RestApiSample.
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. Completare quindi i passaggi aggiuntivi seguenti:

Nel codice di esempio, trovare string authority = …, sostituire common con l'ID tenant dell'organizzazione.
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.
Eseguire l'esempio.

Vedi anche

Esempi
REST API

Condividi tramite