Aggiornamento asincrono con l'API REST

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 del tempo a seconda di molti fattori, tra cui volume di dati, livello di ottimizzazione tramite partizioni e così via. Tradizionalmente, queste operazioni sono state richiamate con metodi esistenti, ad esempio l'uso di TOM (Modello a oggetti tabulari), i cmdlet di PowerShell o TMSL (Tabular Model Scripting Language). Tuttavia, questi metodi possono richiedere connessioni HTTP a esecuzione prolungata e spesso inaffidabili.

L'API REST per Azure Analysis Services consente di eseguire le operazioni di aggiornamento dei dati in modo asincrono. Usando l'API REST, le connessioni HTTP a esecuzione prolungata dalle applicazioni client non sono necessarie. Sono disponibili anche altre funzionalità predefinite per l'affidabilità, ad esempio tentativi automatici e commit in batch.

URL di base

L'URL di base segue 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 del server è:

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

Usando l'URL di base, le risorse e le operazioni possono essere aggiunte in base ai parametri seguenti:

• Tutto ciò che termina in s è una raccolta.
• Tutto ciò che termina con () è una funzione.
• Qualsiasi altro elemento è una risorsa/oggetto.

Ad esempio, è possibile usare il verbo POST nell'insieme 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 valido di Microsoft Entra ID (OAuth 2) nell'intestazione Authorization e devono soddisfare i requisiti seguenti.

• Il token deve essere un token utente o un principale del servizio applicativo.

• 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 gli utenti devono avere * 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 disporre di autorizzazioni sufficienti per il server o il modello per effettuare la chiamata richiesta. Il livello di autorizzazione è determinato dai ruoli all'interno del modello o dal gruppo di amministratori nel server.

  Importante

  Attualmente sono necessarie autorizzazioni del ruolo di amministratore del server .

POST /refreshes

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

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

Il corpo può 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.

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 aver eseguito correttamente il commit di uno o più batch, i batch di cui è stato eseguito correttamente il commit rimarranno impegnati (non si eseguirà l'annullamento del commit per i batch già impegnati).

Valori di stato

GET /refreshes/<refreshId>

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

{
    "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 di operazioni di aggiornamento cronologico per un modello, usare il verbo GET nella raccolta /refreshes. Ecco un esempio del corpo della risposta.

[
    {
        "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 nell'ID di 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 nella funzione /sync. L'intestazione Location nella risposta include l'ID operazione di sincronizzazione.

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: Replicando. I file di database vengono replicati in una cartella di destinazione.
• 1: Riattivazione. Il database viene reidratato sulle istanze del server impostate come sola lettura.
• 2: Completato. Operazione di sincronizzazione completata.
• 3: Errore. Operazione di sincronizzazione non riuscita.
• 4: Finalizzazione. L'operazione di sincronizzazione è stata completata ma esegue i passaggi di pulizia.

Esempio di codice

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

Per usare l'esempio di codice

1. Clona o scarica il repository. Aprire la soluzione RestApiSample.
2. Trova la riga client.BaseAddress = … e inserisci il tuo URL di base.

L'esempio di codice usa l'autenticazione principale del servizio.

Service Principal

Per altre informazioni, vedere Creare un'entità servizio - Portale di Azure e Aggiungere un'entità servizio al ruolo di amministratore del server e seguire la procedura per configurare un'entità servizio e assegnare le autorizzazioni necessarie in Azure AS. Completare quindi i passaggi aggiuntivi seguenti:

1. Nell'esempio di codice trovare l'autorità di stringa = ..., sostituire common con l'ID tenant dell'organizzazione.
2. Commenta/annulla il commento in modo che la classe ClientCredential venga utilizzata per istanziare l'oggetto cred. Verificare che i <valori id> app e <chiave> dell'app siano accessibili in modo sicuro o usare l'autenticazione basata su certificati per le entità servizio.
3. Esegui l'esempio.

Vedere anche

esempi di
REST API