Interfejs API magazynu lokalnego

Za pomocą lokalnego interfejsu API magazynu można przechowywać dane w magazynie lokalnym przeglądarki. Aby korzystać z lokalnego interfejsu API magazynu, należy włączyć przełącznik administratora magazynu lokalnego klienta.

Magazyn lokalny jest izolowany, dzięki czemu każdy typ wizualizacji ma własny oddzielny dostęp do magazynu.

Uwaga

Deweloper ponosi odpowiedzialność za zapewnienie zgodności przechowywanych danych z zasadami organizacyjnymi konsumenta oraz informowanie użytkowników o tym, jakie informacje są przechowywane, jeśli wymaga tego poufność danych. W szczególności deweloperzy wizualizacji niestandardowych powinni szyfrować dane, jeśli spodziewają się tego cele biznesowe lub scenariusze.

Jak używać magazynu lokalnego

Wersja 1

Ta wersja lokalnego interfejsu API magazynu ma zostać wycofana. Nie akceptujemy więcej żądań. Jeśli to możliwe, użyj wersji 2.

W poniższym przykładzie licznik jest zwiększany przy każdym wywołaniu metody aktualizacji . Wartość licznika jest zapisywana lokalnie i wywoływana za każdym razem, gdy wizualizacja zostanie uruchomiona. W ten sposób licznik kontynuuje liczenie od miejsca, w którym została przerwana, zamiast uruchamiać się za każdym razem, gdy wizualizacja jest uruchamiana:

export class Visual implements IVisual {
        // ...
        private updateCountName: string = 'updateCount';
        private updateCount: number;
        private storage: ILocalVisualStorageService;
        // ...

        constructor(options: VisualConstructorOptions) {
            // ...
            this.storage = options.host.storageService;
            // ...

            this.storage.get(this.updateCountName).then(count =>
            {
                this.updateCount = +count;
            })
            .catch(() =>
            {
                this.updateCount = 0;
                this.storage.set(this.updateCountName, this.updateCount.toString());
            });
            // ...
        }

        public update(options: VisualUpdateOptions) {
            // ...
            this.updateCount++;
            this.storage.set(this.updateCountName, this.updateCount.toString());
            // ...
        }
}

Wersja 2

Metody magazynu lokalnego

Interfejs API magazynu lokalnego ma cztery metody:

• stan:

  • Zwraca stan lokalnego interfejsu API magazynu w wersji 2.

    • PrivilegeStatus.DisabledBy Administracja: przełącznik administratora dzierżawy jest wyłączony
    • PrivilegeStatus.NotDeclared: wizualizacja nie ma deklaracji dla magazynu lokalnego w tablicy uprawnień
    • PrivilegeStatus.NotSupported: interfejs API nie jest obsługiwany (zobacz ograniczenia , aby uzyskać więcej informacji)
    • PrivilegeStatus.Allowed: interfejs API jest obsługiwany i dozwolony

  Przed użyciem metod pobierania, ustawiania lub usuwania najlepszym rozwiązaniem jest użycie metody statusu w celu sprawdzenia stanu interfejsu API i upewnienia się, że wizualizacja zachowuje się zgodnie z oczekiwaniami.

• pobierz:

  • Ta metoda oczekuje jednego parametru:

    • key — klucz, którego wartość chcesz uzyskać.

  • Zwraca obietnicę, która rozpoznaje wartość, jeśli klucz istnieje, i odrzuca w przeciwnym razie.

• zestaw:

  • Ta metoda oczekuje dwóch parametrów:

    • key — klucz, który chcesz ustawić jego wartość
    • data — wartość klucza

  • Zwraca obietnicę, która rozwiązuje się z strukturą typu StorageV2ResultInfo, lub odrzuca, jeśli wystąpił błąd.

• usuń:

  • Ta metoda oczekuje jednego parametru:

    • key — klucz pary, którą chcesz usunąć

Jak używać lokalnego interfejsu API magazynu

Aby użyć lokalnego interfejsu API magazynu, dodaj deklarację do tablicy uprawnień w funkcjach wizualizacji.

W poniższym przykładzie pokazano, jak ustawić i pobrać dane z magazynu lokalnego przy użyciu wersji 2 lokalnego interfejsu API magazynu:

import IVisualLocalStorageV2Service = powerbi.extensibility.IVisualLocalStorageV2Service; 
import StorageV2ResultInfo = powerbi.extensibility.StorageV2ResultInfo; 
import PrivilegeStatus = powerbi.PrivilegeStatus; 
 
export class Visual implements IVisual { 
    // ... 
    private updateCountName: string = 'updateCount'; 
    private updateCount: number; 
    private storageV2Service: IVisualLocalStorageV2Service; 
 
    constructor(options: VisualConstructorOptions) { 
        this.storageV2Service = options.host.storageV2Service; 
        this.init(); 
    } 
 
    private async init() { 
        try { 
            let status: powerbi.PrivilegeStatus = await this.storageV2Service.status(); 
            if (status === PrivilegeStatus.DisabledByAdmin) { 
                //handle if the api blocked by admin 
            } else if (status === PrivilegeStatus.Allowed) { 
                this.updateCount = await this.storageV2Service.get(this.updateCountName); 
            } 
        } catch (error) { 
            //handle error 
        } 
    } 

    private async updateCount(count: number) { 
        try { 
            let status: PrivilegeStatus = await this.storageV2Service.status(); 
            if (status === PrivilegeStatus.Allowed) { 
                let resultInfo: StorageV2ResultInfo = this.storageV2Service.set(this.updateCountName, count); 
                if (resultInfo.success) { 
                    //updateCount was set. 
                } else { 
 
                } 
            } 
        } catch (error) { 
            // handle error 
        } 
    } 

    private async removeUpdateCount() { 
        let status: PrivilegeStatus = await this.storageV2Service.status(); 
        if (status === PrivilegeStatus.Allowed) { 
            this.storageV2Service.remove(this.updateCountName); 
        } 
    } 
} 

Rozważania i ograniczenia

Zagadnienia i ograniczenia w wersji 1

• Limit magazynu lokalnego wynosi 1 mb na identyfikator GUID.
• Dane mogą być udostępniane między wizualizacjami tylko z tym samym identyfikatorem GUID.
• Nie można udostępniać danych innemu wystąpieniu programu Power BI Desktop.
• Interfejs API magazynu lokalnego nie jest domyślnie aktywowany. Aby aktywować ją dla wizualizacji usługi Power BI, wyślij żądanie do pomocy technicznej wizualizacji usługi Power BI. pbicvsupport@microsoft.com
• Interfejs API magazynu lokalnego nie obsługuje await konstrukcji. Dozwolone są tylko then metody i catch .

Wizualizacja powinna być dostępna w usłudze AppSource i być certyfikowana.

Zagadnienia i ograniczenia w wersji 2

• Limit magazynu lokalnego wizualizacji niestandardowych wynosi 100 KB.
• Dane mogą być udostępniane między wizualizacjami z tym samym identyfikatorem GUID, tym samym środowiskiem i tylko dla tego samego użytkownika.
• Interfejs API jest obsługiwany w następujących środowiskach:
  • Internet
  • Klasyczna
  • Osadzanie saas
  • Aplikacje mobilne
  • Serwer raportów
• Magazyn lokalny nie jest obsługiwany podczas eksportowania do formatu PDF lub pptx.
• Interfejs API jest obsługiwany tylko wtedy, gdy użytkownik jest zalogowany.
• Dane wizualizacji są czyszczone 29 dni po ostatnim czasie modyfikacji.
• Ten interfejs API jest uprzywilejowanym interfejsem API.
• Klucz (parametr podany do ustawienia, get, Remove) ma następujące ograniczenia:
  • Długość musi być mniejsza niż 128 znaków
  • Nie można zawierać znaku '|'
• Jeśli przeglądarka jest w trybie kiosku, dostępność magazynu lokalnego może się różnić między przeglądarkami a ustawieniami właściciela kiosku.
• Istnieje wiele powodów, dla których ten interfejs API może nie być obsługiwany. Na przykład środowisko może nie być obsługiwane lub magazyn lokalny przeglądarki jest niedostępny. Zalecamy sprawdzenie stanu interfejsu API przed użyciem metod set/get/remove. Obsługa błędów jest ważna, ponieważ nawet jeśli interfejs API jest obsługiwany, może zakończyć się niepowodzeniem.

Powiązana zawartość

• Interfejs API wizualizacji niestandardowej usługi Power BI