ライセンスと取引機能の適用 (パブリックプレビュー)

[アーティクル]
11/04/2024

AppSource でダウンロードするための Power BI ビジュアルを作成するときに、Microsoft システムを使用してライセンスを管理および適用できるようになりました。エンドユーザーは、Microsoft 365 管理センターなどの使い慣れたツールを使用してライセンスを割り当てて管理します。ライセンス API を使用すると、これらのライセンスを適用し、ライセンスを持つユーザーのみがビジュアルをレンダリングできるようになります。

ライセンスの適用プロセス

次の表は、Microsoft を通じてビジュアルライセンスを管理する手順を示しています。

手順	詳細
パートナーセンターでオファーを作成する	Microsoft コマースシステムを通じた取引を選択します。 Microsoft がライセンスを管理できるようにします。価格と使用可能状況を設定します。
Power BI ビジュアルパッケージにライセンスの適用を追加する	Power BI ランタイムライセンスを使用するようにパッケージを作成または再構成します。これにより、各ユーザーのアクセスに応じてライセンスが適用されます。
顧客が AppSource でオファーを検出し、サブスクリプションを購入する	顧客が AppSource でオファーを購入すると、Power BI ビジュアルのライセンスも取得されます。
顧客がサブスクリプションを管理し、ユーザーライセンスを割り当て/割り当て解除する	Office や Power BI などの他のサブスクリプションの場合と同様に、顧客が Microsoft 365 管理センターでサブスクリプションを管理し、これらのビジュアルとオファーのライセンスを割り当てます。
ランタイムチェックを適用する	使用開始時の API を使用してランタイムライセンスチェックを適用することで、顧客に統一されたエクスペリエンスが提供されます。
レポートを表示して成長を促進する	収益、支払い情報、注文とライセンスの詳細に関する分析情報を取得します。購入、更新、取り消されたライセンスと注文に関する情報を、時間の経過と地域別に表示します。

ライセンス API

ライセンス API を使用すると、Power BI ビジュアルの開発者が Power BI ビジュアルライセンスを適用できます。この API では、Power BI ユーザーに割り当てられている Power BI ビジュアルライセンスに関する情報の取得がサポートされています。また、Power BI ビジュアルに表示されるライセンス関連の通知をトリガーし、不足しているライセンスを購入する必要があることをユーザーに通知することもできます。ビジュアルには独自のライセンス UX を表示しないでください。代わりに、次のセクションで詳しく説明するように、Power BI でサポートされている定義済みの通知のいずれかを使用してください。

Power BI ライセンスの詳細については、ライセンスの適用に関する記事を参照してください。

注意

ライセンス API は、バージョン 4.7 以降で使用できます。使用しているバージョンを確認するには、pbiviz.json ファイルの apiVersion を確認してください。

アクティブなユーザーに割り当てられているビジュアルのサービスプランを取得する

サービスプランを割り当てるには、getAvailableServicePlans への呼び出しを追加します (IVisualLicenseManager から実行できます)。パフォーマンスの観点から、ライセンスの取り込みを 1 回試み (できれば constructor または init の呼び出しで)、結果を保存します。
ライセンスが取得されると、Power BI セッション中に Power BI ホスト側にキャッシュされ、それ以降の呼び出しではキャッシュされたデータが返されます。

export interface IVisualLicenseManager {
        getAvailableServicePlans(): IPromise<powerbi.extensibility.visual.LicenseInfoResult>;
    }

ライセンスの取得は長い操作になる可能性があるため、 getAvailableServicePlans 呼び出しは非同期呼び出しであるため、コード内でそのように処理する必要があります。
メソッドの呼び出しに対する応答として、LicenseInfoResult オブジェクトが返されます。

export interface LicenseInfoResult {
        plans: ServicePlan[] | undefined;
        isLicenseUnsupportedEnv: boolean; 
        isLicenseInfoAvailable: boolean; 
    }

plans - アクティブユーザーがこのビジュアルで購入したサービスプランの配列。 (その他のビジュアルで購入したライセンスは、応答には含まれません。)
ServicePlan には、サービス識別子 (spIdentifier) とその状態 (ServicePlanState) が含まれています。

spIdentifier: パートナーセンターでオファーのプランを構成したときに生成されるサービス ID の文字列の値 (以下の例を参照してください)

状態 – 割り当てられたプランの状態を表す列挙型 (ServicePlanState)。
サポートされているサービスプランの状態:

State	説明
非アクティブ	ライセンスがアクティブでなく、プロビジョニングのベネフィットを得るために使用できないことを示します。
アクティブ	ライセンスがアクティブであり、プロビジョニングのベネフィットを得るために使用できることを示します。
警告	支払い違反が原因でライセンスの猶予期間に入っていることを示します。
Suspended	支払い違反が原因でライセンスの保留期間に入っていることを示します。
Unknown	Microsoft Sentinel の値。

使用可能なライセンスを表すのは "アクティブ" と "警告" の状態のみです。その他のすべての状態は、使用可能なライセンスが得られないものとして扱う必要があります。

isLicenseUnsupportedEnv - ライセンスの管理または適用をサポートしていない Power BI 環境でビジュアルがレンダリングされていることを示します。現在、次の Power BI 環境では、ライセンスの管理またはライセンスの適用はサポートされていません。
- Embedded - Web に公開、PaaS 埋め込み
- 国/地域内クラウド (国/地域内クラウドでの取引機能に関する一般的なサポートに依存)
- RS Server (計画的なサポートなし)
- REST API を使用したエクスポート (PDF\PPT)
isLicenseInfoAvailable - ライセンス情報を取得できるかどうかを示します。 Power BI Desktop ユーザーがサインインしていない場合、またはインターネットに接続されていない (オフライン) 場合、ライセンスの取得が失敗する可能性があります。 Web の場合、一時的なサービス停止によりライセンスの取得が失敗する可能性があります。

getAvailableServicePlansを呼び出して、このビジュアルのユーザーのサービスプランを取得する例を次に示します。

private currentUserValidPlans: ServicePlan[] | undefined;
private hasServicePlans: boolean | undefined;
private isLicenseUnsupportedEnv: boolean | undefined;

this.licenseManager.getAvailableServicePlans()
 .then(({ plans, isLicenseUnsupportedEnv, isLicenseInfoAvailable }: LicenseInfoResult) => {
  if (isLicenseInfoAvailable && !isLicenseUnsupportedEnv) {
   this.currentUserValidPlans = plans?.filter(({ spIdentifier, state }) => 
    (state === powerbi.ServicePlanState.Active || state === powerbi.ServicePlanState.Warning)
   );
   this.hasServicePlans = !!currentUserValidPlans?.length;
  }
  this.isLicenseUnsupportedEnv = isLicenseUnsupportedEnv;
 }).catch((err) => {
  this.currentUserValidPlans = undefined;
  this.hasServicePlans = undefined;
  console.log(err);
 });

Note

この例では、ユーザーがこのビジュアルの有効なプランを持っているかどうかを確認する方法のみを示します。 plans配列には異なるspIdentifier値が含まれる場合があり、各識別子は異なる状態で複数回出現する可能性があります。

必要なライセンスが不足していることをユーザーに通知する

Power BI プラットフォームには、次のような通知に使用できる、使用開始時のエクスペリエンスがいくつか用意されています。

ビジュアルの機能をすべて利用するには、ライセンスを購入する必要がある
ライセンスが不足しているため、特定のビジュアルの機能がブロックされている
ライセンスが不足しているため、ビジュアル全体がブロックされている
使用中の Power BI 環境がライセンスの管理や適用をサポートしていないため、ビジュアル全体がブロックされている

export interface IVisualLicenseManager {
        notifyLicenseRequired(notificationType: LicenseNotificationType): IPromise<boolean>;
        notifyFeatureBlocked(tooltip: string): IPromise<boolean>;
        clearLicenseNotification(): IPromise<boolean>;
    }

notifyLicenseRequiredを呼び出す例:

private defaultNotificationType: powerbi.LicenseNotificationType = powerbi.LicenseNotificationType.General;
private isNotificaitonDisplayed: boolean = false;

if (!this.isNotificaitonDisplayed) {
    const notificationType = this.isLicenseUnsupportedEnv ? powerbi.LicenseNotificationType.UnsupportedEnv : this.defaultNotificationType
    this.licenseManager.notifyLicenseRequired(this.getNotificationType())
        .then((value) => {
            this.isNotificaitonDisplayed = value;
        }).catch((err) => {
            console.log(err);
        });
}

必要なライセンスが見つからないという一般的なアイコン

notifyLicenseRequired の呼び出しを LicenseNotificationType.General と一緒に使用して、ビジュアルのコンテナーの一部としてアイコンを表示します。
トリガーされると、アイコンは、 clearLicenseNotification または notifyLicenseRequired が呼び出されるまで、ビジュアルの有効期間中保持されます。

Note

LicenseNotificationType.General通知は、ライセンス管理と Power BI 編集シナリオをサポートする環境からのみ適用されます。サポートされていない環境で、またはレポートが読み取りモードまたはダッシュボードで呼び出されると、アイコンは適用されないため、通話の応答に false が返されます。

"ライセンスが必要です" の一般的なアイコンを含むビジュアル表示の例:

ビジュアルの表示に "ライセンスが不足しています" の通知をオーバーレイする

notifyLicenseRequired の呼び出しを LicenseNotificationType.VisualIsBlocked と一緒に使用して、必要なライセンスが見つからないためにビジュアルがブロックされているという通知をビジュアルの表示にオーバーレイします。
トリガーされると、この通知は、 clearLicenseNotification または notifyLicenseRequired が呼び出されるまで、ビジュアルの有効期間中保持されます。

"ビジュアルがブロックされています" の通知を含むビジュアル表示の例。 Power BI Desktop には、 ライセンスの取得 オプションのみが表示されます。

*ビジュアルがブロックされています* の通知を含むビジュアル表示。

ビジュアルの表示に "環境がサポートされていません" の通知をオーバーレイする

notifyLicenseRequired の呼び出しを LicenseNotificationType.UnsupportedEnv と一緒に使用して、使用中の Power BI がライセンスの管理や適用をサポートしていないため、ビジュアルがブロックされているという通知をビジュアルの表示にオーバーレイします。
トリガーされると、アイコンは、 clearLicenseNotification または notifyLicenseRequired が呼び出されるまで、ビジュアルの有効期間中保持されます。

Note

LicenseNotificationType.UnsupportedEnv の通知は、ライセンス環境でサポートされていないコンテキストで呼び出された場合にのみ適用されます。他の環境でこれを呼び出しても通知は適用されないため、呼び出しの応答で false が返されます。

"環境がサポートされていません" の通知を含むビジュアル表示の例:

特定のビジュアルの機能を適用するには、不足していることが判明したライセンスが必要な場合は、ビジュアルのコンテナーの一部としてポップアップバナーを表示する notifyFeatureBlocked 呼び出しを使用できます。バナーでは、通知をトリガーした機能に関する追加情報を提供するために設定および使用できるカスタムヒントもサポートされています。

Note

機能はブロックされます通知は、次の両方の条件が適用される場合にのみ適用されます。

サポートされているライセンス環境から呼び出されます
ブロックオーバーレイは適用されません (LicenseNotificationType.UnsupportedEnv、 LicenseNotificationType.VisualIsBlocked)。

サポートされていない環境でこの通知を呼び出しても通知は適用されないため、呼び出しの応答で false が返されます。

Note

ローカライズされた Power BI 環境をサポートするには、使用しているヒントのローカライズされたバージョンを維持することをお勧めします。ローカライズ API を使用して、Power BI ロケール言語を取得してください。

トリガーされると、バナーは 10 秒間、または他の "機能がブロックされた" バナーがトリガーされるまで、または clearLicenseNotification が呼び出されるまで (最初に表示されるものは何でも) 表示されます。

"機能がブロックされています" バナー通知を含むビジュアル表示の例:

ライセンスされたビジュアルをテストする

ライセンスされたビジュアルを一般公開する前にエンドツーエンドでテストするには、次のようにします。

まったく新しいオファーを作成する場合は、テスト顧客アカウントのプライベートプランとしてビジュアルを追加します。オファーは、購入のためにこのテストアカウントにのみ表示されます。このアカウントを使用して、オファーを公開する前に検証します。
ビジュアルが AppSource で既に使用可能であり、ライセンスを取得したビジュアルにアップグレードする場合 、そのビジュアルをプライベートプランにすることはできません これは、そのビジュアルを AppSource から非表示にし、既存のユーザーがそのビジュアルにアクセスできないためです。現在、公開されたビジュアルをエンドツーエンドでテストする方法はありません。ライセンス API 値をモックしてさまざまな可能性を確認することで、元のビジュアルをテストして AppSource に公開したときと同じ方法でテストします。

考慮事項と制限事項

機能バナーのヒントは 500 文字に制限されています。
機能バナーのヒントにはローカライズが必要です。
ライセンスバンドル (つまり、同じ発行元からの複数のオファーを対象とする 1 つのライセンス) はまだサポートされていません。

Power BI カスタムビジュアルを発行する

他にわからないことがある場合は、 Power BI コミュニティで質問してみてください。

次の方法で共有

ライセンスと取引機能の適用 (パブリックプレビュー)

ライセンスの適用プロセス

ライセンス API

アクティブなユーザーに割り当てられているビジュアルのサービスプランを取得する

必要なライセンスが不足していることをユーザーに通知する

必要なライセンスが見つからないという一般的なアイコン

ビジュアルの表示に "ライセンスが不足しています" の通知をオーバーレイする

ビジュアルの表示に "環境がサポートされていません" の通知をオーバーレイする

特定のビジュアルの機能を適用できなかったことを通知するバナーを表示する

ライセンスされたビジュアルをテストする

考慮事項と制限事項

フィードバック

その他のリソース

次の方法で共有

ライセンスと取引機能の適用 (パブリック プレビュー)

ライセンスの適用プロセス

ライセンス API

アクティブなユーザーに割り当てられているビジュアルのサービス プランを取得する

必要なライセンスが不足していることをユーザーに通知する

必要なライセンスが見つからないという一般的なアイコン

ビジュアルの表示に "ライセンスが不足しています" の通知をオーバーレイする

ビジュアルの表示に "環境がサポートされていません" の通知をオーバーレイする

特定のビジュアルの機能を適用できなかったことを通知するバナーを表示する

ライセンスされたビジュアルをテストする

考慮事項と制限事項

関連するコンテンツ

フィードバック

その他のリソース

ライセンスと取引機能の適用 (パブリックプレビュー)

アクティブなユーザーに割り当てられているビジュアルのサービスプランを取得する