Power BI ビジュアルのシステム統合

この記事では、ビジュアル API と、Power BI によるユーザー、ビジュアル、ホスト間のやり取りの処理方法について説明します。

Power BI のアクションとそれに続く更新が手動で、または自動的に開始できます。 更新の種類は次のとおりです。

• Power BI を介してビジュアルを操作する。
• ビジュアルを直接操作する。
• ビジュアルと Power BI が対話する。

次の図は、ブックマークの選択などの一般的なビジュアルベースのアクションが Power BI でどのように処理されるかを示しています。

Power BI を介してビジュアルを操作する

Power BI では、次のようにビジュアルを更新できます。

• ビジュアルの [プロパティ] パネルを開きます。

  ビジュアルの [プロパティ] パネルを開くと、サポートされているオブジェクトとプロパティが Power BI によってビジュアルの capabilities.json ファイルから取得されます。 プロパティの実際の値を受け取るために、Power BI によって視覚化の getFormattingModel メソッドが呼び出されます (バージョン 5.0 より前の API では代わりに enumerateObjectInstances が呼び出されます)。 API は、最新の書式ペイン モデルのコンポーネント、プロパティ、それらの実際の値を返します。

  詳細については、「Power BI ビジュアルの機能とプロパティ」を参照してください。

• 視覚エフェクトのタイトル、背景、ラベル、凡例をカスタマイズします。

  [書式] パネルでプロパティの値を変更すると、Power BI によって update メソッドが呼び出されます。 Power BI から新しい options オブジェクトが update メソッドに渡され、オブジェクトに新しい値が含まれます。

  詳細については、「Power BI ビジュアルのオブジェクトとプロパティ」を参照してください。

• ビジュアルのサイズを変更します。

  ビジュアルのサイズを変更すると、Power BI によって update メソッドが呼び出され、新しい options オブジェクトが渡されます。 options オブジェクトには、ビジュアルの新しい幅と高さを含む viewport オブジェクトが入れ子になっています。

• レポート、ページ、またはビジュアル レベルでフィルターを適用します。

  Power BI では、フィルター条件に基づいてデータがフィルター処理されます。 Power BI では、ビジュアルの update メソッドが呼び出され、新しいデータでビジュアルが更新されます。

  入れ子になったオブジェクトのいずれかに新しいデータがある場合、ビジュアルには options オブジェクトの新しい更新が取得されます。 更新がどのように行われるかは、ビジュアルのデータ ビュー マッピング構成によって異なります。

  詳細については、「Power BI ビジュアルでのデータ ビューのマッピングについて理解する」を参照してください。

• レポート内の別のビジュアルにあるデータ ポイントを選択します。

  レポート内の別のビジュアルにあるデータ ポイントを選択すると、Power BI では選択したデータ ポイントがフィルター処理されるか強調表示され、ビジュアルの update メソッドが呼び出されます。 ビジュアルによって、フィルター処理された新しいデータが取得されます。または、強調表示の配列を使用して同じデータが取得されます。

  詳細については、「Power BI ビジュアルでデータ ポイントを強調表示する」を参照してください。

• レポートの [ブックマーク] パネルでブックマークを選択します。

  [ブックマーク] パネルでブックマークを選択すると、次のいずれかになります。

  • registerOnSelectionCallback メソッドによって渡され、登録された関数が Power BI から呼び出されます。 コールバック関数によって、対応するブックマークの選択範囲の配列が取得されます。

  • Power BI によって、options オブジェクト内の対応する filter オブジェクトを使用して updateメソッドが呼び出されます。

    どちらの場合も、受け取った選択または filter オブジェクトに応じて、ビジュアルでその状態が変更されます。

    ブックマークとフィルターの詳細については、「Power BI ビジュアルでの Visual Filters API」を参照してください。

ビジュアルを直接操作する

次のようにビジュアルを直接操作して更新することもできます。

• データ要素の上にマウス ポインターを合わせます。

  ビジュアルには、Power BI Tooltips API を介してデータ ポイントに関する詳細情報を表示できます。 ビジュアル要素の上にマウス ポインターを合わせると、ビジュアルによってイベントが処理され、関連するツールヒント要素に関するデータが表示されます。 ビジュアルには、標準のツールヒントまたはレポート ページのツールヒントが表示されます。

  詳細については、「Power BI ビジュアルにヒントを追加する」を参照してください。

• ビジュアルのプロパティを変更すると (たとえば、ツリーを展開して)、ビジュアルの新しい状態がビジュアルのプロパティに保存されます。

  Power BI API を使用して視覚エフェクトにプロパティ値を保存できます。 たとえば、ビジュアルを操作し、ビジュアルのプロパティ値を保存または更新する必要がある場合、ビジュアルから persistProperties メソッドを呼び出すことができます。

• URL を選択します。

  既定では、ビジュアルから URL を直接開くことはできません。 新しいタブで URL を開くには、ビジュアルから launchUrl メソッドを呼び出し、URL をパラメーターとして渡す方法があります。

  詳細については、「起動 URL を作成する」を参照してください。

• ビジュアルを介してフィルターを適用します。

  ビジュアルから applyJsonFilter メソッドを呼び出し、条件を渡して他のビジュアルのデータをフィルター処理できます。 基本、詳細、タプル フィルターなど、いくつかの種類のフィルターを使用できます。

  詳細については、「Power BI ビジュアルでの Visual Filters API」を参照してください。

• ビジュアル内の要素を選択します。

  Power BI ビジュアルでの選択の詳細については、「Power BI ビジュアルの選択によってビジュアルに対話機能を追加する」を参照してください。

ビジュアルと Power BI が対話する

場合によっては、ユーザーからの入力なしで、ビジュアルによって Power BI ホストとの通信が開始されることがあります。

• ビジュアルを使うと、より多くのデータを Power BI に要求できます。

  ビジュアルでは、データが部分ごとに処理されます。 fetchMoreData API メソッドによって、セマンティック モデル内のデータの次のフラグメントが要求されます。

  詳細については、「より多くのデータを Power BI からフェッチする」を参照してください。

• イベント サービスがトリガーされます。

  Power BI を使って、レポートを PDF にエクスポートすることや、メールでレポートを送信することができます (認定済みビジュアルにのみ適用されます)。 レンダリングが完了し、ビジュアルを PDF またはメールとしてキャプチャする準備ができたことを Power BI に通知するには、ビジュアルから Rendering Events API を呼び出す必要があります。

  詳細については、「Power BI から PDF にレポートをエクスポートする」を参照してください。

  イベント サービスの詳細については、「Power BI ビジュアルでイベントを "レンダリング" する」を参照してください。

関連するコンテンツ

視覚化の作成と Microsoft AppSource への追加に興味がある場合は 次の記事を参照してください。

• ビジュアル API
• Power BI の円形カード視覚化を開発する
• Power BI 視覚化を Microsoft コマーシャル マーケットプレースに発行する