Aggiornamento avanzato con l'API REST di Power BI

È 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, 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 dettagli dell'aggiornamento
• Aggiorna annullamento
• Configurazione del timeout

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 Dati, e Aggiornamenti sono Collezioni . Group, Datasete Refresh sono oggetti .

Requisiti

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

• Un modello semantico in Power BI Premium, Premium per utente, o Power BI Embedded.
• Un ID gruppo e un ID set di dati da usare nell'URL della richiesta.
• Ambito di autorizzazione per 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 valido nell'intestazione Authorization. Il token deve soddisfare i requisiti seguenti:

• Essere un token utente o un principale del 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.

POST /refreshes

Per eseguire un aggiornamento, utilizzare il verbo POST sulla collezione /refreshes per aggiungere un nuovo oggetto di aggiornamento alla collezione. L'intestazione Location nella risposta include il requestId. Poiché l'operazione è asincrona, un'applicazione client può disconnettersi e usare il 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,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

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.

Risposta

202 Accepted

La risposta include anche un campo Location response-header per puntare il chiamante all'operazione di aggiornamento creata e accettata. Il Location è la posizione 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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Proprietà della risposta

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 comprende 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 il 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 comando DELETE sull'oggetto di aggiornamento specificando il requestId.

Per 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 di modello pianificati o su richiesta che sono stati attivati selezionando il pulsante di aggiornamento nel portale, utilizzando DELETE /refreshes/<requestId>.
• Gli aggiornamenti programmati e su richiesta dei modelli, attivati selezionando il pulsante di aggiornamento nel portale, non supportano l'ottenimento dei dettagli dell'operazione di aggiornamento usando 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 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

Un'operazione di aggiornamento può includere più tentativi se viene specificato retryCount. Ogni tentativo ha un timeout predefinito di 5 ore, che può essere modificato usando il parametro timeout. La durata totale dell'aggiornamento, inclusi i tentativi, non deve superare 24 ore.

Se retryCount specifica un numero, viene avviata una nuova operazione di aggiornamento con il limite di timeout. Il servizio ritenta l'operazione fino a quando non ha successo, raggiunge il limite di retryCount o raggiunge il limite massimo di 24 ore dal primo tentativo.

È possibile modificare il timeout per abbreviare la durata dell'aggiornamento per un rilevamento degli errori più veloce o estenderla oltre le 5 ore predefinite per gli aggiornamenti dei dati più complessi.

Quando si pianifica l'aggiornamento del modello semantico con l'API REST "Aggiorna set di dati", prendere in considerazione i limiti di tempo e il parametro retryCount. Un aggiornamento può superare il timeout se il tentativo iniziale non riesce e retryCount è impostato su 1 o più. Se si richiede un aggiornamento con "retryCount": 1 e il primo tentativo ha esito negativo dopo 4 ore, inizia un secondo tentativo. Se l'operazione ha esito positivo in 3 ore, il tempo totale per l'aggiornamento è di 7 ore.

Se le operazioni di aggiornamento hanno esito negativo regolarmente, superano il limite di timeout 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 su GitHub.

Per usare l'esempio di codice:

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

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

Contenuto correlato

• API REST per l'aggiornamento del dataset di Power BI
• Usare le API REST di Power BI