แชร์ผ่าน

API ตัวกรองวิชวลในวิชวล Power BI

  • บทความ

API ตัวกรองวิชวลช่วยให้คุณสามารถกรองข้อมูลในวิชวล Power BI ได้ ความแตกต่างหลักระหว่าง API ตัวกรองและวิธีอื่น ๆ ในการเลือกข้อมูลคือวิธีการที่จะส่งผลต่อวิชวลอื่น ๆ ในรายงาน เมื่อมีการใช้ตัวกรองกับวิชวล เฉพาะข้อมูลที่ถูกกรองเท่านั้นที่สามารถมองเห็นได้ในวิชวลทั้งหมด แม้จะมีการไฮไลต์การสนับสนุนโดยวิชวลอื่น ๆ

เมื่อต้องการเปิดใช้งานการกรองสําหรับวิชวล ไฟล์ capabilities.json ควรประกอบด้วยfilterวัตถุในส่วนgeneral

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

หมายเหตุ

  • อินเทอร์เฟส API ตัวกรองวิชวลพร้อมใช้งานใน แพคเกจแบบจําลอง powerbi แพคเกจนี้ยังประกอบด้วยคลาสในการสร้างอินสแตนซ์ตัวกรอง

    npm install powerbi-models --save

  • ถ้าคุณกําลังใช้เครื่องมือเวอร์ชันเก่ากว่า (เวอร์ชันก่อนหน้า 3.x.x) ให้รวมอยู่ใน powerbi-models แพคเกจวิชวล สําหรับข้อมูลเพิ่มเติม โปรดดูคําแนะนําสั้น ๆ เพิ่ม API ตัวกรองขั้นสูงไปยังวิชวลแบบกําหนดเอง เมื่อต้องการตรวจสอบเวอร์ชันที่คุณกําลังใช้ ให้ตรวจสอบ apiVersion ในไฟล์ pbiviz.json

ตัวกรองทั้งหมดใช้ IFilter อินเทอร์เฟซ ดังที่แสดงในโค้ดต่อไปนี้:

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

ที่ใด target คือคอลัมน์ตารางในแหล่งข้อมูล

มีตัวกรอง API สามตัว:

API ตัวกรองพื้นฐาน

อินเตอร์เฟซตัวกรองพื้นฐานแสดงในโค้ดต่อไปนี้:

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

ที่ใด:

  • operatorเป็นการแจงนับที่มีค่า In, NotIn และ All
  • values เป็นค่าสําหรับเงื่อนไข

ตัวอย่างของตัวกรองพื้นฐาน

ตัวอย่างต่อไปนี้จะแสดงแถว col1 ทั้งหมดที่เท่ากับค่า 1, 2 หรือ 3

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

SQL ที่เทียบเท่ากับตัวอย่างข้างต้นคือ:

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

เมื่อต้องการสร้างตัวกรอง คุณสามารถใช้คลาส BasicFilter ในpowerbi-models

ถ้าคุณกําลังใช้เครื่องมือเวอร์ชันเก่ากว่า คุณควรมีอินสแตนซ์ของแบบจําลองในวัตถุหน้าต่างโดยใช้ window['powerbi-models']ดังที่แสดงในโค้ดต่อไปนี้:

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);

วิชวลจะเรียกใช้ตัวกรองโดยเรียกใช้ applyJsonFilter() เมธอด บนอินเทอร์เฟซ IVisualHostโฮสต์ ซึ่งกําหนดให้กับวิชวลในเมธอดคอนสตรักเตอร์

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

API ตัวกรองขั้นสูง

API ตัวกรองขั้นสูงเปิดใช้งานการเลือกจุดข้อมูลและคิวรีการกรองแบบไขว้วิชวลที่ซับซ้อนโดยยึดตามเกณฑ์หลายอย่าง เช่น LessThan, Contains, Is, IsBlank และอื่น ๆ)

ตัวกรองนี้ถูกนํามาใช้ใน Visuals API เวอร์ชัน 1.7.0

ซึ่งตรงกันข้ามกับ API พื้นฐาน ใน API ตัวกรองขั้นสูง:

  • targetต้องใช้ทั้ง table ชื่อ และ column (API พื้นฐานเพิ่งมี column)
  • ตัวดําเนินการ คือ And และ Or (ตรงกันข้ามกับ In)
  • ตัวกรองใช้เงื่อนไข (น้อยกว่า มากกว่า และอื่น ๆ) แทนที่จะเป็นค่าที่มีอินเทอร์เฟซ:
interface IAdvancedFilterCondition {
    value: (string | number | boolean);
    operator: AdvancedFilterConditionOperators;
}

ตัวดําเนินการเงื่อนไขสําหรับ operator พารามิเตอร์คือ: None, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Contains, DoesNotContain, StartsWith, DoesNotStartWith, Is, IsNot, IsBlank และ "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);

SQL ที่เทียบเท่าคือ:

SELECT * FROM table WHERE col1 < 0;

สําหรับโค้ดตัวอย่างฉบับสมบูรณ์สําหรับการใช้ API ตัวกรองขั้นสูง ให้ ไปที่ พื้นที่เก็บข้อมูลวิชวล Sampleslicer

API ตัวกรองทูเพิล (ตัวกรองหลายคอลัมน์)

API ตัวกรองทูเพิลถูกนํามาใช้ใน Visuals API 2.3.0 ซึ่งคล้ายกับ API ตัวกรองพื้นฐาน แต่จะช่วยให้คุณสามารถกําหนดเงื่อนไขสําหรับหลายคอลัมน์และตารางได้

อินเทอร์เฟซตัวกรองจะแสดงในโค้ดต่อไปนี้:

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

โดย

  • target เป็นอาร์เรย์ของคอลัมน์ที่มีชื่อตาราง:

    declare type ITupleFilterTarget = IFilterTarget[];

    ตัวกรองสามารถระบุที่อยู่ของคอลัมน์จากตารางต่างๆ

  • $schemaคือhttps://powerbi.com/product/schema#tuple

  • filterTypeคือ FilterType.Tuple

  • operator อนุญาตให้ใช้ได้เฉพาะในตัว ดําเนินการ In เท่านั้น

  • values เป็นอาร์เรย์ของทูเพิลค่า ทูเพิลแต่ละชุดแสดงชุดข้อมูลที่อนุญาตหนึ่งชุดของค่าคอลัมน์เป้าหมาย

declare type TupleValueType = ITupleElementValue[];

interface ITupleElementValue {
    value: PrimitiveValueType
}

ตัวอย่างที่สมบูรณ์:

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);

สำคัญ

ลําดับของชื่อคอลัมน์และค่าเงื่อนไขมีความสําคัญ

SQL ที่เทียบเท่ากับโค้ดข้างต้นคือ:

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

คืนค่าตัวกรอง JSON จากมุมมองข้อมูล

เริ่มต้นด้วย API เวอร์ชัน 2.2.0 คุณสามารถกู้คืนตัวกรอง JSON จาก VisualUpdateOptions ดังที่แสดงในโค้ดต่อไปนี้:

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

เมื่อคุณสลับบุ๊กมาร์ก Power BI จะupdateเรียกใช้เมธอด ของวิชวลและวิชวลได้รับวัตถุที่สอดคล้องกันfilter สําหรับข้อมูลเพิ่มเติม โปรดดู เพิ่มการสนับสนุนบุ๊กมาร์กสําหรับวิชวล Power BI

ตัวกรอง JSON ตัวอย่าง

โค้ดตัวกรอง JSON ตัวอย่างบางตัวจะแสดงในรูปต่อไปนี้:

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

ล้างตัวกรอง JSON

หากต้องการรีเซ็ตหรือล้างตัวกรอง ให้ส่งผ่าน null ค่าไปยังตัวกรอง API

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

เนื้อหาที่เกี่ยวข้อง

ใช้การเลือกวิชวล Power BI เพื่อเพิ่มการโต้ตอบไปยังวิชวล