Web API 2의 작업 결과Action Results in Web API 2

ASP.NET Core WEB API를 사용 하는 것이 좋습니다.Consider using ASP.NET Core web API. ASP.NET 4.x Web API에 비해 다음과 같은 이점이 있습니다.It has the following advantages over ASP.NET 4.x Web API:

  • ASP.NET Core은 Windows, macOS 및 Linux에서 최신 클라우드 기반 웹 앱을 빌드하기 위한 오픈 소스 플랫폼 간 프레임 워크입니다.ASP.NET Core is an open-source, cross-platform framework for building modern, cloud-based web apps on Windows, macOS, and Linux.
  • ASP.NET Core MVC 컨트롤러 및 web API 컨트롤러는 통합 되어 있습니다.The ASP.NET Core MVC controllers and web API controllers are unified.
  • 테스트 가능성을 고려하여 설계되었습니다.Architected for testability.
  • Windows, macOS 및 Linux에서 개발하고 실행할 수 있습니다.Ability to develop and run on Windows, macOS, and Linux.
  • 오픈 소스이며 커뮤니티에 중점을 둡니다.Open-source and community-focused.
  • 최신 클라이언트 쪽 프레임 워크 및 개발 워크플로를 통합 합니다.Integration of modern, client-side frameworks and development workflows.
  • 클라우드 지원 환경 기반 구성 시스템입니다.A cloud-ready, environment-based configuration system.
  • 기본 제공 종속성 주입.Built-in dependency injection.
  • 간단한 고성능 모듈식 HTTP 요청 파이프라인을 포함합니다.A lightweight, high-performance, and modular HTTP request pipeline.
  • Kestrel, [IIS] (f: host-and-deploy/IIS/Index, http.sys, Nginx, ApacheDocker에서 호스팅할 수 있습니다.Ability to host on Kestrel, [IIS](xref:host-and-deploy/iis/index, HTTP.sys, Nginx, Apache, and Docker.
  • Side-by-side 버전 관리.Side-by-side versioning.
  • 최신 웹 개발을 간소화하는 도구를 포함합니다.Tooling that simplifies modern web development.

이 항목에서는 ASP.NET Web API 컨트롤러 작업의 반환 값을 HTTP 응답 메시지로 변환 하는 방법에 대해 설명 합니다.This topic describes how ASP.NET Web API converts the return value from a controller action into an HTTP response message.

Web API 컨트롤러 작업은 다음 중 하나를 반환할 수 있습니다.A Web API controller action can return any of the following:

  1. voidvoid
  2. HttpResponseMessageHttpResponseMessage
  3. IHttpActionResultIHttpActionResult
  4. 다른 형식Some other type

웹 API는 반환 되는 방법에 따라 다른 메커니즘을 사용 하 여 HTTP 응답을 만듭니다.Depending on which of these is returned, Web API uses a different mechanism to create the HTTP response.

반환 형식Return type Web API에서 응답을 만드는 방법How Web API creates the response
voidvoid 빈 204 반환 (내용 없음)Return empty 204 (No Content)
HttpResponseMessageHttpResponseMessage HTTP 응답 메시지로 직접 변환 합니다.Convert directly to an HTTP response message.
IHttpActionResultIHttpActionResult ExecuteAsync 를 호출 하 여 HttpResponseMessage를 만든 다음 HTTP 응답 메시지로 변환 합니다.Call ExecuteAsync to create an HttpResponseMessage, then convert to an HTTP response message.
기타 형식Other type Serialize 된 반환 값을 응답 본문에 씁니다. 200 (OK)을 반환 합니다.Write the serialized return value into the response body; return 200 (OK).

이 항목의 나머지 부분에서는 각 옵션에 대해 자세히 설명 합니다.The rest of this topic describes each option in more detail.

voidvoid

반환 형식이 void이면 웹 API는 상태 코드 204 (콘텐츠 없음)가 포함 된 빈 HTTP 응답을 반환 합니다.If the return type is void, Web API simply returns an empty HTTP response with status code 204 (No Content).

컨트롤러 예:Example controller:

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

HTTP 응답:HTTP response:

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

HttpResponseMessageHttpResponseMessage

작업에서 HttpResponseMessage를 반환 하는 경우 Web API는 HttpResponseMessage 개체의 속성을 사용 하 여 응답을 채우도록 반환 값을 HTTP 응답 메시지로 직접 변환 합니다.If the action returns an HttpResponseMessage, Web API converts the return value directly into an HTTP response message, using the properties of the HttpResponseMessage object to populate the response.

이 옵션을 사용 하면 응답 메시지를 매우 효과적으로 제어할 수 있습니다.This option gives you a lot of control over the response message. 예를 들어 다음 컨트롤러 작업은 Cache-control 헤더를 설정 합니다.For example, the following controller action sets the Cache-Control header.

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;
    } 
}

응답: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는 미디어 포맷터 를 사용 하 여 serialize 된 모델을 응답 본문에 씁니다.If you pass a domain model to the CreateResponse method, Web API uses a media formatter to write the serialized model into the response body.

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 헤더를 사용 하 여 포맷터를 선택 합니다.Web API uses the Accept header in the request to choose the formatter. 자세한 내용은 콘텐츠 협상을 참조 하세요.For more information, see Content Negotiation.

IHttpActionResultIHttpActionResult

IHttpActionResult 인터페이스는 Web API 2에서 도입 되었습니다.The IHttpActionResult interface was introduced in Web API 2. 기본적으로 HttpResponseMessage 팩터리를 정의 합니다.Essentially, it defines an HttpResponseMessage factory. IHttpActionResult 인터페이스를 사용할 경우의 몇 가지 이점은 다음과 같습니다.Here are some advantages of using the IHttpActionResult interface:

  • 컨트롤러의 유닛 테스트 를 간소화 합니다.Simplifies unit testing your controllers.
  • HTTP 응답을 만들기 위한 공통 논리를 개별 클래스로 이동 합니다.Moves common logic for creating HTTP responses into separate classes.
  • 응답 생성에 대 한 하위 수준 세부 정보를 숨겨 컨트롤러 작업의 의도를 명확 하 게 합니다.Makes the intent of the controller action clearer, by hiding the low-level details of constructing the response.

IHttpActionResult 에는 HttpResponseMessage 인스턴스를 비동기식으로 만드는 단일 메서드인 ExecuteAsync이 포함 되어 있습니다.IHttpActionResult contains a single method, ExecuteAsync, which asynchronously creates an HttpResponseMessage instance.

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

컨트롤러 작업에서 IHttpActionResult를 반환 하는 경우 Web API는 ExecuteAsync 메서드를 호출 하 여 HttpResponseMessage를 만듭니다.If a controller action returns an IHttpActionResult, Web API calls the ExecuteAsync method to create an HttpResponseMessage. 그런 다음 HttpResponseMessage 를 HTTP 응답 메시지로 변환 합니다.Then it converts the HttpResponseMessage into an HTTP response message.

다음은 일반 텍스트 응답을 만드는 간단한 IHttpActionResult 구현입니다.Here is a simple implementation of IHttpActionResult that creates a plain text response:

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);
    }
}

컨트롤러 작업 예:Example controller action:

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

응답:Response:

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

일반적으로 IHttpActionResult 네임 스페이스에 정의 된 구현을 사용 합니다.More often, you use the IHttpActionResult implementations defined in the System.Web.Http.Results namespace. ApiController 클래스는 이러한 기본 제공 작업 결과를 반환 하는 도우미 메서드를 정의 합니다.The ApiController class defines helper methods that return these built-in action results.

다음 예에서는 요청이 기존 제품 ID와 일치 하지 않는 경우 컨트롤러가 ApiController 를 호출 하 여 404 (찾을 수 없음) 응답을 만듭니다.In the following example, if the request does not match an existing product ID, the controller calls ApiController.NotFound to create a 404 (Not Found) response. 그렇지 않으면 컨트롤러가 ApiController를 호출 하 여 제품을 포함 하는 200 (OK) 응답을 만듭니다 .Otherwise, the controller calls ApiController.OK, which creates a 200 (OK) response that contains the product.

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

기타 반환 형식Other Return Types

다른 모든 반환 형식에 대해 Web API는 미디어 포맷터 를 사용 하 여 반환 값을 직렬화 합니다.For all other return types, Web API uses a media formatter to serialize the return value. Web API는 serialize 된 값을 응답 본문에 씁니다.Web API writes the serialized value into the response body. 응답 상태 코드는 200 (정상)입니다.The response status code is 200 (OK).

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

이 방법의 단점은 404와 같은 오류 코드를 직접 반환할 수 없다는 것입니다.A disadvantage of this approach is that you cannot directly return an error code, such as 404. 그러나 오류 코드에 대해 HttpResponseException 을 throw 할 수 있습니다.However, you can throw an HttpResponseException for error codes. 자세한 내용은 ASP.NET Web API의 예외 처리를 참조 하세요.For more information, see Exception Handling in ASP.NET Web API.

Web API는 요청에 Accept 헤더를 사용 하 여 포맷터를 선택 합니다.Web API uses the Accept header in the request to choose the formatter. 자세한 내용은 콘텐츠 협상을 참조 하세요.For more information, see Content Negotiation.

요청 예Example request

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

예제 응답Example response

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}]