Web API 2 のアクションの結果

[アーティクル]
04/28/2024

ASP.NET Core Web API の使用を検討してください。 ASP.NET 4.x Web API に対して次の利点があります:

ASP.NET Core は、Windows、macOS、Linux で最新のクラウドベースの Web アプリを構築するための、オープンソースのクロスプラットフォームフレームワークです。
ASP.NET Core MVC コントローラーと Web API コントローラーが統合されています。
テストの容易性を考慮したアーキテクチャ。
Windows、macOS、Linux 上で開発および実行できること。
オープンソースでコミュニティ重視。
最新のクライアント側フレームワークと開発ワークフローの統合。
クラウド対応で環境ベースの構成システム。
組み込まれている依存性の注入。
軽量で高パフォーマンスのモジュール化された HTTP 要求パイプライン。
Kestrel、IIS、HTTP.sys、Nginx、Apache、Docker でホストすることができます。
side-by-side でのバージョン管理。
最新の Web 開発を簡単にするツール。

このトピックでは、Web API ASP.NET コントローラーアクションからの戻り値を HTTP 応答メッセージに変換する方法について説明します。

Web API コントローラーアクションは、次のいずれかを返せます。

無効
HttpResponseMessage
IHttpActionResult
その他の型

返されるメカニズムに応じて、Web API は異なるメカニズムを使用して HTTP 応答を作成します。

返り値の種類	Web API で応答を作成する方法
無効	空の 204 を返します (コンテンツなし)
HttpResponseMessage	HTTP 応答メッセージに直接変換します。
IHttpActionResult	ExecuteAsync を呼び出して HttpResponseMessage を作成し、HTTP 応答メッセージに変換します。
その他の種類	シリアル化された戻り値を応答本文に書き込みます。200 (OK) を返します。

このトピックの残りの部分では、各オプションについて詳しく説明します。

無効

戻り値の型が void の場合、Web API は、状態コード 204 (コンテンツなし) を含む空の HTTP 応答を返します。

コントローラーの例:

public class ValuesController : ApiController
{
    public void Post()
    {
    }
}

HTTP 応答:

HTTP/1.1 204 No Content
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 02:13:26 GMT

HttpResponseMessage

アクションが HttpResponseMessage を返す場合、Web API は、HttpResponseMessage オブジェクトのプロパティを使用して、戻り値を HTTP 応答メッセージに直接変換して応答を作成します。

このオプションを使用すると、応答メッセージを制御できる幅が広がります。たとえば、次のコントローラーアクションは、Cache-Control ヘッダーを設定します。

public class ValuesController : ApiController
{
    public HttpResponseMessage Get()
    {
        HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value");
        response.Content = new StringContent("hello", Encoding.Unicode);
        response.Headers.CacheControl = new CacheControlHeaderValue()
        {
            MaxAge = TimeSpan.FromMinutes(20)
        };
        return response;
    } 
}

応答:

HTTP/1.1 200 OK
Cache-Control: max-age=1200
Content-Length: 10
Content-Type: text/plain; charset=utf-16
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

ドメインモデルを CreateResponse メソッドに渡すと、Web API は、メディアフォーマッタを使用して、シリアル化されたモデルを応答本文に書き込みます。

public HttpResponseMessage Get()
{
    // Get a list of products from a database.
    IEnumerable<Product> products = GetProductsFromDB();

    // Write the list to the response body.
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
    return response;
}

Web API では、要求の Accept ヘッダーを使用してフォーマッタを選択します。詳細については、「コンテンツネゴシエーション」をご覧ください。

IHttpActionResult

IHttpActionResult インターフェイスは Web API 2 で導入されました。基本的には、これは HttpResponseMessage ファクトリを定義します。 IHttpActionResult インターフェイスを使用する利点を次に示します。

コントローラーの単体テストを簡略化します。
HTTP 応答を作成するための一般的なロジックを別のクラスに移動します。
応答を構築する低レベルの詳細を非表示にすることで、コントローラーアクションの意図をより明確にします。

IHttpActionResult には、HttpResponseMessage インスタンスを非同期的に作成する ExecuteAsync という 1 つのメソッドが含まれています。

public interface IHttpActionResult
{
    Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}

コントローラーアクションが IHttpActionResult を返す場合、Web API は ExecuteAsync メソッドを呼び出して HttpResponseMessage を作成します。次に、HttpResponseMessage を HTTP 応答メッセージに変換します。

プレーンテキスト応答を作成する IHttpActionResult の簡単な実装を次に示します。

public class TextResult : IHttpActionResult
{
    string _value;
    HttpRequestMessage _request;

    public TextResult(string value, HttpRequestMessage request)
    {
        _value = value;
        _request = request;
    }
    public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        var response = new HttpResponseMessage()
        {
            Content = new StringContent(_value),
            RequestMessage = _request
        };
        return Task.FromResult(response);
    }
}

コントローラーアクションの例:

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return new TextResult("hello", Request);
    }
}

応答:

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: text/plain; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT

hello

多くの場合、System.Web.Http.Results 名前空間で定義されている IHttpActionResult 実装を使用します。 ApiController クラスは、これらの組み込みアクションの結果を返すヘルパーメソッドを定義します。

次の例では、要求が既存の製品 ID と一致しない場合、コントローラーは ApiController.NotFound を呼び出し、404 (見つからない) 応答を作成します。それ以外の場合、コントローラーは ApiController.OK を呼び出し、製品を含む 200 (OK) 応答を作成します。

public IHttpActionResult Get (int id)
{
    Product product = _repository.Get (id);
    if (product == null)
    {
        return NotFound(); // Returns a NotFoundResult
    }
    return Ok(product);  // Returns an OkNegotiatedContentResult
}

その他の戻り値の型

他のすべての戻り値の型では、Web API はメディアフォーマッタを使用して戻り値をシリアル化します。 Web API は、シリアル化された値を応答本文に書き込みます。応答状態コードは 200 (OK) です。

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

この方法の欠点は、404 などのエラーコードを直接返せない点です。ただし、エラーコードに HttpResponseException をスローできます。詳細については、「ASP.NET Web API での例外処理」をご覧ください。

Web API では、要求の Accept ヘッダーを使用してフォーマッタを選択します。詳細については、「コンテンツネゴシエーション」をご覧ください。

要求の例

GET http://localhost/api/products HTTP/1.1
User-Agent: Fiddler
Host: localhost:24127
Accept: application/json

応答の例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 08:53:35 GMT
Content-Length: 56

[{"Id":1,"Name":"Yo-yo","Category":"Toys","Price":6.95}]

次の方法で共有

Web API 2 のアクションの結果

無効

HttpResponseMessage

IHttpActionResult

その他の戻り値の型

フィードバック

その他のリソース