Rozhranie API filtrov vo vizuáloch služby Power BI

Článok
06/06/2024

Rozhranie API filtrov vizuálov umožňuje filtrovať údaje vo vizuáloch služby Power BI. Hlavným rozdielom medzi rozhraním API filtra a inými spôsobmi výberu údajov je spôsob, akým ovplyvní iné vizuály v zostave. Po použití filtra na vizuál budú vo všetkých vizuáloch viditeľné iba filtrované údaje, a to napriek podpore zvýraznenia inými vizuálmi.

Ak chcete povoliť filtrovanie vizuálu, súbor capabilities.json by mal v sekcii general obsahovať filter objekt.

"objects": {
        "general": {
            "displayName": "General",
            "displayNameKey": "formattingGeneral",
            "properties": {
                "filter": {
                    "type": {
                        "filter": true
                    }
                }
            }
        }
    }

Poznámka

Rozhrania API filtrov vizuálov sú k dispozícii v balíku powerbi-models . Tento balík obsahuje tiež triedy na vytvorenie inštancií filtra.
```
npm install powerbi-models --save
```
Ak používate staršiu verziu nástrojov (staršiu než 3.x.x), zahrňte do powerbi-models balíka vizuálov. Ďalšie informácie nájdete v stručnom návode Pridanie rozhrania API rozšíreného filtra do vlastného vizuálu. Ak chcete zistiť, ktorú verziu používate, pozrite si apiVersion súbor pbiviz.json .

Všetky filtre používajú IFilter rozhranie, ako je to znázornené v nasledujúcom kóde:

export interface IFilter {
        $schema: string;
        target: IFilterTarget;
}

Kde target sa v zdroji údajov nachádza stĺpec tabuľky.

Existujú tri rozhrania API filtrov:

Rozhranie API základného filtra
Rozhranie API rozšíreného filtra
Rozhranie API n-tíc filtrov (s viacerými stĺpcami)

Rozhranie API základného filtra

Rozhranie základného filtra je zobrazené v nasledujúcom kóde:

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

Kde:

operator je enumerácia s hodnotami In, NotIn a All.
values sú hodnoty pre podmienku.

Príklad základného filtra

V nasledujúcom príklade sa vrátia všetky riadky, v ktorých col1 sa rovná hodnote 1, 2 alebo 3.

let basicFilter = {
    target: {
        column: "Col1"
    },
    operator: "In",
    values: [1,2,3]
}

Ekvivalentom jazyka SQL vyššie uvedeného príkladu je:

SELECT * FROM table WHERE col1 IN ( 1 , 2 , 3 )

Ak chcete vytvoriť filter, môžete použiť triedu BasicFilter v powerbi-models.

Ak používate staršiu verziu nástroja, mali by ste v objekte okna použiť inštanciu modelov pomocou window['powerbi-models'], ako je to znázornené v nasledujúcom kóde:

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')),
    column: categories.source.displayName
};

let values = [ 1, 2, 3 ];

let filter: IBasicFilter = new window['powerbi-models'].BasicFilter(target, "In", values);

Vizuál vyvolá filter zavolaním metódy v applyJsonFilter() hostiteľskom rozhraní , IVisualHostktorá sa poskytne vizuálu v metóde konštruktora.

IVisualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

Rozhranie API rozšíreného filtra

Rozhranie API rozšíreného filtra umožňuje komplexný výber údajových bodov naprieč vizuálmi a filtrovanie dotazov na základe viacerých kritérií, ako sú napr. LessThan, Contains, Is, IsBlank atď.).

Tento filter bol predstavený vo verzii 1.7.0 rozhrania API vizuálov.

Na rozdiel od základného rozhrania API v rozhraní API rozšíreného filtra:

Vyžaduje target názov table a column aj (základné rozhranie API práve malo column).
Operátory sú And a Or (na rozdiel od In).
Filter namiesto hodnôt s rozhraním používa podmienky (menšie ako, väčšie ako atď.):

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

Operátory podmienok pre operator parameter sú: None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, IsNot, IsBlank a "IsNotBlank"'

let categories: DataViewCategoricalColumn = this.dataView.categorical.categories[0];

let target: IFilterColumnTarget = {
    table: categories.source.queryName.substr(0, categories.source.queryName.indexOf('.')), // table
    column: categories.source.displayName // col1
};

let conditions: IAdvancedFilterCondition[] = [];

conditions.push({
    operator: "LessThan",
    value: 0
});

let filter: IAdvancedFilter = new window['powerbi-models'].AdvancedFilter(target, "And", conditions);

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

Ekvivalentom jazyka SQL je:

SELECT * FROM table WHERE col1 < 0;

Ak chcete úplný vzorový kód na použitie rozhrania API rozšíreného filtra, prejdite do odkladacieho priestoru vizuálov Sampleslicer.

Rozhranie API n-tíc filtrov (filtrovanie viacerých stĺpcov)

Rozhranie API n-tíc filtrov bolo predstavené v rozhraní API vizuálov, vo verzii 2.3.0. Je podobný rozhraniu API základného filtra, ale umožňuje vám definovať podmienky pre viacero stĺpcov a tabuliek.

Rozhranie filtra je zobrazené v nasledujúcom kóde:

interface ITupleFilter extends IFilter {
    $schema: string;
    filterType: FilterType;
    operator: TupleFilterOperators;
    target: ITupleFilterTarget;
    values: TupleValueType[];
}

Kde

target je pole stĺpcov s názvami tabuliek:
```
declare type ITupleFilterTarget = IFilterTarget[];
```
Filter môže riešiť stĺpce z rôznych tabuliek.
$schema hodnota je https://powerbi.com/product/schema#tuple.
filterType je FilterType.Tuple.
operator umožňuje použitie iba v operátore In .
values je pole n-tíc hodnôt. Každá n-tka predstavuje jednu povolenú kombináciu hodnôt cieľového stĺpca.

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

Úplný príklad:

let target: ITupleFilterTarget = [
    {
        table: "DataTable",
        column: "Team"
    },
    {
        table: "DataTable",
        column: "Value"
    }
];

let values = [
    [
        // the first column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team1" // the value for the `Team` column of the `DataTable` table
        },
        {
            value: 5 // the value for the `Value` column of the `DataTable` table
        }
    ],
    [
        // the second column combination value (or the column tuple/vector value) that the filter will pass through
        {
            value: "Team2" // the value for `Team` column of `DataTable` table
        },
        {
            value: 6 // the value for `Value` column of `DataTable` table
        }
    ]
];

let filter: ITupleFilter = {
    $schema: "https://powerbi.com/product/schema#tuple",
    filterType: FilterType.Tuple,
    operator: "In",
    target: target,
    values: values
}

// invoke the filter
visualHost.applyJsonFilter(filter, "general", "filter", FilterAction.merge);

Dôležité

Dôležité je poradie názvov stĺpcov a hodnôt podmienok.

Ekvivalentom SQL vyššie uvedeného kódu je:

SELECT * FROM DataTable WHERE ( Team = "Team1" AND Value = 5 ) OR ( Team = "Team2" AND Value = 6 );

Obnovenie filtra JSON v zobrazení údajov

Od rozhrania API verzie 2.2.0 môžete obnoviť filter JSON z VisualUpdateOptions, ako je to znázornené v nasledujúcom kóde:

export interface VisualUpdateOptions extends extensibility.VisualUpdateOptions {
    viewport: IViewport;
    dataViews: DataView[];
    type: VisualUpdateType;
    viewMode?: ViewMode;
    editMode?: EditMode;
    operationKind?: VisualDataChangeOperationKind;
    jsonFilters?: IFilter[];
}

Keď prepnete záložky, služba Power BI zavolá update metódu vizuálu a vizuál získa zodpovedajúci filter objekt. Ďalšie informácie nájdete v téme Pridanie podpory záložiek pre vizuály služby Power BI.

Vzorový filter JSON

Niektoré kódy vzorového filtra JSON sú zobrazené na nasledujúcom obrázku:

Screenshot of sample JSON filter code showing values in an array.

Vymazanie filtra JSON

Ak chcete filter obnoviť alebo vymazať, odovzdajte null hodnotu do rozhrania API filtra.

// invoke the filter
visualHost.applyJsonFilter(null, "general", "filter", FilterAction.merge);

Pridanie interaktivity do vizuálu pomocou výberov vizuálov služby Power BI

Zdieľať cez

Rozhranie API filtrov vo vizuáloch služby Power BI

Rozhranie API základného filtra

Príklad základného filtra

Rozhranie API rozšíreného filtra

Rozhranie API n-tíc filtrov (filtrovanie viacerých stĺpcov)

Obnovenie filtra JSON v zobrazení údajov

Vzorový filter JSON

Vymazanie filtra JSON

Pripomienky

Ďalšie zdroje informácií

Zdieľať cez

Rozhranie API filtrov vo vizuáloch služby Power BI

Rozhranie API základného filtra

Príklad základného filtra

Rozhranie API rozšíreného filtra

Rozhranie API n-tíc filtrov (filtrovanie viacerých stĺpcov)

Obnovenie filtra JSON v zobrazení údajov

Vzorový filter JSON

Vymazanie filtra JSON

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií