API Archiviazione locale

Con l'API di archiviazione locale è possibile archiviare i dati nella risorsa di archiviazione locale del browser. Per usare l'API di archiviazione locale, è necessario abilitare l'opzione di amministratore dell'archiviazione locale del cliente.

L'archiviazione locale è isolata in modo che ogni tipo di oggetto visivo abbia un accesso di archiviazione separato.

Nota

È responsabilità dello sviluppatore assicurarsi che i dati archiviati siano conformi ai criteri dell'organizzazione dell'utente e per informare gli utenti sulle informazioni archiviate, se la riservatezza dei dati lo richiede. In particolare, gli sviluppatori di oggetti visivi personalizzati devono crittografare i dati se gli obiettivi o gli scenari aziendali lo prevedono.

Come usare l'archiviazione locale

Versione 1

Questa versione dell'API di archiviazione locale è pianificata per la deprecazione. Non stiamo accettando altre richieste. Quando possibile, usare la versione 2.

Nell'esempio seguente un contatore viene aumentato ogni volta che viene chiamato il metodo update . Il valore del contatore viene salvato localmente e chiamato ogni volta che viene avviato l'oggetto visivo. In questo modo, il contatore continua a contare da dove è stato interrotto anziché ricominciare ogni volta che viene avviato l'oggetto visivo:

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

Versione 2

Metodi di archiviazione locale

L'API di archiviazione locale ha quattro metodi:

• status:

  • Restituisce lo stato dell'API di archiviazione locale v2.

    • PrivilegeStatus.DisabledBy Amministrazione: l'opzione dell'amministratore del tenant è disattivata
    • PrivilegeStatus.NotDeclared: l'oggetto visivo non ha alcuna dichiarazione per l'archiviazione locale nella matrice dei privilegi
    • PrivilegeStatus.NotSupported: l'API non è supportata (vedere limitazioni per altre informazioni)
    • PrivilegeStatus.Allowed: l'API è supportata e consentita

  Prima di usare i metodi get, set o remove , è consigliabile usare il metodo di stato per controllare lo stato dell'API e assicurarsi che l'oggetto visivo si comporti come previsto.

• get:

  • Questo metodo prevede un parametro:

    • key : chiave di cui si vuole ottenere il valore.

  • Restituisce una promessa che viene risolta con il valore se la chiave esiste e rifiuta in caso contrario.

• set:

  • Questo metodo prevede due parametri:

    • key : chiave che si desidera impostare il relativo valore
    • data : valore per la chiave

  • Restituisce una promessa che viene risolta in uno struct del tipo StorageV2ResultInfoo rifiuta se si è verificato un errore.

• remove:

  • Questo metodo prevede un parametro:

    • key : chiave della coppia da rimuovere

Come usare l'API di archiviazione locale

Per usare l'API di archiviazione locale, aggiungere una dichiarazione alla matrice di privilegi nelle funzionalità visive.

L'esempio seguente illustra come impostare e recuperare dati dall'archiviazione locale usando la versione 2 dell'API di archiviazione locale:

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

Considerazioni e limitazioni

Considerazioni e limitazioni versione 1

• Il limite di archiviazione locale è 1 mb per GUID.
• I dati possono essere condivisi solo tra oggetti visivi con lo stesso GUID.
• I dati non possono essere condivisi con un'altra istanza di Power BI Desktop.
• L'API di archiviazione locale non è attivata per impostazione predefinita. Per attivarlo per l'oggetto visivo di Power BI, inviare una richiesta al supporto degli oggetti visivi di Power BI, pbicvsupport@microsoft.com.
• L'API di archiviazione locale non supporta await le costruzioni. Sono consentiti solo then i metodi e catch .

L'oggetto visivo deve essere disponibile in AppSource e deve essere certificato.

Considerazioni e limitazioni versione 2

• Il limite di archiviazione locale degli oggetti visivi personalizzati è 100 KB.
• I dati possono essere condivisi tra oggetti visivi con lo stesso GUID, lo stesso ambiente e solo per lo stesso utente.
• L'API è supportata negli ambienti seguenti:
  • Web
  • Desktop
  • Incorporamento SaaS
  • Mobile
  • Server di report
• L'archiviazione locale non è supportata durante l'esportazione in FORMATO PDF o pptx.
• L'API è supportata solo quando un utente ha eseguito l'accesso.
• I dati di un oggetto visivo vengono cancellati 29 giorni dopo l'ora di modifica più recente.
• Questa API è un'API con privilegi.
• La chiave (parametro fornito per impostare, ottenere, rimuovere) presenta le restrizioni seguenti:
  • La lunghezza deve essere inferiore a 128 caratteri
  • Impossibile contenere il carattere '|'
• Se il browser è in modalità tutto schermo, la disponibilità dell'archiviazione locale potrebbe variare tra i browser e le impostazioni del proprietario del chiosco multimediale.
• Questa API potrebbe non essere supportata per molti motivi. Ad esempio, l'ambiente potrebbe non essere supportato o l'archiviazione locale del browser non è disponibile. È consigliabile controllare lo stato dell'API prima di usare i metodi set/get/remove . La gestione degli errori è importante perché, anche se l'API è supportata, potrebbe non riuscire.

Contenuto correlato

• API visiva personalizzata di Power BI