ローカル ストレージ API

ローカル ストレージ API を使用すると、ブラウザーのローカル ストレージにデータを格納できます。 ローカル ストレージ API を使用するには、顧客の ローカル ストレージ管理者スイッチ を有効にする必要があります。

ローカル ストレージは孤立しており、各種のビジュアルに個々のストレージ アクセスが与えられます。

Note

保存されたデータがコンシューマーの組織ポリシーに準拠していることを確認し、データの秘密度で必要な場合に、格納される情報についてユーザーに通知するのは開発者の責任です。 特に、カスタム ビジュアル開発者は、ビジネスの目標やシナリオで求められる場合はデータを暗号化する必要があります。

ローカル ストレージの使用方法

Version 1

このバージョンの ローカル ストレージ API は廃止予定です。 新規の要求は受け付けていません。 可能な場合は、バージョン 2 を使用してください。

次の例では、"更新" メソッドが呼び出されるたびにカウンターが増えます。 カウンターの値はローカルで保存され、ビジュアルが起動するたびに呼び出されます。 このように、カウンターは最後にカウントしたところからカウントを続けます。ビジュアルの起動のたびに最初から始めることはありません。

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

Version 2

ローカル ストレージ メソッド

ローカル ストレージ API には、次の 4 つの方法があります:

• status:

  • ローカル ストレージ v2 API の状態を返します。

    • PrivilegeStatus.DisabledByAdmin: テナント管理者スイッチがオフです
    • PrivilegeStatus.NotDeclared: ビジュアルには、特権配列内のローカル ストレージの宣言がありません
    • PrivilegeStatus.NotSupported: API はサポートされていません (詳細については、「制限事項」を参照してください)
    • PrivilegeStatus.Allowed: API はサポートされ、許可されています

  get、set、または remove メソッドを使用する前に、status メソッドを使用して API の状態を確認し、ビジュアルが期待どおりに動作することを確認することをお勧めします。

• 取得:

  • このメソッドには、1 つのパラメーターが必要です:

    • key – 取得したい値を持つキー。

  • キーが存在する場合は値で解決される Promise を返し、それ以外の場合は拒否します。

• set:

  • このメソッドには、2 つのパラメーターが必要です:

    • key – 値を設定したいキー
    • data – キーの値

  • 型 StorageV2ResultInfo の 構造体 に解決される Promise を返すか、エラーが発生した場合には拒否します。

• remove:

  • このメソッドには、1 つのパラメーターが必要です:

    • 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 を同じくするビジュアル間でのみ共有できます。
• データは PowerBI Desktop の別インスタンスと共有できません。
• ローカル ストレージ API は既定ではアクティブになっていません。 Power BI ビジュアルに対してアクティブにするには、要求を Power BI ビジュアル サポート (pbicvsupport@microsoft.com) に送信します。
• ローカル ストレージ API では、コンストラクタでの await はサポートされていません。 許可されるのは、then および catch メソッドのみです。

ビジュアルが AppSource で利用可能であり、認定されている必要があります。

バージョン 2 の考慮事項と制限事項

• カスタム ビジュアルのローカル ストレージの制限は 100 KB です。
• データは、同じ GUID、同じ環境、および同じユーザーに対してのみビジュアル間で共有できます。
• API は、次の環境でサポートされています:
  • Web
  • デスクトップ
  • SaaS 埋め込み
  • Mobile
  • レポート サーバー
• PDF または pptx にエクスポートする場合、ローカル ストレージはサポートされません。
• API は、ユーザーがサインインしている場合にのみサポートされます。
• ビジュアルのデータは、最新の変更時刻から 29 日後に消去されます。
• この API は特権 API です。
• キー (set、get、remove に指定されたパラメーター) には、次の制限があります:
  • 128 文字未満である必要があります
  • 文字 '|' を含めることはできません
• ブラウザーがキオスク モードの場合、ローカル ストレージの可用性はブラウザーとキオスク所有者の設定によって異なる場合があります。
• この API がサポートされない理由は多数あります。 たとえば、環境がサポートされていない場合や、ブラウザーのローカル ストレージが使用できない場合があります。 set/get/remove メソッドを 使用する前に、API の状態を確認することをお勧めします。 API がサポートされている場合でも失敗する可能性があるため、エラー処理は重要です。

関連するコンテンツ

• Power BI カスタム ビジュアル API