Możliwości i właściwości wizualizacji usługi Power BI

Każda wizualizacja ma plik capabilities.json tworzony automatycznie po uruchomieniu pbiviz new <visual project name> polecenia w celu utworzenia nowej wizualizacji. Plik capabilities.json opisuje obiekt wizualny dla hosta.

Plik capabilities.json informuje hosta o tym, jakie dane akceptuje wizualizacja, jakie atrybuty można dostosowywać do wprowadzenia w okienku właściwości oraz inne informacje potrzebne do utworzenia wizualizacji. Począwszy od interfejsu API w wersji 4.6.0, wszystkie właściwości modelu możliwości są opcjonalne z wyjątkiem privileges, które są wymagane.

Plik capabilities.json zawiera listę obiektów głównych w następującym formacie:

{
    "privileges": [ ... ],
    "dataRoles": [ ... ],
    "dataViewMappings": [ ... ],
    "objects":  { ... },
    "supportsHighlight": true|false,
    "advancedEditModeSupport": 0|1|2,
    "sorting": { ... }
    ...
}

Podczas tworzenia nowej wizualizacji domyślny plik capabilities.json zawiera następujące obiekty główne:

• Uprawnienia
• dataRoles
• dataViewMappings
• Obiekty

Powyższe obiekty są tymi, które są potrzebne do powiązania danych. W razie potrzeby można je edytować na potrzeby grafiki.

Następujące inne obiekty główne są opcjonalne i można je dodać zgodnie z potrzebami:

• podpowiedzi
• supportsHighlight
• Sortowanie
• przechodzenie do szczegółów
• expandCollapse
• supportsKeyboardFocus
• obsługuje synchronizację stanu filtra
• advancedEditModeSupport
• supportsLandingPage
• supportsEmptyDataView
• supportsMultiVisualSelection
• Sumy częściowe
• keepAllMetadataColumns
• migracja

Wszystkie te obiekty i ich parametry można znaleźć w schemacie capabilities.json

uprawnienia: zdefiniuj specjalne uprawnienia, których wymaga Twoja wizualizacja

Uprawnienia to specjalne operacje, do których element wizualny wymaga dostępu, aby działać. Uprawnienia przyjmują tablicę obiektów privilege, które definiują wszystkie właściwości uprawnień. W poniższych sekcjach opisano uprawnienia dostępne w usłudze Power BI.

Uwaga

W interfejsie API w wersji 4.6.0 uprawnienia muszą być określone w pliku capabilities.json. We wcześniejszych wersjach dostęp zdalny jest automatycznie udzielany i pobieranie do plików nie jest możliwe. Aby dowiedzieć się, której wersji używasz, sprawdź apiVersion w pliku pbiviz.json.

Definiowanie uprawnień

Definicja uprawnień JSON zawiera następujące składniki:

• name - (łańcuch znaków) Nazwa uprawnienia.
• essential - (Wartość logiczna) Wskazuje, czy funkcjonalność wizualizacji wymaga tego uprawnienia. Wartość true oznacza, że wymagane jest uprawnienie; false oznacza, że uprawnienie nie jest obowiązkowe.
• parameters - (tablica ciągów)(opcjonalnie) Argumenty. Jeśli brakuje parameters, jest ona uznawana za pustą tablicę.

Poniżej przedstawiono typy uprawnień, które należy zdefiniować:

• Uzyskiwanie dostępu do zasobów zewnętrznych
• Pobierz do pliku
• Uprawnienia pamięci lokalnej

Uwaga

Nawet w przypadku tych uprawnień przyznanych w wizualizacji administrator musi włączyć przełącznik w ustawieniach administratora, aby umożliwić użytkownikom w organizacji korzystanie z tych ustawień.

Zezwalaj na dostęp do internetu

Aby umożliwić wizualizacji dostęp do zewnętrznego zasobu lub witryny internetowej, dodaj te informacje jako uprawnienia w sekcji możliwości. Definicja uprawnień zawiera opcjonalną listę adresów URL, do których wizualizacja może uzyskać dostęp w formacie http://xyz.com lub https://xyz.com. Każdy adres URL może również zawierać symbol wieloznaczny, aby określić poddomeny.

Poniższy kod jest przykładem ustawienia uprawnień zezwalających na dostęp do zasobów zewnętrznych:

{
    "name": "WebAccess",
    "essential": true,
    "parameters": [ "https://*.microsoft.com", "http://example.com" ]
}

WebAccess Powyższe uprawnienie oznacza, że wizualizacja musi uzyskać dostęp do dowolnej poddomeny microsoft.com domeny za pośrednictwem protokołu HTTPS tylko i example.com bez domen podrzędnych za pośrednictwem protokołu HTTP, a to uprawnienie dostępu jest niezbędne do działania wizualizacji.

Pobieranie do pliku

Aby umożliwić użytkownikowi eksportowanie danych z wizualizacji do pliku, ustaw wartość ExportContenttrue.

To ExportContent ustawienie umożliwia wizualizacji eksportowanie danych do plików w następujących formatach:

• .txt
• .csv
• .json
• .tmplt
• .xml
• .pdf
• .xlsx

To ustawienie jest niezależne od ograniczeń pobierania zastosowanych w ustawieniach dzierżawy organizacji dotyczących eksportu i udostępniania i nie mają one na nie wpływu.

Poniższy kod jest przykładem ustawienia uprawnień, które umożliwia pobieranie do pliku:

"privileges": [
    {
        "name": "ExportContent",
        "essential": true
    }
]

Uprawnienia pamięci lokalnej

To uprawnienie umożliwia niestandardowej wizualizacji przechowywanie informacji w lokalnej pamięci przeglądarki użytkownika.

Poniżej przedstawiono przykład ustawienia uprawnień, które umożliwia korzystanie z magazynu lokalnego:

"privileges": [
    {
        "name": "LocalStorage",
        "essential": true
    }
]

Brak wymaganych uprawnień

Jeśli wizualizacja nie wymaga żadnych specjalnych uprawnień, tablica powinna być pusta privileges :

  "privileges": []

Wiele uprawnień

W poniższym przykładzie pokazano, jak ustawić kilka uprawnień dla wizualizacji niestandardowej.

"privileges": [
    {
        "name": "WebAccess",
        "essential": true,
        "parameters": [ "https://*.virtualearth.net" ]
    },
    {
        "name": "ExportContent",
        "essential": false
    }
]

dataroles: zdefiniuj pola danych oczekiwane przez wizualizację

Aby zdefiniować pola, które można powiązać z danymi, użyj polecenia dataRoles. dataRoles to tablica DataViewRole obiektów, która definiuje wszystkie wymagane właściwości. Obiekty dataRoles są polami wyświetlanymi w okienku Właściwości.

Użytkownik przeciąga pola danych do tych obiektów, aby powiązać pola danych z obiektami.

Właściwości elementu DataRole

Zdefiniuj element DataRoles z następującymi właściwościami:

• name: wewnętrzna nazwa tego pola danych (musi być unikatowa).
• displayName: nazwa wyświetlana użytkownikowi w okienku Właściwości .
• rodzaj: rodzaj pola:
  • Grouping: zestaw wartości dyskretnych używanych do grupowania pól miary.
  • Measure: Pojedyncze wartości liczbowe.
  • GroupingOrMeasure: wartości, których można użyć jako grupowania lub miary.
• opis: krótki opis tekstu pola (opcjonalnie).
• requiredTypes: wymagany typ danych dla tej roli danych. Wartości, które nie są zgodne, są ustawione na wartość null (opcjonalnie).
• preferredTypes: preferowany typ danych dla tej roli danych (opcjonalnie).

Prawidłowe typy danych dla parametrów requiredTypes i preferredTypes

• bool: wartość logiczna
• Liczba całkowita: wartość całkowita
• numeryczne: wartość liczbowa
• text: wartość tekstowa
• geography: Dane geograficzne

przykład dataRoles

"dataRoles": [
    {
        "displayName": "My Category Data",
        "name": "myCategory",
        "kind": "Grouping",
        "requiredTypes": [
            {
                "text": true
            },
            {
                "numeric": true
            },
            {
                "integer": true
            }
        ],
        "preferredTypes": [
            {
                "text": true
            }
        ]
    },
    {
        "displayName": "My Measure Data",
        "name": "myMeasure",
        "kind": "Measure",
        "requiredTypes": [
            {
                "integer": true
            },
            {
                "numeric": true
            }
        ],
        "preferredTypes": [
            {
                "integer": true
            }
        ]
    }
]
...
}

Powyższe role danych tworzą pola wyświetlane na poniższej ilustracji:

dataViewMappings: sposób mapowania danych

Obiekty dataViewMappings opisują relację ról danych ze sobą i umożliwiają określenie wymagań warunkowych dotyczących wyświetlania widoków danych.

Większość wizualizacji udostępnia jedno mapowanie, ale można podać wiele dataViewMappings. Każde prawidłowe mapowanie tworzy widok danych.

"dataViewMappings": [
    {
        "conditions": [ ... ],
        "categorical": { ... },
        "table": { ... },
        "single": { ... },
        "matrix": { ... }
    }
]

Aby uzyskać więcej informacji, zobacz Omówienie mapowania widoku danych w wizualizacjach usługi Power BI.

obiekty: definiowanie opcji okienka właściwości

Obiekty opisują konfigurowalne właściwości powiązane z wizualizacją. Obiekty zdefiniowane w tej sekcji to obiekty, które są wyświetlane w okienku Format. Każdy obiekt może mieć wiele właściwości, a każda właściwość ma skojarzony typ.

"objects": {
    "myCustomObject": {
        "properties": { ... }
    }
}

Aby na przykład obsługiwać ciągi formatu dynamicznego w wizualizacji niestandardowej, zdefiniuj następujący obiekt:

"objects": {
        "general": {
            "properties": {
                "formatString": {
                    "type": {
                        "formatting": {
                            "formatString": true
                        }
                    }
                }
            }
        },

Aby uzyskać więcej informacji, zobacz Obiekty i właściwości wizualizacji usługi Power BI.

Powiązana zawartość

• Omówienie mapowania widoku danych w wizualizacjach usługi Power BI
• Obiekty i właściwości wizualizacji usługi Power BI
• Opcje sortowania wizualizacji usługi Power BI