Uncategorized

Power BI REST API を使ったデータ連携

By on • ( Leave a comment )

Power BI を使った開発

こんにちは。

Power BI における Provisioning (例 : カスタム アプリと連携したデータの準備など) を自動化する方法として、カスタムの Content Pack を作成する方法と、REST API を使う方法があります。

ここでは、REST API を使った Provisioning について注意点も含め紹介したいと思います。

補足 : Content Pack 開発の詳細は解説しませんが、ISV 企業の方は、自社アプリと連携して動作する独自の Content Pack を開発して、Power BI の一般ユーザーに公開できます。(既に、Salesforce, Webtrends, Twilio 等々、多くの Content Pack が登録されています。Content Pack 開発に興味ある方は、http://dev.powerbi.com/ からコンタクトしてください。)
なお、Power BI Pro をご利用の方は、自分が所属するテナント向けに (皆さんの所属企業, 学校向けに)、カスタムの Content Pack (Organizational Content Pack) を配置 (発行) してテナント内で共有できます。(情シス向け)

 

Power BI で使用するオブジェクト

Power BI REST API を使ったアプリを構築するには、Power BI で扱うオブジェクト構成をある程度理解しておく必要があります。(このあと、いくつかの用語が出てくるためです。)

Power BI を構成する 3 大要素として Dashboards (ダッシュボード), Reports (レポート), Datasets (データセット) があります。

Power BI の Dataset (データセット) は、通常、何某かの Data Source (例えば、Excel Workbook, SQL Server 等の Database, Salesforce 等の Application, など) と 1 : 1 に紐付きますが、今回は、後述するように REST API を使って作成するため、Data Source と紐付かない独立した Dataset を使用します。なお、単一の Dataset には複数の Table を含めることができ、各 Table (表) は、Column (列) と Row (行) で構成されます。(つまり、Dataset は、一連の Table の集まった、データの意味的な 1 まとまりと考えてください。)

また、Report (レポート) は、単一の Dataset に紐付いて作成される表現 (グラフ, チャート含む) であり、Report にとって Dataset は必須です。(ただし、Power BI Desktop を使用した場合には、特別に、複数の Dataset を組み合わせて単一の Report を作成できるようです。) 逆に、単一の Dataset は複数の Report で参照できます。Dashboard (ダッシュボード) は Report などが Pin 留めされた Tile と呼ばれる要素の集まったキャンバスで、複数の Report と関係付けられます。

補足 : Power BI の構成については「Power BI – basic concepts」が参考になります。

 

アプリ登録

REST API を使用する前に、アプリの登録をおこない、access token を取得するための HTTP Flow を実装します。

ここでは具体的手順は省略しますが、「Azure AD を使った API 連携の Client 開発 (OAuth 2.0 紹介)」で解説した手順で、Azure Portal を使って、Azure AD の Application 登録をおこないます。

この際、Application の Required Permissions として、下図の通り [Power BI service] を追加して、今回は少なくとも [Read and Write all Datasets], [View content properties] の Delegated Permissions を設定します。(後者の Permission は、このあと紹介する Import 結果の確認で必要になります。)
なお、下図では、すべての Delegated Permissions を設定しています。

補足 : この Permission 設定をおこなう前に、ログインしているアカウントで Power BI Service にアクセスして事前に Sign Up をおこなってください。(サインアップしていない場合、上図のような Power BI Service の Application が表示されません。)

なお、毎度の注意点ですが、一般の利用者 (データ連携をおこなうアプリケーションの利用者) はこの登録は不要です。REST API を使ったアプリの提供者 (ISV) のみが上記の登録をおこないます。(「Azure Active Directory の Common Consent Framework」を参照してください。)

 

認証 (Authentication)

あとは、OAuth の Flow で access token を取得します。

以下に、Web Application の場合の HTTP Flow の例 (サンプル) を簡単に箇条書きしますが、この Flow の詳細については「Azure AD を使った API 連携の Client 開発 (OAuth 2.0 紹介)」を参照してください。(下記の通り、resource には https://analysis.windows.net/powerbi/api を指定します。)

1) Web Browser (または Web Browser Component) を使って下記 URL を表示します。(この際、Azure AD のログイン画面が表示されます。)

GET https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id=f0fcd7f1-cbcd-4f97-bd4b-0ab5bd6086d4&resource=https%3a%2f%2fanalysis.windows.net%2fpowerbi%2fapi&redirect_uri=https%3a%2f%2flocalhost%2ftest01

2) 表示されるログイン画面で、Azure AD (Office 365) のアカウントで Login すると、下記に Redirect されます。

GET https://localhost/test01?code=AAABAAAAiL...&session_state=...

3) 上記の code を使って、下記の HTTP POST を要求します。

POST https://login.microsoftonline.com/common/oauth2/tokenContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code=AAABAAAAiL...&client_id=f0fcd7f1-cbcd-4f97-bd4b-0ab5bd6086d4&client_secret=7AWSirHm30...&redirect_uri=https%3A%2F%2Flocalhost%2Ftest01

4) 上記の Response として、下記の通り access token が取得できます。

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8{  "token_type": "Bearer",  "expires_in": "3599",  "scope": "Dataset.ReadWrite.All",  "expires_on": "1451979315",  "not_before": "1451975415",  "resource": "https://analysis.windows.net/powerbi/api",  "access_token": "eyJ0eXAiOi...",  "refresh_token": "AAABAAAAiL...",  "id_token": "eyJ0eXAiOi..."}

 

開発 – Dataset の作成

では、ここから REST API を使います。まず、Table を 1 つだけ含んだ簡単な Dataset を作成してみましょう。

上記で取得した access token を使って、以下の HTTP Request を発行します。今回は単一の Table のみを作成していますが、複数の Table を作成するには、下記の tables の配列に複数の要素を設定します。

POST https://api.powerbi.com/v1.0/myorg/datasetsAccept: application/jsonAuthorization: Bearer eyJ0eXAiOi...Content-Type: application/json; charset=utf-8{  "name": "ProductOrder",  "tables": [{  "name": "Product",  "columns": [{  "name": "ProductID",  "dataType": "Int64"},{  "name": "Name",  "dataType": "string"},{  "name": "Category",  "dataType": "string"},{  "name": "OrderDate",  "dataType": "DateTime"}  ]}  ]}

Dataset (および、その中の Table) の作成に成功すると、下記の通り HTTP Response が返ってきます。ここで返って来る Dataset id (下記の 0fc7c737-4e20-463f-8e7b-8e9641a6a0e9) は、この後の処理で必要になります。

HTTP/1.1 201 CreatedContent-Type: application/json; odata.metadata=minimalLocation: https://api.powerbi.com/v1.0/myorg/datasets('0fc7c737-4e20-463f-8e7b-8e9641a6a0e9'){  "@odata.context": "http://api.powerbi.com/v1.0/myorg/$metadata#datasets/$entity",  "id": "0fc7c737-4e20-463f-8e7b-8e9641a6a0e9",  "name": "ProductOrder",  "defaultRetentionPolicy": "None"}

Power BI にログインして確認すると、下図の通り、ProductID, Name, Category, OrderDate の各列を持つ Table「Product」と、それを含んだ Dataset「ProductOrder」が作成されています。

REST API を使って Table のスキーマ変更なども可能です。

 

開発 – Data の更新

上記で作成した Table にデータを挿入するには、対象となる Table に Row を追加します。

対象となる Table の Row は、以下の URI で表現されます。

https://api.powerbi.com/v1.0/myorg/datasets/  {dataset_id}/tables/{table_name}/rows

今回の場合は、下記の通りです。

https://api.powerbi.com/v1.0/myorg/datasets/  0fc7c737-4e20-463f-8e7b-8e9641a6a0e9/  tables/Product/rows

例えば、今回作成した「Product」の Table にデータを挿入するには、下記の通り HTTP Request をおこないます。(成功すると、Response として HTTP 200 OK が返ります。)
もちろん、データの削除も可能です。

POST https://api.powerbi.com/v1.0/myorg/datasets/0fc7c737-4e20-463f-8e7b-8e9641a6a0e9/tables/Product/rowsAccept: application/jsonAuthorization: Bearer eyJ0eXAiOi...Content-Type: application/json; charset=utf-8{  "rows": [{  "ProductID": 1,  "Name": "Digital Camera",  "Category": "Hardware",  "OrderDate": "10/29/2015"}  ]}

上記の Dataset を使用した Report や Dashboard (例えば、上記の Table のデータを使った Report が Pin 留めされた Dashboard) を作成していただくとわかりますが、REST API でデータを更新すると、Real-time に Dashboard (Dashboard 上の Tile) が更新されます。つまり、Azure Stream Analytics と連携した Dashboard のように、刻一刻と変化するデータのモニタリングなどの目的でも、この REST API を使うことができます。(REST API を使うと、アプリに関連するデータをあらかじめ準備して展開するような強力なソリューションを開発できます。)

なお、現時点では、上記のように REST API で作成した Dataset のみが REST API を使ってデータ更新可能ですので注意してください。
この制約は、例えば、このあと述べるシナリオでも大きな障壁となってきます。。。

 

開発 – Artifacts の Import

さて、ここまで、Dataset を中心に処理を見てきましたが、Report や Dashboard は Visualization を含んでいるため REST API のみで作成するようにはなっていません。そこで、ここで紹介する Import API を使うと、Dataset だけでなく、あらかじめ作成しておいた Report も一緒に配置 (Provisioning) できます。

まず、Import の対象となる Artifact は Power BI Desktop を使って作成・保存します。下図の通り、Power BI Desktop を使って、上記と同じ構成の Dataset が構築できるので、この Dataset を使用した Report なども同時に作成しておきます。

そして保存の際に、Power BI File (.pbix ファイル) の形式で保存します。

補足 : Power BI Desktop で Data Source と接続しない独立した Dataset を作成するには、[データの入力] ボタンをクリックします。(このとき入力する名前が Table 名になります。)

下記の通り Multipart form-data 形式の REST API を呼び出すと、この保存された .pbix ファイルを使用しているテナントに Import できます。

なお下記で Query String として必ず datasetDisplayName (作成する Dataset の名前です) を指定するようにしてください。(Table 名は、上記の Power BI Desktop で作成した名前がそのまま使用されますが、Dashboard 名はこの datasetDisplayName で指定する必要があります。)

また、ここでは .pbix ファイルの Binary Data を直接渡していますが、OneDrive for Business に .pbix ファイルを配置しておくと、File Path (URI) を指定して Import することも可能です。

POST https://api.powerbi.com/beta/myorg/imports?datasetDisplayName=ProductOrderAccept: application/jsonAuthorization: Bearer eyJ0eXAiOi...Content-Type: multipart/form-data; boundary="A300testx"--A300testxContent-Disposition: form-data; name=fieldNameHere; filename=test.pbixContent-Type: application/octet-stream{PBIX binary data here}--A300testx--

上記の呼び出しに成功すると、Power BI Desktop で作成した Dataset や Report がそのまま Import され、HTTP Response として下記のように Import Id が返されます。

HTTP/1.1 202 AcceptedContent-Type: application/json; charset=utf-8Location: https://wabi-west-us-redirect.analysis.windows.net/beta/myorg/imports/3811a280-330b-40db-bfb1-a4dad0cf1958{"id":"3811a280-330b-40db-bfb1-a4dad0cf1958"}

作成された Dataset id などを取得したい場合には、上記の Import id を使って下記の通り結果を取得できます。

HTTP Request

GET https://api.powerbi.com/beta/myorg/imports/3811a280-330b-40db-bfb1-a4dad0cf1958Accept: application/jsonAuthorization: Bearer eyJ0eXAiOi...

HTTP Response

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8{  "id": "3811a280-330b-40db-bfb1-a4dad0cf1958",  "importState": "Succeeded",  "createdDateTime": "2016-01-05T09:05:57.85",  "updatedDateTime": "2016-01-05T09:05:57.85",  "reports": [{  "id": "645ef020-b172-4942-9b3e-93553918052f",  "name": "ProductOrder",  "webUrl": "https://app.powerbi.com/reports/645ef020-b172-4942-9b3e-93553918052f"}  ],  "datasets": [{  "id": "bc6752c7-d311-4f99-a749-0082c7cb881d",  "name": "ProductOrder",  "tables": [  ],  "webUrl": "https://app.powerbi.com/datasets/bc6752c7-d311-4f99-a749-0082c7cb881d"}  ],  "name": "ProductOrder"}

なお、繰り返しますが、残念なことに、前述の通り、上記の方法で Import した Dataset に REST API を使ってデータ (row) の追加・削除をおこなうことは、現在はできません。
つまり現時点では、この方法で Provision された Dashboard は、アプリからは主に列挙や参照の目的でしか扱えないので注意してください。(ここがつながってくると良いのですが。。。) カスタムの Content Pack のような仕組みを、ここで紹介している REST API だけで作るのは、今のところ無理な感じです。。。

Categories: Uncategorized

Tagged as: ,

Leave a Reply