本機存放區 API

使用本機存放區 API，您即可將資料儲存在瀏覽器的本機存放區中。 若要使用本機存放區 API，客戶的本機存放區管理員切換控制必須已啟用。

本機存放區會隔離，以便每種視覺效果類型都有自己單獨的存放區存取權。

注意

開發人員有責任確保儲存的資料符合取用者的組織原則，並在資料的敏感度需要時通知使用者儲存了哪些資訊。 特別是，如果商務目標或案例需要，則自訂視覺效果開發人員應該加密資料。

如何使用本機存放區

第 1 版

此版本的本機存放區 API 已排定淘汰。 我們不會再接受任何要求。 可能的話，請使用第 2 版。

在下列範例中，每當呼叫 update 方法時，就會增加計數器。 計數器值會儲存在本機，每次視覺效果啟動時即會呼叫該值。 如此一來，計數器就會從離開的位置繼續計數，而不是在每次啟動視覺效果時重新開始：

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

第 2 版

本機存放區方法

本機存放區 API 有四種方法：

• status：

  • 傳回本機存放區 v2 API 的狀態。

    • PrivilegeStatus.DisabledByAdmin：租用戶系統管理員切換控制已關閉
    • PrivilegeStatus.NotDeclared：視覺效果在權限陣列中不具有本機存放區的宣告
    • PrivilegeStatus.NotSupported：不支援 API (如需詳細資訊，請參閱限制)
    • PrivilegeStatus.Allowed：支援和允許 API

  在使用 get、set 或 remove 方法之前，最佳做法是使用 status 方法檢查 API 的狀態，並確保您的視覺效果如預期運作。

• get：

  • 此方法需要一個參數：

    • Key – 您要取得其值的索引鍵。

  • 如果索引鍵存在，則傳回使用該值解析的 Promise，否則拒絕。

• set：

  • 此方法需要兩個參數：

    • Key – 您想要設定其值的索引鍵
    • data – 索引鍵的值

  • 傳回會解析為類型 StorageV2ResultInfo 的 struct 的 Promise，如果發生錯誤，則拒絕。

• remove：

  • 此方法需要一個參數：

    • Key – 您要移除的配對索引鍵

如何使用本機存放區 API

若要使用本機存放區 API，請將宣告新增至視覺效果功能中的權限陣列。

下列範例會顯示如何使用本機存放區 API 第 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); 
        } 
    } 
} 

考量與限制

考量與限制第 1 版

• 本機存放區限制是每個 GUID 1 MB。
• 只有相同的 GUID 才能在視覺效果之間共用資料。
• 資料無法與 Power BI Desktop 的另一個執行個體共用。
• 預設不會啟用本機存放區 API。 若要針對您的 Power BI 視覺效果加以啟動，請將要求傳送給 Power BI 視覺效果支援 pbicvsupport@microsoft.com。
• 本機存放區 API 不支援 await 建構。 只允許 then 和 catch 方法。

您的視覺效果應該在 AppSource 中提供，且經過認證。

考量與限制第 2 版

• 自訂視覺效果本機存放區限制為 100 KB。
• 只有相同的 GUID、相同環境，以及相同使用者才能在視覺效果之間共用資料。
• 下列環境支援 API：
  • Web
  • 桌面
  • SaaS 內嵌
  • 行動
  • 報表伺服器
• 匯出至 PDF 或 pptx 時不支援本機存放區。
• 只有在使用者登入時，才支援 API。
• 視覺效果的資料會在最近的修改時間之後的 29 天清除。
• 此 API 是具特殊權限的 API。
• 該索引鍵 (提供給 set、get、Remove 的參數) 具有下列限制：
  • 文字必須少於 128 個字元
  • 不能包含字元「|」
• 如果瀏覽器處於 kiosk 模式，則本機存放區可用性可能會因瀏覽器以及 kiosk 擁有者的設定而異。
• 不支援此 API 的原因有很多。 例如，環境可能不受支援，或瀏覽器的本機存放區無法使用。 建議您先檢查 API 的 status，再使用 set/get/remove 方法。 錯誤處理很重要，因為即使支援 API，也可能失敗。

相關內容

• Power BI 自訂視覺效果 API