API de stockage local

L’API de stockage local vous permet de stocker des données dans le stockage local du navigateur. Pour utiliser l’API de stockage local, le commutateur d’administration du stockage local du client doit être activé.

Le stockage local est isolé afin que chaque type de visuel dispose de son propre accès de stockage distinct.

Remarque

Il incombe au développeur de s’assurer que les données stockées sont conformes aux stratégies organisationnelles du consommateur et d’informer les utilisateurs des informations stockées, si la sensibilité des données l’exige. En particulier, les développeurs de visuels personnalisés doivent chiffrer les données si les objectifs ou scénarios métier s’attendent à ce qu’elles soient chiffrées.

Comment utiliser le stockage local

Version 1

Cette version de l’API de stockage local sera prochainement dépréciée. Nous n’acceptons plus de requêtes. Si possible, utilisez la version 2.

Dans l’exemple suivant, un compteur est augmenté chaque fois que la méthode update est appelée. La valeur du compteur est enregistrée localement et appelée chaque fois que le visuel démarre. Ainsi, le compteur continue à compter là où il s’était arrêté au lieu de recommencer à chaque démarrage du visuel :

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

Version 2

Méthodes de stockage local

L’API de stockage local comprend quatre méthodes :

• status :

  • Retourne l’état de l’API de stockage local v2.

    • PrivilegeStatus.DisabledByAdmin : le commutateur d’administration du locataire est désactivé
    • PrivilegeStatus.NotDeclared : le visuel n’a pas de déclaration pour le stockage local dans le tableau de privilèges
    • PrivilegeStatus.NotSupported : l’API n’est pas prise en charge (pour plus d’informations, consultez les limitations)
    • PrivilegeStatus.Allowed : l’API est prise en charge et autorisée

  Avant d’utiliser les méthodes get, set ou remove, nous vous recommandons d’utiliser la méthode status pour vérifier l’état de l’API et vous assurer que votre visuel se comporte comme prévu.

• get :

  • Cette méthode attend un paramètre :

    • key : clé dont vous souhaitez obtenir la valeur.

  • Retourne une promesse qui est résolue avec la valeur si la clé existe ; sinon, elle est rejetée.

• set :

  • Cette méthode attend deux paramètres :

    • key : clé dont vous souhaitez définir la valeur
    • data : valeur de la clé

  • Retourne une promesse qui est résolue en struct du type StorageV2ResultInfo ou qui est rejetée en cas d’erreur.

• remove :

  • Cette méthode attend un paramètre :

    • key : clé de la paire que vous souhaitez supprimer

Comment utiliser l’API de stockage local

Pour utiliser l’API de stockage local, ajoutez une déclaration au tableau de privilèges dans les fonctionnalités des visuels.

L’exemple suivant montre comment définir et récupérer des données à partir du stockage local en utilisant la version 2 de l’API de stockage 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); 
        } 
    } 
} 

Observations et limitations

Considérations et limitations (version 1)

• La limite de stockage local est de 1 Mo par GUID.
• Les données peuvent être partagées uniquement entre les visuels ayant le même GUID.
• Les données ne peuvent pas être partagées avec une autre instance de Power BI Desktop.
• L’API de stockage local n’est pas activée par défaut. Afin de l’activer pour votre visuel Power BI, envoyez une demande au support technique des visuels Power BI à l’adresse pbicvsupport@microsoft.com.
• L’API de stockage local ne prend pas en charge les constructions await. Seules les méthodes then et catch sont autorisées.

Votre visuel doit être disponible dans AppSource et être certifié.

Considérations et limitations (version 2)

• La limite de stockage locale des visuels personnalisés est de 100 Ko.
• Vous pouvez partager des données entre visuels avec le même GUID, le même environnement et pour le même utilisateur uniquement.
• L’API est prise en charge dans les environnements suivants :
  • web
  • Bureau
  • Incorporation SaaS
  • Mobile
  • Serveur de rapports
• Le stockage local n’est pas pris en charge si vous choisissez le format d’exportation PDF ou pptx.
• L’API est uniquement prise en charge lorsqu’un utilisateur est connecté.
• Les données d’un visuel sont effacées 29 jours après l’heure de modification la plus récente.
• Cette API est une API privilégiée.
• Le paramètre key fourni aux méthodes set, get et remove présente les restrictions suivantes :
  • Doit comporter moins de 128 caractères
  • Ne peut pas contenir le caractère « | »
• Si le navigateur est en mode kiosque, la disponibilité du stockage local peut différer entre les navigateurs et selon les paramètres du propriétaire du kiosque.
• Les raisons pour lesquelles cette API peut ne pas être prise en charge sont nombreuses. Par exemple, l’environnement peut ne pas être pris en charge ou le stockage local du navigateur n’est pas disponible. Nous vous recommandons de vérifier l’état (status) de l’API avant d’utiliser les méthodes set/get/remove. La gestion des erreurs est importante, car l’API peut échouer même si elle est prise en charge.

Contenu connexe

• API des visuels personnalisés Power BI