チュートリアル:Power BI のビジュアルを開発するTutorial: Developing a Power BI visual

開発者が Power BI にカスタム ビジュアルを簡単に追加して、ダッシュボードとレポートで使用できるようにします。We’re enabling developers to easily add custom visuals into Power BI for use in dashboard and reports. すぐに始められるように、すべての視覚化のコードが GitHub で公開されています。To help you get started, we’ve published the code for all of our visualizations to GitHub.

ビジュアル化のフレームワークのほか、コミュニティの皆様が Power BI の質の高いのカスタム ビジュアルをビルドするのに役立つテスト スイートとツールを提供しています。Along with the visualization framework, we’ve provided our test suite and tools to help the community build high-quality custom visuals for Power BI.

このチュートリアルでは、Circle Card という名前の Power BI カスタム ビジュアルを開発して、円の中に書式設定されたメジャー値を表示する方法を示します。This tutorial shows you how to develop a Power BI custom visual named Circle Card to display a formatted measure value inside a circle. Circle Card ビジュアルでは、色の塗りつぶしと枠線の太さのカスタマイズをサポートします。The Circle Card visual supports customization of fill color and thickness of its outline.

Power BI Desktop レポートでは、Circle Card になるようにカードが修正されます。In the Power BI Desktop report, the cards are modified to become Circle Cards.

Power BI カスタム ビジュアルのサンプル出力

このチュートリアルで学習する内容は次のとおりです。In this tutorial, you learn how to:

  • Power BI カスタム ビジュアルを作成する。Create a Power BI custom visual.
  • D3 ビジュアル要素を使ってカスタム ビジュアルを開発する。Develop the custom visual with D3 visual elements.
  • ビジュアル要素を使ってデータ バインドを構成する。Configure data binding with the visual elements.
  • データ値を書式設定する。Format data values.


開発者環境を設定するSetting up the developer environment

前提条件の他に、インストールする必要があるツールがいくつかあります。In addition to the prerequisites, there are a few more tools you need to install.

node.js のインストールInstalling node.js

  1. Node.js をインストールするには、Web ブラウザーで [Node.js] に移動します。To install Node.js, in a web browser, navigate to Node.js.

  2. 最新機能の MSI インストーラーをダウンロードします。Download the latest feature MSI installer.

  3. インストーラーを実行して、インストールの手順に従います。Run the installer, and then follow the installation steps. 使用許諾契約に同意して、すべての既定値を受け入れます。Accept the terms of the license agreement and all defaults.

     Node.js の設定Node.js setup

  4. コンピューターを再起動します。Restart the computer.

パッケージのインストールInstalling packages

次に、pbiviz パッケージをインストールする必要があります。Now you need to install the pbiviz package.

  1. コンピューターが再起動された後に、Windows PowerShell を開きます。Open Windows PowerShell after the computer has been restarted.

  2. pbiviz をインストールするには、次のコマンドを入力します。To install pbiviz, enter the following command.

    npm i -g powerbi-visuals-tools

証明書の作成とインストールCreating and installing a certificate


  1. 証明書を作成してインストールするには、次のコマンドを入力します。To create and install a certificate, enter the following command.

    pbiviz --install-cert

    結果が返され、"パスフレーズ" が生成されています。It returns a result that produces a passphrase. ここでは、"パスフレーズ" は 15105661266553327 になっています。In this case, the passphrase is 15105661266553327. 証明書のインポート ウィザードも起動します。It also starts the Certificate Import Wizard.

    PowerShell 経由で作成された証明書

  2. 証明書のインポート ウィザードで、ストアの場所が [現在のユーザー] に設定されていることを確認します。In the Certificate Import Wizard, verify that the store location is set to Current User. [次へ] を選択します。Then select Next.


  3. [File to Import](インポートするファイル) 手順で、 [次へ] を選択します。At the File to Import step, select Next.

  4. [秘密キーの保護] 手順で、[パスワード] ボックスに、証明書の作成で受け取ったパスフレーズを貼り付けます。ここでも、パスフレーズは 15105661266553327 です。At the Private Key Protection step, in the Password box, paste the passphrase you received from creating the cert. Again, in this case it is 15105661266553327.


  5. [証明書ストア] 手順で、 [証明書をすべて次のストアに配置する] オプションを選択します。At the Certificate Store step, select the Place all certificates in the Following store option. 次に、 [参照] を選択します。Then select Browse.


  6. [証明書ストアの選択] ウィンドウで、 [信頼されたルート証明機関] を選択して、 [OK] をクリックします。In the Select Certificate Store window, select Trusted Root Certification Authorities and then select OK. その後、 [証明書ストア] 画面で [次へ] をクリックします。Then select Next on the Certificate Store screen.


  7. インポートを完了するには、 [完了] を選択します。To complete the import, select Finish.

  8. セキュリティの警告を受信した場合は、 [はい] を選択します。If you receive a security warning, select Yes.


  9. インポートが成功したという通知を受け取った場合は、 [OK] をクリックします。When notified that the import was successful, select OK.



Windows PowerShell セッションを閉じないでください。Do not close the Windows PowerShell session.


  1. 左上の鍵がロックされている場合は、鍵を選択してロックを解除します。If the lock in the upper left is locked, select it to unlock. localhost を検索し、証明書をダブルクリックします。Search for localhost and double-click on the certificate.

    OSX 上で SSL 証明書 1 をインストールする

  2. [Always Trust] (常に信頼する) を選択して、ウィンドウを閉じます。Select Always Trust and close the window.

    OSX 上で SSL 証明書 2 をインストールする

  3. ユーザー名とパスワードを入力します。Enter your username and password. [Update Settings] (設定の更新) を選択します。Select Update Settings.

    OSX 上で SSL 証明書 3 をインストールする

  4. 開いているブラウザーをすべて閉じます。Close any browsers that you have open.


証明書が認識されない場合は、コンピューターの再起動が必要である可能性があります。If the certificate is not recognized, you may need to restart your computer.

カスタム ビジュアルの作成Creating a custom visual

環境を設定できたので、次はカスタム ビジュアルを作成します。Now that you have set up your environment, it is time to create your custom visual.

このチュートリアルの完全なソース コードをダウンロードできます。You can download the full source code for this tutorial.

  1. Power BI Visual Tools パッケージがインストール済みであることを確認します。Verify that the Power BI Visual Tools package has been installed.


    ヘルプの出力が表示されます。You should see the help output.

     ym/       /+oshddhys+/
     ym/              /+oyhddhyo+/
     ym/                     /osyhdho
     ym/                           sm+
     ym/               yddy        om+
     ym/         shho /mmmm/       om+
         /    oys/ +mmmm /mmmm/       om+
     oso  ommmh +mmmm /mmmm/       om+
     ymmmy smmmh +mmmm /mmmm/       om+
     ymmmy smmmh +mmmm /mmmm/       om+
     ymmmy smmmh +mmmm /mmmm/       om+
     +dmd+ smmmh +mmmm /mmmm/       om+
             /hmdo +mmmm /mmmm/ /so+//ym/
                 /dmmh /mmmm/ /osyhhy/
                     //   dmmd
         PowerBI Custom Visual Tool
     Usage: pbiviz [options] [command]
     new [name]        Create a new visual
     info              Display info about the current visual
     start             Start the current visual
     package           Package the current visual into a pbiviz file
     update [version]  Updates the api definitions and schemas in the current visual. Changes the version if specified
     help [cmd]        display help for [cmd]
     -h, --help      output usage information
     -V, --version   output the version number
     --install-cert  Install localhost certificate

  2. サポートされているコマンドの一覧を含む、出力を確認します。Review the output, including the list of supported commands.


  3. カスタム ビジュアル プロジェクトを作成するために、次のコマンドを入力します。To create a custom visual project, enter the following command. CircleCard はプロジェクトの名前です。CircleCard is the name of the project.

    pbiviz new CircleCard

    新しい CircleCard の結果


    プロンプトの現在の位置で、新しいプロジェクトを作成します。You create the new project at the current location of the prompt.

  4. プロジェクト フォルダーに移動します。Navigate to the project folder.

    cd CircleCard
  5. カスタム ビジュアルを開始します。Start the custom visual. これで、お使いのコンピューターでホストしながら、CircleCard ビジュアルが実行中になりました。Your CircleCard visual is now running while being hosted on your computer.

    pbiviz start

    カスタム ビジュアルの実行開始


Windows PowerShell セッションを閉じないでください。Do not close the Windows PowerShell session.

カスタム ビジュアルのテストTesting the custom visual

このセクションでは、Power BI Desktop レポートをアップロードし、カスタム ビジュアルを表示するようにレポートを編集して、CircleCard カスタム ビジュアルをテストします。In this section, we are going to test the CircleCard custom visual by uploading a Power BI Desktop report and then editing the report to display the custom visual.

  1. [PowerBI.com] にサインインして [歯車] アイコン に移動し、 [設定] を選択します。Sign in to PowerBI.com > go to the Gear icon > then select Settings.

    Power BI の設定

  2. [開発者] を選択して、 [テスト用の開発者向けビジュアルを有効にする] チェックボックスをオンにします。Select Developer then check the Enable Developer Visual for testing checkbox.


  3. Power BI Desktop レポートをアップロードします。Upload a Power BI Desktop report.

    [データ] > [ファイル] > [ローカル ファイル] の順に移動します。Get Data > Files > Local File.

    まだ Power BI Desktop レポートをお持ちでない場合は、サンプルの Power BI Desktop レポートをダウンロードできます。You can download a sample Power BI Desktop report if you do not have one created already.

    データの取得 ローカル ファイルGet Data Local File

    レポートを表示するには、左側のナビゲーション ウィンドウにある [レポート] セクションから [US_Sales_Analysis] を選択します。Now to view the report, select US_Sales_Analysis from the Report section in the navigation pane on the left.

    カスタム ビジュアルの Desktop のサンプル

  4. 次に、Power BI サービス内でレポートを編集する必要があります。Now you need to edit the report while in the Power BI service.

    [レポートの編集] へ移動します。Go to Edit report.


  5. [ビジュアル] ウィンドウから [開発者向けビジュアル] を選択します。Select the Developer Visual from the Visualizations pane.



    このビジュアルは、コンピューター上で起動したカスタム ビジュアルを表示しています。This visualization represents the custom visual that you started on your computer. 開発者の設定が有効になっている場合のみ、利用可能です。It is only available when the developer settings have been enabled.

  6. ビジュアルがレポート キャンバスに追加されたことを確認します。Notice that a visualization was added to the report canvas.



    これは、Update メソッドが呼び出された回数を表示する非常に簡単なビジュアルです。This is a very simple visual that displays the number of times its Update method has been called. この段階で、ビジュアルはまだデータを取得していません。At this stage, the visual does not yet retrieve any data.

  7. レポートで新しいビジュアルを選択した状態で、[フィールド] ウィンドウに移動し、[売上] を展開して [数量] を選択します。While selecting the new visual in the report, Go to the Fields Pane > expand Sales > select Quantity.


  8. 次に、新しいビジュアルをテストするために、ビジュアルのサイズを変更して、更新値がインクリメントされていることを確認します。Then to test the new visual, resize the visual and notice the update value increments.


PowerShell で実行されるカスタム ビジュアルを停止するために、Ctrl キーを押しながら C キーを押します。To stop the custom visual running in PowerShell, enter Ctrl+C. バッチ ジョブの終了を求められた場合は、Y を入力して、Enter キーを押します。When prompted to terminate the batch job, enter Y, then press Enter.

ビジュアル要素の追加Adding visual elements

次に、D3 JavaScript ライブラリ をインストールする必要があります。Now you need to install the D3 JavaScript library. D3 とは、Web ブラウザーに動的な対話型データのビジュアルを生成するための JavaScript ライブラリです。D3 is a JavaScript library for producing dynamic, interactive data visualizations in web browsers. 広く実装されている SVG HTML5 および CSS 標準を利用します。It makes use of widely implemented SVG HTML5, and CSS standards.

これで、テキストと共に円を表示するカスタム ビジュアルを開発できるようになりました。Now you can develop the custom visual to display a circle with text.


このチュートリアルの多くのテキスト エントリは、こちらからコピーできます。Many text entries in this tutorial can be copied from here.

  1. PowerShell に D3 ライブラリをインストールするために、次のコマンドを入力します。To install the D3 library in PowerShell, enter the command below.

    npm i d3@3.5.5 --save

    D3 ライブラリのインストール

  2. D3 ライブラリの種類の定義をインストールするために、次のコマンドを入力します。To install type definitions for the D3 library, enter the command below.

    npm i @types/d3@3.5

    D3 ライブラリのインストール

    このコマンドは、JavaScript ファイルに基づいて TypeScript 定義をインストールします。(JavaScript のスーパーセットである)TypeScript でのカスタム ビジュアルの開発が可能になります。This command installs TypeScript definitions based on JavaScript files, enabling you to develop the custom visual in TypeScript (which is a superset of JavaScript). Visual Studio Code は、TypeScript アプリケーションを開発するための理想的な IDE です。Visual Studio Code is an ideal IDE for developing TypeScript applications.

  3. Visual Studio Code を起動します。Launch Visual Studio Code.

    次のコマンドを使用して、PowerShell から Visual Studio Code を起動できます。You can launch Visual Studio Code from PowerShell by using the following command.

    code .
  4. [エクスプローラー] ウィンドウで、 [node_modules] フォルダーを展開して d3 ライブラリがインストールされたことを確認します。In the Explorer pane, expand the node_modules folder to verify that the d3 library was installed.

    Visual Studio Code の D3 ライブラリ

  5. [エクスプローラー] ウィンドウで [node_modules] > [@types] > [d3] の順に展開して、TypeScript ファイルである index.d.ts を確認します。Notice the TypeScript file, index.d.ts, by expanding node_modules > @types > d3 in the Explorer pane.

    Index.d.ts ファイル

  6. pbiviz.json ファイルを選択します。Select the pbiviz.json file.

  7. d3 ライブラリを登録するために、次のファイル参照を externalJS 配列に入力します。To register the d3 library, enter the following file reference into the externalJS array. 既存のファイル参照と新しいファイル参照の間に、必ず "コンマ" を追加してください。Be sure to add a comma between the existing file reference and the new file reference.


    node_modules/d3/d3.min.js の追加

  8. pbiviz.json ファイルへの変更を保存します。Save the pbiviz.json file changes.

ビジュアル要素の開発Developing the visual elements

ここでは、円とサンプル テキストを表示するカスタム ビジュアルを開発する方法を見ていきます。Now we can explore how to develop the custom visual to show a circle and sample text.

  1. [エクスプローラー] ウィンドウで、 [src] フォルダーを展開して、 [visual.ts] を選択します。In the Explorer pane, expand the src folder and then select visual.ts.


    visual.ts ファイルの最上部のコメントに注目してください。Notice the comments at the top of the visual.ts file. MIT ライセンス契約の下で、Power BI カスタム ビジュアル パッケージを使用する権限が、無料で付与されます。Permission to use the Power BI custom visual packages is granted free of charge under the terms of the MIT License. 契約の一環として、ファイルの最上部に必ずコメントを残す必要があります。As part of the agreement, you must leave the comments at the top of the file.

  2. Visual クラスから、以下の既定のカスタム ビジュアル ロジックを削除します。Remove the following default custom visual logic from the Visual class.

    • 4 つのクラス レベルのプライベート変数宣言。The four class-level private variable declarations.
    • コンストラクターのすべてのコード行。All lines of code from the constructor.
    • Update メソッドのすべてのコード行。All lines of code from the update method.
    • parseSettings および enumerateObjectInstances メソッドを含む、モジュール内の残りのすべての行。All remaining lines within the module, including the parseSettings and enumerateObjectInstances methods.

    モジュール コードが次のようになっていることを確認します。Verify that the module code looks like the following.

    module powerbi.extensibility.visual {
    "use strict";
    export class Visual implements IVisual {
        constructor(options: VisualConstructorOptions) {
        public update(options: VisualUpdateOptions) {
  3. Visual クラス宣言の下に、次の class-level プロパティを挿入します。Beneath the Visual class declaration, insert the following class-level properties.

     private host: IVisualHost;
     private svg: d3.Selection<SVGElement>;
     private container: d3.Selection<SVGElement>;
     private circle: d3.Selection<SVGElement>;
     private textValue: d3.Selection<SVGElement>;
     private textLabel: d3.Selection<SVGElement>; 

    Visual.ts ファイルのクラスレベル プロパティ

  4. 次のコードを "コンストラクター "に追加します。Add the following code to the constructor.

    this.svg = d3.select(options.element)
                 .classed('circleCard', true);
    this.container = this.svg.append("g")
                         .classed('container', true);
    this.circle = this.container.append("circle")
                             .classed('circle', true);
    this.textValue = this.container.append("text")
                                 .classed("textValue", true);
    this.textLabel = this.container.append("text")
                                 .classed("textLabel", true);

    このコードでは、ビジュアルの中に SVG グループを追加して、そこに円と 2 つのテキスト要素という合計 3 つの図形を追加します。This code adds an SVG group inside the visual and then adds three shapes: a circle and two text elements.

    ドキュメント内のコードを書式設定するには、Visual Studio Code ドキュメントの任意の場所をクリックして、 [ドキュメントのフォーマット] を選択します。To format the code in the document, right-select anywhere in the Visual Studio Code document, and then select Format Document.


    読みやすさを向上させるために、コード スニペットに貼り付ける際は、必ずドキュメントを書式設定することをお勧めします。To improve readability, it is recommended that you format the document every time that paste in code snippets.

  5. update メソッドに次のコードを追加します。Add the following code to the update method.

    let width: number = options.viewport.width;
    let height: number = options.viewport.height;
     width: width,
     height: height
    let radius: number = Math.min(width, height) / 2.2;
     .style("fill", "white")
     .style("fill-opacity", 0.5)
     .style("stroke", "black")
     .style("stroke-width", 2)
     r: radius,
     cx: width / 2,
     cy: height / 2
    let fontSizeValue: number = Math.min(width, height) / 5;
         x: "50%",
         y: "50%",
         dy: "0.35em",
         "text-anchor": "middle"
     }).style("font-size", fontSizeValue + "px");
    let fontSizeLabel: number = fontSizeValue / 4;
         x: "50%",
         y: height / 2,
         dy: fontSizeValue / 1.2,
         "text-anchor": "middle"
     .style("font-size", fontSizeLabel + "px");

    このコードはビジュアルの幅と高さを設定して、ビジュアル要素の属性と形式を初期化します。This code sets the width and height of the visual, and then initializes the attributes and styles of the visual elements.

  6. visual.ts ファイルを保存します。Save the visual.ts file.

  7. capabilities.json ファイルを選択します。Select the capabilities.json file.

    14 行目から、オブジェクト要素全体 (行 14 ~ 60) を削除します。At line 14, remove the entire objects element (lines 14-60).

  8. capabilities.json ファイルを保存します。Save the capabilities.json file.

  9. PowerShell で、カスタム ビジュアルを起動します。In PowerShell, start the custom visual.

    pbiviz start

自動再読み込みの切り替えToggle auto reload

  1. Power BI レポートに戻ります。Navigate back to the Power BI report.

  2. 開発者向けビジュアルの上に表示されるツールバーで、 [自動再読み込みの切り替え] を選択します。In the toolbar floating above the developer visual, select the Toggle Auto Reload.


    このオプションは、プロジェクトの変更を保存するたびに、ビジュアルが自動的に再読み込みされることを保証します。This option ensures that the visual is automatically reloaded each time you save project changes.

  3. [フィールド] ウィンドウから、 [数量] フィールドを開発者向けビジュアルにドラッグします。From the Fields pane, drag the Quantity field into the developer visual.

  4. ビジュアルが次のようになっていることを確認します。Verify that the visual looks like the following.


  5. ビジュアルのサイズを変更します。Resize the visual.

    ビジュアルで使用可能なディメンションに適合するように、円とテキストの値がスケーリングされることを確認します。Notice that the circle and text value scales to fit the available dimension of the visual.

    update メソッドは、ビジュアルのサイズ変更の際に連続で呼び出され、結果として、ビジュアル要素の再スケーリングが円滑に行われます。The update method is called continuously with resizing the visual, and it results in the fluid rescaling of the visual elements.

    これで、ビジュアル要素の開発が終わりました。You have now developed the visual elements.

  6. 引き続き、ビジュアルを実行します。Continue running the visual.

データ バインドの構成Configuring data binding

データ ロールとデータ ビューのマッピングを定義して、メジャーの値と表示名を表示するようにカスタム ビジュアル ロジックを変更します。Define the data roles and data view mappings, and then modify the custom visual logic to display the value and display name of a measure.

機能の構成Configuring the capabilities

capabilities.json ファイルを変更して、データ ロールとデータ ビューのマッピングを定義します。Modify the capabilities.json file to define the data role and data view mappings.

  1. Visual Studio Code で、capabilities.json ファイルの dataRoles 配列内から、すべてのコンテンツ (行 3 ~ 12) を削除します。In Visual Studio code, in the capabilities.json file, from inside the dataRoles array, remove all content (lines 3-12).

  2. dataRoles 配列内に、次のコードを挿入します。Inside the dataRoles array, insert the following code.

     "displayName": "Measure",
     "name": "measure",
     "kind": "Measure"

    dataRoles 配列に、種類がメジャーの単一のデータ ロールを定義しました。名前は measure、表示は Measure となります。The dataRoles array now defines a single data role of type measure, that is named measure, and displays as Measure. このデータ ロールによって、メジャー フィールドまたは集計されたフィールドのどちらかを渡すことが可能になります。This data role allows passing either a measure field, or a field that is summarized.

  3. dataViewMappings 配列内から、すべてのコンテンツ (行 10 ~ 31) を削除します。From inside the dataViewMappings array, remove all content (lines 10-31).

  4. dataViewMappings 配列内に、次のコンテンツを挿入します。Inside the dataViewMappings array, insert the following content.

            "conditions": [
                { "measure": { "max": 1 } }
            "single": {
                "role": "measure"

    これで、measure という名前のデータ ロールに 1 つのフィールドを渡すことができるように、dataViewMappings 配列を定義しました。The dataViewMappings array now defines one field can be passed to the data role named measure.

  5. capabilities.json ファイルを保存します。Save the capabilities.json file.

  6. Power BI で、ビジュアルがメジャーと共に構成できるようになったことを確認します。In Power BI, notice that the visual now can be configured with Measure.



    ビジュアル プロジェクトには、データ バインド ロジックがまだ含まれていません。The visual project does not yet include data binding logic.

データビューの確認Exploring the dataview

  1. ビジュアルの上に表示されるツールバーで、 [Dataview の表示] を選択します。In the toolbar floating above the visual, select Show Dataview.

    Dataview の表示

  2. single まで下方向に展開して、値を確認します。Expand down into single, and then notice the value.


  3. metadata から、さらに columns 配列内へと下方向に展開して、特に formatdisplayName の値を確認します。Expand down into metadata, and then into the columns array, and in particular notice the format and displayName values.

    displayName 値

  4. もう一度ビジュアルに切り替えて、ビジュアルの上に表示されるツールバーで、 [Dataview の表示] を選択します。To toggle back to the visual, in the toolbar floating above the visual, select Show Dataview.


データ バインドの構成Configuring data binding

  1. Visual Studio Codevisual.tsファイルに、update メソッドの最初のステートメントとして、次のステートメントを追加します。In Visual Studio Code, in the visual.ts file, add the following statement as the first statement of the update method.

    let dataView: DataView = options.dataViews[0];

    Update 配列の Dataview

    このステートメントでは、簡単にアクセスできるように dataView を 1 つの変数に代入して、dataView オブジェクトを参照するようにその変数を宣言します。This statement assigns the dataView to a variable for easy access, and declares the variable to reference the dataView object.

  2. update メソッドで、 .text("Value") を次のように置き換えます。In the update method, replace .text("Value") with the following.

    .text(dataView.single.value as string)

    textValue の置き換え

  3. update メソッドで、 .text("Label") を次のように置き換えます。In the update method, replace .text("Label") with the following.


    textLabel の置き換え

  4. visual.ts ファイルを保存します。Save the visual.ts file.

  5. Power BI で、ビジュアルを確認します。値と表示名が表示されています。In Power BI, review the visual, which now displays the value and the display name.

これで、データ ロールを構成して、ビジュアルをデータビューにバインドできました。You have now configured the data roles and bound the visual to the dataview.

次のチュートリアルでは、カスタム ビジュアルに書式設定オプションを追加する方法について説明します。In the next tutorial you learn how to add formatting options to the custom visual.


カスタム ビジュアルのデバッグに関するヒントについては、デバッグ ガイドを参照してください。For tips about debugging your custom visual, see the debugging guide.

次の手順Next steps