Dynamics CRM Online 2015 Update 1 新機能: Web API 開発者プレビュー その 2

みなさん、こんにちは。

前回に引き続き Dynamics CRM Online 2015 Update 1 で提供される
Web API 開発者プレビューについて紹介します。連載記事になるため
第 1 回からご覧ください。

Web API 開発者プレビュー その 1

多くの開発者は、ただ説明されるよりハンズオンを希望されるため、
この連載でもハンズオン形式で機能を紹介していきます。

OData エンドポイントを利用する場合、T4 テンプレートなどを利用
したクライアントを作成する方法が一般的ですが、実際の通信で何が
起きているかを理解するため、まずは HttpClient を使います。

※T4 テンプレートを利用した機能の利用は、連載の後半で紹介します。

事前準備

Azure AD への登録

OAuth 2.0 を利用するには、Dynamics CRM Online の認証を行う Azure
AD 上で開発するアプリケーションを事前に登録する必要があります。
以下の手順で登録を行います。

1. ブラウザで https://manage.windowsazure.com へ接続します。

2. Azure サブスクリプションがあるアカウントでログインします。
利用する Dynamics CRM Online とは異なるアカウントでも結構です。

3. 左のメニュー一覧より Active Directory を選択します。

4. 利用する Dynamics CRM Online と異なるテナントにログインした場合で
ディレクトリの一覧に Dynamics CRM Online のディレクトリが表示されて
いない場合、以下手順で追加します。Dynamics CRM Online のディレクトリ
が表示されている場合はステップ 10 に進んでください。

5. 新規ボタンをクリックして、APP SERVICE | ACTIVE DIRECTORY より
ディレクトリを選択します。

6. カスタム作成をクリックして「既存ディレクトリの使用」を選択します。

7. 「サインアウトする準備ができました。」をチェックしてチェック
マークをクリックします。自動的にサインアウトされた後、サインインを
求められるので Dynamics CRM Online の管理者でログインします。

8. ユーザーをディレクトリの管理者にするか聞かれるので承認します。

9. 再度自動的にサインアウトされるので元のアカウントでログインします。

10. ディレクトリ一覧より Dynamics CRM Online のテナントを選択します。

11. アプリケーションタブをクリックして、画面下にある「追加」ボタンを
クリックします。

12. 「組織で開発中のアプリケーションを追加」を選択します。

13. 名前に「CRM Web API Test」と入力し、「ネイティブクライアント
アプリケーション」を選択して次へ進みます。

14. リダイレクト URI に 「https://localhost/webapipreview」と
入力して、完了します。

15. アプリケーション登録後、「構成」タブを選択します。

16. 表示されている「クライアント ID」を控えます。

17. 画面下部にある「アプリケーションの追加」をクリックします。

18. アプリケーションの一覧より Dynamics CRM Online を選択して
画面右下の完了マークをクリックします。

19. デリゲートされたアクセスより「Access CRM Online as organization
users」にチェックを入れます。

20. 画面下部の「保存」ボタンをクリックしたら登録完了です。

コンソールアプリケーションの作成

まず検証で利用するコンソールアプリケーションを準備します。

1. Visual Studio を起動します。新しいプロジェクトより Visual C# の
コンソールアプリケーションを作成します。ここでは名前を
CrmWebAPITest としました。

2. Web API は OAuth 2.0 での認証/認可が必要なため、NuGet より
ADAL (Active Directory Authentication Library) を追加します。
プロジェクトを右クリックして、「NuGet パッケージの管理」を
クリックします。

3. 左ペインで「オンライン」を選択して、画面右上の検索窓に
「ADAL」と入力して検索します。

4. 検索結果より 「Active Directory Authentication Library」を選択
してインストールします。

5. 同様に 「JSON.NET」もインストールしてください。

6. プロジェクト内の「参照設定」を右クリックして「参照の追加」を
クリックします。アセンブリより以下のアセンブリを追加します。

System.Net
System.Net.Http

また以下の using ステートメントを追加します。

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System.Net.Http;
using System.Net.Http.Headers;

7. クラスレベルのフィールドとして Main メソッドの前に以下を
追加します。 clientId は先ほど取得したものを入力してください。
※serverUrl をご利用の環境にアドレスに変更してください。

#region クラスレベルメンバー

static string serverUrl = "https://<CRM組織名>.crm7.dynamics.com";
static string authUrl = "https://login.windows.net/common";
static string clientId = "取得したIDを入力";
static string redirectUri = "https://localhost/webapipreview";

#endregion クラスレベルメンバー

8. Main メソッドに認証および実行部分とエラーハンドリングのコードを
追加します。

try
{
    AuthenticationContext authContext = new AuthenticationContext(authUrl);
    AuthenticationResult result = authContext.AcquireToken(serverUrl, clientId, new Uri(redirectUri));

    Program app = new Program();
    Task.WaitAll(Task.Run(async () => await app.Run(result.AccessToken)));
}          
catch (System.Exception ex)
{
    Console.WriteLine("エラーが発生しました。");
    Console.WriteLine(ex.Message);
}
finally
{
    Console.WriteLine("Press <Enter> to exit.");
    Console.ReadLine();
}       

9. プログラムを実行するメソッドを追加します。

public async Task Run(string accessToken)
{
    // HttpClient の作成
    using (HttpClient httpClient = new HttpClient())
    {
        // Web API アドレスの作成
        string serviceUrl = serverUrl + "/api/data/";
        // ヘッダーの設定
        httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    }
}

10. ソリューションをビルドします。参考までのプログラムの
全体を以下に示します。

using Microsoft.IdentityModel.Clients.ActiveDirectory;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace CrmWebAPITest
{
    class Program
    {
        #region クラスレベルメンバー
       
        static string serverUrl = .crm7.dynamics.com">https://<CRM組織名>.crm7.dynamics.com;
        static string authUrl = "https://login.windows.net/common";
        static string clientId = "取得したIDを入力";
        static string redirectUri = "https://localhost/webapipreview";

        #endregion クラスレベルメンバー

        public async Task Run(string accessToken)
        {
            // HttpClient の作成
            using (HttpClient httpClient = new HttpClient())
            {
                // Web API アドレスの作成
                string serviceUrl = serverUrl + "/api/data/";
                // ヘッダーの設定
                httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
                httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            }
        }

        static void Main(string[] args)
        {
            try
            {
                AuthenticationContext authContext = new AuthenticationContext(authUrl);
                AuthenticationResult result = authContext.AcquireToken(serverUrl, clientId, new Uri(redirectUri));

                Program app = new Program();
                Task.WaitAll(Task.Run(async () => await app.Run(result.AccessToken)));
            }          
            catch (System.Exception ex)
            {
                Console.WriteLine("エラーが発生しました。");
                Console.WriteLine(ex.Message);
            }
            finally
            {
                Console.WriteLine("Press <Enter> to exit.");
                Console.ReadLine();
            }       
        }
    }
}

動作確認

ここまで準備したものが期待通り動作するか確認します。

1. 上記ステップ 9 で追加したメソッド内にブレークポイントを
設定します。F5 キーを押下してプログラムを実行します。

2. サインイン画面が出るので、Dynamics CRM Online 組織に
アクセスできる権限でサインインします。

3. ブレークポイントがヒットしたら、AccessToken が取得できて
いるか確認します。

まとめ

少し手順が長かったですが、今回の作業で事前準備が整いました。
次回以降で実際に色々な機能を試していきますので、お楽しみに！

- 中村 憲一郎