로컬 스토리지 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: 시각적 개체에 권한 배열의 로컬 스토리지에 대한 선언이 없습니다.
    • PrivilegeStatus.NotSupported: API는 지원되지 않습니다(자세한 내용은 제한 사항 참조).
    • PrivilegeStatus.Allowed: API가 지원되고 허용됨

  get, set 또는 remove 메서드를 사용하기 전에 상태 메서드를 사용하여 API의 상태 검사 시각적 개체가 예상대로 작동하는지 확인하는 것이 가장 좋습니다.

• get:

  • 이 메서드에는 다음 매개 변수가 하나 있습니다.

    • key – 값을 가져올 키입니다.

  • 키가 있는 경우 값으로 확인되고 그렇지 않으면 거부하는 프라미스를 반환합니다.

• set:

  • 이 메서드에는 다음 두 개의 매개 변수가 있습니다.

    • key – 값을 설정하려는 키
    • data – 키의 값

  • 형식StorageV2ResultInfo의 구조체로 확인되거나 오류가 발생한 경우 거부하는 프라미스를 반환합니다.

• remove:

  • 이 메서드에는 다음 매개 변수가 하나 있습니다.

    • 키 – 제거할 쌍의 키

로컬 스토리지 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당 1mb입니다.
• GUID가 동일한 시각적 개체 간에만 데이터를 공유할 수 있습니다.
• Power BI Desktop의 다른 인스턴스와 데이터를 공유할 수 없습니다.
• 로컬 스토리지 API는 기본적으로 활성화되지 않습니다. Power BI 시각적 개체에 대해 활성화하려면 Power BI 시각적 개체 지원(pbicvsupport@microsoft.com)에 요청을 보내세요.
• 로컬 스토리지 API는 await 생성을 지원하지 않습니다. 전용 then 및 catch 메서드가 허용됩니다.

시각적 개체는 AppSource에서 사용할 수 있어야 하며 인증되어야 합니다.

고려 사항 및 제한 사항 버전 2

• 사용자 지정 시각적 개체 로컬 스토리지 제한은 100KB입니다.
• 동일한 GUID, 동일한 환경을 사용하는 시각적 개체와 동일한 사용자에 대해서만 데이터를 공유할 수 있습니다.
• API는 다음 환경에서 지원됩니다.
  • 웹
  • 바탕 화면
  • SaaS 포함
  • 모바일
  • 보고서 서버
• 로컬 스토리지는 PDF 또는 pptx로 내보낼 때 지원되지 않습니다.
• API는 사용자가 로그인한 경우에만 지원됩니다.
• 시각적 개체의 데이터는 가장 최근 수정 시간 이후 29일 후에 지워집니다.
• 이 API는 권한 있는 API입니다.
• 키(설정, 가져오기, 제거에 제공된 매개 변수)에는 다음과 같은 제한 사항이 있습니다.
  • 길이는 128자 미만이어야 합니다.
  • 문자 '|'을(를) 포함할 수 없습니다.
• 브라우저가 키오스크 모드인 경우 로컬 스토리지 가용성은 브라우저와 키오스크 소유자의 설정에 따라 다를 수 있습니다.
• 이 API가 지원되지 않는 이유는 여러 가지가 있습니다. 예를 들어 환경이 지원되지 않거나 브라우저의 로컬 스토리지를 사용할 수 없습니다. set/get/remove 메서드를 사용하기 전에 API의 상태 검사 것이 좋습니다. API가 지원되더라도 실패할 수 있으므로 오류 처리가 중요합니다.

관련 콘텐츠

• Power BI 사용자 지정 시각적 개체 API