Demander des données de sous-total agrégées

  • Article

LAPI total et sous-total permet aux visuels personnalisés avec une vue de données de matrice de demander des données de sous-total agrégées à partir de l’hôte Power BI. Les sous-totaux sont calculés pour le modèle sémantique de matrice entier ou spécifiés pour des niveaux individuels de la hiérarchie de données de matrice. Consultez l’exemple de rapport pour obtenir un exemple d’API de total et sous-total dans un visuel Power BI.

Notes

La demande de données de sous-total est prise en charge dans les versions 2.6.0 et ultérieures. La propriété rowSubtotalType est disponible dans la version 5.1.0 et les versions ultérieures. Pour identifier la version que vous utilisez, consultez la section apiVersion dans le fichier pbiviz.json.

Chaque fois qu’un visuel actualise ses données, il émet une requête d’extraction de données au service principal Power BI. Ces requêtes de données sont généralement destinées aux valeurs des champs que l’utilisateur a fait glisser dans les barres de champs du visuel. Parfois, le visuel a besoin que d’autres agrégations ou sous-totaux (par exemple, somme ou nombre) soient appliqués à ces barres de champs. L’API de total et sous-total vous permet de personnaliser la requête de données sortantes pour demander plus de données d’agrégation ou de sous-total.

Screenshot of visual with subtotals row and columns highlighted.

L’API sous-totaux

L’API offre la personnalisation suivante pour chaque type de vue de données (uniquement les vues de données de matrice actuellement) :

  • rowSubtotals : (booléen) indique si les données de sous-total doivent être demandées pour tous les champs dans la barre de champs de lignes.
  • rowSubtotalsPerLevel : (booléen) indique si les données de sous-total peuvent être basculées pour les champs individuels dans la barre de champs de la ligne.
  • columnSubtotals : (booléen) indique si les données de sous-total doivent être demandées pour tous les champs dans la barre de champs de colonnes.
  • columnSubtotalsPerLevel : (booléen) indique si les données de sous-total peuvent être basculées pour les champs individuels dans la barre de champs de colonnes.
  • levelSubtotalEnabled : (booléen) indique si les sous-totaux sont demandés pour la ligne ou la colonne. Contrairement à toutes les autres propriétés, cette propriété est appliquée à des lignes ou colonnes individuelles.
  • rowSubtotalsType : (« Haut » ou « Bas ») indique si la ligne avec les données de total doit être récupérée avant (top) ou après (bottom) le reste des données. Si cette propriété a la valeur bottom, le total ne peut être affiché qu’une fois que toutes les données ont été extraites. Par défaut, il s’agit de bottom.

Chacun des commutateurs précédemment répertoriés se voit attribuer une valeur basée sur les propriétés associées dans le volet de propriétés et les valeurs par défaut.

Utilisation de l’API sous-total

Le fichier capabilities.json du visuel doit :

  • spécifier la propriété avec laquelle chacun des commutateurs ci-dessus est mappé.
  • indiquer la valeur par défaut à utiliser si la propriété n’est pas définie.

Les commutateurs utilisent un format semblable à l’exemple suivant :

    "rowSubtotals": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "rowSubtotals" 
                }, 
                "defaultValue": true 
            },

Le code précédent indique que les sous-totaux de ligne sont activés par la propriété rowSubtotals dans l’objet subTotals. La propriété a la valeur par défaut true.

L’API est automatiquement activée pour un visuel chaque fois que la structure de sous-totaux et tous les mappages de commutateurs sont définis dans le fichier capabilities.json.

Le code suivant est un exemple de configuration d’API complète dans le fichier capabilities.json (copié à partir de l’exemple de visuel d’API) :

"subtotals": { 
        "matrix": { 
            "rowSubtotals": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "rowSubtotals" 
                }, 
                "defaultValue": true 
            }, 
            "rowSubtotalsPerLevel": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "perRowLevel" 
                }, 
                "defaultValue": false 
            }, 
            "columnSubtotals": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "columnSubtotals" 
                }, 
                "defaultValue": true 
            }, 
            "columnSubtotalsPerLevel": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "perColumnLevel" 
                }, 
                "defaultValue": false 
            }, 
            "levelSubtotalEnabled": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "levelSubtotalEnabled" 
                }, 
                "defaultValue": true 
            },
            "rowSubtotalsType": {
                "propertyIdentifier": {
                    "objectName": "subtotals",
                    "propertyName": "rowSubtotalsType"
                },
                "defaultValue": "Bottom"
            }
        } 
    }

Il est important que la fonction enumerateProperties() du visuel soit alignée sur les valeurs par défaut spécifiées dans le fichier capabilities.json. La logique de personnalisation opère en fonction des valeurs par défaut spécifiées. Si la fonction enumerateProperties() et les valeurs par défaut ne sont pas alignées, les personnalisations de sous-total réelles peuvent différer des attentes des utilisateurs.

enum RowSubtotalType {
        Top = "Top",
        Bottom = "Bottom",
   }

Pour passer en revue les personnalisations disponibles, développez le menu déroulant Sous-totaux dans le volet de propriétés Format. Modifiez les paramètres des sous-totaux et suivez les modifications apportées à la présentation des sous-totaux (nommées Totaux) dans le volet Visualisations.

Screenshot of the Power BI Visualizations pane, which shows the Column and Row subtotals field wells.

Considérations et limitations

  • La propriété rowSubtotalsType n’est disponible que pour les lignes. Vous ne pouvez pas définir les sous-totaux de colonne sur le début d’une colonne.

  • La fonctionnalité Développer et réduire remplace rowSubtotals. Les sous-totaux s’affichent lorsque les lignes sont développées, même si rowSubtotals est défini sur false.

Contenu connexe

Ajouter de l’interactivité à un visuel en utilisant des sélections de visuels Power BI