Aggiornamento avanzato con l'API REST di Power BI

  • Articolo

È possibile usare qualsiasi linguaggio di programmazione che supporti le chiamate REST per eseguire operazioni di aggiornamento semantico del modello usando l'API REST del set di dati di aggiornamento di Power BI.

L'aggiornamento ottimizzato per modelli partizionati di grandi dimensioni e complessi viene tradizionalmente richiamato con metodi di programmazione che usano TOM (modello a oggetti tabulari), cmdlet di PowerShell o TMSL (Tabular Model Scripting Language). Tuttavia, questi metodi richiedono connessioni HTTP a esecuzione prolungata che possono non essere affidabili.

L'API REST del set di dati di aggiornamento di Power BI può eseguire operazioni di aggiornamento del modello in modo asincrono, quindi non sono necessarie connessioni HTTP a esecuzione prolungata dalle applicazioni client. Rispetto alle operazioni di aggiornamento standard, l'aggiornamento avanzato con l'API REST offre più opzioni di personalizzazione e le funzionalità seguenti utili per i modelli di grandi dimensioni:

  • Commit batch
  • Aggiornamento a livello di tabella e partizione
  • Applicazione di criteri di aggiornamento incrementale
  • Dettagli aggiornamento GET
  • Annullamento di aggiornamenti

Nota

  • In precedenza, l'aggiornamento avanzato veniva chiamato aggiornamento asincrono con l'API REST. Tuttavia, un aggiornamento standard che usa l'API REST Refresh Dataset viene eseguito in modo asincrono anche dalla sua natura intrinseca.
  • Le operazioni di aggiornamento avanzato dell'API REST di Power BI non aggiornano automaticamente le cache dei riquadri. Le cache dei riquadri vengono aggiornate solo quando un utente accede a un report.

URL di base

L'URL di base è nel formato seguente:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

È possibile aggiungere risorse e operazioni all'URL di base in base ai parametri. Nel diagramma seguente Gruppi, Set di datie Aggiornamenti sono raccolte. Group, Datasete Refresh sono oggetti.

Diagramma che mostra il flusso di aggiornamento asincrono.

Requisiti

Per usare l'API REST sono necessari i requisiti seguenti:

  • Modello semantico in Power BI Premium, Premium per utente o Power BI Embedded.
  • ID gruppo e ID set di dati da usare nell'URL della richiesta.
  • Ambito di autorizzazione Dataset.ReadWrite.All.

Il numero di aggiornamenti è limitato in base alle limitazioni generali per gli aggiornamenti basati su API per i modelli Pro e Premium.

Autenticazione

Tutte le chiamate devono eseguire l'autenticazione con un token OAuth 2 Microsoft Entra ID valido nell'intestazione dell'autorizzazione. Il token deve soddisfare i requisiti seguenti:

  • Essere un token utente o un'entità servizio dell'applicazione.
  • Impostare correttamente il gruppo di destinatari su https://api.powerbi.com.
  • Essere usato da un utente o da un'applicazione con autorizzazioni sufficienti per il modello.

Nota

Le modifiche all'API REST non modificano le autorizzazioni attualmente definite per gli aggiornamenti del modello.

POST /refreshes

Per eseguire un aggiornamento, utilizzare il verbo POST nell'insieme /refreshes per aggiungere un nuovo oggetto refresh all'insieme. L'intestazione Posizione nella risposta include il requestId. Poiché l'operazione è asincrona, un'applicazione client può disconnettersi e usare requestId per controllare lo stato in un secondo momento, se necessario.

Il codice seguente illustra una richiesta di esempio:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

Il corpo della richiesta potrebbe essere simile all'esempio seguente:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Nota

Il servizio accetta una sola operazione di aggiornamento alla volta per un modello. Se è presente un aggiornamento in esecuzione corrente e viene inviata un'altra richiesta, viene restituito un codice di stato HTTP 400 Bad Request.

Parametri

Per eseguire un'operazione di aggiornamento avanzata, è necessario specificare uno o più parametri nel corpo della richiesta. I parametri specificati possono specificare il valore predefinito o un valore facoltativo. Quando la richiesta specifica i parametri, tutti gli altri parametri si applicano all'operazione con i relativi valori predefiniti. Se la richiesta non specifica parametri, tutti i parametri usano i valori predefiniti e viene eseguita un'operazione di aggiornamento standard.

Nome Type Default Descrizione
type Enumerazione automatic 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.
commitMode Enumerazione transactional Determina se eseguire il commit di oggetti in batch o solo al termine. Le modalità sono transactional e partialBatch. Quando si usa partialBatch, l'operazione di aggiornamento non si verifica all'interno di una transazione. Ogni comando viene eseguito singolarmente. Se si verifica un errore, il modello potrebbe essere vuoto o includere solo un subset dei dati. Per evitare errori e mantenere i dati presenti nel modello prima dell'avvio dell'operazione, eseguire l'operazione con commitMode = transactional.
maxParallelism Int 10 Determina il numero massimo di thread che possono eseguire i comandi di elaborazione in parallelo. Questo valore è allineato alla proprietà MaxParallelism che può essere impostata nel comando Sequence TMSL o usando altri metodi.
retryCount Int 0 Numero di tentativi di esecuzione dell'operazione prima dell'esito negativo.
objects Matrice Modello intero Matrice di oggetti da elaborare. Ogni oggetto include table durante l'elaborazione di un'intera tabella o table e partition durante l'elaborazione di una partizione. Se non vengono specificati oggetti, l'intero modello viene aggiornato.
applyRefreshPolicy Booleano true Se viene definito un criterio di aggiornamento incrementale, determina se applicarlo. Le modalità sono true o false. Se il criterio non viene applicato, il processo completo lascia invariate le definizioni di partizione e aggiorna completamente tutte le partizioni nella tabella.

Se commitMode è transactional, applyRefreshPolicy può essere true o false. Se commitMode è partialBatch, applyRefreshPolicy di true non è supportato e applyRefreshPolicy deve essere impostato su false.
effectiveDate Data Data corrente Se viene applicato un criterio di aggiornamento incrementale, il parametro effectiveDate sostituisce la data corrente. Se non specificato, l'ora UTC viene utilizzata per determinare il giorno corrente.

Response

202 Accepted

La risposta include anche un campo Location dell'intestazione di risposta per puntare il chiamante all'operazione di aggiornamento creata e accettata. Location è il percorso della nuova risorsa creata dalla richiesta, che include il requestId necessario per alcune operazioni di aggiornamento avanzate. Nella risposta seguente, ad esempio, requestId è l'ultimo identificatore nella risposta 87f31ef7-1e3a-4006-9b0b-191693e79e9e.

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /refreshes

Usare il verbo GET nella raccolta /refreshes per elencare le operazioni di aggiornamento cronologiche, correnti e in sospeso.

Il corpo della risposta potrebbe essere simile all'esempio seguente:

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Nota

Power BI potrebbe eliminare le richieste se sono presenti troppe richieste in un breve periodo di tempo. Power BI esegue un aggiornamento, accoda la richiesta successiva ed elimina tutte le altre. Per impostazione predefinita, non è possibile eseguire query sullo stato delle richieste eliminate.

Proprietà della risposta

Nome Tipo Descrizione
requestId GUID Identificatore della richiesta di aggiornamento. È necessario requestId per eseguire una query sullo stato delle singole operazioni di aggiornamento o annullare un'operazione di aggiornamento in corso.
refreshType String OnDemand indica che l'aggiornamento è stato attivato in modo interattivo tramite il portale di Power BI.
Scheduled indica che una pianificazione dell'aggiornamento del modello ha attivato l'aggiornamento.
ViaApi indica che una chiamata API ha attivato l'aggiornamento.
ViaEnhancedApi indica che una chiamata API ha attivato un aggiornamento avanzato.
startTime String Data e ora di inizio dell'aggiornamento.
endTime String Data e ora di fine dell'aggiornamento.
status String Completed indica che l'operazione di aggiornamento è stata completata correttamente.
Failed indica che l'operazione di aggiornamento non è riuscita.
Unknown indica che non è possibile determinare lo stato di completamento. Con questo stato, endTime è vuoto.
Disabled indica che l'aggiornamento è stato disabilitato dall'aggiornamento selettivo.
Cancelled indica che l'aggiornamento è stato annullato correttamente.
extendedStatus String Aumenta la proprietà status per fornire altre informazioni.

Nota

In Azure Analysis Services il risultato status completato è succeeded. Se si esegue la migrazione di una soluzione Azure Analysis Services a Power BI, potrebbe essere necessario modificare le soluzioni.

Limitare il numero di operazioni di aggiornamento restituite

L'API REST di Power BI supporta la limitazione del numero richiesto di voci nella cronologia di aggiornamento usando il parametro facoltativo $top. Se non specificato, il valore predefinito corrisponde a tutte le voci disponibili.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET /refreshes/<requestId>

Per controllare lo stato di un'operazione di aggiornamento, usare il verbo GET nell'oggetto di aggiornamento specificando requestId. Se l'operazione è in corso, status restituisce InProgress, come nel corpo della risposta di esempio seguente:

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE /refreshes/<requestId>

Per annullare un'operazione di aggiornamento avanzato in corso, utilizzare il verbo DELETE nell'oggetto refresh specificando requestId.

ad esempio:

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

Considerazioni e limitazioni

L'operazione di aggiornamento presenta le considerazioni e le limitazioni seguenti:

Operazioni di aggiornamento standard

  • Non è possibile annullare gli aggiornamenti del modello programmati o manuali su richiesta usando DELETE /refreshes/<requestId>.
  • Gli aggiornamenti manuali pianificati e su richiesta non supportano il recupero dei dettagli dell'operazione di aggiornamento tramite GET /refreshes/<requestId>.
  • Ottieni dettagli e Annulla sono nuove operazioni solo per l'aggiornamento avanzato. L'aggiornamento standard non supporta queste operazioni.

Power BI Embedded

Se la capacità viene sospesa manualmente nel portale di Power BI o tramite PowerShell o si verifica un'interruzione del sistema, lo stato di qualsiasi operazione di aggiornamento avanzato continua rimane InProgress per un massimo di sei ore. Se la capacità riprende entro sei ore, l'operazione di aggiornamento riprende automaticamente. Se la capacità riprende dopo più di sei ore, l'operazione di aggiornamento potrebbe restituire un errore di timeout. È quindi necessario riavviare l'operazione di aggiornamento.

Rimozione del modello semantico

Power BI usa la gestione dinamica della memoria per ottimizzare la memoria della capacità. Se il modello viene rimosso dalla memoria durante un'operazione di aggiornamento, potrebbe essere restituito l'errore seguente:

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

La soluzione consiste nell'eseguire di nuovo l'operazione di aggiornamento. Per altre informazioni sulla gestione dinamica della memoria e sulla rimozione del modello, vedere Rimozione del modello.

Limiti di tempo dell'operazione di aggiornamento

La quantità massima di tempo per una singola operazione di aggiornamento è di cinque ore. Se l'operazione di aggiornamento non viene completata correttamente entro il limite di cinque ore e retryCount non è specificato o viene specificato come 0 (impostazione predefinita) nel corpo della richiesta, viene restituito un errore di timeout.

Se retryCount specifica 1 o un altro numero, viene avviata una nuova operazione di aggiornamento con un limite di cinque ore. Se l'operazione di ripetizione dei tentativi non riesce, il servizio continua a ripetere l'operazione di aggiornamento fino al maggior numero di tentativi specificati da retryCount oppure fino al limite di tempo di elaborazione dell'aggiornamento avanzato di 24 ore dall'inizio della prima richiesta di aggiornamento.

Quando si pianifica la soluzione di aggiornamento del modello avanzato con l'API REST Aggiorna set di dati, è importante considerare questi limiti di tempo e il parametro retryCount. Il completamento dell'aggiornamento può superare le cinque ore se un'operazione di aggiornamento iniziale ha esito negativo e retryCount specifica 1 o più.

Ad esempio, se si richiede un'operazione di aggiornamento con "retryCount": 1 e l'operazione di ripetizione iniziale non riesce dopo quattro ore dall'ora di avvio, viene avviata una seconda operazione di aggiornamento per tale richiesta. Se la seconda operazione di aggiornamento ha esito positivo in tre ore, il tempo totale per l'esecuzione corretta della richiesta di aggiornamento è di sette ore.

Se le operazioni di aggiornamento hanno esito negativo, superano il limite di cinque ore o superano il tempo desiderato per l'operazione di aggiornamento, è consigliabile ridurre la quantità di dati da aggiornare dall'origine dati. È possibile suddividere l'aggiornamento in più richieste, ad esempio una richiesta per ogni tabella. È anche possibile specificare partialBatch nel parametro commitMode.

Esempio di codice

Per un esempio di codice C# da iniziare, vedere RestApiSample in GitHub.

Per usare l'esempio di codice:

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

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

Contenuto correlato