Actualisation améliorée avec l’API REST Power BI

Vous pouvez utiliser n’importe quel langage de programmation qui prend en charge les appels REST pour effectuer des opérations d’actualisation de modèle sémantique à l’aide de l’API REST du jeu de données d’actualisation Power BI.

L’actualisation optimisée pour les modèles partitionnés volumineux et complexes est traditionnellement appelée avec des méthodes de programmation qui utilisent TOM (modèle objet tabulaire), les applets de commande PowerShell ou TMSL (langage de script de modèle tabulaire). Toutefois, ces méthodes nécessitent des connexions HTTP longues qui peuvent être peu fiables.

L’API REST du jeu de données d’actualisation Power BI peut effectuer des opérations d’actualisation de modèle de manière asynchrone, de sorte que les connexions HTTP longues à partir d’applications clientes ne sont pas nécessaires. Par rapport aux opérations d’actualisation standard, d’actualisation améliorée avec l’API REST offre davantage d’options de personnalisation et les fonctionnalités suivantes qui sont utiles pour les modèles volumineux :

• Validations par lot
• Actualisation au niveau de la table et de la partition
• Application de stratégies d’actualisation incrémentielle
• GET Détails de l’actualisation
• Annulation d’actualisation
• Configuration du délai d’expiration

Note

• Auparavant, l’actualisation améliorée était appelée actualisation asynchrone avec l’API REST. Toutefois, une actualisation standard qui utilise l’API REST Actualiser le jeu de données s’exécute également de manière asynchrone par sa nature inhérente.
• Les opérations d’actualisation améliorées de l’API REST Power BI n’actualisent pas automatiquement les caches de vignettes. Les caches de vignettes sont actualisés uniquement lorsqu’un utilisateur accède à un rapport.

Base URL (URL de base)

L’URL de base est au format suivant :

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

Vous pouvez ajouter des ressources et des opérations à l’URL de base en fonction des paramètres. Dans le diagramme suivant, les groupes , les jeux de données et les actualisations sont des collections . Groupe, Jeu de donnéeset Actualisation sont des objets .

Exigences

Vous avez besoin des conditions suivantes pour utiliser l’API REST :

• Modèle sémantique dans Power BI Premium, Premium par utilisateur ou Power BI Embedded.
• ID de groupe et ID de jeu de données à utiliser dans l’URL de la requête.
• Étendue d’autorisation Dataset.ReadWrite.All.

Le nombre d’actualisations est limité conformément aux limitations générales des actualisations basées sur l’API pour les modèles Pro et Premium.

Authentification

Tous les appels doivent être authentifiés avec un jeton OAuth 2 Microsoft Entra ID valide dans l’en-tête d'autorisation. Le jeton doit répondre aux exigences suivantes :

• Doit être un jeton d’utilisateur ou un principal de service d’application.
• Définissez correctement l’audience sur https://api.powerbi.com.
• Être utilisé par un utilisateur ou une application disposant d’autorisations suffisantes sur le modèle.

Note

Les modifications apportées à l’API REST ne modifient pas les autorisations actuellement définies pour les actualisations de modèle.

POST /refreshes

Pour effectuer une actualisation, utilisez le verbe POST sur la collection /refreshes pour ajouter un nouvel objet d’actualisation à la collection. L’en-tête Localisation dans la réponse inclut requestId. Étant donné que l’opération est asynchrone, une application cliente peut se déconnecter et utiliser l'requestId pour vérifier l’état ultérieurement si nécessaire.

Le code suivant montre un exemple de requête :

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

Le corps de la requête peut ressembler à l’exemple suivant :

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

Note

Le service accepte une seule opération d’actualisation à la fois pour un modèle. S’il existe une actualisation en cours d’exécution et qu’une autre requête est envoyée, un code d’état HTTP 400 Bad Request retourne.

Paramètres

Pour effectuer une opération d’actualisation améliorée, vous devez spécifier un ou plusieurs paramètres dans le corps de la requête. Les paramètres spécifiés peuvent spécifier la valeur par défaut ou une valeur facultative. Lorsque la requête spécifie des paramètres, tous les autres paramètres s’appliquent à l’opération avec leurs valeurs par défaut. Si la requête ne spécifie aucun paramètre, tous les paramètres utilisent leurs valeurs par défaut et une opération d’actualisation standard se produit.

Nom	Type	Par défaut	Description
type	Énumération	automatic	Type de traitement à effectuer. Les types s’alignent sur les types de commandes d’actualisation TMSL : full, clearValues, calculate, dataOnly, automaticet defragment. Le type add n’est pas pris en charge.
commitMode	Énumération	transactional	Détermine s’il faut valider des objets par lots ou uniquement une fois terminés. Les modes sont transactional et partialBatch. Lorsque vous utilisez partialBatch l’opération d’actualisation ne se produit pas dans une transaction. Chaque commande est validée individuellement. En cas d’échec, le modèle peut être vide ou inclure uniquement un sous-ensemble des données. Pour vous protéger contre les défaillances et conserver les données qui se trouvait dans le modèle avant le démarrage de l’opération, exécutez l’opération avec commitMode = transactional.
maxParallelism	Int	10	Détermine le nombre maximal de threads qui peuvent exécuter les commandes de traitement en parallèle. Cette valeur s’aligne sur la propriété MaxParallelism qui peut être définie dans la commande TMSL Sequence ou à l’aide d’autres méthodes.
retryCount	Int	0	Nombre de tentatives de l’opération avant d’échouer.
objects	Tableau	Intégralité du modèle	Tableau d’objets à traiter. Chaque objet inclut table lors du traitement d’une table entière, ou table et partition lors du traitement d’une partition. Si aucun objet n’est spécifié, l’intégralité du modèle est actualisée.
applyRefreshPolicy	Booléen	true	Si une stratégie d’actualisation incrémentielle est définie, détermine s’il faut appliquer la stratégie. Les modes sont true ou false. Si la stratégie n’est pas appliquée, le processus complet laisse les définitions de partition inchangées et actualise entièrement toutes les partitions de la table. Si commitMode est transactional, applyRefreshPolicy peut être true ou false. Si commitMode est partialBatch, applyRefreshPolicy de true n’est pas pris en charge et applyRefreshPolicy doit être défini sur false.
effectiveDate	Date	Date actuelle	Si une stratégie d’actualisation incrémentielle est appliquée, le paramètre effectiveDate remplace la date actuelle. Si ce n’est pas spécifié, le jour actuel est déterminé à l’aide de la configuration du fuseau horaire sous 'Actualiser'.
timeout	Chaîne	05:00:00 (5 heures)	Si une timeout est spécifiée, chaque tentative d’actualisation des données sur le modèle sémantique respecte ce délai d’expiration. Une demande d’actualisation unique peut inclure plusieurs tentatives si retryCount est spécifié, ce qui peut entraîner la durée totale de l’actualisation au-delà du délai d’expiration spécifié. Par exemple, la définition d’une timeout de 1 heure avec une retryCount de 2 peut entraîner une durée d’actualisation totale allant jusqu’à 3 heures. Les utilisateurs peuvent ajuster le timeout pour raccourcir la durée d’actualisation pour une détection d’échec plus rapide ou l’étendre au-delà des 5 heures par défaut pour les actualisations de données plus complexes. Toutefois, la durée totale de l’actualisation, y compris les nouvelles tentatives, ne peut pas dépasser 24 heures.

Réponse

202 Accepted

La réponse inclut également un champ d’en-tête de réponse Location pour pointer l’appelant vers l’opération d’actualisation créée et acceptée. L'Location est l'emplacement de la nouvelle ressource créée par la demande, qui inclut le requestId requis par certaines opérations de rafraîchissement améliorées. Par exemple, dans la réponse suivante, requestId est le dernier identificateur de la réponse 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

Utilisez le verbe GET sur la collection /refreshes pour répertorier les opérations d’actualisation historiques, actuelles et en attente.

Le corps de la réponse peut ressembler à l’exemple suivant :

[
    {
        "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"
    }
]

Note

Power BI peut supprimer des demandes s’il y a trop de demandes pendant une courte période. Power BI effectue une actualisation, met en file d’attente la requête suivante et supprime toutes les autres. Par conception, vous ne pouvez pas interroger l’état des demandes supprimées.

Propriétés de réponse

Nom	Type	Description
requestId	Guid	Identificateur de la demande d’actualisation. Vous avez besoin de requestId pour interroger l'état de l'opération de rafraîchissement unique ou annuler une opération de rafraîchissement en cours.
refreshType	Chaîne	OnDemand indique que l’actualisation a été déclenchée de manière interactive via le portail Power BI. Scheduled indique qu’une planification d’actualisation du modèle a déclenché l’actualisation. ViaApi indique qu’un appel d’API a déclenché l’actualisation. ViaEnhancedApi indique qu’un appel d’API a déclenché une actualisation améliorée.
startTime	Chaîne	Date et heure de début de l’actualisation.
endTime	Chaîne	Date et heure de fin de l’actualisation.
status	Chaîne	Completed indique que l’opération d’actualisation s’est terminée correctement. Failed indique que l’opération d’actualisation a échoué. Unknown indique que l’état d’achèvement ne peut pas être déterminé. Avec cet état, endTime est vide. Disabled indique que l’actualisation a été désactivée par une actualisation sélective. Cancelled indique que l’actualisation a été annulée avec succès.
extendedStatus	Chaîne	Complète la propriété status pour fournir plus d’informations.

Note

Dans Azure Analysis Services, le résultat status terminé est succeeded. Si vous migrez une solution Azure Analysis Services vers Power BI, vous devrez peut-être modifier vos solutions.

Limiter le nombre d’opérations d’actualisation retournées

L’API REST Power BI prend en charge la limitation du nombre demandé d’entrées dans l’historique d’actualisation à l’aide du paramètre facultatif $top. S’il n’est pas spécifié, la valeur par défaut est toutes les entrées disponibles.

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

GET /refreshes/<requestId>

Pour vérifier l’état d’une opération d’actualisation, utilisez le verbe GET sur l’objet d’actualisation en spécifiant le requestId. Si l’opération est en cours, status retourne InProgress, comme dans l’exemple de corps de réponse suivant :

{
    "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>

Pour annuler une opération d’actualisation améliorée en cours, utilisez le verbe DELETE sur l’objet d’actualisation en spécifiant le requestId.

Par exemple

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

Considérations et limitations

L’opération d’actualisation présente les considérations et limitations suivantes :

Opérations d’actualisation standard

• Vous ne pouvez pas annuler les actualisations planifiées ou à la demande qui ont été déclenchées en sélectionnant le bouton d’actualisation dans le portail, à l’aide de DELETE /refreshes/<requestId>.
• Les actualisations planifiées et à la demande du modèle qui ont été déclenchées en sélectionnant le bouton d’actualisation dans le portail ne prennent pas en charge l’obtention des détails de l’opération d’actualisation à l’aide de GET /refreshes/<requestId>.
• Obtenir les détails et Annuler sont de nouvelles opérations seulement pour l’actualisation améliorée. L’actualisation standard ne prend pas en charge ces opérations.

Power BI Embedded

Si la capacité est suspendue manuellement dans le portail Power BI ou à l’aide de PowerShell ou si une panne système se produit, l’état d’une opération d’actualisation améliorée continue reste InProgress pendant un maximum de six heures. Si la capacité reprend dans les six heures, l’opération d’actualisation reprend automatiquement. Si la capacité est rétablie après plus de six heures, l’opération d’actualisation peut retourner une erreur de dépassement de d’expiration. Vous devez ensuite redémarrer l’opération d’actualisation.

Éviction de modèle sémantique

Power BI utilise la gestion de la mémoire dynamique pour optimiser la mémoire de capacité. Si le modèle est supprimé de la mémoire pendant une opération d’actualisation, l’erreur suivante peut retourner :

{
    "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 solution consiste à réexécuter l’opération d’actualisation. Pour en savoir plus sur la gestion dynamique de la mémoire et l'éviction de modèle, consultez Éviction de modèle.

Limites de temps de l’opération d’actualisation

Une opération d’actualisation peut inclure plusieurs tentatives si retryCount est spécifié. Chaque tentative a un délai d’expiration par défaut de 5 heures, qui peut être ajusté à l’aide du paramètre timeout. La durée totale de l’actualisation, y compris les nouvelles tentatives, ne doit pas dépasser 24 heures.

Si retryCount spécifie un nombre, une nouvelle opération d’actualisation commence par la limite de délai d’expiration. Le service retente cette opération jusqu’à ce qu’elle réussisse, atteint la limite de retryCount ou atteint le maximum de 24 heures à partir de la première tentative.

Vous pouvez ajuster le timeout pour raccourcir la durée d’actualisation pour accélérer la détection des défaillances ou l’étendre au-delà des 5 heures par défaut pour les actualisations de données plus complexes.

Lorsque vous planifiez l’actualisation de votre modèle sémantique avec l’API REST Actualiser le jeu de données, tenez compte des limites de temps et du paramètre retryCount. Une actualisation peut dépasser le délai d’expiration si la tentative initiale échoue et que retryCount est défini sur 1 ou plus. Si vous demandez une actualisation avec « retryCount » : 1 et que la première tentative échoue après 4 heures, une deuxième tentative commence. Si cela réussit dans 3 heures, la durée totale de l’actualisation est de 7 heures.

Si les opérations d’actualisation échouent régulièrement, dépassent la limite de temps d’expiration ou dépassent la durée d’opération d’actualisation souhaitée, envisagez de réduire la quantité de données actualisées à partir de la source de données. Vous pouvez fractionner l’actualisation en plusieurs requêtes, par exemple une demande pour chaque table. Vous pouvez également spécifier partialBatch dans le paramètre commitMode.

Exemple de code

Pour obtenir un exemple de code C# pour commencer, consultez RestApiSample sur GitHub.

Pour utiliser l’exemple de code :

1. Clonez ou téléchargez le dépôt.
2. Ouvrez la solution RestApiSample.
3. Recherchez la ligne client.BaseAddress = … et fournissez votre URL de base .

L’exemple de code utilise l’authentification du principal de service.

Contenu connexe

• API REST Power BI d'actualisation de jeu de données
• Utiliser les API REST Power BI