Contrôler les segments de rapport
À l’aide des API de segment, vous pouvez obtenir et définir l’état d’un segment Power BI. En outre, vous pouvez utiliser la configuration de charge pour modifier l’état du segment lors du chargement d’un rapport.
Il existe deux types de visuels de segment :
Out-of-the-box : segments pour les visuels Power BI prêtes à l’emploi. Les segments prêtes à l’emploi prennent en charge tous les visuels Power BI fournis avec Power BI (Bureau et service).
Visuels Power BI à partir d’AppSource et de fichiers : segments pour les visuels Power BI tiers, disponibles à partir d’AppSource ou sous la forme d’un fichier .pbiviz . Les segments pour les visuels Power BI à partir d’AppSource et de fichiers, ou en bref des visuels à partir d’AppSource ou de fichiers, sont des segments pour les visuels Power BI créés par les développeurs.
Objet Slicer
Il existe quatre types de segments :
Segment catégoriel
Les segments catégoriels prennent en charge les affichages suivants :
- Une liste
- Menu déroulant
- Cartes de valeur
Vous pouvez sélectionner un ou plusieurs éléments dans ces listes pour filtrer le rapport en conséquence.
Pour modifier une sélection pour ces types de segments, vous devez créer un IBasicFilter objet . Pour plus d’informations sur la création d’un filtre de base, consultez Filtre de base.
const basicFilter = {
$schema: "http://powerbi.com/product/schema#basic",
target: {
table: "Store",
column: "Count"
},
operator: "In",
values: [1, 2, 3, 4],
filterType: models.FilterType.BasicFilter
};
await visual.setSlicerState({
filters: [basicFilter]
});
Si la cible du segment est une hiérarchie, fournissez une IFilterHierarchyTarget cible. Pour plus d’informations, consultez Utiliser des cibles pour sélectionner le champ de données sur lequel agir.
const basicFilter = {
$schema: "http://powerbi.com/product/schema#basic",
target: {
table: "Store",
hierarchy: "Country",
hierarchyLevel: "Code"
},
operator: "In",
values: [456, 943],
filterType: models.FilterType.BasicFilter
};
await visual.setSlicerState({
filters: [basicFilter]
});
Segment de plage
Les segments de plage prennent en charge des conditions telles que :
- Entre
- Avant
- Après
Pour modifier une sélection pour les segments de plage, créez un IAdvancedFilter objet . Pour plus d’informations, consultez Filtre avancé.
const advancedFilter = {
$schema: "http://powerbi.com/product/schema#advanced",
target: {
table: "Store",
column: "Number"
},
logicalOperator: "And",
conditions: [
{
operator: "GreaterThanOrEqual",
value: 30
},
{
operator: "LessThan",
value: 40
}
],
filterType: models.FilterType.AdvancedFilter
};
await visual.setSlicerState({
filters: [advancedFilter]
});
Segment de date relative
Les segments de dates relatives prennent en charge des conditions telles que :
- Semaine dernière
- Cinq dernières années
Pour modifier une sélection pour les segments de dates relatives, créez un IRelativeDateFilter objet . Pour plus d’informations, consultez Objets de filtre de date et d’heure relative.
const relativeDateFilter = {
$schema: "http://powerbi.com/product/schema#relativeDate",
target: {
table: "Sales",
column: "OrderDate"
},
operator: models.RelativeDateOperators.InLast,
timeUnitsCount: 30,
timeUnitType: models.RelativeDateFilterTimeUnit.Days,
includeToday: true,
filterType: models.FilterType.RelativeDate
};
await visual.setSlicerState({
filters: [relativeDateFilter]
});
Segment de temps relatif
Les segments de temps relatifs prennent en charge des conditions telles que :
- Cinq dernières minutes
- Cette heure
Pour modifier une sélection pour les segments de temps relatifs, créez un IRelativeTimeFilter objet . Pour plus d’informations, consultez Filtres de date et d’heure relatives.
const relativeTimeFilter = {
$schema: "http://powerbi.com/product/schema#relativeTime",
target: {
table: "Sales",
column: "OrderDate"
},
operator: models.RelativeDateOperators.InLast,
timeUnitsCount: 5,
timeUnitType: models.RelativeDateFilterTimeUnit.Minutes,
filterType: models.FilterType.RelativeTime
};
await visual.setSlicerState({
filters: [relativeTimeFilter]
});
Segment de hiérarchie
Les segments de hiérarchie vous permettent de filtrer à partir de plusieurs champs associés.
Le segment Hierarchy est pris en charge à partir du SDK version 2.21. Définissez les sélections dans le segment de hiérarchie avec l’API setSlicerState ou obtenez les sélections de hiérarchie actuelles avec l’API getSlicerState.
En savoir plus sur l’ajout de champs aux segments de hiérarchie.
Filtre de hiérarchie
Le IHierarchyFilter décrit la hiérarchie du segment. Utilisez les getSlicerState méthodes et setSlicerState avec ce filtre.
interface IHierarchyFilter extends IFilter {
target: (IFilterTarget | IFilterKeyTarget)[];
hierarchyData: IHierarchyFilterNode[];
}
hierarchyData- les éléments sélectionnés et non sélectionnés dans une arborescence de hiérarchie où chacunIHierarchyFilterNodereprésente une sélection de valeur unique.interface IHierarchyFilterNode { value?: PrimitiveValueType; keyValues?: PrimitiveValueType[]; children?: IHierarchyFilterNode[]; operator?: HierarchyFilterNodeOperators; }keyValuesOuvaluedoit être définichildren– Liste des enfants de nœud pertinents pour la sélection actuelleoperator: opérateur pour les objets uniques dans l’arborescence. L’opérateur peut être l’un des éléments suivants :
type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";Selected: la valeur est explicitement sélectionnée.NotSelected: la valeur n’est pas explicitement sélectionnée.Inherited: la sélection de la valeur est en fonction de la valeur parente dans la hiérarchie, ou par défaut s’il s’agit de la valeur racine.
operatorest facultatif. Si aucun opérateur n’est défini, la valeur par défaut estInherited.
Exemples de segments de hiérarchie
Les exemples suivants décrivent différents scénarios d’utilisation de l’API setSlicerState avec des segments de hiérarchie.
Sélectionnez des valeurs à différents niveaux. Par exemple, sélectionnez « Qtr 1 » et « Qtr 2 » en 2013 et « Qtr 1 » et « Qtr 2 » en 2014.
const filter = { "$schema": http://powerbi.com/product/schema#hierarchy, "target": [ { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Year" }, { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Quarter" } ], "filterType": 9, "hierarchyData": [ { "operator": "Inherited", "value": 2013, "children": [ { "operator": "Selected", "value": "Qtr 1" }, { "operator": "Selected", "value": "Qtr 2" } ] }, { "operator": "Inherited", "value": 2014, "children": [ { "operator": "Selected", "value": "Qtr 1" }, { "operator": "Selected", "value": "Qtr 2" } ] } ] }; await slicer.setSlicerState({ filters: [filter] });
Sélectionnez des valeurs à différents niveaux avec des exceptions. Par exemple, sélectionnez 2014 sans « Qtr 1 ».
const filter = { "$schema": http://powerbi.com/product/schema#hierarchy, "target": [ { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Year" }, { "table": "Dates", "hierarchy": "Date Hierarchy", "hierarchyLevel": "Quarter" } ], "filterType": 9, "hierarchyData": [ { "operator": "Selected", "value": 2014, "children": [ { "operator": "NotSelected", "value": "Qtr 1" } ] } ] }; await slicer.setSlicerState({ filters: [filter] });
Commencez par l’opérateur
NotSelectedpour sélectionner tout sauf certaines valeurs. Par exemple, sélectionnez tout sauf « Qtr 1 » de 2008 et 2009.const filter = { "$schema": http://powerbi.com/product/schema#hierarchy, "target": [ { "table": "Dates", "column": "Year" }, { "table": "Dates", "column": "Quarter" } ], "filterType": 9, "hierarchyData": [ { "operator": "NotSelected", "value": 2009 }, { "operator": "Inherited", "value": 2008, "children": [ { "operator": "NotSelected", "value": "Q1" } ] } ] } await slicer.setSlicerState({ filters: [filter] });
API de segment
Vous pouvez utiliser les méthodes suivantes pour les visuels de slicer type :
- Obtenir l’état du segment -
getSlicerState - Définir l’état du segment -
setSlicerState
Notes
La configuration des segments de synchronisation enregistrée dans un rapport est reconnue par les API de segment. Cela signifie que si vous définissez un segment à l’aide de l’API, tous les segments du même groupe de synchronisation seront affectés.
Obtenir l’état du segment
Pour obtenir un état de segment, vous devez rechercher l’instance visuelle du segment et appeler getSlicerState. Le résultat est de type ISlicerState.
Par défaut, aucun filtre n’est appliqué au segment. Dans ce cas, getSlicerState retourne ISlicerState avec un tableau vide de filtres.
getSlicerState fonctionne à la fois pour les visuels prêtes à l’emploi et à partir d’AppSource ou de segments de fichiers.
let state = await visual.getSlicerState();
Définir l’état du segment
Pour définir un état de segment, vous devez rechercher l’instance visuelle du segment , créer l’état du segment et appeler setSlicerState avec l’état du segment que vous avez créé.
await visual.setSlicerState(state);
L’état du segment est un ISlicerState objet .
interface ISlicerState {
filters: ISlicerFilter[];
targets?: SlicerTarget[];
}
Pour réinitialiser un segment, appelez setSlicerState avec un tableau vide de filtres.
Définition d’un segment pour des visuels à partir d’AppSource ou de fichiers
Pour définir des visuels à partir d’AppSource ou d’une sélection de segment de fichiers, vous devez créer un ISlicerFilter objet, qui peut être des types suivants :
IBasicFilterIAdvancedFilterIRelativeDateFilterIRelativeTimeFilter
Différents visuels d’AppSource ou des segments de fichiers prennent en charge différents types de filtres. Pour déterminer le type de filtre requis pour modifier le segment, appelez visual.getSlicerState().
Pour plus d’informations sur les types de filtres, consultez Contrôler les filtres de rapport.
Définition des segments sur le chargement du rapport
La configuration de la charge de rapport prend en charge la modification de l’état des segments. Cela vous permet de modifier l’état des segments de rapport pendant le chargement du rapport. Pour ce faire, transmettez un ISlicer tableau.
interface IReportLoadConfiguration {
...
slicers?: ISlicer[];
}
Chaque ISlicer objet contient un sélecteur et un état de segment.
interface ISlicer {
selector: SlicerSelector;
state: ISlicerState;
}
Utilisez un nom visuel ou un sélecteur cible de segment pour sélectionner le segment à modifier. Pour plus d’informations, consultez Utiliser des sélecteurs pour contrôler les visuels qui sont appliqués.
Notes
Si vous passez différents ISlicer objets qui se trouvent dans le même groupe de synchronisation, le résultat sera inattendu.
Appliquer un segment à des exemples de chargement
Cette section comprend deux exemples de configuration de charge avec des segments.
Définir un segment spécifique par nom
let slicers = [ { selector: { $schema: "http://powerbi.com/product/schema#visualSelector", visualName: "d1feb8891635af3b335a" }, state: { filters: [advancedFilter] } } ]; let embedConfig = { ... slicers: slicers, };Définir des segments par cible de segment
let target = { table: "Store", column: "StoreNumber" }; let slicers = [ { selector: { $schema: "http://powerbi.com/product/schema#slicerTargetSelector", target: target }, state: { filters: [advancedFilter] } } ]; let embedConfig = { ... slicers: slicers, };
Considérations et limitations
Les segments Tuple ne sont pas pris en charge.
Le segment Hierarchy est pris en charge à partir du SDK version 2.21.
Les segments prêtes à l’emploi ne prennent en charge qu’un seul filtre.
L’appel
setSlicerStatesur un visuel qui n’est pas un segment renvoie une promesse rejetée avec l’erreur Opération fonctionne uniquement sur les segments.Il n’existe aucune API pour modifier la configuration de synchronisation des segments.