API til lokalt lager

Med API'en til lokalt lager kan du gemme data i browserens lokale lager. Hvis du vil bruge API'en til lokalt lager, skal kundens lokale lageradministratorkontakt aktiveres.

Lokalt lager er isoleret, så hver type visualisering har sin egen separate lageradgang.

Bemærk

Det er udviklerens ansvar at sikre, at de lagrede data er i overensstemmelse med forbrugerens organisationspolitikker, og at informere brugerne om, hvilke oplysninger der gemmes, hvis dataenes følsomhed kræver det. Udviklere af brugerdefinerede visualiseringer skal især kryptere dataene, hvis forretningsmål eller scenarier forventer det.

Sådan bruger du lokalt lager

Version 1

Denne version af API'en til det lokale lager er planlagt til udfasning. Vi accepterer ikke flere anmodninger. Når det er muligt, skal du bruge Version 2.

I følgende eksempel øges en tæller, når opdateringsmetoden kaldes. Tællerværdien gemmes lokalt og kaldes, hver gang visualiseringen starter. På denne måde fortsætter tælleren med at tælle fra det sted, hvor den slap, i stedet for at starte forfra, hver gang visualiseringen 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());
            // ...
        }
}

Version 2

Lokale lagringsmetoder

Api'en til det lokale lager har fire metoder:

• status:

  • Returnerer status for den lokale lager-v2-API.

    • PrivilegeStatus.DisabledByAdmin: Lejeradministratorkontakten er slået fra
    • PrivilegeStatus.NotDeclared: Visualiseringen har ingen erklæring for det lokale lager i rettighedsmatrixen
    • PrivilegeStatus.NotSupported: API'en understøttes ikke (se begrænsninger for at få flere oplysninger)
    • PrivilegeStatus.Allowed: API'en understøttes og tillades

  Før du bruger metoderne get, set eller remove, er det bedste praksis at bruge statusmetoden til at kontrollere status for API'en og sikre, at din visualisering fungerer som forventet.

• hent:

  • Denne metode forventer én parameter:

    • key – den nøgle, hvis værdi du vil hente.

  • Returnerer et løfte, der løses med værdien, hvis nøglen findes, og afviser ellers.

• sæt:

  • Denne metode forventer to parametre:

    • key – den nøgle, du vil angive dens værdi
    • data – værdien for nøglen

  • Returnerer et løfte, der omsættes til en struktur af typen StorageV2ResultInfo, eller afviser, hvis der opstod en fejl.

• fjern:

  • Denne metode forventer én parameter:

    • key – nøglen til det par, du vil fjerne

Sådan bruger du api'en til lokalt lager

Hvis du vil bruge API'en til lokalt lager, skal du føje en erklæring til rettighedsmatrixen i visualiseringsfunktioner.

I følgende eksempel kan du se, hvordan du angiver og henter data fra det lokale lager ved hjælp af version 2 af API'en til lokalt lager:

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

Overvejelser og begrænsninger

Overvejelser og begrænsninger Version 1

• Den lokale lagergrænse er 1 mb pr. GUID.
• Data kan kun deles mellem visualiseringer med det samme GUID.
• Data kan ikke deles med en anden forekomst af Power BI Desktop.
• Den lokale lager-API er ikke aktiveret som standard. Hvis du vil aktivere den for din Power BI-visualisering, skal du sende en anmodning til understøttelse af Power BI-visualiseringer, pbicvsupport@microsoft.com.
• Api'en til det lokale lager understøtter await ikke konstruktioner. Kun then og catch metoder er tilladt.

Din visualisering skal være tilgængelig i AppSource og være certificeret.

Overvejelser og begrænsninger Version 2

• Den lokale lagergrænse for brugerdefinerede visualiseringer er 100 KB.
• Data kan deles mellem visualiseringer med det samme GUID, samme miljø og kun for den samme bruger.
• API'en understøttes i følgende miljøer:
  • Internet
  • Desktop
  • SaaS-integrering
  • Mobil
  • Rapportserver
• Lokalt lager understøttes ikke, når der eksporteres til PDF eller pptx.
• API'en understøttes kun, når en bruger er logget på.
• En visualiserings data ryddes 29 dage efter det seneste ændringstidspunkt.
• Denne API er en privilegeret API.
• Nøglen (parameter, der er angivet til at angive, hente, fjerne) har følgende begrænsninger:
  • Længden skal være mindre end 128 tegn
  • Må ikke indeholde tegnet '|'
• Hvis browseren er i kiosktilstand, kan tilgængeligheden af det lokale lager variere mellem browsere og af kioskejerens indstillinger.
• Der er mange årsager til, at denne API ikke understøttes. Miljøet understøttes muligvis ikke, eller browserens lokale lager er ikke tilgængeligt. Vi anbefaler, at du kontrollerer API'ens status, før du bruger set/get/remove-metoderne. Fejlhåndtering er vigtig, da den muligvis mislykkes, selvom API'en understøttes.

Relateret indhold

• Api til brugerdefineret visualisering i Power BI