Web API のサンプル (C#)

[アーティクル]
03/03/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

このトピックでは、C# で実装した Web API のサンプルについて説明します各サンプルでは Microsoft Dynamics 365 Web API の様々な側面について扱いますが、同様の特性と構造を備えています。

注意

この実装方法では下位レベルのオブジェクト作成と明示的 HTTP メッセージの呼び出しが使用されます。この方法では Web API の動作を制御する下位レベルのオブジェクトプロパティの制御と表示が可能です。これは内部構造について理解することを目的としており、必ずしも開発者の生産性が最適化されたエクスペリエンスを提供する手法を表すものではありません。

一方、OData ライブラリなどの上位レベルのライブラリでは、この下位レベルのクライアントロジックの大部分が取り除かれています。OData T4 テンプレートは任意で OData ライブラリと組み合わせて、自動生成クライアントエンティティクラスへの使用が可能です。

このトピックの内容

前提条件

Web API サンプルの一覧 (C#)

サンプルのダウンロードおよび実行方法

各サンプルの共通要素

前提条件

以下は Dynamics 365 Web API C# サンプルの構築および実行に必要です:

Microsoft Visual Studio 2015 以降のバージョン。無料バージョンである Visual Studio Community はここでダウンロードして入手できます。
参照先の NuGet パッケージをダウンロードおよび更新するにはインターネットに接続されている必要があります。
Dynamics Dynamics 365 Online または設置型 (以降)。すべての Dynamics 365 のインストールの種類においては、CRUD 操作を実行する特権を持ったユーザーアカウントが必要となります。
Dynamics 365 (オンライン) に対してサンプルを実行するには、Azure Active Directory にアプリケーションを登録し、クライアント ID とリダイレクト URL を取得する必要があります。詳細については、「チュートリアル: Azure Active Directory に Dynamics 365 アプリを登録する」を参照してください。

Web API サンプルの一覧 (C#)

次の表は、C# で実行されたサンプルを示します。Web API のサンプルで説明されているように、HTTP 要求および応答メッセージに重点を置いている対応するサンプルグループトピックで、各サンプルはより一般的な方法で説明されています。

サンプル	サンプルグループ	説明
Web API 基本操作のサンプル (C#)	Web API Operations 操作のサンプル	Dynamics 365 エンティティレコードの作成、取得、更新、削除、関連付け、および関連付け解除の各操作を実行する方法を説明します。
Web API クエリデータのサンプル (C#)	Web API クエリデータのサンプル	OData v4 クエリ構文と機能および Microsoft Dynamics 365 クエリ機能を使用する方法を説明します。定義済みクエリに関する作業の例を含み、FetchXML を使用してクエリを実行します。
Web API 条件付き演算サンプル (C#)	Web API 条件付き演算サンプル	ETag の条件を指定する条件付き演算の実行方法を示します。
Web API 機能およびアクションのサンプル (C#)	Web API 機能およびアクションのサンプル	ユーザー定義アクションを含む、バインドされた関数とバインドされていない関数およびアクションの使用方法を説明します。

サンプルのダウンロードおよび実行方法

各サンプルのソース・コードは MSDN Code Gallery で入手可能です。各サンプルをダウンロードするリンクはサンプルトピックに含まれています。ダウンロードするサンプルは Visual Studio 2015 ソリューションファイルを格納する圧縮ファイルです。詳細については、各サンプルトピックの「このサンプルの実行」セクションを参照してください。

各サンプルの共通要素

ほとんどのサンプルには、通常 Web API C# プログラムの基本構造を提供する類似する構造および共通のメソッドやリソースが含まれています。

また、これらの要素の大半は、Dynamics 365 Web API にアクセスする新しいソリューションを作成するときに表示されます。詳細については、「Visual Studio (C#) で Dynamics 365 Web API プロジェクトを起動する」を参照してください。

ライブラリやフレームワークの使用

この C# の実装は、HTTP 通信、アプリケーション構成、認証、エラー処理、および JSON のシリアル化の以下のヘルパーコードによって異なります。

System.Net.Http namespace に含まれている標準 .NET Framework HTTP メッセージングクラスは、特に HttpClient、HttpRequestMessage、および HttpResponseMessage は HTTP メッセージングに使用されます。
Dynamics 365 Web API Helper Library は、アプリケーション構成ファイルの読み込み、Dynamics 365 サーバーでの認証、およびエラー処理操作の支援に使用されます。詳細については、「Microsoft Dynamics 365 Web API Helper Library (C#) の使用」を参照してください。
Newtonsoft Json.NET ライブラリは JSON データ形式をサポートします。

Json.NET Library

C# およびその他の管理言語は JSON データ形式をネイティブにサポートしていないため、最適な方法として、この機能のライブラリを使用することです。詳細については、「JavaScript および .NET の JavaScript Object Notation (JSON) の概要」を参照してください。 Json.NET は .NET プロジェクトによく使用されます。 JSON データのシリアル化、変換、クエリ、および形式設定を行う堅牢で、パフォーマンスの高い、オープンソース (MIT ライセンス) のフレームワークを提供します。詳細については、「Json.NET ドキュメント」を参照してください。

C# サンプルでは、このライブラリは主に .NET オブジェクトと HTTP のメッセージ本文間でのデータのシリアル化に使用されます。ライブラリには、このタスクを実行する複数のメソッドがありますが、サンプルで使用されている方法では、個々の JObject インスタンスを作成し、Dynamics 365 エンティティインスタンス (レコード) を表示します。たとえば、次のコードは Dynamics 365 contact EntityType インスタンスを表示する様々な contact1 を作成し、この種類における一部のプロパティの値を指定します。

JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";

最後のステートメントでのブラケット記法の使用は、Add メソッドと同じです。また、Parse 静的メソッドを使用することによって、このインスタンス化を実行できます。

JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");

JObject は全般的な JSON の種類を示すため、ランタイムの読み取りは多くの場合除外されます。たとえば、次のステートメントは構文的には有効ですが、contact EntityType には age プロパティがないためランタイムエラーが発生する可能性があります。

contact1.Add("age", 37); //Possible error--no age property exists in contact!

エンティティの変数が初期化されると、複数の System.Net.Http クラスからのサポートにより、それをメッセージ本文に送信できます。例:

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

検索操作中にエンティティインスタンスのシリアル化解除することによって、JObject インスタンスを作成することもできます。例:

//contact2Uri contains a reference to an existing CRM contact instance.
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());

正常な応答とエラーの処理

一般には、サンプルでは HTTP 応答を処理するシンプルな方法が使用されています。要求が成功すると、操作における情報は通常、コンソールに出力されます。応答により JSON ペイロードまたは役立つヘッダーも送信される場合は、この情報は要求が成功した場合にのみ処理されます。最後に、Dynamics 365 エンティティが作成された場合は、entityUris コレクションはそのリソースの URL によって更新されます。DeleteRequiredRecords メソッドメソッドはこのコレクションを使用し、オプションで、Dynamics 365 サーバーのサンプルから作成されたデータを削除します。

要求が失敗した場合は、失敗した操作に関するコンテキストメッセージを出力し、CrmHttpResponseException のユーザー定義の例外メッセージが表示されます。例外ハンドラーは、例外についての詳細を出力し、DeleteRequiredRecords を呼び出すクリーンアップロジックを含む finally ブロックに制御パスします。次のコードはレコードを作成する POST 要求のエラー処理方法について示しています。

if (response.StatusCode == HttpStatusCode.NoContent)  //204
{
Console.WriteLine("POST succeeded, entity created!”);
//optionally process response message headers or body here, for example:
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();
entityUris.Add(entityUri);
}
else
{
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);
throw new CrmHttpResponseException(response.Content);
}

HttpStatusCode.NoContent は HTTP ステータスコード 204 (コンテンツなし) と同じです。このステータスコードは POST 要求が成功したことを意味します。詳細については、「HTTP 要求の作成とエラーの処理」を参照してください。

特性とメソッド

多くのサンプルでは、ー般的な構造上のパターンと同じパターンが示され、次の特性を備えています:

すべての適切な C# サンプルコードには Program.cs という名前の主要ソースファイルが含まれており、サンプルプロジェクトと同じ名前の単一クラスが含まれています。
サンプルクラスと Microsoft Dynamics 365 Web API Helper Library (C#) の使用は名前空間である Microsoft.Crm.Sdk.Samples に含まれています。
サンプルには次のコメントが含まれています: 概要がクラスおよびメソッドレベルに提供され、ほとんどの主要な個々のステートメントは同じコメントまたは 1 行のコメントを関連付けています。また、アプリケーション構成ファイル App.config などの補足ファイルには、多くの場合、重要なコメントも含まれています。
主要サンプルクラスは、通常、以下のメソッドの共通セットを含むように構成されています: メインメソッド、ConnectToCRM メソッド、CreateRequiredRecords メソッド、RunAsync メソッド、DisplayException メソッド、および DeleteRequiredRecords メソッドです。

メインメソッド

定義では、このメソッドはサンプルの実行を開始します。上位レベルの制御フローおよび例外処理コードロジックのみが含まれ、多くの場合、コードはまさに以下の通りになります:

static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}

ConnectToCRM メソッド

このメソッドはヘルパーライブラリを呼び出し、アプリケーション構成ファイルを読み込み、次に、指定した Dynamics 365 サーバーへの接続を確立します。これらの手順によって、Web 要求の送信および応答の受信を行うプログラムを介して使用される HttpClient クラスのプロパティを初期化します。次のプロパティがこのオブジェクトに設定されている点に注意します:

//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

サンプルのアプリケーション構成および認証の詳細については、「Microsoft Dynamics 365 Web API Helper Library (C#) の使用」を参照してください。

CreateRequiredRecords メソッド

このメソッドは、サンプルでこれらの操作が主要事項とみなされない場合にのみ、サンプルで必要とするエンティティレコードを作成し、初期化します。たとえば、サンプルではレコードの作成を主要なタスクとみなすため、Web API 基本操作のサンプル (C#) にはこのメソッドは含まれません。

RunAsync メソッド

この非同期メソッドは、適切なソース・コードを格納するか、またはさらに長いプログラムに対しては、適切なサンプルコードをグループ化するメソッドを呼び出します。含まれているコードは埋め込まれているコメントにより説明されており、コメントはそれぞれに対応するサンプルトピックの備考セクションで検索できます。

DisplayException メソッド

このヘルパーメソッドは、内部例外を含む例外情報を標準コンソールに表示します。

DeleteRequiredRecords メソッド

この付属メソッドは、特に CreateRequiredRecords メソッドメソッドによって、サンプルレコードとプログラムで作成されたそのほかの Dynamics 365 サーバープログラムを任意で削除します。この操作の検証をユーザーにクエリし、entityUris コレクションで繰り返し、HTTP DELETE メッセージを使用して、各要素を削除しようとします。

Web API のサンプル (C#)

このトピックの内容

前提条件

Web API サンプルの一覧 (C#)

サンプルのダウンロードおよび実行方法

各サンプルの共通要素

ライブラリやフレームワークの使用

Json.NET Library

正常な応答とエラーの処理

特性とメソッド

メインメソッド

ConnectToCRM メソッド

CreateRequiredRecords メソッド

RunAsync メソッド

DisplayException メソッド

DeleteRequiredRecords メソッド

関連項目

その他のリソース

Web API のサンプル (C#)

このトピックの内容

前提条件

Web API サンプルの一覧 (C#)

サンプルのダウンロードおよび実行方法

各サンプルの共通要素

ライブラリやフレームワークの使用

Json.NET Library

正常な応答とエラーの処理

特性とメソッド

メイン メソッド

ConnectToCRM メソッド

CreateRequiredRecords メソッド

RunAsync メソッド

DisplayException メソッド

DeleteRequiredRecords メソッド

関連項目

その他のリソース

メインメソッド