API Penyimpanan Lokal

Dengan API penyimpanan lokal, Anda dapat menyimpan data di penyimpanan lokal browser. Untuk menggunakan API penyimpanan lokal, pengalihan admin penyimpanan lokal pelanggan harus diaktifkan.

Penyimpanan lokal diisolasi sehingga setiap jenis visual memiliki akses penyimpanan terpisah.

Catatan

Pengembang bertanggung jawab untuk memastikan bahwa data yang disimpan sesuai dengan kebijakan organisasi konsumen, dan untuk memberi tahu pengguna tentang informasi apa yang disimpan, jika sensitivitas data memerlukannya. Secara khusus, pengembang visual kustom harus mengenkripsi data jika tujuan atau skenario bisnis mengharapkannya.

Cara menggunakan penyimpanan lokal

Versi 1

Versi API penyimpanan lokal ini dijadwalkan untuk penghentian. Kami tidak menerima permintaan lagi. Jika memungkinkan, gunakan Versi 2.

Dalam contoh berikut, penghitung ditingkatkan setiap kali metode pembaruan dipanggil. Nilai penghitung disimpan secara lokal dan dipanggil setiap kali visual dimulai. Dengan cara ini, penghitung terus menghitung dari tempat penghitungan ditinggalkan alih-alih memulai setiap kali visual dimulai:

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 2

Metode penyimpanan lokal

API penyimpanan lokal memiliki empat metode:

• status:

  • Mengembalikan status API penyimpanan lokal v2.

    • PrivilegeStatus.DisabledByAdmin: sakelar admin penyewa nonaktif
    • PrivilegeStatus.NotDeclared: visual tidak memiliki deklarasi untuk penyimpanan lokal dalam array hak istimewa
    • PrivilegeStatus.NotSupported: API tidak didukung (lihat batasan untuk informasi selengkapnya)
    • PrivilegeStatus.Allowed: API didukung dan diizinkan

  Sebelum menggunakan metode get, set, atau remove , sebaiknya gunakan metode status untuk memeriksa status API dan memastikan bahwa visual Anda berperilaku seperti yang diharapkan.

• dapatkan:

  • Metode ini mengharapkan satu parameter:

    • key – kunci yang nilainya ingin Anda dapatkan.

  • Mengembalikan janji yang diselesaikan dengan nilai jika kunci ada, dan menolak sebaliknya.

• set:

  • Metode ini mengharapkan dua parameter:

    • key – kunci yang ingin Anda tetapkan nilainya
    • data – nilai untuk kunci

  • Mengembalikan janji yang diselesaikan ke struct jenis StorageV2ResultInfo, atau menolak jika terjadi kesalahan.

• hapus:

  • Metode ini mengharapkan satu parameter:

    • kunci – kunci pasangan yang ingin Anda hapus

Cara menggunakan API penyimpanan lokal

Untuk menggunakan API penyimpanan lokal, tambahkan deklarasi ke array hak istimewa dalam kemampuan visual.

Contoh berikut menunjukkan cara mengatur dan mengambil data dari penyimpanan lokal menggunakan api penyimpanan lokal versi 2:

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

Pertimbangan dan batasan

Pertimbangan dan batasan Versi 1

• Batas penyimpanan lokal adalah 1 mb per GUID.
• Data hanya dapat dibagikan antar visual dengan GUID yang sama.
• Data tidak dapat dibagikan dengan instans Power BI Desktop lain.
• API penyimpanan lokal tidak diaktifkan secara default. Untuk mengaktifkannya untuk visual Power BI Anda, kirim permintaan ke dukungan visual Power BI, pbicvsupport@microsoft.com.
• API penyimpanan lokal tidak mendukung await konstruksi. Hanya metode then dan catch yang diizinkan.

Visual Anda harus tersedia di AppSource dan disertifikasi.

Pertimbangan dan batasan Versi 2

• Batas penyimpanan lokal visual kustom adalah 100 KB.
• Data dapat dibagikan antara visual dengan GUID yang sama, lingkungan yang sama, dan hanya untuk pengguna yang sama.
• API didukung di lingkungan berikut:
  • Web
  • Desktop
  • SaaS Embed
  • Seluler
  • Server Laporan
• Penyimpanan lokal tidak didukung saat Mengekspor ke PDF atau pptx.
• API hanya didukung saat pengguna masuk.
• Data visual dibersihkan 29 hari setelah waktu modifikasi terbaru.
• API ini adalah API istimewa.
• Kunci (parameter yang disediakan untuk mengatur, mendapatkan, Menghapus) memiliki batasan berikut:
  • Panjangnya harus kurang dari 128 karakter
  • Tidak boleh berisi karakter '|'
• Jika browser dalam mode kios, ketersediaan penyimpanan lokal mungkin berbeda antara browser, dan oleh pengaturan pemilik kios.
• Ada banyak alasan API ini mungkin tidak didukung. Misalnya, lingkungan mungkin tidak didukung atau penyimpanan lokal browser tidak tersedia. Sebaiknya periksa status API sebelum menggunakan metode set/get/remove . Penanganan kesalahan penting karena bahkan jika API didukung, mungkin gagal.

Konten terkait

• Power BI API visual kustom