Dynamics CRM 2016 SDK 新機能: Web API その 4: Function の利用

Article
12/16/2015

みなさん、こんにちは。

前回に引き続き、Dynamics CRM 2016 SDK の新機能として、正式版と
なった Web API について紹介します。

今回は Function について紹介します。

Function 概要

正式版のリリースでは、より多くの組織要求をサポートしていますが、
大きく分類すると Function も Action も WhoAmI のような組織要求と
なります。違いは Function はデータの変更を伴わない作業であるのに
対して Action はデータの変更を伴うものとして分類されています。

Bound と Unbound Function

Function はさらに Bound Function と Unbound Function に分類されます。
Bound Function はエンティティのレコードに依存しますが、Unbound
Function はレコードに依存しません。具体的な例は以下で紹介します。

Unbound Function

まず Unbound Function の例として WhoAmI 要求を実装します。

プログラムの実装

1. 前回利用した Visual Studio ソリューションを開き、Program.cs
ファイルを開きます。新しく以下のメソッドを追加します。

public async Task RunFunction(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);

}
}

2. Main メソッドの以下のコードを書き換えて、新しいメソッドを
呼ぶように変更します。

元)
Task.WaitAll(Task.Run(async () => await app.RunFetchXMLQuery(result.AccessToken)));

変更後)
Task.WaitAll(Task.Run(async () => await app.RunFunction(result.AccessToken)));

3. 新しく追加した RunFunctionメソッド内に以下のコードを追加
して、WhoAmI を実行します。

// WhoAmI 要求の実行
HttpResponseMessage whoamiRes = await httpClient.GetAsync(serviceUrl + "WhoAmI");
JToken whoami = JObject.Parse(whoamiRes.Content.ReadAsStringAsync().Result);

// 結果の表示
Console.WriteLine("UserId:{0}", whoami["UserId"]);
Console.WriteLine("OrganizationId:{0}", whoami["OrganizationId"]);
Console.WriteLine("BusinessUnitId:{0}", whoami["BusinessUnitId"]);

動作確認

1. F5 キーを押下してプログラムを実行します。

2. 認証ダイアログが表示されたらログインします。

3. WhoAmI の実行結果が表示されることを確認します。

Bound Function

次に Bound Function の例として RetrieveUserPrivileges 要求を実装します。

Function 定義の確認

まずは Function 定義を確認します。

1. ブラウザで Dynamics CRM 組織にログインします。

2. 新しいタブを開き、以下のアドレスを入力します。
https://<組織名>.crm7.dynamics.com/api/data/v8.0/$metadata

3. XML の結果が表示されたら RetrieveUserPrivileges を検索します。
Function の IsBound 要素が true であることを確認します。第一引数が
Bound するエンティティとなります。また返り値の型とプロパティを
確認しておきます。

プログラムの実装

1. 以下のコードを上記のコードに続けて追加します。systemusers(<id>) で
SystemUser を特定して、Microsoft.Dynamics.CRM.RetrieveUserPrivileges() と
続けています。

2. 以下のコードで結果を表示します。戻り値の型の情報より RolePrivilege が
あることが分かっているため、プロパティを取得しています。

// 結果のデシリアライズ
JToken userPrivileges = JObject.Parse(retrieveUserPrivilegesRes.Content.ReadAsStringAsync().Result)["RolePrivileges"];

// 権限の表示
foreach (JToken userPrivilege in userPrivileges)
{
    Console.WriteLine("Depth: {0}", userPrivilege["Depth"]);
    Console.WriteLine("PrivilegeId: {0}", userPrivilege["PrivilegeId"]);
    Console.WriteLine("BusinessUnitId: {0}", userPrivilege["BusinessUnitId"]);
}

動作確認

1. F5 キーを押下してプログラムを実行します。

2. 認証ダイアログが表示されたらログインします。

3. 権限の一覧が表示されることを確認します。

以下に今回追加したメソッドを示します。

        // WhoAmI 要求の実行
        HttpResponseMessage whoamiRes = await httpClient.GetAsync(serviceUrl + "WhoAmI");
        JToken whoami = JObject.Parse(whoamiRes.Content.ReadAsStringAsync().Result);

        // 結果の表示
        Console.WriteLine("UserId:{0}", whoami["UserId"]);
        Console.WriteLine("OrganizationId:{0}", whoami["OrganizationId"]);
        Console.WriteLine("BusinessUnitId:{0}", whoami["BusinessUnitId"]);

        // RetrieveUserPrivileges 要求の実行
        HttpResponseMessage retrieveUserPrivilegesRes = await httpClient.GetAsync(serviceUrl + "systemusers(" + whoami["UserId"] + ")/Microsoft.Dynamics.CRM.RetrieveUserPrivileges()");
        JToken userPrivileges = JObject.Parse(retrieveUserPrivilegesRes.Content.ReadAsStringAsync().Result)["RolePrivileges"];

        // 権限の表示
        foreach (JToken userPrivilege in userPrivileges)
        {
            Console.WriteLine("Depth: {0}", userPrivilege["Depth"]);
            Console.WriteLine("PrivilegeId: {0}", userPrivilege["PrivilegeId"]);
            Console.WriteLine("BusinessUnitId: {0}", userPrivilege["BusinessUnitId"]);
        }
    }
}

まとめ

今回は Function の利用方法を紹介しました。次回は Action を
紹介しますので、お楽しみに！

- 中村憲一郎

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

Dynamics CRM 2016 SDK 新機能: Web API その 4: Function の利用

Additional resources