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 Actualisation des modèles sémantiques Power BI.

L’optimisation de l’actualisation pour les modèles partitionnés volumineux et complexes a été traditionnellement appelée avec des méthodes de programmation utilisant TOM (Tabular Object Model), des cmdlets PowerShell ou TMSL (Tabular Model Scripting Language). Toutefois, ces méthodes nécessitent des connexions HTTP de longue durée qui peuvent être peu fiables.

L’API REST Actualisation des modèles Power BI peut effectuer des opérations d’actualisation de modèle de manière asynchrone, de sorte que les connexions HTTP de longue durée à partir d’applications clientes ne sont pas nécessaires. Par rapport aux opérations d’actualisation standard, l’actualisation améliorée avec l’API REST fournit les options de personnalisation et de fonctionnalités suivantes, utiles pour les grands modèles :

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

Notes

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

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, Jeux de données et Actualisations sont des collections. Groupe, Jeu de données et Actualisation sont des objets.

Spécifications

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

• Un 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é en fonction des limitations générales visant les actualisations basées sur une API pour les modèles Pro et Premium.

Authentification

Tous les appels doivent être authentifiés avec un jeton OAuth2 Microsoft Entra ID valide dans l’en-tête Authorization. Le jeton doit remplir les conditions 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.

Remarque

Les modifications de l’API REST ne changent pas les autorisations, car elles sont 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 refresh à la collection. L’en-tête Location de la réponse comprend requestId. L’opération étant asynchrone, une application cliente peut se déconnecter et utiliser 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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Remarque

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

Paramètres

Pour une opération d’actualisation améliorée, vous devez spécifier un ou plusieurs paramètres dans le corps de la demande. 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	Default	Description
type	Enum	automatic	Type de traitement à effectuer. Les types sont alignés avec les types de commande d’actualisation TMSL full, clearValues, calculate, dataOnly, automatic et 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é. Les modes sont transactional et partialBatch. Lors de l’utilisation de partialBatch, l’opération d’actualisation ne se produit pas au cours d’une transaction. Chaque commande est validée individuellement. En cas de défaillance, le modèle risque d’être vide ou d’inclure uniquement une partie 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 pouvant exécuter des commandes de traitement en parallèle. Cette valeur est alignée sur la propriété MaxParallelism qui peut être définie dans la commande TMSL Sequence ou avec d’autres méthodes.
retryCount	Int	0	Nombre de nouvelles tentatives de l’opération avant l’échec.
objects	Array	Intégralité du modèle	Tableau d’objets à traiter. Chaque objet comprend 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é, le modèle entier est actualisé.
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 et 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. S’il n’est pas spécifié, UTC est utilisé pour déterminer le jour actuel.

Response

202 Accepted

La réponse comprend également un champ d’en-tête de réponse Location pour faire pointer l’appelant vers l’opération d’actualisation qui a été créée et acceptée. Location est l’emplacement de la nouvelle ressource créée par la demande, qui inclut le requestId, que certaines opérations d’actualisation améliorées nécessitent. 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 lister 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",
        "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"
    }
]

Notes

Power BI peut supprimer des demandes si trop de demandes sont effectuées en peu de temps. Power BI effectue une actualisation, met en file d’attente la demande suivante et annule toutes les autres. Par conception, vous ne pouvez pas interroger l’état sur les requêtes abandonnées.

Propriétés de la réponse

Name	Type	Description
requestId	Guid	Identificateur de la demande d’actualisation. requestId est obligatoire pour rechercher l’état d’une opération d’actualisation individuelle ou annuler une opération d’actualisation en cours.
refreshType	String	OnDemand indique que l’actualisation a été déclenchée de manière interactive par le biais du 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	String	Date et heure de début de l’actualisation.
endTime	String	Date et heure de fin de l’actualisation.
status	String	Completed indique que l’opération d’actualisation a réussi. Failed indique que l’opération d’actualisation a échoué. Unknown indique un état d’achèvement qui ne peut pas être déterminé. Avec cet état, endTime est vide. Disabled indique que l’actualisation a été désactivée par l’actualisation sélective. Cancelled indique que l’actualisation a été annulée avec succès.
extendedStatus	String	Complète la propriété status pour fournir plus d’informations.

Notes

Dans Azure Analysis Services, le résultat terminé de status 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 d’entrées demandé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 l’ensemble des 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 refresh 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 refresh 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 de modèle manuelles planifiées ou à la demande à l’aide de DELETE /refreshes/<requestId>.
• Les actualisations planifiées et à la demande manuelles des modèles ne prennent pas en charge l’obtention des détails de l’opération d’actualisation en utilisant 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 du système se produit, l’état de toute opération d’actualisation améliorée en cours reste InProgress pendant un maximum de six heures. Si la capacité est rétablie 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 dynamique de la mémoire 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 de mémoire dynamique et l’éviction de modèles, consultez Éviction de modèles.

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

La durée maximale d’une opération d’actualisation est de cinq heures. Si l’opération d’actualisation ne se termine pas correctement dans la limite de cinq heures et si retryCount n’est pas spécifié, ou si 0 (par défaut) est spécifié dans le corps de la demande, une erreur de délai d’attente est retournée.

Si retryCount spécifie 1 ou un autre nombre, une nouvelle opération d’actualisation avec une limite de cinq heures démarre. Si les opérations de nouvelle tentative suivantes échouent, le service continue de réessayer d’accomplir une opération d’actualisation jusqu’à atteindre le nombre de nouvelles tentatives spécifié dans retryCount, ou la limite de temps de traitement d’actualisation étendue de 24 heures à compter du début de la première demande d’actualisation.

Lorsque vous planifiez votre solution d’actualisation de modèle améliorée avec l’API REST Actualisation du modèle sémantique, il est important de prendre en compte ces limites de temps et le paramètre retryCount. Une actualisation réussie peut dépasser cinq heures si une opération d’actualisation initiale échoue et que retryCount spécifie 1 ou plus.

Par exemple, si vous demandez une opération d’actualisation avec "retryCount": 1, et que l’opération de nouvelle tentative initiale échoue quatre heures après l’heure de début, une deuxième opération d’actualisation commence pour cette demande. Si cette deuxième opération d’actualisation réussit après trois heures, la durée totale d’exécution de la demande d’actualisation est de sept heures.

Si les opérations d’actualisation échouent régulièrement, dépassent la limite de cinq heures ou dépassent la durée souhaitée d’une opération d’actualisation réussie, 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 pour chaque table. Vous pouvez également spécifier partialBatch dans le paramètre commitMode.

Exemple de code

Pour un exemple de code C# pour vous aider à démarrer, consultez RestApiSample sur GitHub.

Pour utiliser l’exemple de code :

1. Clonez ou téléchargez le référentiel.
2. Ouvrez la solution RestApiSample.
3. Recherchez la ligne client.BaseAddress = … et indiquez votre URL de base.

L’exemple de code utilise l’authentification d’un principal de service.

Contenu connexe

• API REST Actualisation de jeu de données Power BI
• Utiliser les API REST Power BI