Směrování ve webovém rozhraní API ASP.NET

Tento článek popisuje, jak ASP.NET webové rozhraní API směruje požadavky HTTP na kontrolery.

Poznámka

Pokud znáte ASP.NET MVC, je směrování webového rozhraní API velmi podobné směrování MVC. Hlavní rozdíl spočívá v tom, že webové rozhraní API k výběru akce používá příkaz HTTP, nikoli cestu URI. Ve webovém rozhraní API můžete také použít směrování ve stylu MVC. Tento článek nepředpokládá žádné znalosti ASP.NET MVC.

Směrovací tabulky

Ve webovém rozhraní API ASP.NET je kontroler třída, která zpracovává požadavky HTTP. Veřejné metody kontroleru se nazývají metody akcí nebo jednoduše akce. Když architektura webového rozhraní API obdrží požadavek, směruje požadavek na akci.

K určení akce, která se má vyvolat, používá rozhraní směrovací tabulku. Šablona projektu sady Visual Studio pro webové rozhraní API vytvoří výchozí trasu:

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

Tato trasa je definována v souboru WebApiConfig.cs , který je umístěn v adresáři App_Start :

Další informace o třídě najdete v WebApiConfig tématu Konfigurace ASP.NET webového rozhraní API.

Pokud webové rozhraní API hostujete sami, musíte nastavit směrovací tabulku přímo na objektu HttpSelfHostConfiguration . Další informace najdete v tématu Samoobslužné hostování webového rozhraní API.

Každá položka ve směrovací tabulce obsahuje šablonu trasy. Výchozí šablona trasy pro webové rozhraní API je api/{controller}/{id}. V této šabloně je "api" segment literálové cesty a {controller} a {id} jsou zástupné proměnné.

Když rozhraní webového rozhraní API obdrží požadavek HTTP, pokusí se spárovat identifikátor URI s jednou ze šablon tras ve směrovací tabulce. Pokud se žádná trasa shoduje, klient obdrží chybu 404. Například následující identifikátory URI odpovídají výchozí trase:

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

Následující identifikátor URI se však neshoduje, protože chybí segment "api":

• /contacts/1

Poznámka

Důvodem použití rozhraní API v trase je vyhnout se kolizím se směrováním ASP.NET MVC. Tímto způsobem můžete /contacts přejít na kontroler MVC a /api/contacts přejít na kontroler webového rozhraní API. Pokud se vám tato konvence nelíbí, můžete samozřejmě změnit výchozí směrovací tabulku.

Jakmile se najde odpovídající trasa, webové rozhraní API vybere kontroler a akci:

• Pokud chcete najít kontroler, webové rozhraní API přidá k hodnotě proměnné {controller} hodnotu Controller.
• Pokud chcete najít akci, webové rozhraní API se podívá na příkaz HTTP a pak vyhledá akci, jejíž název začíná tímto názvem slovesa HTTP. Například u požadavku GET webové rozhraní API vyhledá akci s předponou Get, například GetContacts nebo GetAllContacts. Tato konvence platí pouze pro příkazy GET, POST, PUT, DELETE, HEAD, OPTIONS a PATCH. Další příkazy HTTP můžete povolit pomocí atributů na kontroleru. Příklad toho uvidíme později.
• Další zástupné proměnné v šabloně trasy, například {id}, se mapují na parametry akce.

Podívejme se na příklad. Předpokládejme, že definujete následující kontroler:

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

Tady jsou některé možné požadavky HTTP spolu s akcí, která se pro každý z nich vyvolá:

Příkaz HTTP	Cesta identifikátoru URI	Akce	Parametr
GET	api/products	GetAllProducts	(žádné)
GET	api/products/4	GetProductById	4
DELETE	api/products/4	DeleteProduct	4
POST	api/products	(bez shody)

Všimněte si, že segment {id} identifikátoru URI, pokud je k dispozici, je mapován na parametr id akce. V tomto příkladu kontroler definuje dvě metody GET, jednu s parametrem ID a druhou bez parametrů.

Všimněte si také, že požadavek POST selže, protože kontroler nedefinuje metodu Post....

Varianty směrování

Předchozí část popisuje základní mechanismus směrování pro ASP.NET webové rozhraní API. Tato část popisuje některé varianty.

Příkazy HTTP

Místo použití konvence vytváření názvů pro příkazy HTTP můžete explicitně zadat příkaz HTTP pro akci tak, že metodu action ozdobíte jedním z následujících atributů:

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

V následujícím příkladu FindProduct je metoda mapována na požadavky GET:

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

Pokud chcete povolit více příkazů HTTP pro akci nebo povolit jiné příkazy HTTP než GET, PUT, POST, DELETE, HEAD, OPTIONS a PATCH, použijte [AcceptVerbs] atribut, který obsahuje seznam příkazů HTTP.

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

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

Směrování podle názvu akce

S výchozí šablonou směrování webové rozhraní API používá k výběru akce příkaz HTTP. Můžete ale také vytvořit trasu, kde je název akce zahrnutý v identifikátoru URI:

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

V této šabloně trasy parametr {action} pojmenuje metodu action na kontroleru. S tímto stylem směrování použijte atributy k určení povolených příkazů HTTP. Předpokládejme například, že kontroler má následující metodu:

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

V tomto případě by se požadavek GET na "api/products/details/1" namapoval na metodu Details . Tento styl směrování se podobá ASP.NET MVC a může být vhodný pro rozhraní API ve stylu RPC.

Název akce můžete přepsat pomocí atributu [ActionName] . V následujícím příkladu jsou dvě akce, které se mapují na api/products/thumbnail/id. Jeden podporuje GET a druhý podporuje POST:

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

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

Jiné akce

Pokud chcete zabránit vyvolání metody jako akce, použijte [NonAction] atribut . To signalizuje architektuře, že metoda není akce, i když by jinak odpovídala pravidlům směrování.

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

Další čtení

Toto téma poskytuje základní přehled o směrování. Další podrobnosti najdete v tématu Výběr směrování a akce, který přesně popisuje, jak architektura odpovídá identifikátoru URI trase, vybere kontroler a pak vybere akci, která se má vyvolat.