ASP.NET Web API의 라우팅Routing in ASP.NET Web API

Mike Wassonby Mike Wasson

이 문서에서는 ASP.NET Web API는 컨트롤러에 HTTP 요청을 라우팅하는 방법을 설명 합니다.This article describes how ASP.NET Web API routes HTTP requests to controllers.

Note

ASP.NET MVC에 익숙한 경우 Web API 라우팅은 MVC 라우팅과 매우 유사 합니다.If you are familiar with ASP.NET MVC, Web API routing is very similar to MVC routing. 주요 차이점은 Web API는 URI 경로가 아니라 HTTP 동사를 사용 하 여 작업을 선택 한다는 것입니다.The main difference is that Web API uses the HTTP verb, not the URI path, to select the action. Web API에서 MVC 스타일 라우팅을 사용할 수도 있습니다.You can also use MVC-style routing in Web API. 이 문서에서는 ASP.NET MVC에 대 한 지식이 있다고 가정 하지 않습니다.This article does not assume any knowledge of ASP.NET MVC.

라우팅 테이블Routing Tables

ASP.NET Web API에서 컨트롤러 는 HTTP 요청을 처리 하는 클래스입니다.In ASP.NET Web API, a controller is a class that handles HTTP requests. 컨트롤러의 공용 메서드를 작업 메서드 또는 간단히 동작이라고 합니다.The public methods of the controller are called action methods or simply actions. 웹 API 프레임 워크에서 요청을 받으면 요청을 작업으로 라우팅합니다.When the Web API framework receives a request, it routes the request to an action.

호출할 동작을 결정 하기 위해 프레임 워크는 라우팅 테이블을 사용 합니다.To determine which action to invoke, the framework uses a routing table. Web API 용 Visual Studio 프로젝트 템플릿은 기본 경로를 만듭니다.The Visual Studio project template for Web API creates a default route:

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

이 경로는 WebApiConfig.cs 파일에 정의 되며, 앱 _ 시작 디렉터리에 배치 됩니다.This route is defined in the WebApiConfig.cs file, which is placed in the App_Start directory:

클래스에 대 한 자세한 내용은 WebApiConfig ASP.NET Web API 구성을 참조 하세요.For more information about the WebApiConfig class, see Configuring ASP.NET Web API.

Web API를 자체 호스트 하는 경우에는 개체에 직접 라우팅 테이블을 설정 해야 합니다 HttpSelfHostConfiguration .If you self-host Web API, you must set the routing table directly on the HttpSelfHostConfiguration object. 자세한 내용은 웹 API 자체 호스팅을 참조 하세요.For more information, see Self-Host a Web API.

라우팅 테이블의 각 항목에는 경로 템플릿이포함 되어 있습니다.Each entry in the routing table contains a route template. Web API에 대 한 기본 경로 템플릿은 " API/{controller}/{id}입니다 " .The default route template for Web API is "api/{controller}/{id}". 이 템플릿에서 " api " 는 리터럴 경로 세그먼트이 고 {controller} 및 {id}는 자리 표시자 변수입니다.In this template, "api" is a literal path segment, and {controller} and {id} are placeholder variables.

웹 API 프레임 워크는 HTTP 요청을 받으면 라우팅 테이블의 경로 템플릿 중 하나에 대해 URI를 일치 시 키 려 고 시도 합니다.When the Web API framework receives an HTTP request, it tries to match the URI against one of the route templates in the routing table. 경로가 일치 하지 않으면 클라이언트에서 404 오류를 수신 합니다.If no route matches, the client receives a 404 error. 예를 들어 다음 Uri는 기본 경로와 일치 합니다.For example, the following URIs match the default route:

  • /api/연락처/api/contacts
  • /api/contacts/1/api/contacts/1
  • /api/products/gizmo1/api/products/gizmo1

그러나 다음 URI는 api 세그먼트가 없으므로 일치 하지 않습니다 " " .However, the following URI does not match, because it lacks the "api" segment:

  • /contacts/1/contacts/1

Note

경로에서 "api"를 사용 하는 이유는 ASP.NET MVC 라우팅과의 충돌을 방지 하기 위한 것입니다.The reason for using "api" in the route is to avoid collisions with ASP.NET MVC routing. 이러한 방식으로 " /연락처를 " MVC 컨트롤러로 이동 하 고///또는 " 연락처를 " 웹 api 컨트롤러로 이동할 수 있습니다.That way, you can have "/contacts" go to an MVC controller, and "/api/contacts" go to a Web API controller. 물론이 규칙을 원하지 않는 경우 기본 경로 테이블을 변경할 수 있습니다.Of course, if you don't like this convention, you can change the default route table.

일치 하는 경로가 발견 되 면 Web API는 컨트롤러 및 작업을 선택 합니다.Once a matching route is found, Web API selects the controller and the action:

  • 웹 API는 컨트롤러를 찾기 위해 " " {controller} 변수 값에 컨트롤러를 추가 합니다.To find the controller, Web API adds "Controller" to the value of the {controller} variable.
  • 동작을 찾기 위해 Web API는 HTTP 동사를 찾은 다음 이름이 해당 HTTP 동사 이름으로 시작 하는 작업을 찾습니다.To find the action, Web API looks at the HTTP verb, and then looks for an action whose name begins with that HTTP verb name. 예를 들어 GET 요청을 사용 하는 경우 Web API는 " " " getcontact " 또는 " getallcontacts와 같이 get이 " 접두사로 추가 된 작업을 찾습니다.For example, with a GET request, Web API looks for an action prefixed with "Get", such as "GetContact" or "GetAllContacts". 이 규칙은 GET, POST, PUT, DELETE, HEAD, OPTIONS 및 PATCH 동사에만 적용 됩니다.This convention applies only to GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH verbs. 컨트롤러에서 특성을 사용 하 여 다른 HTTP 동사를 사용 하도록 설정할 수 있습니다.You can enable other HTTP verbs by using attributes on your controller. 이에 대 한 예제는 나중에 살펴보겠습니다.We'll see an example of that later.
  • 경로 템플릿의 다른 자리 표시자 변수 (예: {id} )는 동작 매개 변수에 매핑됩니다.Other placeholder variables in the route template, such as {id}, are mapped to action parameters.

예를 살펴보겠습니다.Let's look at an example. 다음 컨트롤러를 정의 한다고 가정 합니다.Suppose that you define the following controller:

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

다음은 각각에 대해 호출 되는 작업과 함께 가능한 몇 가지 HTTP 요청입니다.Here are some possible HTTP requests, along with the action that gets invoked for each:

HTTP 동사HTTP Verb URI 경로URI Path 작업Action 매개 변수Parameter
GETGET a p i/제품api/products GetAllProductsGetAllProducts 없음을(none)
GETGET a p i/제품/4api/products/4 GetProductByIdGetProductById 44
DeleteDELETE a p i/제품/4api/products/4 DeleteProductDeleteProduct 44
POSTPOST a p i/제품api/products (일치 항목 없음)(no match)

URI의 {id} 세그먼트 (있는 경우)가 동작의 id 매개 변수에 매핑됩니다.Notice that the {id} segment of the URI, if present, is mapped to the id parameter of the action. 이 예제에서 컨트롤러는 두 개의 GET 메서드를 정의 합니다. 하나는 id 매개 변수를 사용 하 고 다른 하나는 매개 변수를 포함 하지 않습니다.In this example, the controller defines two GET methods, one with an id parameter and one with no parameters.

또한 컨트롤러에서 " post ... 메서드를 정의 하지 않으므로 post 요청은 실패 합니다. "Also, note that the POST request will fail, because the controller does not define a "Post..." method.

라우팅 변형Routing Variations

이전 섹션에서는 ASP.NET Web API에 대 한 기본 라우팅 메커니즘에 대해 설명 했습니다.The previous section described the basic routing mechanism for ASP.NET Web API. 이 섹션에서는 몇 가지 변형에 대해 설명 합니다.This section describes some variations.

HTTP 동사HTTP verbs

HTTP 동사에 대 한 명명 규칙을 사용 하는 대신 작업 메서드를 다음 특성 중 하나로 데코레이팅 하 여 동작에 대 한 HTTP 동사를 명시적으로 지정할 수 있습니다.Instead of using the naming convention for HTTP verbs, you can explicitly specify the HTTP verb for an action by decorating the action method with one of the following attributes:

  • [HttpGet]
  • [HttpPut]
  • [HttpPost]
  • [HttpDelete]
  • [HttpHead]
  • [HttpOptions]
  • [HttpPatch]

다음 예제에서 FindProduct 메서드는 GET 요청에 매핑됩니다.In the following example, the FindProduct method is mapped to GET requests:

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

작업에 대해 여러 HTTP 동사를 허용 하거나 GET, PUT, POST, DELETE, HEAD, OPTIONS 및 PATCH 이외의 HTTP 동사를 허용 하려면 [AcceptVerbs] http 동사 목록을 사용 하는 특성을 사용 합니다.To allow multiple HTTP verbs for an action, or to allow HTTP verbs other than GET, PUT, POST, DELETE, HEAD, OPTIONS, and PATCH, use the [AcceptVerbs] attribute, which takes a list of HTTP verbs.

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

작업 이름별 라우팅Routing by Action Name

기본 라우팅 템플릿을 사용 하는 경우 Web API는 HTTP 동사를 사용 하 여 작업을 선택 합니다.With the default routing template, Web API uses the HTTP verb to select the action. 그러나 URI에 작업 이름이 포함 된 경로를 만들 수도 있습니다.However, you can also create a route where the action name is included in the URI:

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

이 경로 템플릿에서 {action} 매개 변수는 컨트롤러의 동작 메서드 이름을로 설정 합니다.In this route template, the {action} parameter names the action method on the controller. 이 스타일의 라우팅을 사용 하 여 특성을 사용 하 여 허용 되는 HTTP 동사를 지정 합니다.With this style of routing, use attributes to specify the allowed HTTP verbs. 예를 들어 컨트롤러에 다음 메서드가 있다고 가정 합니다.For example, suppose your controller has the following method:

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

이 경우 "api/products/details/1"에 대 한 GET 요청은 Details 메서드에 매핑됩니다.In this case, a GET request for "api/products/details/1" would map to the Details method. 이 라우팅 스타일은 ASP.NET MVC와 비슷하며 RPC 스타일 API에 적합할 수 있습니다.This style of routing is similar to ASP.NET MVC, and may be appropriate for an RPC-style API.

특성을 사용 하 여 작업 이름을 재정의할 수 있습니다 [ActionName] .You can override the action name by using the [ActionName] attribute. 다음 예제에서는 a p i/ " 제품/축소판 그림/id에 매핑되는 두 가지 작업을 수행 합니다. 하나는 GET을 지원 하 고 다른 하나는 POST를 지원 합니다.In the following example, there are two actions that map to "api/products/thumbnail/id. One supports GET and the other supports POST:

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

비 작업Non-Actions

메서드가 동작으로 호출 되는 것을 방지 하려면 특성을 사용 [NonAction] 합니다.To prevent a method from getting invoked as an action, use the [NonAction] attribute. 이는 다른 방법으로 라우팅 규칙과 일치 하는 경우에도 메서드가 동작이 아니라는 프레임 워크에 신호를 보냅니다.This signals to the framework that the method is not an action, even if it would otherwise match the routing rules.

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

추가 정보Further Reading

이 항목에서는 라우팅에 대 한 개략적인 보기를 제공 했습니다.This topic provided a high-level view of routing. 자세한 내용은 라우팅 및 작업 선택, 프레임 워크가 경로에 대 한 URI를 정확히 일치 하는 방식에 대해 설명 하 고, 컨트롤러를 선택한 다음 호출할 작업을 선택 하는 방법을 참조 하세요.For more detail, see Routing and Action Selection, which describes exactly how the framework matches a URI to a route, selects a controller, and then selects the action to invoke.