HttpClient を使用して REST サービスを利用する

  • 5 分

最新の Web サービスの多くで、REST アーキテクチャが実装されています。 この構造により、Web サービスは、一連の明確に定義されたエンドポイントを介して操作とデータを公開できます。 クライアント アプリがデータを取得、変更、作成、または削除するために REST Web サービスに送信する要求では、定義済みの動詞のセットが使われます。 REST Web サービスは、これらの要求に標準の方法で応答します。 このアプローチにより、クライアント アプリの構築が容易になります。

REST モデルは、HTTP プロトコルの上に構築されています。 .NET MAUI アプリケーションは、HttpClient クラスを使って REST Web サービスに要求を送信できます。 このユニットでは、HttpClient と、それを使って REST Web サービスと対話する方法について学習します。

HttpClient クラスとは

HttpClient は .NET クラスであり、アプリでそれを使うと、REST Web サービスに HTTP 要求を送信して、HTTP 応答を受信できます。 Web サービスで公開されるリソースは、一連の URI で識別されます。 URI は、Web サービスのアドレスと、そのアドレスで利用できるリソースの名前を組み合わせたものです。

HttpClient クラスでは、パフォーマンスのためにタスク ベースの API が使用されており、HTTP ヘッダー、状態コード、送受信される実際のデータを含むメッセージ本文など、要求メッセージの情報にアクセスできます。

Diagram showing how a client app uses an HttpClient object to send and receive HTTP messages and responses

HttpClient クラスは System.Net.Http 名前空間にあります。 アプリでは、既定のコンストラクターを使って HttpClient オブジェクトを作成できます。

using System.Net.Http;
...

var client = new HttpClient();

HttpClient オブジェクトを使って CRUD 操作を実行する

REST Web サービスを使うと、クライアントは HTTP 動詞のセットを介してデータに対する操作を実行できます。 HTTP 動詞の役割は、リソースで実行する必要のあるアクションを示すことです。 多くの HTTP 動詞がありますが、最も一般的なのは POST、GET、PUT、DELETE の 4 つです。 次のように、サービスで実装されたこれらの動詞を使用することで、クライアント アプリケーションは作成、読み取り、更新、削除 (CRUD) の操作を実行して、オブジェクトのライフサイクルを管理できます。

  • POST 動詞では、新しいリソースを作成することを示します。

  • GET 動詞では、リソースを取得することを示します。

  • PUT 動詞では、リソースを更新することを示します。

  • DELETE 動詞では、リソースを削除することを示します。

Diagram showing the basic CRUD operations that a REST service can implement, including get, post, put and delete.

HttpClient を使用して新しいリソースを作成する

HttpClient を使って新しいリソースを作成するには、HttpRequestMessage オブジェクトに渡す SendAsync メソッドを使用できます。

HttpRequestMessage は、Web サービスに送信される要求をモデル化するためのものです。 HTTP 動詞と Web サービスの URL を指定し、送信するペイロードを HttpRequestMessage.Content プロパティで設定します。

HttpClient client = new HttpClient();

HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Post, url);
message.Content = JsonContent.Create<Part>(part);

HttpResponseMessage response = await client.SendAsync(message);

このコード フラグメントでは、次のタスクを実行します。

  • メッセージの送信に使われる HttpClient のインスタンスを、client という名前で作成します。
  • メッセージのモデル化に使われる HttpRequestMessage のインスタンスを、message という名前で作成します。 message は、HTTP 動詞と URL を保持しています。
  • JsonContent.Create 関数を使って、HttpRequestMessage の Content プロパティを設定します。 この関数は、part 変数を、Web サービスへの送信に適した JSON に自動的にシリアル化します。
  • それは、HttpClient オブジェクトを使ってメッセージを送信します。 返される HttpResponseMessage には、状態コードや Web サービスによって返された情報などの情報が含まれます。

HttpClient を使ってリソースを読み取る

HttpMethod.Get で HttpRequestMessage を初期化すること以外は、前述と同じ手法を使って Web サービスからリソースを読み取ることができます。 ただし、HttpClient には、ショートカットを提供する便利なメソッドがいくつかあります。

HTTPClient を使ってリソースを読み取るには、次の例で示すように GetStringAsync メソッドを使います。

HttpClient client = new HttpClient();

string text = await client.GetStringAsync("https://...");

GetStringAsync メソッドは、リソースを参照する URI を受け取り、応答を文字列として返します。 文字列の応答は、アプリが要求したリソースです。 応答データの形式は、JSON や XML など、要求されたサービスの既定値になります。 アプリは、MediaTypeWithQualityHeaderValue ヘッダーを追加することにより、データが特定の形式で返される必要があることを、Web サービスに伝えることができます。 たとえば、JSON 形式でデータを返送するようアプリで要求する場合は、次のコードを使用できます。

HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

この例では、結果は文字列として返され、応答メッセージの本文のみが含まれます。 ヘッダー、本文、状態コードを含む応答全体を取得するには、GetAsync メソッドを呼び出します。 データは HttpResponseMessage オブジェクトとして返されます。

HttpClient を使用してリソースを更新する

HttpClient を使ってリソースを更新するには、PUT 動詞で初期化された HttpRequestMessage を使います。 次のコードは、新しいリソースを作成するために必要なコードと似ています。

HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Put, url);

message.Content = JsonContent.Create<Part>(part);

HttpResponseMessage response = await client.SendAsync(message);

注意

POST と PUT の基本的な違いはべき等性です。 同じ PUT 要求を何回も繰り返した場合は、同じリソースが同じデータで更新され、効果は要求を 1 回だけ送信した場合と同じになります。 同じ POST 要求を何回も発行すると、結果として、REST サービスにより、リソースの複数のコピーが作成されます。

HttpClient を使用してリソースを削除する

HttpClient を使ってリソースを削除するには、DELETE 動詞で初期化された HttpRequestMessage を使って SendAsync を呼び出します。

HttpClient client = new HttpClient();
HttpRequestMessage message = new HttpRequestMessage(HttpMethod.Delete, url);

HttpResponseMessage response = await client.SendAsync(message);

応答には、ヘッダー、状態コード、削除されたオブジェクトが含まれます。

要求からの応答を処理する

すべての HTTP 要求からは応答メッセージが返されます。 応答のデータは、アプリで送信された動詞によって異なります。 たとえば、HTTP GET 要求の応答本文には、要求したリソースのデータが含まれています。

POST 要求の応答本文では作成されたリソースのコピーが返されますが、PUT 要求の応答本文は空のはずです。

常に応答メッセージの状態コードを調べて処理する必要があります。 この状態コードが 200 番台 (200、201、202 など) の場合、操作は成功したものと見なされますが、後で詳細情報が必要になる場合があります。

300 番台の状態コードは、おそらくはリソースが別の場所に移動された結果として、要求が Web サービスによって別のアドレスにリダイレクトされた可能性があることを示します。

400 番台の状態コードは、クライアントまたはアプリケーションのエラーを示します。 たとえば、状態コード 403 は、Web サービスではユーザーの認証が必要ですが、アプリでそれが行われていないことを意味します。 状態コード 404 は、存在しないリソースにアプリがアクセスしようとしたときに発生します。

500 番台の状態コードは、サービスが利用できない、ビジー状態で要求を処理できないなど、サーバー側のエラーを示します。

HttpClient オブジェクトを通じて送信された要求によって返される HttpResponseMessage オブジェクトは、さまざまな状態コードを処理する複雑さの多くを抽象化できます。 このコード フラグメントは、応答メッセージの状態コードが成功を示していることを確認し、何らかの失敗を示す状態コードを処理する方法を示しています。

static readonly HttpClient client = new HttpClient();

...
// Call asynchronous network methods in a try/catch block to handle exceptions.
try
{
    //... Initiate the HttpRequest

    HttpResponseMessage response = await client.SendAsync(msg);
    response.EnsureSuccessStatusCode(); // Check that the status code is in the 200 range. Throw an HttpRequestException if not
    
    string responseBody = await response.Content.ReadAsStringAsync();
    
    ... // Handle the response
}
catch(HttpRequestException e)
{
    ... // Handle any status codes that indicate an error. 
        // The status code is available in the field e.StatusCode
}

知識チェック

1.

REST Web サービスで新しいリソースを作成するために使用する HTTP 動詞はどれですか?

2.

HTTP 要求が成功したことを確認するには、HttpResponseMessage クラスのどのメソッドを呼び出す必要がありますか?