Yerel Depolama API'si

Yerel depolama API'siyle, verileri tarayıcının yerel depolama alanında depolayabilirsiniz. Yerel depolama API'sini kullanmak için müşterinin yerel depolama yönetici anahtarının etkinleştirilmesi gerekir.

Yerel depolama, her görsel türünün kendi ayrı depolama erişimine sahip olması için yalıtılır.

Not

Depolanan verilerin tüketicinin kuruluş ilkelerine uygun olduğundan emin olmak ve verilerin duyarlılığı gerektiriyorsa, hangi bilgilerin depolandığı konusunda kullanıcıları bilgilendirmek geliştiricinin sorumluluğundadır. Özellikle, özel görsel geliştiricilerin iş hedefleri veya senaryolar bunu bekliyorsa verileri şifrelemesi gerekir.

Yerel depolamayı kullanma

Sürüm 1

Yerel depolama API'sinin bu sürümü kullanımdan kaldırılması için zamanlanmıştır. Başka istek kabul etmeyeceğiz. Mümkün olduğunda Sürüm 2'yi kullanın.

Aşağıdaki örnekte, güncelleştirme yöntemi her çağrıldığında bir sayaç artırılır. Sayaç değeri yerel olarak kaydedilir ve görsel her başlatıldığında çağrılır. Bu şekilde sayaç, görsel her başlatıldığında başlamak yerine kaldığı yerden saymaya devam eder:

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

Sürüm 2

Yerel depolama yöntemleri

Yerel depolama API'sinin dört yöntemi vardır:

• durum:

  • Yerel depolama v2 API'sinin durumunu döndürür.

    • PrivilegeStatus.DisabledBy Yönetici: Kiracı yönetici anahtarı kapalı
    • PrivilegeStatus.NotDeclared: Görselde privileges dizisindeki yerel depolama için bildirim yok
    • PrivilegeStatus.NotSupported: API desteklenmiyor (daha fazla bilgi için sınırlamalara bakın)
    • PrivilegeStatus.Allowed: API desteklenir ve izin verilir

  Alma, ayarlama veya kaldırma yöntemlerini kullanmadan önce, API'nin durumunu denetlemek ve görselinizin beklendiği gibi davrandığından emin olmak için durum yöntemini kullanmak en iyi yöntemdir.

• get:

  • Bu yöntem bir parametre bekler:

    • key – değerini almak istediğiniz anahtar.

  • Anahtar varsa değeriyle çözümleyen ve aksini reddeden bir söz döndürür.

• set:

  • Bu yöntem iki parametre bekler:

    • key – değerini ayarlamak istediğiniz anahtar
    • data – anahtarın değeri

  • türündeki StorageV2ResultInfobir yapıya çözümleyen veya hata oluştuğunda reddeden bir söz döndürür.

• kaldır:

  • Bu yöntem bir parametre bekler:

    • key – kaldırmak istediğiniz çiftin anahtarı

Yerel depolama API'sini kullanma

Yerel depolama API'sini kullanmak için görsel özelliklerdeki privileges dizisine bir bildirim ekleyin.

Aşağıdaki örnekte, yerel depolama API'sinin 2. sürümünü kullanarak yerel depolamadan veri ayarlama ve yerel depolamadan veri alma gösterilmektedir:

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

Dikkat edilecekler ve sınırlamalar

Önemli noktalar ve sınırlamalar Sürüm 1

• Yerel depolama sınırı GUID başına 1 MB'tır.
• Veriler yalnızca aynı GUID'ye sahip görseller arasında paylaşılabilir.
• Veriler başka bir Power BI Desktop örneğiyle paylaşılamaz.
• Yerel depolama API'si varsayılan olarak etkinleştirilmez. Power BI görselinizde etkinleştirmek için Power BI görselleri desteğine bir istek gönderin. pbicvsupport@microsoft.com
• Yerel depolama API'si yapıları desteklemez await . Yalnızca then ve catch yöntemlerine izin verilir.

Görselinizin AppSource'ta kullanılabilir olması ve sertifikalı olması gerekir.

Önemli noktalar ve sınırlamalar Sürüm 2

• Özel görseller yerel depolama sınırı 100 KB'tır.
• Veriler aynı GUID'ye, aynı ortama sahip görseller arasında ve yalnızca aynı kullanıcı için paylaşılabilir.
• API aşağıdaki ortamlarda desteklenir:
  • Web
  • Masaüstü
  • SaaS Ekleme
  • Mobil
  • Rapor Sunucusu
• PDF veya pptx'e aktarıldığında yerel depolama desteklenmez.
• API yalnızca bir kullanıcı oturum açtığında desteklenir.
• Bir görselin verileri, en son değişiklik zamanından 29 gün sonra temizlenir.
• Bu API ayrıcalıklı bir API'dir.
• Anahtar (ayarlamak, almak, Kaldırmak için sağlanan parametre) aşağıdaki kısıtlamalara sahiptir:
  • Uzunluk 128 karakterden az olmalıdır
  • '|' karakteri içeremez
• Tarayıcı bilgi noktası modundaysa, yerel depolama kullanılabilirliği tarayıcılar arasında ve bilgi noktası sahibinin ayarlarına göre farklılık gösterebilir.
• Bu API'nin desteklenmemesi için birçok neden vardır. Örneğin, ortam desteklenmiyor veya tarayıcının yerel depolama alanı kullanılamıyor olabilir. Set/get/remove yöntemlerini kullanmadan önce API'nin durumunu denetlemenizi öneririz. API destekleniyor olsa bile başarısız olabileceğinden hata işleme önemlidir.

İlgili içerik

• Power BI özel görsel API'si