LINQPad 4 用 Dynamics CRM REST/Web API ドライバーが公開されました!

みなさん、こんにちは。

今日は先日公開された、LINQPad 4 用 Dynamics CRM REST および Web API 向け
ドライバーを紹介します。

REST 用: https://crmlinqpadrest.codeplex.com/
Web API 用: https://crmlinqpadwebapi.codeplex.com/

SOAP 用については、以下をご覧ください。
LINQPad 4 用 Dynamics CRM ドライバーが公開されました!

LINQPad とは

LINQPad (https://www.linqpad.net/) は LINQ クエリを様々なデータソースに対して
実行できる、開発者向けのツールです。また、LINQ クエリだけでなく C#/F#/VB の
ステートメントやコードブロックを実行する機能持っています。一部の機能は
無償で提供されていますが、IntelliSense やデバッグ機能は有償となっています。

Dynamics CRM ドライバーの利用

LINQPad 4 用 Dynamics CRM REST/Web API ドライバーを使うと LINQPad の
データソースとして Dynamics CRM が指定できます。早速試してみましょう。

ドライバーのインストール

1. LINQPad がインストールされていない場合、https://www.linqpad.net/ よりダウン
ロードしてインストールしてください。

2. REST 用と Web API 用のページより CRMLinqPadDriverREST.lpx ファイルと
CRMLinqPadDriverWebAPI.lpx ファイルをダウンロードします。

3. LINQPad を開いて、画面左上の Add connection リンクをクリックします。

4. 開いた画面で View more drivers… ボタンをクリックします。

5. 次の画面で Browse ボタンをクリックします。

6. ダウンロードした lpx ファイルを選択して “Open” をクリックします。

7. 同じ作業をもう一方の lpx にも実行します。

REST 用ドライバーの利用

まず REST 用 ドライバーの利用方法から紹介します。

接続の作成

1. データコンテキストの選択画面で Dynamics CRM REST Linq Pad Driver を
選択して Next をクリックします。

2. 既に ClientId がある場合、“Register to Azure AD automatically” のチェックを
外すと、ClientId を入力できます。ClientId の詳細は後ほど紹介します。不明な
場合は “Login to CRM” をクリックします。

3. 任意の組織にログインします。

4. 組織にログイン後、メタデータの取得が始まります。終わるまでしばらく待ちます。

5. Loading Data… の表示が消えたら、Exit ボタンをクリックします。LINQPad が
スキーマを作成するので、またしばらく待ちます。完了すると以下の画面の様に
スキーマ一覧が表示されます。

LINQ クエリの実行

1. まずクエリウィンドウ右上にある Connection タブから、作成した接続を
選択します。複数の接続がある場合は適切なものを選択してください。

2. 以下のように LINQ クエリを入力します。

3. “Play” ボタンをクリックするか F5 キーを押下して実行します。

4. 結果の右側にある SQL タブを選択すると、実行した LINQ クエリに相当する
OData クエリが表示されます。

Web API ドライバーの利用

Web API は Dynamics CRM Online 2015 Update 1 でリリースされた機能で、
プレビューの扱いです。機能は既定で無効になっているため、以下手順で
有効にします。尚、Web API の詳細は今後の記事で紹介します。

Web API (プレビュー) の有効化

1. ブラウザで Dynamics CRM Online に接続ます。設定 | 管理 | システムの
設定を開きます。

2. プレビュータブをクリックして、機能を有効にします。
※「プレビューを有効にする」項目の「無効化する」と「無効化しない」
は誤訳であり、後日修正されます。以下の通りに設定してください。

接続の作成

1. データコンテキストの選択画面で Dynamics CRM Web API Linq Pad Driver を
選択して Next をクリックします。

2. 既に ClientId がある場合、“Register to Azure AD automatically” のチェックを
外すと、ClientId を入力できます。ClientId の詳細は後ほど紹介します。不明な
場合は “Login to CRM” をクリックします。

3. Web API を有効にした組織にログインします。ログイン完了後、自動的に
メタデータを取得するので、完了するまで待ちます。

4. Loading Data… の表示が消えたら、Exit ボタンをクリックします。

LINQ クエリの実行

1. まずクエリウィンドウ右上にある Connection タブから、作成した接続を
選択します。複数の接続がある場合は適切なものを選択してください。

2. 以下のように LINQ クエリを入力します。

3. “Play” ボタンをクリックするか F5 キーを押下して実行します。

4. 結果の右側にある SQL タブを選択すると、実行した LINQ クエリに相当する
OData クエリが表示されます。

C# ステートメントの実行

Web API はデータのクエリ以外に、関数の実行もサポートしています。
LINQ クエリに続いて、C# ステートメントも試してみましょう。

1. Language のドロップダウンより C# Statement(s) を選択します。
以下のステートメントを記述して実行します。結果が表示されます。

2. 結果の右側にある SQL タブを選択すると、実行した関数に相当する
OData クエリが表示されます。

3. より複雑なステートメントを実行することもできます。以下の例は
取引先企業の作成を行った後、作成したレコードを関連に設定した
営業案件を作成するコードです。

// 取引先企業の作成
DataServiceCollection<account> accounts = new DataServiceCollection<account>(this);
account myaccount = new account();
accounts.Add(myaccount);
// 列の値を設定
myaccount.name = "Test Account";
// 作成を実行
this.SaveChanges(SaveChangesOptions.PostOnlySetProperties);

// 営業案件の作成
DataServiceCollection<opportunity> opportunities = new DataServiceCollection<opportunity>(this);
opportunity myopportunity = new opportunity();
opportunities.Add(myopportunity);
// 列の値を設定
myopportunity.name = "Test Opps";
// 関連を設定
myopportunity.opportunity_customer_accounts = myaccount;

// 作成を実行
this.SaveChanges(SaveChangesOptions.PostOnlySetProperties);

Console.WriteLine("営業案件が作成されました。");

Azure AD アプリケーションの登録

Dynamics CRM Online の REST および Web API エンドポイントは OAuth 2.0
による認証/認可をサポートしています。ただし OAuth 2.0 を利用するには、
事前にアプリケーション(今回の場合 LINQPad のドライバー) を Azure AD に
登録する必要があり、通常手動での作業が必要となります。
※手順は Walkthrough: Register a CRM app with Active Directory を参照。

これらの手作業をなくすために、ドライバーは Azure AD にアプリケーションを
自動登録する仕組みを含んでいます。詳細が気になる方は是非ソースコードを
確認してください。

既定では、Dynamics CRM にログインしたユーザー権限でアプリケーションの
登録を試しますが、権限が不足している場合は Azure AD に権限があるユーザー
を求められます。もし Azure AD が他のユーザーに管理されている場合は、別途
アプリケーションを登録していただき、ClientId を取得してください。

ClientId 取得後、以下の画面にて “Register to Azure AD” のチェックを外すことで
手動で ClientId を設定できます。

ツールで自動登録された場合、以下のように登録されます。

REST 用ドライバーを設置型で利用している場合は、Windows 統合
認証を利用するため、 AD FS に対する登録は不要です。

まとめ

LINQPad を利用すると、ちょっとしたクエリ確認や動作確認をしたい
場合に非常に便利です。是非お試しください!

- 中村 憲一郎