Contrôler les filtres de rapport

Article
07/09/2024

Lorsque vous incorporez un rapport Power BI, vous pouvez appliquer filtres automatiquement pendant la phase de chargement, ou vous pouvez modifier les filtres dynamiquement une fois le rapport chargé. Par exemple, vous pouvez créer votre propre volet de filtre personnalisé et appliquer automatiquement ces filtres aux rapports pour afficher les insights spécifiques à l’utilisateur. Vous pouvez également créer un bouton qui permet à l’utilisateur d’appliquer des filtres au rapport incorporé.

Les types de filtres suivants sont pris en charge :

de base - IBasicFilter
- IAdvancedFilter avancé
top N - ITopNFilter
date relative - IRelativeDateFilter
temps relatif - IRelativeTimeFilter

Attributs de l’objet de filtre

Tous les types de filtre héritent de l’interface IFilter. Les attributs répertoriés ci-dessous sont pertinents pour tous les types de filtres.

interface IFilter {
    $schema: string;
    target: IFilterGeneralTarget;
    filterType: FilterType;
    displaySettings?: IFilterDisplaySettings;
}

Schéma

L’attribut $schema définit le type de filtre. Il existe cinq schémas disponibles, un pour chaque type de filtre :

de base - https://powerbi.com/product/schema#basic
- https://powerbi.com/product/schema#advanced avancé
date relative - https://powerbi.com/product/schema#relativeDate
temps relatif - https://powerbi.com/product/schema#relativeTime
top N - https://powerbi.com/product/schema#topN

Paramètres d’affichage

L’attribut displaySettings définit la façon dont le filtre est affiché dans le volet filtres.

interface IFilterDisplaySettings {
    isLockedInViewMode?: boolean;
    isHiddenInViewMode?: boolean;
    displayName?: string;
}

isLockedInViewMode : un filtre verrouillé est appliqué et affiché dans le volet filtre. La valeur du filtre ne peut pas être modifiée en mode d’affichage . Définissez-la sur true pour verrouiller le filtre.
isHiddenInViewMode : un filtre masqué est appliqué au rapport, mais n’est pas affiché dans le volet filtre en mode vue. Définissez-la sur true pour masquer le filtre.
displayName - Un filtre peut être affiché dans le volet de filtre avec un nom personnalisé. Utilisez cet attribut pour définir un nom personnalisé pour votre filtre. Lorsque la valeur n’est pas définie ou null, le nom par défaut du filtre s’affiche (généralement le nom du champ de données filtrés).

Type de filtre

L’attribut filterType définit le type du filtre. Utilisez l’énumération suivante, définie dans la bibliothèque de modèles :

enum FilterType {
    Advanced = 0,
    Basic = 1,
    Unknown = 2,
    IncludeExclude = 3,
    RelativeDate = 4,
    TopN = 5,
    Tuple = 6,
    RelativeTime = 7,
}

Cible

L’attribut target définit la cible du filtre. Pour plus d’informations, consultez Utiliser des cibles pour sélectionner le champ de données à agir sur.

Attributs supplémentaires par type de filtre

Chaque type de filtre a sa propre interface avec un ensemble différent d’attributs. Les interfaces de filtre font partie de la bibliothèque powerbi-models.

Filtre de base

de filtre de base a un seul opérateur avec une ou plusieurs valeurs.

interface IBasicFilter extends IFilter {
    operator: BasicFilterOperators;
    values: (string | number | boolean)[];
    requireSingleSelection?: boolean;
}

operator : pour le filtre de base, l’opérateur peut être l’un des éléments suivants :
```
type BasicFilterOperators = "In" | "NotIn" | "All"
```
values : tableau de valeurs pour le filtre, toutes les valeurs doivent être du même type.
requireSingleSelection : définit s’il est possible de sélectionner plusieurs valeurs sur le filtre. S’il est défini sur true, une seule valeur peut être sélectionnée.

Par exemple:

const basicFilter = {
  $schema: "https://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1, 2, 3, 4],
  filterType: models.FilterType.BasicFilter,
  requireSingleSelection: true
}

Filtre avancé

de filtre avancé a un opérateur logique unique et une ou deux conditions qui ont leur propre opérateur et leur propre valeur.

interface IAdvancedFilter extends IFilter {
    logicalOperator: AdvancedFilterLogicalOperators;
    conditions: IAdvancedFilterCondition[];
}

logicalOperator : l’opérateur logique peut être l’un des éléments suivants :
```
type AdvancedFilterLogicalOperators = "And" | "Or";
```

conditions : tableau de conditions pour le filtre avancé, chaque condition a un operator et un value.

interface IAdvancedFilterCondition {
    value?: (string | number | boolean | Date);
    operator: AdvancedFilterConditionOperators;
}

Les opérateurs disponibles pour une condition sont les suivants :

type AdvancedFilterConditionOperators = "None" | "LessThan" | "LessThanOrEqual" | 
"GreaterThan" | "GreaterThanOrEqual" | "Contains" | "DoesNotContain" | "StartsWith" | 
"DoesNotStartWith" | "Is" | "IsNot" | "IsBlank" | "IsNotBlank";

Par exemple:

const advancedFilter = {
  $schema: "https://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Name"
  },
  logicalOperator: "Or",
  conditions: [
    {
      operator: "Contains",
      value: "Wash"
    },
    {
      operator: "Contains",
      value: "Park"
    }
  ],
  filterType: models.FilterType.AdvancedFilter
}

Note

Si vous créez un AdvancedFilter avec une seule condition, définissez la logicalOperator sur "And". L’opérateur logique est ignoré lors de l’analyse par Power BI, car il n’y a qu’une seule condition et lorsque le filtre est sérialisé, l’opérateur logique par défaut est "And". Cela garantit que les filtres retournés lors de l’appel de getFilters, correspondent à ceux définis à l’aide de setFilters.

Filtre N supérieur

filtre N supérieur a un seul opérateur, compteur d’éléments pour la quantité d’éléments à afficher et l’ordre par cible.

interface ITopNFilter extends IFilter {
    operator: TopNFilterOperators;
    itemCount: number;
    orderBy: ITarget;
}

operator - L’opérateur pour le filtre Top N peut être l’un des éléments suivants :
```
type TopNFilterOperators = "Top" | "Bottom";
```
itemCount : quantité d’éléments à afficher.
orderBy : champ de données cible à trier. Pour plus d’informations, consultez Utiliser des cibles pour sélectionner le champ de données à agir sur.

Par exemple:

const topNFilter = {
  $schema: "https://powerbi.com/product/schema#topN",
  target: {
    table: "Store",
    column: "name"
  },
  operator: "Top",
  itemCount: 5,
  orderBy: {
      table: "Product",
      measure: "Count of Product"
   },
  filterType: models.FilterType.TopN
};

Filtres de date et d’heure relatifs

Le filtre de date relative et le filtre de temps relatif héritent tous deux de l’interface IRelativeDateTimeFilter :

interface IRelativeDateTimeFilter extends IFilter {
    operator: RelativeDateOperators;
    timeUnitsCount: number;
    timeUnitType: RelativeDateFilterTimeUnit;
}

operator - L’opérateur pour les filtres de date et d’heure relatifs peut être l’un des éléments suivants :
```
enum RelativeDateOperators {
    InLast = 0,
    InThis = 1,
    InNext = 2,
}
```
timeUnitsCount : durée d’unités.

timeUnitType : définit l’unité de temps que le filtre utilise.

enum RelativeDateFilterTimeUnit {
    Days = 0,
    Weeks = 1,
    CalendarWeeks = 2,
    Months = 3,
    CalendarMonths = 4,
    Years = 5,
    CalendarYears = 6,
    Minutes = 7,
    Hours = 8
}

Le tableau suivant répertorie les heures d’unité prises en charge par les filtres de date et d’heure relatifs.

Unité de temps	Date relative	Heure relative
Jours	✔	✖
Semaines	✔	✖
CalendarWeeks	✔	✖
Mois	✔	✖
CalendarMonths	✔	✖
Années	✔	✖
CalendarYears	✔	✖
Compte-rendu	✖	✔
Heures	✖	✔

includeToday : accepte une valeur booléenne qui spécifie s’il faut inclure le jour actuel dans le filtre.
```
interface IRelativeDateFilter extends IRelativeDateTimeFilter {
includeToday: boolean;
}
```
Note

includeToday n’est pris en charge que par le filtre de date relative .

Exemple de filtre de date relative :

const relativeDateFilter = {
  $schema: "https://powerbi.com/product/schema#relativeDate",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 30,
  timeUnitType: RelativeDateFilterTimeUnit.Days,
  includeToday: true,
  filterType: models.FilterType.RelativeDate
};

Exemple de filtre de temps relatif :

const relativeTimeFilter = {
  $schema: "https://powerbi.com/product/schema#relativeTime",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 12,
  timeUnitType: models.RelativeDateFilterTimeUnit.Hours,
  filterType: models.FilterType.RelativeTime
};

API filtres

Utilisez les méthodes suivantes pour obtenir et mettre à jour les filtres appliqués à un rapport :

Obtenir des filtres - getFilters
Mettre à jour les filtres- updateFilters.

Obtenir des filtres

Utilisez getFilters pour obtenir tous les filtres pour l’un des objets suivants :

Rapport
Page
Visuel

getFilters(): Promise<IFilter[]>

Mettre à jour les filtres

Utilisez updateFilters pour ajouter, remplacer ou supprimer des filtres sur l’objet (rapport, page ou visuel). Reçoit une opération et un tableau de filtres facultatifs.

updateFilters(operation: models.FiltersOperations, filters?: models.IFilter[]): Promise<IHttpPostMessageResponse<void>>

Opération de filtres

Lorsque vous appelez updateFilters vous devez passer l’opération de filtre que vous souhaitez préformer. Les opérations disponibles sont les suivantes :

RemoveAll : supprime tous les filtres au niveau du filtre.
ReplaceAll : remplace tous les filtres existants au niveau du filtre par les filtres donnés.
Add : ajoute les filtres donnés au niveau du filtre (en plus des filtres existants).
Replace : remplace un filtre existant par un filtre donné uniquement si les deux filtres s’appliquent au même champ de données. S’il existe un filtre donné qui ne remplace pas un filtre existant, il est ajouté.

Note

Lors de l’appel de l’API avec RemoveAll, l’argument filtre doit être undefined. Pour toutes les autres opérations, elle doit être définie.

Niveaux de filtres

La mise à jour et l’obtention des filtres peuvent être effectuées à trois niveaux. Les filtres de différents niveaux sont indépendants et la mise à jour des filtres d’un niveau ne change pas une autre. Par exemple, la suppression d’un filtre de page ne la supprime pas d’autres pages du rapport.

Les niveaux pris en charge pour les filtres sont les suivants :

rapport : les filtres sont appliqués à toutes les pages du rapport.
Page : les filtres sont appliqués à la page de rapport active.
visual : les filtres sont appliqués à un visuel spécifique.

Note

Seuls les filtres de niveau visuel prennent en charge le type de filtre ITopNFilter.

Filtres au niveau du rapport

Pour obtenir ou mettre à jour les filtres qui s’appliquent à toutes les pages du rapport, appelez l’API appropriée sur l’objet de rapport. Par exemple:

Obtenir les filtres de rapport

Obtention des filtres appliqués à toutes les pages.

let reportFilters = await report.getFilters();

Ajouter de nouveaux filtres aux filtres de rapport

Ajout de nouveaux filtres, en même temps que les filtres existants, pour toutes les pages.

await report.updateFilters(models.FiltersOperations.Add, filtersArray);

Supprimer les filtres de rapport

Supprimez les filtres appliqués à toutes les pages.

await report.updateFilters(models.FiltersOperations.RemoveAll);

Filtres au niveau de la page

Pour obtenir ou mettre à jour les filtres au niveau de la page, procédez comme suit :

Obtenez l’objet page de la page cible. Pour plus d’informations, consultez Obtenir des pages et des visuels.
Dans l’objet page, appelez l’API appropriée.

Obtenir les filtres de page

Obtention des filtres appliqués à une page spécifique.

let reportFilters = await page.getFilters();

Remplacer tous les filtres de page

Remplacement de tous les filtres existants appliqués à une page spécifique, par un nouvel ensemble de filtres.

await page.updateFilters(models.FiltersOperations.ReplaceAll, filtersArray);

Supprimer les filtres de page

Suppression des filtres appliqués à une page spécifique.

await page.updateFilters(models.FiltersOperations.RemoveAll);

Filtres au niveau visuel

Pour obtenir ou mettre à jour des filtres au niveau visuel, procédez comme suit :

Obtenez l’objet visuel du visuel cible. Pour plus d’informations, consultez Obtenir des pages et des visuels.
Sur l’objet visuel, appelez l’API appropriée.

Obtenir les filtres visuels

Obtention des filtres appliqués à un visuel spécifique.

let reportFilters = await visual.getFilters();

Remplacer les filtres visuels par la même cible

Remplacement des filtres d’un visuel spécifique. Si un filtre existe avec le même champ de données cible qu’un filtre donné, il est remplacé par le filtre donné. Les filtres donnés qui ne correspondent à aucun filtre existant sont ajoutés.

await visual.updateFilters(models.FiltersOperations.Replace, filtersArray);

Supprimer les filtres visuels

Suppression des filtres appliqués à un visuel spécifique.

await visual.updateFilters(models.FiltersOperations.RemoveAll);

Considérations et limitations

Avoir plus de deux conditions lors de la génération d’un de filtre avancé peut entraîner un comportement non défini.
IncludeExclude et Tuple types de filtres ne sont pas pris en charge.
Les cibles de filtre tuple et de hiérarchie ne sont pas prises en charge.

Partager via

Contrôler les filtres de rapport

Attributs de l’objet de filtre

Schéma

Paramètres d’affichage

Type de filtre

Cible

Attributs supplémentaires par type de filtre

Filtre de base

Filtre avancé

Filtre N supérieur

Filtres de date et d’heure relatifs

API filtres

Obtenir des filtres

Mettre à jour les filtres

Opération de filtres

Niveaux de filtres

Filtres au niveau du rapport

Obtenir les filtres de rapport

Ajouter de nouveaux filtres aux filtres de rapport

Supprimer les filtres de rapport

Filtres au niveau de la page

Obtenir les filtres de page

Remplacer tous les filtres de page

Supprimer les filtres de page

Filtres au niveau visuel

Obtenir les filtres visuels

Remplacer les filtres visuels par la même cible

Supprimer les filtres visuels

Considérations et limitations

Ressources supplémentaires

Partager via

Contrôler les filtres de rapport

Attributs de l’objet de filtre

Schéma

Paramètres d’affichage

Type de filtre

Cible

Attributs supplémentaires par type de filtre

Filtre de base

Filtre avancé

Filtre N supérieur

Filtres de date et d’heure relatifs

API filtres

Obtenir des filtres

Mettre à jour les filtres

Opération de filtres

Niveaux de filtres

Filtres au niveau du rapport

Obtenir les filtres de rapport

Ajouter de nouveaux filtres aux filtres de rapport

Supprimer les filtres de rapport

Filtres au niveau de la page

Obtenir les filtres de page

Remplacer tous les filtres de page

Supprimer les filtres de page

Filtres au niveau visuel

Obtenir les filtres visuels

Remplacer les filtres visuels par la même cible

Supprimer les filtres visuels

Considérations et limitations

Contenu connexe

Ressources supplémentaires