API för lokal lagring

Med det lokala lagrings-API:et kan du lagra data i webbläsarens lokala lagring. Om du vill använda det lokala lagrings-API:et måste kundens lokala lagringsadministratörsväxel vara aktiverad.

Lokal lagring är isolerad så att varje typ av visuellt objekt har sin egen separata lagringsåtkomst.

Kommentar

Det är utvecklarens ansvar att se till att lagrade data överensstämmer med konsumentens organisationsprinciper och att informera användarna om vilken information som lagras, om känsligheten för data kräver det. I synnerhet bör anpassade visuella utvecklare kryptera data om affärsmål eller scenarier förväntar sig det.

Så här använder du lokal lagring

Version 1

Den här versionen av det lokala lagrings-API:et är schemalagd för utfasning. Vi tar inte emot fler begäranden. Använd version 2 när det är möjligt.

I följande exempel ökas en räknare när uppdateringsmetoden anropas. Räknarvärdet sparas lokalt och anropas varje gång det visuella objektet startar. På så sätt fortsätter räknaren att räkna från där den slutade i stället för att börja om varje gång det visuella objektet startas:

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

Lokala lagringsmetoder

Det lokala lagrings-API:et har fyra metoder:

• status:

  • Returnerar status för det lokala lagrings-v2-API:et.

    • PrivilegeStatus.DisabledByAdmin: klientadministratörsknappen är inaktiverad
    • PrivilegeStatus.NotDeclared: det visuella objektet har ingen deklaration för den lokala lagringen i behörighetsmatrisen
    • PrivilegeStatus.NotSupported: API:et stöds inte (se begränsningar för mer information)
    • PrivilegeStatus.Allowed: API:et stöds och tillåts

  Innan du använder metoderna get, set eller remove är det bästa praxis att använda statusmetoden för att kontrollera statusen för API:et och se till att ditt visuella objekt fungerar som förväntat.

• hämta:

  • Den här metoden förväntar sig en parameter:

    • key – den nyckel vars värde du vill få.

  • Returnerar ett löfte som matchar med värdet om nyckeln finns och avvisar något annat.

• set:

  • Den här metoden förväntar sig två parametrar:

    • key – den nyckel som du vill ange dess värde
    • data – värdet för nyckeln

  • Returnerar ett löfte som matchar en struct av typen StorageV2ResultInfo, eller avvisar om ett fel uppstod.

• ta bort:

  • Den här metoden förväntar sig en parameter:

    • key – nyckeln för det par som du vill ta bort

Så här använder du det lokala lagrings-API:et

Om du vill använda det lokala lagrings-API:et lägger du till en deklaration i matrisen privilegier i visuella funktioner.

I följande exempel visas hur du anger och hämtar data från den lokala lagringen med hjälp av version 2 av det lokala lagrings-API:et:

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

Beaktanden och begränsningar

Överväganden och begränsningar version 1

• Den lokala lagringsgränsen är 1 mb per GUID.
• Data kan endast delas mellan visuella objekt med samma GUID.
• Data kan inte delas med en annan instans av Power BI Desktop.
• Det lokala lagrings-API:et aktiveras inte som standard. Om du vill aktivera det för ditt visuella Power BI-objekt skickar du en begäran till stöd för visuella Power BI-objekt, pbicvsupport@microsoft.com.
• Det lokala lagrings-API:et stöder await inte konstruktioner. Endast then och catch metoder tillåts.

Ditt visuella objekt ska vara tillgängligt i AppSource och certifieras.

Överväganden och begränsningar version 2

• Den lokala lagringsgränsen för anpassade visuella objekt är 100 KB.
• Data kan delas mellan visuella objekt med samma GUID, samma miljö och endast för samma användare.
• API:et stöds i följande miljöer:
  • Webb
  • Skrivbord
  • SaaS-inbäddning
  • Mobilt
  • Rapportserver
• Lokal lagring stöds inte när du exporterar till PDF eller pptx.
• API:et stöds endast när en användare är inloggad.
• Ett visuellt objekts data rensas 29 dagar efter den senaste ändringstiden.
• Det här API:et är ett privilegierat API.
• Nyckeln (parametern som anges för att ange, hämta, Ta bort) har följande begränsningar:
  • Längden måste vara mindre än 128 tecken
  • Det går inte att innehålla tecknet |.
• Om webbläsaren är i helskärmsläge kan tillgängligheten för lokal lagring skilja sig mellan webbläsare och kioskägarens inställningar.
• Det finns många orsaker till att det här API:et kanske inte stöds. Miljön kanske till exempel inte stöds eller så är webbläsarens lokala lagring inte tillgänglig. Vi rekommenderar att du kontrollerar statusen för API:et innan du använder metoderna set/get/remove. Felhantering är viktigt eftersom även om API:et stöds kan det misslyckas.

Relaterat innehåll

• Api för anpassade visuella Power BI-objekt