Controlar segmentações de relatórios
Usando as APIs de segmentação de dados, você pode obter e definir o estado de uma segmentação do Power BI. Além disso, você pode usar a configuração de carga para alterar o estado da segmentação ao carregar um relatório.
Há dois tipos de visuais de segmentação de dados:
Pronto para uso – Segmentações de dados para visuais prontos para uso do Power BI. Segmentações prontas para uso dão suporte a todos os visuais do Power BI que são enviados com o Power BI (Desktop e serviço).
Visuais do Power BI do AppSource e arquivos – Segmentações de dados para visuais de terceiros do Power BI, disponíveis no AppSource ou como um arquivo .pbiviz . Segmentações para visuais do Power BI do AppSource e arquivos, ou em visuais curtos do AppSource ou arquivos, são segmentações de dados para visuais do Power BI criados por desenvolvedores.
Objeto Slicer
Há quatro tipos de segmentação de dados:
- Segmentações categóricas
- Segmentações de intervalo
- Segmentações de data relativa
- Segmentações de hierarquia
Segmentação categórica
Segmentações categóricas dão suporte às seguintes exibições:
- Uma lista
- Um menu suspenso
- Cartões de valor
Você pode selecionar um ou vários itens dessas listas para filtrar o relatório adequadamente.
Para alterar uma seleção para esse tipo de segmentação de dados, você precisa criar um IBasicFilter objeto . Para obter mais informações sobre como criar um filtro básico, consulte Filtro básico.
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]
});
Se o destino da segmentação for uma hierarquia, forneça um IFilterHierarchyTarget destino. Para obter mais informações, consulte Usar destinos para selecionar em qual campo de dados 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]
});
Segmentação de intervalo
As segmentações de intervalo dão suporte a condições como:
- Entre
- Antes
- After (após)
Para alterar uma seleção para segmentações de intervalo, crie um IAdvancedFilter objeto . Para obter mais informações, consulte Filtro avançado.
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]
});
Segmentação de data relativa
Segmentações de data relativas dão suporte a condições como:
- Última Semana
- Últimos cinco anos
Para alterar uma seleção para segmentações de data relativas, crie um IRelativeDateFilter objeto . Para obter mais informações, consulte Objetos de filtro de data e hora relativa relativos.
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]
});
Segmentação de dados de tempo relativo
Segmentações de tempo relativas dão suporte a condições como:
- Últimos cinco minutos
- Esta hora
Para alterar uma seleção para segmentações de tempo relativas, crie um IRelativeTimeFilter objeto . Para obter mais informações, consulte Filtros de data e hora relativa relativos.
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]
});
Segmentação de hierarquia
As segmentações de hierarquia permitem filtrar de vários campos relacionados.
A segmentação de hierarquia tem suporte do SDK versão 2.21. Defina seleções na segmentação de hierarquia com a API setSlicerState ou obtenha as seleções de hierarquia atuais com a API getSlicerState.
Leia sobre como adicionar campos a segmentações de hierarquia.
Filtro de hierarquia
O IHierarchyFilter descreve a hierarquia de segmentação de dados. Use os getSlicerState métodos e setSlicerState com esse filtro.
interface IHierarchyFilter extends IFilter {
target: (IFilterTarget | IFilterKeyTarget)[];
hierarchyData: IHierarchyFilterNode[];
}
hierarchyData– os itens selecionados e não selecionados em uma árvore de hierarquia em que cadaIHierarchyFilterNodeum representa uma seleção de valor único.interface IHierarchyFilterNode { value?: PrimitiveValueType; keyValues?: PrimitiveValueType[]; children?: IHierarchyFilterNode[]; operator?: HierarchyFilterNodeOperators; }- Ou
valuekeyValuesdeve ser definido children– Lista dos filhos do nó relevantes para a seleção atualoperator– O operador para objetos únicos na árvore. O operador pode ser um dos seguintes:
type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";Selected– o valor é selecionado explicitamente.NotSelected– o valor não está explicitamente selecionado.Inherited– a seleção de valor é de acordo com o valor pai na hierarquia ou o padrão se for o valor raiz.
operatoré opcional. Se nenhum operador for definido, o padrão seráInherited.- Ou
Exemplos de segmentação de hierarquia
Os exemplos a seguir descrevem cenários diferentes para usar a setSlicerState API com segmentações de hierarquia.
Selecione valores em diferentes níveis. Por exemplo, selecione 'Qtr 1' e 'Qtr 2' em 2013 e 'Qtr 1' e 'Qtr 2' em 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] });
Selecione valores em diferentes níveis com exceções. Por exemplo, selecione 2014 sem '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] });
Comece com o
NotSelectedoperador para selecionar tudo , exceto determinados valores. Por exemplo, selecione tudo, exceto "Qtr 1" de 2008 e 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] });
APIs de segmentação de dados
Você pode usar os seguintes métodos para visuais com o slicer tipo :
- Obter o estado da segmentação -
getSlicerState - Definir o estado da segmentação -
setSlicerState
Observação
A configuração de segmentações de dados de sincronização salva em um relatório é reconhecida pelas APIs de segmentação de dados. Isso significa que, se você definir uma segmentação usando a API, todas as segmentações no mesmo grupo de sincronização serão afetadas.
Obter o estado da segmentação
Para obter um estado de segmentação de dados, você precisa encontrar a instância visual da segmentação e chamar getSlicerState. O resultado é do tipo ISlicerState.
Por padrão, a segmentação de dados não terá filtros aplicados a ela. Nesses casos, getSlicerState retornará ISlicerState com uma matriz vazia de filtros.
getSlicerState funciona tanto para visuais prontos quanto para visuais do AppSource ou segmentações de arquivos.
let state = await visual.getSlicerState();
Definir o estado da segmentação
Para definir um estado de segmentação de dados, você precisa encontrar a instância visual da segmentação , criar o estado da segmentação de dados e chamar setSlicerState com o estado da segmentação que você criou.
await visual.setSlicerState(state);
O estado da segmentação de dados é um ISlicerState objeto .
interface ISlicerState {
filters: ISlicerFilter[];
targets?: SlicerTarget[];
}
Para redefinir uma segmentação de dados, chame setSlicerState com uma matriz vazia de filtros.
Configurando uma segmentação de dados para visuais do AppSource ou arquivos
Para definir um visual do AppSource ou da seleção de segmentação de arquivos, você precisa criar um ISlicerFilter objeto, que pode ser dos seguintes tipos:
IBasicFilterIAdvancedFilterIRelativeDateFilterIRelativeTimeFilter
Diferentes visuais do AppSource ou segmentações de arquivos dão suporte a diferentes tipos de filtros. Para determinar o tipo de filtro necessário para modificar a segmentação, chame visual.getSlicerState().
Para obter mais informações sobre tipos de filtro, consulte Controlar filtros de relatório.
Configurando segmentações na carga do relatório
A configuração de carga de relatório dá suporte à alteração do estado das segmentações de dados. Isso permite que você altere o estado das segmentações de relatório durante a carga do relatório. Para fazer isso, passe uma ISlicer matriz.
interface IReportLoadConfiguration {
...
slicers?: ISlicer[];
}
Cada ISlicer objeto contém um seletor e um estado de segmentação de dados.
interface ISlicer {
selector: SlicerSelector;
state: ISlicerState;
}
Use um nome visual ou seletor de destino de segmentação para selecionar qual segmentação alterar. Para obter mais informações, consulte Usar seletores para controlar quais visuais são afetados.
Observação
Se você passar objetos diferentes ISlicer que estão no mesmo grupo de sincronização, o resultado será inesperado.
Aplicar segmentação em exemplos de carga
Esta seção inclui dois exemplos de configuração de carga com segmentações de dados.
Definir uma segmentação de dados específica por nome
let slicers = [ { selector: { $schema: "http://powerbi.com/product/schema#visualSelector", visualName: "d1feb8891635af3b335a" }, state: { filters: [advancedFilter] } } ]; let embedConfig = { ... slicers: slicers, };Definir segmentações por destino de segmentação
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, };
Considerações e limitações
Não há suporte para segmentações de tupla.
A segmentação de hierarquia tem suporte do SDK versão 2.21.
As segmentações prontas para uso dão suporte apenas a um único filtro.
Chamar
setSlicerStateem um visual que não é uma segmentação de dados retornará uma promessa rejeitada com o erro Operação funciona apenas em segmentações de dados.Não há nenhuma API para alterar a configuração de sincronização de segmentações de dados.