API локального хранилища

С помощью API локального хранилища можно хранить данные в локальном хранилище браузера. Чтобы использовать API локального хранилища, необходимо включить параметр локального администратора хранилища клиента.

Локальное хранилище изолировано, чтобы каждый тип визуального элемента имеет собственный отдельный доступ к хранилищу.

Примечание.

Разработчик несет ответственность за обеспечение соответствия хранимых данных политикам организации потребителя и информирование пользователей о том, какие сведения хранятся, если чувствительность данных требует его. В частности, пользовательские разработчики визуальных элементов должны шифровать данные, если бизнес-цели или сценарии ожидают его.

Использование локального хранилища

Версия 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());
            // ...
        }
}

Версия 2

Методы локального хранилища

API локального хранилища имеет четыре метода:

• status.

  • Возвращает состояние API локального хранилища версии 2.

    • PrivilegeStatus.DisabledByAdmin: отключен параметр администратора клиента
    • PrivilegeStatus.NotDeclared: визуальный элемент не имеет объявления для локального хранилища в массиве привилегий
    • PrivilegeStatus.NotSupported: API не поддерживается (см . ограничения для получения дополнительных сведений )
    • PrivilegeStatus.Allowed: API поддерживается и разрешено

  Прежде чем использовать метод get, set или remove , рекомендуется использовать метод состояния , чтобы проверить состояние API и убедиться, что визуальный элемент работает должным образом.

• get.

  • Этот метод ожидает один параметр:

    • ключ — ключ , значение которого требуется получить.

  • Возвращает обещание, которое разрешается со значением, если ключ существует, и отклоняет в противном случае.

• set.

  • Этот метод ожидает два параметра:

    • key — ключ , который необходимо задать для его значения.
    • data — значение ключа

  • Возвращает обещание, которое разрешает структуру типа StorageV2ResultInfoили отклоняет, если произошла ошибка.

• remove.

  • Этот метод ожидает один параметр:

    • key — ключ пары, которую вы хотите удалить

Использование API локального хранилища

Чтобы использовать API локального хранилища, добавьте объявление в массив привилегий в визуальных возможностях.

В следующем примере показано, как задать и извлечь данные из локального хранилища с помощью версии 2 локального API хранилища:

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

• Ограничение локального хранилища составляет 1 МБ на GUID.
• Данные можно совместно использовать между визуальными элементами только с тем же ИДЕНТИФИКАТОРом GUID.
• Невозможно предоставить общий доступ к данным другому экземпляру Power BI Desktop.
• По умолчанию API локального хранилища не активируется. Чтобы активировать его для визуального элемента Power BI, отправьте запрос в поддержку pbicvsupport@microsoft.comвизуальных элементов Power BI.
• API локального хранилища не поддерживает await конструкции. Разрешены только then методы.catch

Визуальный элемент должен быть доступен в AppSource и быть сертифицирован.

Рекомендации и ограничения версии 2

• Ограничение локального хранилища пользовательских визуальных элементов составляет 100 КБ.
• Данные можно совместно использовать между визуальными элементами с одинаковым ИДЕНТИФИКАТОРом GUID, одной средой и только для одного пользователя.
• API поддерживается в следующих средах:
  • Интернет
  • Персональный компьютер
  • Внедрение SaaS
  • Мобильные службы
  • ReportServer
• Локальное хранилище не поддерживается при экспорте в PDF или pptx.
• API поддерживается только при входе пользователя.
• Данные визуального элемента очищаются через 29 дней после последнего времени изменения.
• Этот API является привилегированным API.
• Ключ (параметр, предоставленный для задания, get, Remove) имеет следующие ограничения:
  • Длина должна быть меньше 128 символов
  • Не удается содержать символ "|"
• Если браузер находится в режиме киоска, доступность локального хранилища может отличаться между браузерами и параметрами владельца киоска.
• Существует множество причин, по которым этот API может быть не поддерживается. Например, среда может не поддерживаться или локальное хранилище браузера недоступно. Перед использованием методов set/get/remove рекомендуется проверить состояние API. Обработка ошибок важна, так как даже если API поддерживается, это может завершиться ошибкой.

Связанный контент

• Пользовательский API визуальных элементов Power BI