API de armazenamento local

Com a API de armazenamento local, você pode armazenar dados no armazenamento local do navegador. Para usar a API de armazenamento local, a opção de administração de armazenamento local do cliente deve ser habilitada.

O armazenamento local é isolado para que cada tipo de visual tenha seu próprio acesso de armazenamento separado.

Nota

É responsabilidade do desenvolvedor garantir que os dados armazenados estejam em conformidade com as políticas organizacionais do consumidor e informar os usuários sobre quais informações são armazenadas, se a sensibilidade dos dados exigir. Em particular, os desenvolvedores visuais personalizados devem criptografar os dados se os objetivos ou cenários de negócios esperarem isso.

Como usar o armazenamento local

Versão 1

Esta versão da API de armazenamento local está agendada para descontinuação. Não aceitamos mais pedidos. Sempre que possível, utilize a Versão 2.

No exemplo a seguir, um contador é aumentado sempre que o método update é chamado. O valor do contador é salvo localmente e chamado sempre que o visual é iniciado. Desta forma, o contador continua contando de onde parou, em vez de começar de novo cada vez que o visual é iniciado:

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

Versão 2

Métodos de armazenamento local

A API de armazenamento local tem quatro métodos:

• Estado:

  • Retorna o status da API v2 de armazenamento local.

    • PrivilegeStatus.DisabledByAdmin: a opção de administrador do locatário está desativada
    • PrivilegeStatus.NotDeclared: o visual não tem nenhuma declaração para o armazenamento local na matriz de privilégios
    • PrivilegeStatus.NotSupported: a API não é suportada (consulte as limitações para obter mais informações)
    • PrivilegeStatus.Allowed: a API é suportada e permitida

  Antes de usar os métodos get, set ou remove , é uma prática recomendada usar o método status para verificar o status da API e garantir que seu visual se comporte conforme o esperado.

• Obtenha:

  • Este método espera um parâmetro:

    • key – a chave cujo valor você deseja obter.

  • Retorna uma promessa que é resolvida com o valor se a chave existir e rejeita de outra forma.

• conjunto:

  • Este método espera dois parâmetros:

    • chave – a chave que você deseja definir seu valor
    • dados – o valor para a chave

  • Retorna uma promessa que resolve para uma struct do tipo StorageV2ResultInfoou rejeita se ocorreu um erro.

• remover:

  • Este método espera um parâmetro:

    • chave – a chave do par que você deseja remover

Como usar a API de armazenamento local

Para usar a API de armazenamento local, adicione uma declaração à matriz de privilégios em recursos visuais.

O exemplo a seguir mostra como definir e recuperar dados do armazenamento local usando a versão 2 da API de armazenamento local:

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

Considerações e limitações

Considerações e limitações Versão 1

• O limite de armazenamento local é de 1 mb por GUID.
• Os dados podem ser compartilhados entre elementos visuais apenas com o mesmo GUID.
• Os dados não podem ser compartilhados com outra instância do Power BI Desktop.
• A API de armazenamento local não é ativada por padrão. Para ativá-lo para seu visual do Power BI, envie uma solicitação para o suporte visual do Power BI, pbicvsupport@microsoft.com.
• A API de armazenamento local não suporta await construções. Apenas then e catch métodos são permitidos.

Seu visual deve estar disponível no AppSource e ser certificado.

Considerações e limitações Versão 2

• O limite de armazenamento local de visuais personalizados é de 100 KB.
• Os dados podem ser compartilhados entre elementos visuais com o mesmo GUID, mesmo ambiente e apenas para o mesmo usuário.
• A API é suportada nos seguintes ambientes:
  • Web
  • Ambiente de Trabalho
  • Incorporação de SaaS
  • Móvel
  • Servidor de relatório
• O armazenamento local não é suportado ao exportar para PDF ou pptx.
• A API é suportada apenas quando um usuário está conectado.
• Os dados de um visual são limpos 29 dias após o tempo de modificação mais recente.
• Esta API é uma API privilegiada.
• A chave (parâmetro fornecido para definir, obter, remover) tem as seguintes restrições:
  • O comprimento deve ter menos de 128 caracteres
  • Não é possível conter o caractere '|'
• Se o navegador estiver no modo de quiosque, a disponibilidade de armazenamento local pode diferir entre navegadores e pelas configurações do proprietário do quiosque.
• Há muitas razões pelas quais essa API pode não ser suportada. Por exemplo, o ambiente pode não ser suportado ou o armazenamento local do navegador não está disponível. Recomendamos verificar o status da API antes de usar os métodos set/get/remove. O tratamento de erros é importante, pois mesmo que a API seja suportada, ela pode falhar.

Conteúdos relacionados

• API visual personalizada do Power BI