ASP.NET Core Web API에서 응답 데이터 서식 지정Format response data in ASP.NET Core Web API

• 1/28/2021
• 읽는 데 12분 걸림
• • R
  • o

작성자: Rick Anderson 및 Steve SmithBy Rick Anderson and Steve Smith

ASP.NET Core MVC는 응답 데이터 서식 지정을 지원합니다.ASP.NET Core MVC has support for formatting response data. 응답 데이터는 특정 형식 또는 클라이언트 요청 형식에 대한 응답으로 형식을 지정할 수 있습니다.Response data can be formatted using specific formats or in response to client requested format.

예제 코드 살펴보기 및 다운로드 (다운로드 방법)View or download sample code (how to download)

형식별 작업 결과Format-specific Action Results

일부 작업 결과 형식은 JsonResult 및 ContentResult와 같이 특정 형식과 관련됩니다.Some action result types are specific to a particular format, such as JsonResult and ContentResult. 작업은 클라이언트 기본 설정에 관계 없이 특정 형식으로 서식이 지정된 결과를 반환할 수 있습니다.Actions can return results that are formatted in a particular format, regardless of client preferences. 예를 들어 JsonResult를 반환하면 JSON 형식의 데이터가 반환됩니다.For example, returning JsonResult returns JSON-formatted data. ContentResult 또는 문자열 하나를 반환하면 일반 텍스트 형식의 문자열 데이터가 반환됩니다.Returning ContentResult or a string returns plain-text-formatted string data.

특정 형식을 반환하는 작업은 필요하지 않습니다.An action isn't required to return any specific type. ASP.NET Core는 모든 개체 반환 값을 지원합니다.ASP.NET Core supports any object return value. IActionResult 형식이 아닌 개체를 반환하는 작업의 결과는 적절한 IOutputFormatter 구현을 사용하여 직렬화됩니다.Results from actions that return objects that are not IActionResult types are serialized using the appropriate IOutputFormatter implementation. 자세한 내용은 ASP.NET Core 웹 API에서 컨트롤러 작업 반환 형식를 참조하세요.For more information, see ASP.NET Core 웹 API에서 컨트롤러 작업 반환 형식.

기본 제공 도우미 메서드 Ok는 다음 JSON 형식 데이터를 반환합니다. [!code-csharp]The built-in helper method Ok returns JSON-formatted data: [!code-csharp]

샘플 다운로드는 작성자 목록을 반환합니다.The sample download returns the list of authors. F12 브라우저 개발자 도구 또는 이전 코드의 Postman 사용:Using the F12 browser developer tools or Postman with the previous code:

• content-type:이 포함된 응답 헤더 application/json; charset=utf-8이 표시됩니다.The response header containing content-type: application/json; charset=utf-8 is displayed.
• 요청 헤더가 표시됩니다.The request headers are displayed. 예를 들어 Accept 헤더가 있습니다.For example, the Accept header. Accept 헤더는 앞의 코드에서 무시됩니다.The Accept header is ignored by the preceding code.

서식 있는 일반 텍스트 데이터를 반환하려면 ContentResult 및 Content 도우미를 사용합니다.To return plain text formatted data, use ContentResult and the Content helper:

// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
    return Content("An API listing authors of docs.asp.net.");
}

위의 코드에서 반환된 Content-Type은 text/plain입니다.In the preceding code, the Content-Type returned is text/plain. 문자열을 반환하면 text/plain의 Content-Type이 제공됩니다.Returning a string delivers Content-Type of text/plain:

// GET api/authors/version
[HttpGet("version")]
public string Version()
{
    return "Version 1.0.0";
}

반환 형식이 여러 개인 작업의 경우 IActionResult를 반환합니다.For actions with multiple return types, return IActionResult. 예를 들어 수행된 작업의 결과에 따라 서로 다른 HTTP 상태 코드를 반환합니다.For example, returning different HTTP status codes based on the result of operations performed.

콘텐츠 협상Content negotiation

콘텐츠 협상은 클라이언트가 헤더 수락을 지정하는 경우 발생합니다.Content negotiation occurs when the client specifies an Accept header. ASP.NET Core MVC에서 사용하는 기본 형식은 JSON입니다.The default format used by ASP.NET Core is JSON. 콘텐츠 협상은 다음과 같은 특징을 가집니다.Content negotiation is:

• ObjectResult에 의해 구현됩니다.Implemented by ObjectResult.
• 도우미 메서드에서 반환된 상태 코드별 작업 결과 상태 코드에 기본적으로 제공됩니다.Built into the status code-specific action results returned from the helper methods. 작업 결과 도우미 메서드는 ObjectResult를 기반으로 합니다.The action results helper methods are based on ObjectResult.

모델 형식이 반환되는 경우 반환 형식은 ObjectResult입니다.When a model type is returned, the return type is ObjectResult.

다음 작업 메서드는 Ok 및 NotFound 도우미 메서드를 사용합니다.The following action method uses the Ok and NotFound helper methods:

// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    var result = _authors.GetByNameSubstring(namelike);
    if (!result.Any())
    {
        return NotFound(namelike);
    }
    return Ok(result);
}

기본적으로 ASP.NET Core는 application/json, text/json, text/plain 미디어 형식을 지원합니다.By default, ASP.NET Core supports application/json, text/json, and text/plain media types. Fiddler 또는 Postman과 같은 도구는 반환 형식을 지정하도록 Accept 요청 헤더를 설정할 수 있습니다.Tools such as Fiddler or Postman can set the Accept request header to specify the return format. Accept 헤더에 서버가 지원하는 형식이 포함되어 있으면 해당 형식이 반환됩니다.When the Accept header contains a type the server supports, that type is returned. 다음 섹션에서는 추가적인 포맷터를 추가하는 방법을 보여줍니다.The next section shows how to add additional formatters.

컨트롤러 작업은 POCO(Plain Old CLR Objects)를 반환할 수 있습니다.Controller actions can return POCOs (Plain Old CLR Objects). POCO가 반환되면 런타임에서는 개체를 래핑하는ObjectResult를 자동으로 만듭니다.When a POCO is returned, the runtime automatically creates an ObjectResult that wraps the object. 클라이언트는 형식이 지정된 직렬화된 개체를 가져옵니다.The client gets the formatted serialized object. 반환되는 개체가 null이면 204 No Content 응답이 반환됩니다.If the object being returned is null, a 204 No Content response is returned.

개체 형식 반환하기:Returning an object type:

// GET api/authors/RickAndMSFT
[HttpGet("{alias}")]
public Author Get(string alias)
{
    return _authors.GetByAlias(alias);
}

위 코드에서는 유효한 작성자 별칭에 대한 요청이 작성자의 데이터와 함께 200 OK 응답을 반환합니다.In the preceding code, a request for a valid author alias returns a 200 OK response with the author's data. 잘못된 별칭에 대한 요청은 204 No Content 응답을 반환합니다.A request for an invalid alias returns a 204 No Content response.

Accept 헤더The Accept header

콘텐츠 협상 은 Accept 헤더가 요청에 나타나는 경우에 발생합니다.Content negotiation takes place when an Accept header appears in the request. 요청에 Accept 헤더가 포함되어 있으면 ASP.NET Core는 다음을 수행합니다.When a request contains an accept header, ASP.NET Core:

• 기본 설정 순서에 따라 Accept 헤더의 미디어 형식을 열거합니다.Enumerates the media types in the accept header in preference order.
• 지정된 형식 중 하나로 응답을 생성할 수 있는 포맷터를 찾으려고 시도합니다.Tries to find a formatter that can produce a response in one of the formats specified.

클라이언트의 요청을 충족할 수 있는 포맷터가 없는 경우 ASP.NET Core는 다음을 수행합니다.If no formatter is found that can satisfy the client's request, ASP.NET Core:

• 406 Not Acceptable MvcOptions.ReturnHttpNotAcceptable 가 또는로 설정 된 경우를 반환 합니다. trueReturns 406 Not Acceptable if MvcOptions.ReturnHttpNotAcceptable is set to true, or -
• 응답을 생성할 수 있는 첫 번째 포맷터를 찾으려고 시도합니다.Tries to find the first formatter that can produce a response.

요청된 형식에 대해 포맷터가 구성되지 않은 경우에는 개체의 서식을 지정할 수 있는 첫 번째 포맷터가 사용됩니다.If no formatter is configured for the requested format, the first formatter that can format the object is used. 요청에 Accept 헤더가 표시되지 않을 경우 다음이 수행됩니다.If no Accept header appears in the request:

• 개체를 처리할 수 있는 첫 번째 포맷터는 응답을 직렬화하는 데 사용됩니다.The first formatter that can handle the object is used to serialize the response.
• 발생하는 협상이 없습니다.There isn't any negotiation taking place. 서버에서 반환할 형식을 결정합니다.The server is determining what format to return.

Accept 헤더에 */*가 포함되는 경우, RespectBrowserAcceptHeader가 MvcOptions에서 true로 설정되지 않으면 헤더는 무시됩니다.If the Accept header contains */*, the Header is ignored unless RespectBrowserAcceptHeader is set to true on MvcOptions.

브라우저 및 콘텐츠 협상Browsers and content negotiation

일반적인 API 클라이언트와 달리 웹 브라우저는 Accept 헤더를 제공합니다.Unlike typical API clients, web browsers supply Accept headers. 웹 브라우저는 와일드카드를 비롯한 다양한 형식을 지정합니다.Web browser specify many formats, including wildcards. 기본적으로 프레임워크가 브라우저에서 요청이 수신되는 것을 감지할 경우 다음이 수행됩니다.By default, when the framework detects that the request is coming from a browser:

• Accept 헤더는 무시됩니다.The Accept header is ignored.
• 달리 구성되지 않은 경우 콘텐츠가 JSON에 반환됩니다.The content is returned in JSON, unless otherwise configured.

이것은 API를 소비할 때 브라우저에서 보다 일관된 환경을 제공합니다.This provides a more consistent experience across browsers when consuming APIs.

브라우저 Accept 헤더를 적용하도록 앱을 구성하려면 RespectBrowserAcceptHeader를 true로 설정합니다.To configure an app to honor browser accept headers, set RespectBrowserAcceptHeader to true:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        options.RespectBrowserAcceptHeader = true; // false by default
    });
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        options.RespectBrowserAcceptHeader = true; // false by default
    });

    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

포맷터 구성Configure formatters

추가 형식을 지원해야 하는 앱은 적절한 NuGet 패키지를 추가하고 지원을 구성할 수 있습니다.Apps that need to support additional formats can add the appropriate NuGet packages and configure support. 입력 및 출력에 대한 개별 포맷터가 있습니다.There are separate formatters for input and output. 입력 포맷터는 모델 바인딩에서 사용됩니다.Input formatters are used by Model Binding. 출력 포맷터는 응답의 형식을 지정하는 데 사용됩니다.Output formatters are used to format responses. 사용자 지정 포맷터 생성에 대한 정보는 사용자 지정 포맷터를 참조하세요.For information on creating a custom formatter, see Custom Formatters.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddXmlSerializerFormatters();
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
            .AddJsonOptions(options => 
               options.JsonSerializerOptions.PropertyNamingPolicy = null);
}

[HttpGet("error")]
public IActionResult GetError()
{
    return Problem("Something went wrong!");
}

services.AddControllers().AddJsonOptions(options =>
{
    // Use the default property (Pascal) casing.
    options.JsonSerializerOptions.PropertyNamingPolicy = null;

    // Configure a custom converter.
    options.JsonSerializerOptions.Converters.Add(new MyCustomJsonConverter());
});

public IActionResult Get()
{
    return Json(model, new JsonSerializerOptions
    {
        WriteIndented = true,
    });
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddNewtonsoftJson();
}

services.AddControllers().AddNewtonsoftJson(options =>
{
    // Use the default property (Pascal) casing
    options.SerializerSettings.ContractResolver = new DefaultContractResolver();

    // Configure a custom converter
    options.SerializerSettings.Converters.Add(new MyCustomJsonConverter());
});

public IActionResult Get()
{
    return Json(model, new JsonSerializerSettings
    {
        Formatting = Formatting.Indented,
    });
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
        .AddXmlSerializerFormatters();
}

형식 지정Specify a format

응답 형식을 제한 하려면 필터를 적용 [Produces] 합니다.To restrict the response formats, apply the [Produces] filter. 대부분의 필터와 마찬가지로, [Produces] 작업, 컨트롤러 또는 전역 범위에서 적용할 수 있습니다.Like most Filters, [Produces] can be applied at the action, controller, or global scope:

[ApiController]
[Route("[controller]")]
[Produces("application/json")]
public class WeatherForecastController : ControllerBase
{

이전 [Produces] 필터:The preceding [Produces] filter:

• 컨트롤러 내의 모든 작업이 JSON 형식 응답을 반환하도록 강제합니다.Forces all actions within the controller to return JSON-formatted responses.
• 다른 포맷터가 구성되고 클라이언트에서 다른 형식을 지정하는 경우 JSON이 반환됩니다.If other formatters are configured and the client specifies a different format, JSON is returned.

자세한 내용은 필터를 참조하세요.For more information, see Filters.

특수한 사례 포맷터Special case formatters

일부 특수한 경우 기본 제공 포맷터를 사용하여 구현됩니다.Some special cases are implemented using built-in formatters. 기본적으로 string 반환 형식은 text/plain(Accept 헤더를 통해 요청된 경우 text/html)으로 형식이 지정됩니다.By default, string return types are formatted as text/plain (text/html if requested via the Accept header). 이 동작은 StringOutputFormatter를 제거하여 삭제할 수 있습니다.This behavior can be deleted by removing the StringOutputFormatter. 포맷터들은 ConfigureServices 방법에서 제거됩니다.Formatters are removed in the ConfigureServices method. 모델 개체 반환 형식이 있는 작업은 null을 반환하는 경우 204 No Content를 반환합니다.Actions that have a model object return type return 204 No Content when returning null. 이 동작은 HttpNoContentOutputFormatter를 제거하여 삭제할 수 있습니다.This behavior can be deleted by removing the HttpNoContentOutputFormatter. 다음 코드를 StringOutputFormatter 및 HttpNoContentOutputFormatter를 제거합니다.The following code removes the StringOutputFormatter and HttpNoContentOutputFormatter.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(options =>
    {
        // requires using Microsoft.AspNetCore.Mvc.Formatters;
        options.OutputFormatters.RemoveType<StringOutputFormatter>();
        options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
    });
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        // requires using Microsoft.AspNetCore.Mvc.Formatters;
        options.OutputFormatters.RemoveType<StringOutputFormatter>();
        options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
    });

    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

StringOutputFormatter가 없으면 기본 제공 JSON 포맷터가 string 반환 형식의 형식을 지정합니다.Without the StringOutputFormatter, the built-in JSON formatter formats string return types. 기본 제공 JSON 포맷터가 제거되고 XML 포맷터를 사용할 수 있는 경우, XML 포맷터가 string 반환 형식의 형식을 지정합니다.If the built-in JSON formatter is removed and an XML formatter is available, the XML formatter formats string return types. 그렇지 않으면 string 반환 형식이 406 Not Acceptable을 반환합니다.Otherwise, string return types return 406 Not Acceptable.

HttpNoContentOutputFormatter가 없으면 null 개체는 구성된 포맷터를 사용하여 서식이 지정됩니다.Without the HttpNoContentOutputFormatter, null objects are formatted using the configured formatter. 예를 들면 다음과 같습니다.For example:

• JSON 포맷터는 null의 본문이 포함된 응답을 반환합니다.The JSON formatter returns a response with a body of null.
• XML 포맷터는 xsi:nil="true"로 설정된 특성을 사용하여 빈 XML 요소를 반환합니다.The XML formatter returns an empty XML element with the attribute xsi:nil="true" set.

응답 형식 URL 매핑Response format URL mappings

클라이언트는 URL의 일부로 특정 형식을 요청할 수 있습니다. 예를 들면 다음과 같습니다.Clients can request a particular format as part of the URL, for example:

• 쿼리 문자열 또는 경로의 부분에서.In the query string or part of the path.
• .Xml 또는 .json과 같은 서식 지정 파일 확장명을 사용하여.By using a format-specific file extension such as .xml or .json.

요청 경로의 매핑은 API가 사용하는 경로에 지정해야 합니다.The mapping from request path should be specified in the route the API is using. 예를 들면 다음과 같습니다.For example:

[Route("api/[controller]")]
[ApiController]
[FormatFilter]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}.{format?}")]
    public Product Get(int id)
    {

위 경로를 사용하면 요청된 형식을 선택적 파일 확장명으로 지정할 수 있습니다.The preceding route allows the requested format to be specified as an optional file extension. 특성은에 [FormatFilter] 형식 값이 있는지 확인 RouteData 하 고 응답이 생성 될 때 응답 형식을 적절 한 포맷터에 매핑합니다.The [FormatFilter] attribute checks for the existence of the format value in the RouteData and maps the response format to the appropriate formatter when the response is created.