API for lokal lagring

Med den lokale lagrings-API-en kan du lagre data i nettleserens lokale lagringsplass. Hvis du vil bruke den lokale lagrings-API-en, må kundens lokale lagringsadministratorbytte aktiveres.

Lokal lagring er isolert slik at hver type visualobjekt har sin egen separate lagringstilgang.

Merk

Det er utviklerens ansvar å sikre at de lagrede dataene samsvarer med forbrukerens organisasjonspolicyer, og å informere brukerne om hvilken informasjon som lagres, hvis følsomheten til dataene krever det. Spesielt bør utviklere av egendefinerte visualobjekter kryptere dataene hvis forretningsmål eller scenarioer forventer det.

Slik bruker du lokal lagringsplass

Versjon 1

Denne versjonen av API-en for lokal lagring er planlagt for avskrivning. Vi godtar ikke flere forespørsler. Bruk versjon 2 når det er mulig.

I eksemplet nedenfor økes en teller når oppdateringsmetoden kalles. Tellerverdien lagres lokalt og kalles hver gang visualobjektet starter. På denne måten fortsetter telleren å telle fra der den slapp i stedet for å starte på nytt hver gang visualobjektet startes:

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

Versjon 2

Lokale lagringsmetoder

API-en for lokal lagring har fire metoder:

• status:

  • Returnerer statusen for den lokale lagringsplassen v2 API.

    • PrivilegeStatus.DisabledByAdmin: bryteren for leieradministrator er slått av
    • PrivilegeStatus.NotDeclared: visualobjektet har ingen deklarasjon for den lokale lagringsplassen i rettighetsmatrisen
    • PrivilegeStatus.NotSupported: API-en støttes ikke (se begrensninger for mer informasjon)
    • PrivilegeStatus.Allowed: API-en støttes og tillates

  Før du bruker metodene hent, angi eller fjerne, er det anbefalt fremgangsmåte å bruke statusmetoden til å kontrollere statusen for API-en og sikre at visualobjektet fungerer som forventet.

• få:

  • Denne metoden forventer én parameter:

    • nøkkelen – nøkkelen du vil hente verdien for.

  • Returnerer et løfte som løses med verdien hvis nøkkelen finnes, og avviser ellers.

• sett:

  • Denne metoden forventer to parametere:

    • nøkkel – nøkkelen du vil angi verdien for
    • data – verdien for nøkkelen

  • Returnerer et løfte som løser en struktur av typen StorageV2ResultInfo, eller avviser hvis det oppstod en feil.

• fjern:

  • Denne metoden forventer én parameter:

    • nøkkel – nøkkelen til paret du vil fjerne

Slik bruker du API-en for lokal lagring

Hvis du vil bruke den lokale lagrings-API-en, legger du til en deklarasjon i rettighetsmatrisen i visuelle funksjoner.

Følgende eksempel viser hvordan du angir og henter data fra den lokale lagringsplassen ved hjelp av versjon 2 av den lokale lagrings-API-en:

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

Hensyn og begrensninger

Vurderinger og begrensninger versjon 1

• Den lokale lagringsgrensen er 1 mb per GUID.
• Data kan bare deles mellom visualobjekter med samme GUID.
• Data kan ikke deles med en annen forekomst av Power BI Desktop.
• API-en for lokal lagring er ikke aktivert som standard. Hvis du vil aktivere den for Power BI-visualobjektet, sender du en forespørsel til power bi-visualobjektstøtte. pbicvsupport@microsoft.com
• API-en for lokal lagring støtter await ikke konstruksjoner. Bare then metoder og catch metoder er tillatt.

Visualobjektet skal være tilgjengelig i AppSource og være sertifisert.

Vurderinger og begrensninger versjon 2

• Grensen for lokal lagringsplass for egendefinerte visualobjekter er 100 kB.
• Data kan deles mellom visualobjekter med samme GUID, samme miljø og bare for samme bruker.
• API-en støttes i følgende miljøer:
  • Web
  • Skrivebord
  • SaaS Embed
  • Mobil
  • Rapportserver
• Lokal lagring støttes ikke når du eksporterer til PDF eller pptx.
• API-en støttes bare når en bruker er logget på.
• Dataene for et visualobjekt fjernes 29 dager etter den siste endringstiden.
• Denne API-en er en privilegert API.
• Nøkkelen (parameteren angitt for å angi, hente, fjerne) har følgende begrensninger:
  • Lengden må inneholde færre enn 128 tegn
  • Kan ikke inneholde tegnet |
• Hvis nettleseren er i kioskmodus, kan lokal lagringstilgjengelighet variere mellom nettlesere og av kioskeierens innstillinger.
• Det er mange grunner til at denne API-en kanskje ikke støttes. Det kan for eksempel hende at miljøet ikke støttes, eller at nettleserens lokale lagringsplass ikke er tilgjengelig. Vi anbefaler at du kontrollerer statusen for API-en før du bruker metodene for sett/hent/fjern. Feilbehandling er viktig siden selv om API-en støttes, kan den mislykkes.

Relatert innhold

• API for egendefinert visualobjekt i Power BI