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, o comutador de administrador de armazenamento local do cliente deve estar habilitado.

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

Observação

É 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 confidencialidade dos dados assim o exigir. Em particular, os desenvolvedores visuais personalizados devem criptografar os dados se as metas ou cenários de negócios assim o esperarem.

Como usar o armazenamento local

Versão 1

Esta versão da API de armazenamento local está agendada para substituição. Não estamos aceitando mais solicitações. Quando possível, use 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 cada vez que o visual é iniciado. Dessa forma, o contador continuará contando de onde parou, em vez de iniciar sempre que o visual for 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:

• status:

  • Retorna o status da API de armazenamento local v2.

    • PrivilegeStatus.DisabledByAdmin: o comutador de administrador do locatário está desativado
    • 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 tem suporte (confira limitações para obter mais informações)
    • PrivilegeStatus.Allowed: a API tem suporte e é permitida

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

• obter:

  • Esse 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 o contrário.

• set:

  • Esse método espera dois parâmetros:

    • key – a chave que você deseja definir seu valor
    • data – o valor da chave

  • Retorna uma promessa que é resolvida para um struct do tipo StorageV2ResultInfo ou rejeita se ocorrer um erro.

• remove:

  • Esse método espera um parâmetro:

    • key – 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 da Versão 1

• O limite de armazenamento local é de 1 MB por GUID.
• Os dados podem ser compartilhados apenas entre visuais 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. Se desejar ativá-la para o seu visual do Power BI, envie uma solicitação para o suporte a visuais do Power BI, pbicvsupport@microsoft.com.
• A API de armazenamento local não dá suporte a construções await. Somente os métodos then e catch são permitidos.

O visual deve estar disponível em AppSource e ser certificado.

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

• O limite de armazenamento local de visuais personalizados é de 100 KB.
• Os dados podem ser compartilhados entre visuais com o mesmo GUID, o mesmo ambiente e somente para o mesmo usuário.
• A API tem suporte nos ambientes a seguir:
  • Web
  • Área de trabalho
  • Inserção de SaaS
  • Dispositivos móveis
  • Servidor de relatório
• Não há suporte para o armazenamento local ao exportar para PDF ou pptx.
• A API só tem suporte 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.
• Essa API é uma API privilegiada.
• A chave (parâmetro fornecido para set, getRemove) tem as seguintes restrições:
  • O comprimento deve ser menos de 128 caracteres
  • Não é possível conter o caractere ''|''
• Se o navegador estiver no modo de quiosque, a disponibilidade de armazenamento local poderá ser diferente entre os navegadores e de acordo com as configurações do proprietário do quiosque.
• Há muitos motivos pelos quais essa API pode não ter suporte. Por exemplo, o ambiente pode não ter suporte 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 tenha suporte, ela pode falhar.

Conteúdo relacionado

• API de visual personalizado do Power BI