Lokale opslag-API

Met de lokale opslag-API kunt u gegevens opslaan in de lokale opslag van de browser. Als u de lokale opslag-API wilt gebruiken, moet de lokale opslagbeheerder van de klant zijn ingeschakeld.

Lokale opslag wordt geïsoleerd, zodat elk type visual een eigen afzonderlijke opslagtoegang heeft.

Notitie

Het is de verantwoordelijkheid van de ontwikkelaar om ervoor te zorgen dat de opgeslagen gegevens voldoen aan het organisatiebeleid van de consument en om gebruikers te informeren over welke informatie wordt opgeslagen, als de vertrouwelijkheid van de gegevens dit vereist. Ontwikkelaars van aangepaste visuals moeten met name de gegevens versleutelen als bedrijfsdoelen of -scenario's deze verwachten.

Lokale opslag gebruiken

Versie 1

Deze versie van de lokale opslag-API is gepland voor afschaffing. We accepteren geen aanvragen meer. Gebruik indien mogelijk versie 2.

In het volgende voorbeeld wordt een teller verhoogd wanneer de updatemethode wordt aangeroepen. De tellerwaarde wordt lokaal opgeslagen en elke keer dat de visual wordt gestart, aangeroepen. Op deze manier blijft de teller tellen vanaf waar het was gebleven in plaats van telkens opnieuw te beginnen wanneer de visual wordt gestart:

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

Versie 2

Lokale opslagmethoden

De lokale opslag-API heeft vier methoden:

• status:

  • Retourneert de status van de lokale opslag v2-API.

    • PrivilegeStatus.DisabledByAdmin: de tenantbeheerder is uitgeschakeld
    • PrivilegeStatus.NotDeclared: de visual heeft geen declaratie voor de lokale opslag in de bevoegdhedenmatrix
    • PrivilegeStatus.NotSupported: de API wordt niet ondersteund (zie beperkingen voor meer informatie)
    • PrivilegeStatus.Allowed: de API wordt ondersteund en toegestaan

  Voordat u de get-, set- of verwijdermethoden gebruikt, is het raadzaam om de statusmethode te gebruiken om de status van de API te controleren en ervoor te zorgen dat uw visual zich gedraagt zoals verwacht.

• get:

  • Bij deze methode wordt één parameter verwacht:

    • sleutel : de sleutel waarvan u de waarde wilt ophalen.

  • Retourneert een belofte die wordt omgezet met de waarde als de sleutel bestaat en anders weigert.

• set:

  • Deze methode verwacht twee parameters:

    • sleutel : de sleutel die u wilt instellen
    • gegevens : de waarde voor de sleutel

  • Retourneert een belofte die wordt omgezet in een struct van het type StorageV2ResultInfoof wordt geweigerd als er een fout is opgetreden.

• verwijderen:

  • Bij deze methode wordt één parameter verwacht:

    • sleutel : de sleutel van het paar dat u wilt verwijderen

De lokale opslag-API gebruiken

Als u de lokale opslag-API wilt gebruiken, voegt u een declaratie toe aan de bevoegdhedenmatrix in visuele mogelijkheden.

In het volgende voorbeeld ziet u hoe u gegevens instelt en ophaalt uit de lokale opslag met versie 2 van de lokale opslag-API:

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

Overwegingen en beperkingen

Overwegingen en beperkingen versie 1

• De lokale opslaglimiet is 1 mb per GUID.
• Gegevens kunnen alleen worden gedeeld tussen visuals met dezelfde GUID.
• Gegevens kunnen niet worden gedeeld met een ander exemplaar van Power BI Desktop.
• De lokale opslag-API is niet standaard geactiveerd. Als u deze wilt activeren voor uw Power BI-visual, verzendt u een aanvraag naar de ondersteuning van Power BI-visuals. pbicvsupport@microsoft.com
• De lokale opslag-API biedt geen ondersteuning voor await constructies. Alleen then en catch methoden zijn toegestaan.

Uw visual moet beschikbaar zijn in AppSource en zijn gecertificeerd.

Overwegingen en beperkingen versie 2

• De lokale opslaglimiet voor aangepaste visuals is 100 kB.
• Gegevens kunnen worden gedeeld tussen visuals met dezelfde GUID, dezelfde omgeving en alleen voor dezelfde gebruiker.
• De API wordt ondersteund in de volgende omgevingen:
  • Web
  • Desktop
  • SaaS-insluiten
  • Mobiel
  • Rapportserver
• Lokale opslag wordt niet ondersteund wanneer u exporteert naar PDF of pptx.
• De API wordt alleen ondersteund wanneer een gebruiker is aangemeld.
• De gegevens van een visual worden 29 dagen na de meest recente wijzigingstijd gewist.
• Deze API is een bevoegde API.
• De sleutel (parameter die moet worden ingesteld, get, Remove) heeft de volgende beperkingen:
  • De lengte mag niet langer zijn dan 128 tekens
  • Kan het teken | niet bevatten
• Als de browser zich in de kioskmodus bevindt, kan de beschikbaarheid van lokale opslag verschillen tussen browsers en door de instellingen van de kioskeigenaar.
• Er zijn veel redenen waarom deze API mogelijk niet wordt ondersteund. De omgeving wordt mogelijk niet ondersteund of de lokale opslag van de browser is niet beschikbaar. U wordt aangeraden de status van de API te controleren voordat u de methoden set/get/remove gebruikt . Foutafhandeling is belangrijk, omdat zelfs als de API wordt ondersteund, deze mogelijk mislukt.

Gerelateerde inhoud

• Aangepaste VISUELE API voor Power BI