API für lokalen Speicher

Mit der API für den lokalen Speicher können Sie Daten im lokalen Speicher des Browsers speichern. Um die API für den lokalen Speicher zu verwenden, muss die Administratoreinstellung für den lokalen Speicher des Kunden aktiviert sein.

Der lokale Speicher ist isoliert, sodass jeder Visualtyp über einen eigenen separaten Speicherzugriff verfügt.

Hinweis

Es liegt in der Verantwortung der Entwickler, zu gewährleisten, dass die gespeicherten Daten den Organisationsrichtlinien der Endkunden entsprechen. Darüber hinaus liegt es in der Verantwortung der Entwickler, die Benutzer darüber informieren, welche Informationen gespeichert werden, wenn die Vertraulichkeit der Daten das erfordert. Entwickler von benutzerdefinierten Visuals sollten die Daten insbesondere dann verschlüsseln, wenn Geschäftsziele oder -szenarios das erfordern.

So verwenden Sie den lokalen Speicher

Version 1

Diese Version der API für den lokalen Speicher soll eingestellt werden. Es werden keine weiteren Supportanfragen akzeptiert. Verwenden Sie nach Möglichkeit Version 2.

Im folgenden Beispiel wird ein Leistungsindikator jedes Mal erhöht, wenn die Updatemethode aufgerufen wird. Der Indikatorwert wird lokal gespeichert und bei jedem Start des Visuals aufgerufen. So zählt der Leistungsindikator ab der Position, an der er zuletzt angehalten wurde, anstelle jedes Mal neu zu beginnen, wenn das Visual gestartet wird.

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());
            // ...
        }
}

Version 2

Methoden für den lokalen Speicher

Die API für den lokalen Speicher verfügt über vier Methoden:

• status:

  • Gibt den Status der API für den lokalen Speicher (Version 2) zurück

    • PrivilegeStatus.DisabledByAdmin: Die Administratoreinstellung für den Mandanten ist deaktiviert.
    • PrivilegeStatus.NotDeclared: Das Visual verfügt im Berechtigungsarray nicht über eine Deklaration für den lokalen Speicher.
    • PrivilegeStatus.NotSupported: Die API wird nicht unterstützt (weitere Informationen finden Sie im Abschnitt Einschränkungen).
    • PrivilegeStatus.Allowed: Die API wird unterstützt und ist zulässig.

  Vor der Verwendung der Methoden get, set oder remove wird die Verwendung der status-Methode empfohlen, um den Status der API zu überprüfen und sicherzustellen, dass ein erwartungsgemäßes Verhalten des Visuals vorliegt.

• Abrufen:

  • Diese Methode erwartet einen Parameter:

    • key: der Schlüssel, dessen Wert abgerufen werden soll

  • Der Parameter gibt eine Zusage zurück, die mit dem Wert aufgelöst wird, sofern der Schlüssel vorhanden ist. Andernfalls wird der Schlüssel abgelehnt.

• set:

  • Diese Methode erwartet zwei Parameter:

    • key: der Schlüssel, der für den Wert festgelegt werden soll
    • data: der Wert für den Schlüssel

  • Der Parameter gibt eine Zusage zurück, die in einen struct-Wert des Typs StorageV2ResultInfo aufgelöst oder beim Auftreten eines Fehlers abgelehnt wird.

• remove:

  • Diese Methode erwartet einen Parameter:

    • key: der Schlüssel des Paars, das entfernt werden soll

Verwenden der API für den lokalen Speicher

Fügen Sie dem Berechtigungsarray in den Visualfunktionen eine Deklaration hinzu, um die API für den lokalen Speicher zu verwenden.

Das folgende Beispiel zeigt, wie mithilfe der Version 2 der API für den lokalen Speicher Daten aus dem lokalen Speicher festgelegt und abgerufen werden:

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

Überlegungen und Einschränkungen

Version 1: Überlegungen und Einschränkungen

• Das Limit für den lokalen Speicher liegt bei 1 MB pro GUID.
• Daten können nur zwischen Visuals mit derselben GUID freigegeben werden.
• Daten können nicht mit einer anderen Instanz von Power BI Desktop geteilt werden.
• Die API für den lokalen Speicher ist standardmäßig nicht aktiviert. Wenn Sie die API für Ihr Power BI-Visual aktivieren möchten, senden Sie eine Anfrage an das Supportteam für Power BI-Visuals (pbicvsupport@microsoft.com).
• Die lokale Speicher-API unterstützt keine await-Konstruktionen. Nur then- und catch-Methoden sind zulässig.

Ihr Visual sollte in AppSource verfügbar und zertifiziert sein.

Version 2: Überlegungen und Einschränkungen

• Das Limit für den lokalen Speicher liegt für benutzerdefinierte Visuals bei 100 KB.
• Daten können zwischen Visuals mit derselben GUID, derselben Umgebung und ausschließlich für denselben Benutzer freigegeben werden.
• Die API wird in den folgenden Umgebungen unterstützt:
  • Web
  • Desktop
  • SaaS-Einbettung
  • Mobil
  • Berichtsserver
• Der lokale Speicher wird beim Exportieren in die Formate PDF oder PPTX nicht unterstützt.
• Die API wird nur dann unterstützt, wenn ein Benutzer angemeldet ist.
• Die Daten eines Visuals werden 29 Tage nach der letzten Änderung gelöscht.
• Diese API ist eine privilegierte API.
• Der Schlüssel (Parameter, der für die Methoden set, get und remove bereitgestellt wird) weist die folgenden Einschränkungen auf:
  • Die Länge muss unter 128 Zeichen liegen.
  • Er darf das Zeichen „|“ nicht enthalten.
• Wenn sich der Browser im Kioskmodus befindet, kann sich die Verfügbarkeit des lokalen Speichers zwischen Browsern sowie aufgrund der Einstellungen des Kioskbesitzers unterscheiden.
• Diese API wird aus vielen Gründen möglicherweise nicht unterstützt. Beispiel: Die Umgebung wird möglicherweise nicht unterstützt, oder der lokale Speicher des Browsers ist nicht verfügbar. Es wird empfohlen, den Status der API zu überprüfen, bevor sie die Methoden set, get oder remove verwenden. Die Fehlerbehandlung ist wichtig, da selbst dann ein API-Fehler auftreten kann, wenn die API unterstützt wird.

Zugehöriger Inhalt

• Benutzerdefiniertes Visual-API für Power BI