API di 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 lil commutatore di amministrazione 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 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 di aggiornamento. 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.DisabledByAdmin: l'opzione dell'amministratore 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 ottenere, impostare o rimuovere, è consigliabile usare il metodo stato per controllare lo stato dell'API e assicurarsi che l'oggetto visivo si comporti come previsto.

• get:

  • Questo metodo prevede un parametro:

    • chiave - chiave di cui si vuole ottenere il valore.

  • Restituisce una promessa che si risolve con il valore se la chiave esiste e la rifiuta altrimenti.

• set:

  • Questo metodo prevede due parametri:

    • chiave – la chiave da impostare
    • dati – il valore della chiave

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

• remove:

  • Questo metodo prevede un parametro:

    • chiave – la 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 della 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 attivarla 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 le costruzioni await. Sono consentiti solo i metodi then e catch.

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

Considerazioni e limitazioni della 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
  • Dispositivi mobili
  • 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 in base alle impostazioni tutto schermo del proprietario.
• 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 imposta/ottieni/rimuovi. La gestione degli errori è importante perché, anche se l'API è supportata, potrebbe non riuscire.

Contenuto correlato

• API visiva personalizzata di Power BI