Contrôler les filtres de rapport

Lorsque vous incorporez un rapport Power BI, vous pouvez appliquer automatiquement des filtres pendant la phase de chargement ou 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 de 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 :

• Base - IBasicFilter
• Avancé - IAdvancedFilter
• Top N - ITopNFilter
• Date relative - IRelativeDateFilter
• Temps relatif - IRelativeTimeFilter

Attributs d’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 :

• Base - http://powerbi.com/product/schema#basic
• Avancé - http://powerbi.com/product/schema#advanced
• Date relative - http://powerbi.com/product/schema#relativeDate
• Temps relatif - http://powerbi.com/product/schema#relativeTime
• Top N - http://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 de filtre. La valeur de filtre ne peut pas être modifiée en mode affichage. Définissez-la sur true pour verrouiller le filtre.

• isHiddenInViewMode - Un filtre masqué est appliqué au rapport, mais pas affiché dans le volet de filtre en mode affichage. 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é).

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 sur lequel agir.

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

Le 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 de 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, seule une seule valeur peut être sélectionnée.

Par exemple :

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,
  requireSingleSelection: true
}

Advanced filter

Le filtre avancé possède un seul opérateur logique et une ou deux conditions qui ont leur propre opérateur et leur 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: "http://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
}

Notes

Si vous créez une AdvancedFilter seule condition, définissez la logicalOperator valeur "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 getFilters, correspondent à ceux définis à l’aide setFiltersde .

Filtre N principaux

Le filtre N principal a un seul opérateur, compteur d’éléments pour la quantité d’éléments à afficher et 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 sur lequel agir.

Par exemple :

const topNFilter = {
  $schema: "http://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 relative

Le filtre de date relative et le filtre d’heure 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 des 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 unitaires prises en charge par les filtres de date et d’heure relatifs relatifs.

  Unité de temps	Date relative	Temps relatif
  Jours	✔	✖
  Semaines	✔	✖
  CalendarWeeks	✔	✖
  Mois	✔	✖
  CalendarMonths	✔	✖
  Années	✔	✖
  CalendarYears	✔	✖
  Minutes	✖	✔
  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;
  }
  

  Notes

  includeToday est uniquement pris en charge par le filtre de date relative.

Exemple de filtre de date relative :

const relativeDateFilter = {
  $schema: "http://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: "http://powerbi.com/product/schema#relativeTime",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 12,
  timeUnitType: models.RelativeDateFilterTimeUnit.Hours,
  filterType: models.FilterType.RelativeTime
};

Filtre les API

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

• Obtenir des filtres - getFilters
• Mettez à jour les filtres- updateFilters.

Obtenir des filtres

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

• Rapport
• Page
• Visuels

getFilters(): Promise<IFilter[]>

Mise à jour des filtres

Permet d’ajouter updateFilters , de remplacer ou de 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é.

Notes

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 les filtres de mise à jour sur un niveau ne changent pas d’autre. Par exemple, la suppression d’un filtre de page ne le 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.
• Visuel : les filtres sont appliqués à un visuel spécifique.

Notes

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

Filtres au niveau du rapport

Pour obtenir ou mettre à jour les filtres qui s’appliquent à toutes les pages du rapport, appelez l’API pertinente 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 plus des 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 des filtres au niveau de la page, procédez comme suit :

1. Obtenez l’objet de page de la page cible. Pour plus d’informations, consultez Obtenir des pages et des visuels.
2. Dans l’objet de 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, avec 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 du visuel

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

1. Obtenez l’objet visuel pour le visuel cible. Pour plus d’informations, consultez Obtenir des pages et des visuels.
2. 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);

Limites

• Avoir plus de deux conditions lors de la création d’un filtre avancé peut entraîner un comportement non défini.

• IncludeExclude et Tuple les types de filtre ne sont pas pris en charge.

• Les cibles de filtre tuple et de hiérarchie ne sont pas prises en charge.

Étapes suivantes

• Configurer les paramètres de rapport
• Contrôler les segments de rapport
• Personnaliser une disposition de rapport