API de almacenamiento local

Con la API de almacenamiento local, puede almacenar datos en el almacenamiento local del explorador. Para usar la API de almacenamiento local, el conmutador de administrador de almacenamiento localdel cliente debe estar habilitado.

El almacenamiento local está aislado para que cada tipo de objeto visual tenga su propio acceso de almacenamiento independiente.

Nota:

Es responsabilidad del desarrollador asegurarse de que los datos almacenados se ajustan a las directivas organizativas del consumidor y de informar a los usuarios sobre qué información se almacena, si la confidencialidad de los datos lo requiere. En concreto, los desarrolladores visuales personalizados deben cifrar los datos si los objetivos empresariales o los escenarios lo esperan.

Procedimiento para usar el almacenamiento local

Versión 1

Esta versión de la API de almacenamiento local está programada para desuso. No aceptamos más solicitudes. Cuando sea posible, use la versión 2.

En el ejemplo siguiente, se aumenta un contador cada vez que se llama al método update. El valor del contador se guarda localmente y se llama cada vez que se inicia el objeto visual. De este modo, el contador continúa contando desde donde lo ha dejado en lugar de empezar de cero cada vez que se inicia el objeto visual:

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

Versión 2

Métodos de almacenamiento local

La API de almacenamiento local tiene cuatro métodos:

• status:

  • Devuelve el estado de la API de almacenamiento local v2.

    • PrivilegeStatus.DisabledByAdmin: el modificador de administrador de inquilinos está desactivado
    • PrivilegeStatus.NotDeclared: el objeto visual no tiene ninguna declaración para el almacenamiento local en la matriz de privilegios
    • PrivilegeStatus.NotSupported: no se admite la API (vea limitaciones para obtener más información)
    • PrivilegeStatus.Allowed: la API se admite y se permite

  Antes de usar el obtener, establecero quitar métodos, se recomienda usar el método de estado para comprobar el estado de la API y asegurarse de que el objeto visual se comporta según lo previsto.

• obtener:

  • Este método espera un parámetro:

    • clave: la clave cuyo valor desea obtener.

  • Devuelve una promesa que se resuelve con el valor si la clave existe y rechaza de lo contrario.

• set:

  • Este método espera dos parámetros:

    • clave: la clave que desea establecer su valor
    • datos: el valor de la clave

  • Devuelve una promesa que se resuelve en una estructura del tipo StorageV2ResultInfoo rechaza si se produjo un error.

• remove:

  • Este método espera un parámetro:

    • clave: la clave del par que desea quitar

Uso de la API de almacenamiento local

Para usar la API de almacenamiento local, agregue una declaración a la matriz de privilegios en las funcionalidades visuales.

En el ejemplo siguiente se muestra cómo establecer y recuperar datos del almacenamiento local mediante la versión 2 de la API de almacenamiento 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); 
        } 
    } 
} 

Consideraciones y limitaciones

Consideraciones y limitaciones de la versión 1

• El límite de almacenamiento local es de 1 mb por GUID.
• Los datos solo se pueden compartir entre objetos visuales con el mismo GUID.
• Los datos no se pueden compartir con otra instancia de Power BI Desktop.
• La API de almacenamiento local no está activada de forma predeterminada. Para activarla para el objeto visual de Power BI, envíe una solicitud al equipo de soporte técnico de objetos visuales de Power BI, pbicvsupport@microsoft.com.
• La API de almacenamiento local no admite construcciones await. Solo se permiten los métodos then y catch.

El objeto visual debe estar disponible en AppSource y estar certificado.

Consideraciones y limitaciones de versión 2

• El límite de almacenamiento local de objetos visuales personalizados es de 100 KB.
• Los datos se pueden compartir entre objetos visuales con el mismo GUID, el mismo entorno y solo para el mismo usuario.
• La API se admite en los siguientes entornos:
  • Web
  • Escritorio
  • Inserción de SaaS
  • Móvil
  • Servidor de informes
• No se admite el almacenamiento local al exportar a PDF o pptx.
• La API solo se admite cuando un usuario ha iniciado sesión.
• Los datos de un objeto visual se borran 29 días después de la hora de modificación más reciente.
• Esta API es una API con privilegios.
• La clave (parámetro proporcionado para establecer, obtener, Quitar) tiene las restricciones siguientes:
  • La longitud debe tener menos de 128 caracteres.
  • No se puede contener el carácter '|'
• Si el explorador está en modo de pantalla completa, la disponibilidad del almacenamiento local puede diferir entre los exploradores y la configuración del propietario del quiosco.
• Es posible que no se admita esta API. Por ejemplo, es posible que el entorno no se admita o que el almacenamiento local del explorador no esté disponible. Se recomienda comprobar el estado de la API antes de usar los métodos set/get/remove . El control de errores es importante, ya que incluso si se admite la API, podría producirse un error.

Contenido relacionado

• API de objeto visual personalizado de Power BI