Dynamics CRM 2016 SDK 新機能: Web API その 1

Article
12/13/2015

みなさん、こんにちは。

今回から数回で、Dynamics CRM 2016 SDK の新機能として、正式版と
なった Web API について紹介します。

概要

Web API は Microsoft Dynamics CRM Online 2015 Update 1 にてプレビュー
版として公開されましたが、今回のリリースで正式版となりました。

尚、Web API のリリースを受け、REST エンドポイントは Deprecated
となり、今後のリリースで機能が削除される可能性がありますので、
ご注意ください。

提供される機能

Web API は以下の機能がサポートされます。

- OData 4.0 プロトコルのサポート: OData 4.0 についての詳細は次の
リンクをご参照ください。 https://www.odata.org/libraries/
- レコードの CRUD (作成、読み取り、更新、削除)
- WhoAmI など組織サービス Execute メソッドで実行される各種
組織要求の実行
- メタデータの操作
- 探索サービス
- ビューの実行など一部特殊な操作
- エンドポイントのバージョニング

プレビューの時はレコードの CRUD と一部の組織要求のみサポート
していましたが、今回のリリースでは SOAP エンドポイントを
置き換えられるだけの機能を提供しています。

サポートされる認証方式

Microsoft Dynamics CRM Online の場合は OAuth 2.0 認証のみ
ですが、設置型の場合は Windows 統合認証もサポートされます。
また Web リソース内から利用する場合は別途認証は不要です。

検証のための事前準備

次回以降で具体的なコードを紹介していきます。Microsoft
Dynamics CRM Online 環境での操作を紹介しますので、以下の
手順でベースとなるプログラムを準備します。

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/webapi」と
入力して、完了します。

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/webapi”;

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

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

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

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

public async Task Run(string accessToken)
{
    // HttpClient の作成
    using (HttpClient httpClient = new HttpClient())
    {
        // Web API アドレスの作成
        string serviceUrl = serverUrl + "/api/data/v8.0/";
        // ヘッダーの設定
        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 = "https://<CRM組織名>.crm7.dynamics.com";
        static string authUrl = "https://login.windows.net/common";
        static string clientId = "取得したIDを入力";
        static string redirectUri = “https://localhost/webapi”;

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

        public async Task Run(string accessToken)
        {
            // HttpClient の作成
            using (HttpClient httpClient = new HttpClient())
            {
                // Web API アドレスの作成
                string serviceUrl = serverUrl + "/api/data/v8.0/";
                // ヘッダーの設定
                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();
            }
        }
    }
}

まとめ

次回から実際の Web API の機能と利用方法を紹介していきます。
お楽しみに！

- 中村憲一郎

※本情報の内容（添付文書、リンク先などを含む）は、作成日時点でのものであり、予告なく変更される場合があります

Dynamics CRM 2016 SDK 新機能: Web API その 1

Additional resources