本機 儲存體 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.DisabledBy 管理員：租用戶系統管理員切換已關閉
    • PrivilegeStatus.NotDeclared：視覺效果在 privileges 陣列中沒有本機記憶體的宣告
    • PrivilegeStatus.NotSupported：不支援 API（如需詳細資訊，請參閱 限制 ）
    • PrivilegeStatus.Allowed：支持和允許 API

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

• get：

  • 此方法需要一個參數：

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

  • 傳回承諾，如果索引鍵存在，則會使用 值解析，否則會拒絕。

• set：

  • 此方法需要兩個參數：

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

  • 傳回會解析為 型StorageV2ResultInfo別結構的承諾，如果發生錯誤，則拒絕。

• remove：

  • 此方法需要一個參數：

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

如何使用本機記憶體 API

若要使用本機記憶體 API，請在視覺功能中將宣告新增至 privileges 陣列。

下列範例示範如何使用本機記憶體 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
  • Desktop (電腦)
  • SaaS 內嵌
  • 行動
  • 報表伺服器
• 匯出至 PDF 或 pptx 時不支援本機記憶體。
• 只有在使用者登入時，才支援 API。
• 視覺效果的數據會在最近的修改時間之後 29 天清除。
• 此 API 是 具特殊許可權的 API。
• 金鑰（提供給 設定、 取得、 移除） 的索引鍵具有下列限制：
  • 長度必須少於 128 個字元
  • 不能包含字元 '|'
• 如果瀏覽器處於 kiosk 模式，則瀏覽器之間的本機記憶體可用性可能會有所不同，以及 kiosk 擁有者的設定。
• 此 API 有許多原因可能不受支援。 例如，環境可能不受支援，或瀏覽器的本機記憶體無法使用。 建議您先檢查 API 的狀態 ，再使用 set/get/remove 方法。 錯誤處理很重要，因為即使支援 API，也可能失敗。

相關內容

• Power BI 自定義視覺效果 API