開発者ツールを使ってカスタム ビジュアルを作成するUse developer tools to create custom visuals

カスタム ビジュアルの作成では、ユーザーのニーズを満たすと共に、アプリのデザインに合わせることができます。Custom visuals allow you to meet your users' needs and match your app's design. ここでは、開発者ツールを使用して、Power BI 用のカスタム ビジュアルを作成する方法について説明します。Learn how to create a custom visual for Power BI using the developer tools.

注意

このドキュメントを使用すると、起動して実行できるようになります。You can use this document to get up and running. 詳細については、「Power BI Visuals git repo」 (Power BI ビジュアル Git リポジトリ) にあるリファレンス情報を参照してください。For more in-depth information, see the reference information within the Power BI Visuals git repo.

要件Requirements

NodeJS および Power BI ツールをインストールするInstall NodeJS and the Power BI tools

カスタム ビジュアルを作成するには、NodeJS をインストールする必要があります。In order to create a custom visual, you will need to install NodeJS. コマンド ライン ツールを実行するために NodeJS が必須となります。NodeJS is required to run the command line tools.

  1. NodeJS をダウンロードしてインストールします。Download and install NodeJS. 要件はバージョン 4.0 以降ですが、バージョン 5.0 以降の使用をお勧めします。Version 4.0 or later is required but it is recommended to have 5.0 or later.
  2. コマンド ライン ツールをインストールします。Install the command line tools. コマンド プロンプトから次のコマンドを実行します。Run the following command from a command prompt.

     npm install -g powerbi-visuals-tools
    
  3. このツールがインストールされていることを確認するには、パラメーターを指定せずに次のコマンドを実行します。You can confirm that the tools are installed by running the following command without any parameters.

     pbiviz
    

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

    
          +syyso+/
     oms/+osyhdhyso/
     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]
    
     Commands:
    
     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]
    
     Options:
    
     -h, --help      output usage information
     -V, --version   output the version number
     --install-cert  Install localhost certificate
     

<a name"ssl-setup">

サーバー証明書のセットアップServer Certificate setup

ビジュアルのライブ プレビューを有効にするには、信頼されている https サーバーが必要です。To enable a live preview of your visual, a trusted https server is needed. 開始の前に SSL 証明書をインストールする必要があります。これにより、ビジュアル アセットを Web ブラウザーに読み込むことができるようになります。Before you can start, you will need to install an SSL certificate which will allow visual assets to load in your web browser.

注意

これは、開発者のワークステーションでの 1 回限りのセットアップです。This is a one-time setup for your developer workstation.

証明書を追加するには、次のコマンドを実行します。To add a certificate, run the following command.

pbiviz --install-cert

Windows OSWindows OS

  1. [証明書のインストール] を選択します。Select Install Certificate....

  2. [現在のユーザー] を選択し、[次へ] をクリックします。Select Current User and then select Next.

  3. [証明書をすべて次のストアに配置する] を選択し、[参照] を選択します。Select Place all certificate in the following store and select Browse....
  4. [信頼されたルート証明機関] を選択し、[OK] を選択します。Select Trusted Root Certification Authorities and then select OK. [次へ]を選びます。Select Next.

  5. [完了]を選びます。Select Finish.

  6. セキュリティの警告ダイアログ ボックスで、[はい] を選択します。Select Yes on the security warning dialog.

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

注意

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

OSXOSX

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

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

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

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

注意

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

開発者向けビジュアルのライブ プレビューを有効にするEnable live preview of developer visual

カスタム ビジュアルのライブ プレビューを有効にするには、以下の手順を実行します。To enable a live preview of your custom visual, follow these steps. 有効にすると、レポートの編集時に Powerur BI サービス内でビジュアルを使用できます。This allows the visual to be used within the Power BI service when editing reports.

  1. app.powerbi.com を参照し、サインインします。Browse and sign into app.powerbi.com.
  2. 歯車アイコン を選択し、[設定] を選択します。Select the gear icon and then select Settings.

  3. [開発者] を選択し、[テスト用の開発者向けビジュアルを有効にする] を選択します。Select Developer and then select Enable developer visual for testing.

  4. [視覚化] ウィンドウで [開発者向けビジュアル] を選択します。Select the Developer Visual in the Visualization pane.

    注意

    この操作を行うには、開発用コンピューター上のビジュアル フォルダーから pbiviz start を実行しておく必要があります。This requires that you have run pbiviz start from the visual folder on your development machine. ビジュアルの作成方法の詳細については、この記事の「新しいビジュアルを作成する」をご覧ください。For more information on creating your visual, see Create a new visual in this article.

  5. レポート キャンバスで、ビジュアルを選択します。Select the visual in the report canvas. 他のビジュアルの場合と同じ方法でデータをバインドすることができます。You can bind data in the same way you do other visuals.

これでビジュアルの開発を始めることができます。You can now begin developing your visual.

新しいビジュアルを作成するCreate a new visual

新しいビジュアル プロジェクトを作成するには、次のコマンドを実行します。You can create a new visual project by running the following command.

pbiviz new My Visual name

My Visual Name を、ビジュアルに付けたい名前に置き換えることができます。You can replace My Visual Name with the name you want to give the visual. この名前は後で変更することができます。その場合は、生成された pbiviz.json``name フィールドと displayName フィールドを変更します。This can be changed later by modifying the name and displayName fields within the generated pbiviz.json file.

このコマンドにより、コマンドが実行されたディレクトリ内に新しいフォルダーが作成されます。This command will create a new folder in the direct where the command was run. ビジュアル用の基本的なスターター テンプレートも生成されます。It will generate a basic starter template for your visual. コマンドが完了したら、ディレクトリを開き、使い慣れたエディターを使用して、新しいビジュアルでの作業を開始することができます。Once the command completes, you can open the directory and use your favorite editor to start working on your new visual.

Power BI でビジュアルをテストするTesting your visual in Power BI

Power BI サービスではレポートおよびダッシュ ボード内で、ビジュアルをテストすることができます。You can test your visual within the Power BI service within reports and dashboards.

ビジュアルを実行するRunning your visual

ビジュアルを実行するには、次の手順に従います。You can run your visual by doing the following.

  1. プロンプトを開きます。Open a prompt.
  2. ディレクトリを目的のビジュアル フォルダーに切り替えます。Change your directory to be your visual folder. このフォルダーは、pbiviz.json ファイルを含むフォルダーです。This is the folder that contains the pbiviz.json file.
  3. 次のコマンドを実行します。Run the following command.

    pbiviz start
    

間違った場所から実行すると、次のようなエラーが表示されます。If you are in the wrong location, you will see an error similar to the following.

    error  LOAD ERROR Error: pbiviz.json not found. You must be in the root of a visual project to run this command.
        at e (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:67:35)
        at Function.loadVisualPackage (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\lib\VisualPackage.js:62:16)
        at Object.<anonymous> (C:\Users\[user]\AppData\Roaming\npm\node_modules\powerbi-visuals-tools\bin\pbiviz-start.js:43:15)
        at Module._compile (module.js:556:32)
        at Object.Module._extensions..js (module.js:565:10)
        at Module.load (module.js:473:32)
        at tryModuleLoad (module.js:432:12)
        at Function.Module._load (module.js:424:3)
        at Module.runMain (module.js:590:10)
        at run (bootstrap_node.js:394:7)

Power BI でビジュアルを表示するViewing your visual in Power BI

レポート内にビジュアルを表示するには、該当するレポートに移動し、[視覚化] ウィンドウでビジュアルを選択します。To view your visual in a report, go to that report and select the visual within the Visualizations pane.

注意

この操作を行うには、「ビジュアルを実行する」セクションの手順に従って pbiviz start コマンドを事前に実行しておく必要があります。You must run the pbiviz start command before doing this as discribed in the Running your visual section.

ビジュアル用のスターター テンプレートが表示されます。You will then see the starter template for the visual.

ツールバーの項目Toolbar item 説明Description
Refresh visual (ビジュアルの更新)Refresh visual 自動再読み込みが無効になっている場合は、ビジュアルを手動で更新します。Manually refresh the visual if auto reload is disabled.
自動再読み込みの切り替えToggle auto reload オンにすると、ビジュアル ファイルを保存するたびに、ビジュアルが自動的に更新されます。When turned on, the visual will automatically update every time you save your visual file.
Dataview の表示Show dataview デバッグ用にビジュアルの基になるデータ ビューを示します。Shows the visual's underlying data view for debugging
ヘルプを取得Get help GitHub 内のドキュメントです。Documentation within GitHub
フィードバックの送信Send feedback パフォーマンス向上のためにご意見がありましたらお寄せください。Let us know if there is anyway we can improve the experience! (GitHub アカウントが必要)(Requires GitHub account)

Power BI Desktop での使用および配布に備えてビジュアルをパッケージ化するPackage your visual for use in Power BI Desktop and distribution

ビジュアルを Power BI Desktop に読み込む場合、またはビジュアルを Power BI ビジュアル ギャラリーでコミュニティと共有する場合は、あらかじめ pbiviz ファイルを生成しておく必要があります。Before you can load your visual into Power BI Desktop, or share it with the community in the Power BI Visual gallery, you'll need to generate a pbiviz file.

ビジュアルをパッケージ化するには、次の手順に従います。You can package your visual by doing the following.

  1. プロンプトを開きます。Open a prompt.
  2. ディレクトリを目的のビジュアル フォルダーに切り替えます。Change your directory to be your visual folder. このフォルダーは、pbiviz.json ファイルを含むフォルダーです。This is the folder that contains the pbiviz.json file.
  3. 次のコマンドを実行します。Run the following command.

    pbiviz package
    

このコマンドは、ビジュアル プロジェクトの dist/ ディレクトリに pbiviz を作成します。This command will create a pbiviz in the dist/ directory of your visual project. pbiviz ファイルが既に存在している場合、そのファイルは上書きされます。If there is already a pbiviz file present, it will be overwritten.

ビジュアル API バージョンを更新するUpdating the visuals API version

pbiviz new を使用してビジュアルを作成すると、適切な API の種類の定義と json スキーマのコピーがビジュアルのディレクトリにコピーされます。When you create a visual using pbiviz new, a copy of the appropriate API type definitions and json schemas are copied into your visual's directory. pbiviz update コマンドを使用すれば、これらのファイルを必要に応じて更新することができます。You can use the pbiviz update command to update these files if needed. この機能は、Microsoft が過去の API バージョンの修正プログラムをリリースする場合、またはユーザーが最新の API バージョンに更新する場合に便利です。This can be useful if we release a fix for a past API version or if you want to update to the latest API version.

既存の API バージョンを更新するUpdating your existing API version

Microsoft が既存の API に対して更新プログラムをリリースした場合、ユーザーが最新バージョンを取得するには次の手順を実行します。If we release an update to an existing API, you can get the latest version by doing the following.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update

これにより、更新された種類の定義とスキーマを含む npm から最新のツールがダウンロードされます。This will download the latest tools from npm which include the updated type definitions and schemas. pbiviz update を使用すると、 pbiviz.json ファイル内の apiVersion プロパティが最新のバージョンで上書きされます。Using pbiviz update will overwrite the apiVersion property in your pbiviz.json fiel with the latest version.

別の API バージョンにアップグレードするUpgrading to a different API version

上記の場合と同じ手順を使用して、別の API バージョンに更新することができます。You can update to a different API version by using the same steps as mentioned above. 使用する API バージョンを明示的に指定することができます。You can explicitly specify the API version you want to use.

#Update your version of pbiviz
npm install -g powerbi-visuals-tools

#Run update from the root of your visual project, where pbiviz.json is located
pbiviz update 1.2.0

この場合、ビジュアルは API バージョン 1.2.0 に更新されます。This would update yoru visual to API version 1.2.0. 1.2.0 は、希望するどのバージョンとも置き換えることができます。You can replace 1.2.0 with whatever version your wanting to use.

警告

ツールでは常に、安定した API バージョンが既定の API バージョンとして使用されます。The default API version used by the tools will always be the stable version of the API. 既定の API バージョンより前のバージョンは安定性がなく、変更される可能性があります。Any versions later than the default API version are unstable and subject to change. また、予期しない動作をしたり、Power BI サービスと Power BI Desktop とで動作が異なる場合があります。They may have unexpected behaviors and behave differently between the Power BI service and Power BI Desktop. 現在の安定した API バージョンについては、変更ログを参照してください。For the current stable API version, see the change log. プレリリース バージョンの詳細については、ロードマップを参照してください。For more information about pre-release versions, see the roadmap.

ビジュアル プロジェクトの内部Inside the visual project

ビジュアル プロジェクトは、pbiviz new コマンドを実行したときに作成されるフォルダーです。Your visual project is the folder that gets created when you run the pbiviz new command.

ファイルの構造File structure

項目Item 説明Description
assets/assets/ ビジュアル資産 (アイコンやスクリーン ショットなど) を格納するために使用します。Used to store visual assets (icon, screenshots, etc).
dist/dist/ pbiviz package を実行すると、この場所に pbiviz ファイルが生成されます。When you run pbiviz package, the pbiviz file will be generated here.
src/src/ ビジュアルの TypeScript コードです。Typescript code for your visual.
style/style/ ビジュアルの Less スタイルです。Less styles for your visual.
.gitignore.gitignore リポジトリ内の追跡する必要がないファイルを無視するように Git に指示します。Tells git to ignore files that shouldn't be tracked in the repository.
capabilities.jsoncapabilities.json ビジュアルの機能を定義するために使用されます。Used to define the capabilities of your visual.
package.jsonpackage.json モジュールを管理するために npm によって使用されます。Used by npm to manage modules.
pbiviz.jsonpbiviz.json 主要な構成ファイルです。Main configuration file.
tsconfig.jsontsconfig.json TypeScript コンパイラの設定です。Typescript compiler settings. tsconfig.json の詳細については、こちらを参照してください。Learn more about tsconfig.json.

pbiviz.jsonpbiviz.json

このファイルは、ビジュアルの主要な構成ファイルです。This file is the main configuration file for your visual. ビジュアルを構築するのに必要な情報として、メタデータとファイルに関する情報が含まれています。It contains metadata, as well as information about your files, needed to build your visual.

{
    "visual": {
        "name": "myVisual", // internal visual name (should not contain spaces)
        "displayName": "My Visual!", // visual name displayed to user (used in gallery)
        "guid": "PBI_CV_xxxxxxx", // a unique id for this visual MUST BE UNIQUE
        "visualClassName": "Visual" // the entry class for your visual
        "version": "1.0.0", // visual version. Should be semantic version (increment if you update the visual)
        "description": "", // description used in gallery
        "supportUrl": "", // url to where users can get support for this visual
        "gitHubUrl": "" // url to the source in github (if applicable)
    },
    "apiVersion": "1.0.0", //API version this visual was created with
    "author": {
        "name": "", // your name
        "email": "" // your e-mail
    },
    "assets": {
        "icon": "assets/icon.png" // relative path to your icon file (20x20 png)
    },
    "style": "style/visual.less", // relative path to your less file
    "capabilities": "capabilities.json" // relative path to your capabilities definition 
}

ビジュアルのソース (TypeScript)Visual source (TypeScript)

ビジュアル コードは TypeScript で記述する必要があります。TypeScript は JavaScript のスーパー セットであり、高度な機能をサポートすると共に ES6/ES7 機能への早期アクセスに対応します。Visual code should be written in TypeScript, which is a superset of JavaScript that support more advanced features and early access to ES6/ES7 functionality.

すべての TypeScript ファイルを src/ ディレクトリに格納し、tsconfig.jsonfiles 配列に追加する必要があります。All TypeScript files should be stored in the src/ directory and added to the files array in tsconfig.json. これにより、TypeScript コンパイラはそれらを任意の順序で読み込むことができます。This allows the TypeScript compiler to load them and in what order.

ビジュアルがビルドされると、すべての TypeScript ファイルが 1 つの JavaScript ファイルにコンパイルされます。When your visual is built, all of the TypeScript will be compiled into a single JavaScript file. これにより、他のファイルからエクスポートされた要素は、両方のファイルが tsconfig 内にリストされていれば、手動でそれらを require しなくても、参照することができます。This allows you to reference exported elements from other files without needing to manually require them as long as both files are listed in the tsconfig.

ビジュアルを作成するのに必要な数だけファイルとクラスを作成することができます。You can create as many files and classes as you need to create your visual.

TypeScript の詳細については、こちらを参照してください。Learn more about TypeScript.

ビジュアル スタイル (Less)Visual style (Less)

ビジュアルのスタイル設定は、カスケード スタイル シート (CSS) を使用して処理されます。Visual styling is handled using cascading style sheets (CSS). わかりやすくするために、入れ子、変数、mixin、条件、ループなどの高度な機能をサポートする Less プリコンパイラを使用します。これらの機能を使用しない場合は、Less ファイル内にプレーンな CSS だけを記述します。For your convience, we use the Less pre-compiler which supports some advanced features such as nesting, variables, mixins, conditions, loops, etc. If you don't want to use any of these features, you can just write plain CSS in the Less file.

Less ファイルはすべて style/ ディレクトリに保存します。All Less files should be stored in the style/ directory. pbiviz.jsonファイル内の style フィールドに指定されているファイルが読み込まれます。The file specified under the style field within your pbiviz.json file will be loaded. 追加のファイルを読み込むには、@import を使用します。Any additional files should be loaded using @import.

Less の詳細については、こちらを参照してください。Learn more about Less.

デバッグDebugging

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

ビジュアルを AppSource に送信するSubmit your visual to AppSource

他のユーザーが使用できるようにビジュアルをリストすることはできますが、その場合、AppSource に送信する必要があります。You can list your visual for others to use but submitting it to AppSource. このプロセスの詳細については、「カスタム ビジュアルを Office ストアに発行する」を参照してください。For more information on this process, see publish custom visuals to AppSource.

トラブルシューティングTroubleshooting

Pbiviz コマンドが見つかりません (または類似のエラー)Pbiviz command not found (or similar errors)

ターミナル/コマンド ラインで pbiviz を実行する場合は、ヘルプ画面を表示する必要があります。If you run pbiviz in your terminal / command line, you should see the help screen. ヘルプ画面が表示されない場合、コマンドは正しくインストールされていません。If not, it is not installed correctly. バージョン 4.0 以降の NodeJS がインストールされていることを確認します。Make sure you have at least the 4.0 version of NodeJS installed.

詳細については、「NodeJS および Power BI ツールをインストールする」を参照してください。For more information, see Install NodeJS and the Power BI tools...

[視覚化] タブで "ビジュアルのデバッグ" が見つかりませんCannot find the debug visual in the Visualizations tab

"ビジュアルのデバッグ" は、[視覚化] タブ内でプロンプト アイコンのように表示されます。The debug visual looks like a prompt icon within the Visualizations tab.

表示されない場合は、Power BI の設定内で有効にされていることを確認してください。If you don't see it, make sure you have enabled it within the Power BI settings.

注意

ビジュアルのデバッグ機能は、現時点では、Power BI サービスでのみ使用可能で、Power BI Desktop とモバイル アプリでは使用できません。The debug visual is currently only available in the Power BI service and not in Power BI Desktop or the mobile app. パッケージ化したビジュアルはあらゆる場所で機能します。The packaged visual will still work everywhere.

詳細については、「開発者向けビジュアルのライブ プレビューを有効にする」を参照してください。For more information, see Enable live preview of developer visual...

ビジュアル サーバーに接続できませんCan't contact visual server

ビジュアル プロジェクトのルートから、ターミナル/コマンド ラインで pbiviz startコマンドを使用してビジュアル サーバーを実行します。Run the visual server with the command pbiviz start in your terminal / command line from the root of your visual project. サーバーが動作する場合、SSL 証明書が正しくインストールされていない可能性があります。If the server is running, it is likely that your SSL vertificates weren't installed correctly.

詳細については、「ビジュアルを実行する」または「サーバー証明書のセットアップ」を参照してください。For more information, see Running your visual or Server certificate setup.

次の手順Next steps

Power BI での視覚化Visualizations in Power BI
Power BI でのカスタム ビジュアルCustom Visualizations in Power BI
カスタム ビジュアルを Office ストアに発行するPublish custom visuals to the Office store
TypeScriptTypeScript
Less CSSLess CSS

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