Web API のサンプル (C#)

公開日: 2017年1月

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

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

このトピックの内容

前提条件

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 要求および応答メッセージに重点を置いている対応するサンプル グループ トピックで、各サンプルはより一般的な方法で説明されています。

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

各サンプルのソース・コードは 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 メッセージを使用して、各要素を削除しようとします。

関連項目

Microsoft Dynamics 365 Web API の使用
Web API のサンプル
Web API のサンプル (クライアント側の JavaScript)
Web API 基本操作のサンプル (C#)
Web API クエリ データのサンプル (C#)
Web API 条件付き演算サンプル (C#)
Web API 機能およびアクションのサンプル (C#)

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権