Rozhranie API lokálneho úložiska

Vďaka lokálnemu úložisku API môžete ukladať údaje v lokálnom úložisku prehliadača. Ak chcete používať rozhranie API lokálneho úložiska, prepínač správcu lokálneho úložiska zákazníka musí byť povolený.

Lokálne úložisko je izolované tak, aby mal každý typ vizuálu svoj vlastný samostatný prístup k úložisku.

Poznámka

Zodpovednosťou vývojára je zabezpečiť, aby uložené údaje zodpovedali pravidlám organizácie zákazníka a informovať používateľov o tom, aké informácie sú uložené, ak to vyžaduje citlivosť údajov. Predovšetkým by vývojári vlastných vizuálov mali šifrovať údaje, ak ich očakávajú obchodné ciele alebo scenáre.

Používanie lokálneho úložiska

Verzia 1

Táto verzia rozhrania API lokálneho úložiska je naplánovaná na zamietnutie. Ďalšie žiadosti neprijímame. Ak je to možné, použite verziu 2.

V nasledujúcom príklade sa počítadlo zvýši pri volaní metódy update . Hodnota počítadla sa uloží lokálne a zavolá sa pri každom spustení vizuálu. Týmto spôsobom bude počítadlo pokračovať v počítaní, odkiaľ prestalo pri každom spustení vizuálu začínať:

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

Verzia 2

Metódy lokálneho úložiska

Rozhranie API lokálneho úložiska má štyri metódy:

• status (stav):

  • Vráti stav lokálneho úložiska v2 API.

    • PrivilegeStatus.DisabledBy Spravovanie: prepínač správcu nájomníka je vypnutý
    • PrivilegeStatus.NotDeclared: vizuál nemá žiadnu deklaráciu pre lokálne úložisko v poli oprávnenia
    • PrivilegeStatus.NotSupported: rozhranie API nie je podporované (ďalšie informácie nájdete v časti Obmedzenia )
    • PrivilegeStatus.Allowed: rozhranie API je podporované a povolené

  Pred použitím metód získania, nastavenia alebo odstránenia je najlepšie použiť metódu stavu na kontrolu stavu rozhrania API a zabezpečiť, aby sa váš vizuál správal podľa očakávaní.

• získať:

  • Táto metóda očakáva jeden parameter:

    • key – kľúč, ktorého hodnotu chcete získať.

  • Vráti sľub, ktorý sa vyrieši s hodnotou, ak kľúč existuje, a odmietne inak.

• nastavenie:

  • Táto metóda očakáva dva parametre:

    • key – kľúč, ktorý chcete nastaviť jeho hodnotu
    • data – hodnota kľúča

  • Vráti prísľub, ktorý sa vyrieši do záštity typu StorageV2ResultInfoalebo zamietne, ak sa vyskytla chyba.

• odstrániť:

  • Táto metóda očakáva jeden parameter:

    • key – kľúč dvojice, ktorú chcete odstrániť

Používanie rozhrania API lokálneho úložiska

Ak chcete používať rozhranie API lokálneho úložiska, pridajte deklaráciu do poľa oprávnení v rámci možností vizuálu.

V nasledujúcom príklade je uvedené, ako nastaviť a načítať údaje z lokálneho úložiska pomocou verzie 2 rozhrania API lokálneho úložiska:

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

Dôležité informácie a obmedzenia

Dôležité informácie a obmedzenia Verzia 1

• Limit lokálneho úložiska je 1 mb na identifikátor GUID.
• Údaje je možné zdieľať medzi vizuálmi len s rovnakým identifikátorom GUID.
• Údaje nie je možné zdieľať s inou inštanciou aplikácie Power BI Desktop.
• Rozhranie API lokálneho úložiska sa predvolene neaktivuje. Ak ho chcete aktivovať pre svoj vizuál Power BI, odošlite žiadosť oddeleniu podpory pre vizuály služby Power BI, pbicvsupport@microsoft.com.
• Rozhranie API lokálneho úložiska nepodporuje await stavby. Povolené sú iba then metódy a catch .

Váš vizuál by mal byť k dispozícii v službe AppSource a mal by byť certifikovaný.

Dôležité informácie a obmedzenia Verzia 2

• Limit lokálneho úložiska vlastných vizuálov je 100 kB.
• Údaje je možné zdieľať medzi vizuálmi s rovnakým identifikátorom GUID, rovnakým prostredím a len pre rovnakého používateľa.
• Rozhranie API je podporované v nasledujúcich prostrediach:
  • Web
  • Pracovná plocha
  • Vloženie SaaS
  • Mobilné zariadenia
  • Server zostáv
• Lokálne úložisko nie je podporované pri exporte do formátu PDF alebo pptx.
• Rozhranie API je podporované len vtedy, keď je prihlásený používateľ.
• Údaje vizuálu sa vymažú 29 dní po poslednom čase úpravy.
• Toto rozhranie API je privilegované rozhranie API.
• Kľúč (parameter zadaný na nastavenie, získanie, odstránenie) má nasledujúce obmedzenia:
  • Dĺžka musí byť menšia ako 128 znakov.
  • Nemôže obsahovať znak |.
• Ak je prehliadač v režime kiosku, dostupnosť lokálneho úložiska sa môže líšiť medzi prehliadačmi a nastaveniami vlastníka kiosku.
• Existuje mnoho dôvodov, prečo toto rozhranie API možno nie je podporované. Prostredie napríklad nemusí byť podporované alebo lokálny ukladací priestor prehliadača nie je k dispozícii. Pred použitím metód set/get/remove odporúčame skontrolovať stav rozhrania API. Spracovanie chýb je dôležité, pretože aj v prípade, že je podporované rozhranie API, môže zlyhať.

Súvisiaci obsah

• Rozhranie API vlastných vizuálov služby Power BI