Anfordern aggregierter Teilsummendaten

Mit der Gesamt- und Teilsummen-API können benutzerdefinierte Visuals mit einer Matrixdatenansicht aggregierte Teilsummendaten vom Power BI-Host anfordern. Die Teilergebnisse können sowohl für das gesamte Matrixsemantikmodell berechnet als auch für einzelne Ebenen der Matrixdatenhierarchie angegeben werden. Ein Beispiel für die Gesamt- und Teilergebnis-API in einem Power BI-Visual finden Sie im Beispielbericht.

Hinweis

Das Anfordern von Teilergebnisdaten wird in Version 2.6.0 und höher unterstützt. Die rowSubtotalType-Eigenschaft ist in Version 5.1.0 und höher verfügbar. Um herauszufinden, welche Version Sie verwenden, überprüfen Sie die apiVersion in der Datei pbiviz.json.

Jedes Mal, wenn die Daten eines Visuals aktualisiert werden, gibt das Visual eine Anforderungen zum Datenabruf an das Power BI-Back-End aus. Diese Anforderungen stehen in der Regel im Zusammenhang mit den Werten der Felder, die der Benutzer in die Feldbereiche des Visuals gezogen hat. Manchmal müssen allerdings andere Aggregationen oder Teilergebnisse (z. B. Summe, Anzahl) auf die Feldbereiche angewendet werden. Mit der Gesamt- und Teilergebnis-API können Sie die ausgehende Datenabfrage anpassen, um weitere Aggregations- oder Teilergebnisdaten anzufordern.

Die Teilsummen-API

Die API ermöglicht die folgenden Anpassungen für die einzelnen Datenansichtstypen (derzeit nur Matrixdatenansichten).

• rowSubtotals: (boolesch) Gibt an, ob die Teilergebnisdaten für alle Felder im Feldbereich der Zeile angefordert werden sollen.
• rowSubtotalsPerLevel: (boolesch) Gibt an, ob die Teilergebnisdaten für einzelne Felder im Feldbereich der Zeile umgeschaltet werden können.
• columnSubtotals: (boolesch) Gibt an, ob die Teilergebnisdaten für alle Felder im Feldbereich für Spalten angefordert werden sollen.
• columnSubtotalsPerLevel: (boolesch) Gibt an, ob die Teilergebnisdaten für einzelne Felder im Feldbereich für Spalten umgeschaltet werden können.
• levelSubtotalEnabled: (boolesch) Gibt an, ob die Teilergebnisse der Zeile oder Spalte angefordert werden. Im Gegensatz zu allen anderen Eigenschaften wird diese Eigenschaft auf einzelne Zeilen oder Spalten angewendet.
• rowSubtotalsType: („top“ oder „bottom“) Gibt an, ob die Zeile mit den Gesamtergebnisdaten vor (top) oder nach (bottom) den restlichen Daten abgerufen werden soll. Wenn diese Eigenschaft auf bottom festgelegt ist, kann das Gesamtergebnis erst angezeigt werden, nachdem alle Daten abgerufen wurden. Der Standardwert lautet bottom.

Jedem der oben aufgeführten Schalter wird ein Wert zugewiesen, der auf den zugehörigen Eigenschaften im Eigenschaftenbereich und auf den Standardwerten basiert.

Verwenden der Teilsummen-API

Die capabilities.json-Datei des Visuals muss:

• die Eigenschaft angeben, der die oben genannten Schalter jeweils zugeordnet sind.
• den Standardwert angeben, der verwendet werden soll, wenn die Eigenschaft nicht definiert ist.

Die Schalter verwenden ein Format wie im folgenden Beispiel:

    "rowSubtotals": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "rowSubtotals" 
                }, 
                "defaultValue": true 
            },

Im obigen Code werden die Zeilenteilergebnisse durch die rowSubtotals-Eigenschaft im subTotals-Objekt aktiviert. Die Eigenschaft weist einen Standardwert von true auf.

Die API wird automatisch für ein Visual aktiviert, wenn die Teilergebnisstruktur und alle Schalterzuordnungen in der capabilities.json-Datei definiert wurden.

Der folgende Code ist ein Beispiel für die vollständige API-Konfiguration in der capabilities.json-Datei (aus dem API-Beispielvisual kopiert):

"subtotals": { 
        "matrix": { 
            "rowSubtotals": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "rowSubtotals" 
                }, 
                "defaultValue": true 
            }, 
            "rowSubtotalsPerLevel": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "perRowLevel" 
                }, 
                "defaultValue": false 
            }, 
            "columnSubtotals": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "columnSubtotals" 
                }, 
                "defaultValue": true 
            }, 
            "columnSubtotalsPerLevel": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "perColumnLevel" 
                }, 
                "defaultValue": false 
            }, 
            "levelSubtotalEnabled": { 
                "propertyIdentifier": { 
                    "objectName": "subTotals", 
                    "propertyName": "levelSubtotalEnabled" 
                }, 
                "defaultValue": true 
            },
            "rowSubtotalsType": {
                "propertyIdentifier": {
                    "objectName": "subtotals",
                    "propertyName": "rowSubtotalsType"
                },
                "defaultValue": "Bottom"
            }
        } 
    }

Es ist wichtig, dass die enumerateProperties()-Funktion des Visuals die in der capabilities.json-Datei angegebenen Standardwerte beachtet. Die Anpassungslogik verwendet die jeweils angegebenen Standardwerte. Wenn die enumerateProperties()-Funktion und die Standardwerte nicht aufeinander abgestimmt sind, können sich die tatsächlichen Teilergebnisanpassungen von den Erwartungen des Benutzers abweichen.

enum RowSubtotalType {
        Top = "Top",
        Bottom = "Bottom",
   }

Um die verfügbaren Anpassungen zu überprüfen, erweitern Sie das Dropdownmenü Teilergebnisse im Eigenschaftenbereich Format. Ändern Sie die Einstellungen für Teilergebnisse, und verfolgen Sie die Änderungen an der Teilergebnisdarstellung (mit dem Namen Gesamtergebnisse) im Visualisierungsbereich nach.

Überlegungen und Einschränkungen

• Die rowSubtotalsType-Eigenschaft ist nur für Zeilen verfügbar. Spaltenteilergebnisse können nicht auf den Anfang einer Spalte festgelegt werden.

• Das Feature zum Erweitern und Reduzieren überschreibt rowSubtotals. Teilergebnisse werden angezeigt, wenn die Zeilen erweitert werden, auch wenn rowSubtotals auf false festgelegt ist.

Zugehöriger Inhalt

Hinzufügen von Interaktivität zu Visuals mithilfe von Auswahlmöglichkeiten für Power BI-Visuals