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 (tabulare 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 in batch
  • Aggiornamento a livello di tabella e partizione
  • Applicazione di criteri di aggiornamento incrementale
  • GET aggiornare i dettagli
  • Aggiornare l'annullamento

Nota

  • In precedenza, l'aggiornamento avanzato è stato 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, i gruppi, i set di dati e gli aggiornamenti sono raccolte. Group, Dataset e Refresh sono oggetti .

Diagram that shows asynchronous refresh flow.

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 OAuth 2 valido nell'intestazione authorization. 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 Location nella risposta include .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 400 Bad Request codice di stato HTTP.

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, calculatedataOnly, automatic, e defragment. Il add tipo 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. In caso di 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 MaxParallelism proprietà che può essere impostata nel comando TMSL Sequence o utilizzando altri metodi.
retryCount Int 0 Numero di tentativi di esecuzione dell'operazione prima dell'esito negativo.
objects Matrice Intero modello Matrice di oggetti da elaborare. Ogni oggetto include table durante l'elaborazione di un'intera tabella o table durante partition 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 applicare il criterio. 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 effectiveDate parametro esegue l'override della data corrente. Se non specificato, l'ora UTC viene utilizzata per determinare il giorno corrente.

Response

202 Accepted

La risposta include anche un Location campo response-header per puntare il chiamante all'operazione di aggiornamento creata e accettata. Location è il percorso della nuova risorsa creata dalla richiesta, che include l'elemento 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 e elimina tutti gli altri. 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 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 tramite aggiornamento selettivo.
Cancelled indica che l'aggiornamento è stato annullato correttamente.
extendedStatus String Aumenta la status proprietà per fornire altre informazioni.

Nota

In Azure Analysis Services il risultato completato status è 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 è 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 refresh 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 avanzata 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 pianificati o 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>.
  • Ottenere i dettagli e Annullare 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 in corso 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 viene specificata o specificata 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 che retryCount specifica o il 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 retryCount parametro . Un completamento dell'aggiornamento riuscito può superare 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": 1e l'operazione di ripetizione iniziale non riesce quattro ore dall'ora di inizio, 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 commitMode parametro .

Esempio di codice

Per un esempio di codice C# per iniziare, vedere RestApiSample su GitHub.

Per usare l'esempio di codice:

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

L'esempio di codice usa l'autenticazione dell'entità servizio.

Contenuto correlato