Rozhraní API místního úložiště

Pomocí rozhraní API místního úložiště můžete ukládat data v místním úložišti prohlížeče. Pokud chcete použít rozhraní API místního úložiště, musí být povolený přepínač správce místního úložiště zákazníka.

Místní úložiště je izolované, takže každý typ vizuálu má vlastní samostatný přístup k úložišti.

Poznámka:

Je zodpovědností vývojáře zajistit, aby uložená data odpovídala zásadám organizace spotřebitele a aby informovala uživatele o tom, jaké informace jsou uložené, pokud to vyžaduje citlivost dat. Vývojáři vlastních vizuálů by měli data šifrovat, pokud je očekávají obchodní cíle nebo scénáře.

Jak používat místní úložiště

Verze 1

Tato verze rozhraní API místního úložiště je naplánovaná pro vyřazení. Nepřijímáme žádné další žádosti. Pokud je to možné, použijte verzi 2.

V následujícím příkladu se čítač zvýší při každém zavolání metody aktualizace . Hodnota čítače se ukládá místně a volá se při každém spuštění vizuálu. Tímto způsobem čítač pokračuje v počítání místa, kde skončil, místo aby se spouštěl při každém spuštění vizuálu:

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

Verze 2

Metody místního úložiště

Rozhraní API místního úložiště má čtyři metody:

• stav:

  • Vrátí stav rozhraní API místního úložiště v2.

    • PrivilegeStatus.DisabledByAdmin: Přepínač správce tenanta je vypnutý.
    • PrivilegeStatus.NotDeclared: Vizuál nemá pro místní úložiště v poli oprávnění žádnou deklaraci.
    • PrivilegeStatus.NotSupported: Rozhraní API není podporované (další informace najdete v omezeních ).
    • PrivilegeStatus.Allowed: Rozhraní API je podporované a povolené.

  Před použitím metody get, set nebo remove je vhodné použít metodu stavu ke kontrole stavu rozhraní API a zajistit, aby se vizuál chová podle očekávání.

• get:

  • Tato metoda očekává jeden parametr:

    • klíč – klíč, jehož hodnotu chcete získat.

  • Vrátí příslib, který se přeloží s hodnotou, pokud klíč existuje, a jinak odmítne.

• set:

  • Tato metoda očekává dva parametry:

    • key – klíč, který chcete nastavit jeho hodnotu
    • data – hodnota klíče

  • Vrátí příslib, který se přeloží na strukturu typu StorageV2ResultInfonebo odmítne, pokud došlo k chybě.

• odebrat:

  • Tato metoda očekává jeden parametr:

    • klíč – klíč páru, který chcete odebrat

Jak používat rozhraní API místního úložiště

Pokud chcete použít rozhraní API místního úložiště, přidejte do pole oprávnění v možnostech vizuálu deklaraci.

Následující příklad ukazuje, jak nastavit a načíst data z místního úložiště pomocí verze 2 rozhraní API místního úložiště:

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

Úvahy a omezení

Důležité informace a omezení verze 1

• Limit místního úložiště je 1 MB na identifikátor GUID.
• Data je možné sdílet mezi vizuály pouze se stejným identifikátorem GUID.
• Data nejde sdílet s jinou instancí Power BI Desktopu.
• Rozhraní API místního úložiště není ve výchozím nastavení aktivované. Pokud ho chcete aktivovat pro vizuál Power BI, odešlete žádost podpoře pbicvsupport@microsoft.comvizuálů Power BI.
• Rozhraní API místního úložiště nepodporuje await konstrukce. Jsou povoleny pouze then metody a catch metody.

Vizuál by měl být dostupný v AppSource a měl by být certifikovaný.

Důležité informace a omezení verze 2

• Limit místního úložiště vlastních vizuálů je 100 kB.
• Data se dají sdílet mezi vizuály se stejným identifikátorem GUID, stejným prostředím a pouze pro stejného uživatele.
• Rozhraní API je podporováno v následujících prostředích:
  • Web
  • Desktop
  • Vložení SaaS
  • Mobilní
  • Server sestav
• Při exportu do PDF nebo pptx se nepodporuje místní úložiště.
• Rozhraní API se podporuje jenom v případech, kdy je uživatel přihlášený.
• Data vizuálu se vymažou 29 dní po poslední úpravě.
• Toto rozhraní API je privilegované rozhraní API.
• Klíč (parametr zadaný k nastavení, get, Remove) má následující omezení:
  • Délka musí být kratší než 128 znaků.
  • Znak | nemůže obsahovat.
• Pokud je prohlížeč v celoobrazovkovém režimu, může se dostupnost místního úložiště mezi prohlížeči lišit a podle nastavení vlastníka veřejného terminálu.
• Toto rozhraní API nemusí být podporované z mnoha důvodů. Prostředí se například nemusí podporovat nebo není dostupné místní úložiště prohlížeče. Před použitím metod set/get/remove doporučujeme zkontrolovat stav rozhraní API. Zpracování chyb je důležité, protože i když je rozhraní API podporované, může selhat.

Související obsah

• Rozhraní API vlastních vizuálů Power BI