Routing w internetowym interfejsie API ASP.NET

W tym artykule opisano, jak ASP.NET internetowy interfejs API kieruje żądania HTTP do kontrolerów.

Uwaga

Jeśli znasz ASP.NET MVC, routing internetowego interfejsu API jest bardzo podobny do routingu MVC. Główną różnicą jest to, że internetowy interfejs API używa czasownika HTTP, a nie ścieżki identyfikatora URI, aby wybrać akcję. Możesz również użyć routingu w stylu MVC w internetowym interfejsie API. W tym artykule nie przyjęto żadnej wiedzy na temat ASP.NET MVC.

Tabele routingu

W ASP.NET internetowym interfejsie API kontroler jest klasą, która obsługuje żądania HTTP. Publiczne metody kontrolera są nazywane metodami akcji lub po prostu akcjami. Gdy platforma internetowego interfejsu API odbiera żądanie, kieruje je do akcji.

Aby określić, która akcja ma być wywoływana, platforma używa tabeli routingu. Szablon projektu programu Visual Studio dla internetowego interfejsu API tworzy trasę domyślną:

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

Ta trasa jest definiowana w pliku WebApiConfig.cs , który znajduje się w katalogu App_Start :

Aby uzyskać więcej informacji na temat klasy, zobacz Konfigurowanie internetowego interfejsuWebApiConfig API ASP.NET.

Jeśli samodzielnie hostujesz internetowy interfejs API, musisz ustawić tabelę routingu bezpośrednio w HttpSelfHostConfiguration obiekcie . Aby uzyskać więcej informacji, zobacz Self-Host a Web API (Self-Hostowanie internetowego interfejsu API).

Każdy wpis w tabeli routingu zawiera szablon trasy. Domyślny szablon trasy dla internetowego interfejsu API to "api/{controller}/{id}". W tym szablonie "api" jest segmentem ścieżki literału, a {controller} i {id} są zmiennymi zastępczymi.

Gdy platforma internetowego interfejsu API odbiera żądanie HTTP, próbuje dopasować identyfikator URI do jednego z szablonów tras w tabeli routingu. Jeśli żadna trasa nie jest zgodna, klient otrzyma błąd 404. Na przykład następujące identyfikatory URI są zgodne z trasą domyślną:

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

Jednak następujący identyfikator URI nie jest zgodny, ponieważ brakuje mu segmentu "api":

• /contacts/1

Uwaga

Przyczyną używania "interfejsu API" w trasie jest uniknięcie kolizji z routingiem ASP.NET MVC. Dzięki temu możesz przejść do kontrolera MVC "/contacts", a "/api/contacts" przejść do kontrolera internetowego interfejsu API. Oczywiście, jeśli nie podoba ci się ta konwencja, możesz zmienić domyślną tabelę tras.

Po znalezieniu pasującej trasy internetowy interfejs API wybiera kontroler i akcję:

• Aby znaleźć kontroler, internetowy interfejs API dodaje wartość "Controller" do wartości zmiennej {controller} .
• Aby znaleźć akcję, internetowy interfejs API sprawdza czasownik HTTP, a następnie szuka akcji, której nazwa zaczyna się od tej nazwy czasownika HTTP. Na przykład w przypadku żądania GET internetowy interfejs API szuka akcji poprzedzonej ciągiem "Get", takim jak "GetContact" lub "GetAllContacts". Ta konwencja dotyczy tylko czasowników GET, POST, PUT, DELETE, HEAD, OPTIONS i PATCH. Inne czasowniki HTTP można włączyć przy użyciu atrybutów na kontrolerze. Zobaczymy przykład tego później.
• Inne zmienne zastępcze w szablonie trasy, takie jak {id}, są mapowane na parametry akcji.

Spójrzmy na przykład. Załóżmy, że definiujesz następujący kontroler:

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

Poniżej przedstawiono niektóre możliwe żądania HTTP wraz z akcją wywoływaną dla każdego z nich:

Czasownik HTTP	Ścieżka identyfikatora URI	Akcja	Parametr
GET	api/products	GetAllProducts	(brak)
GET	api/products/4	GetProductById	4
DELETE	api/products/4	DeleteProduct (Usuń produkt)	4
POST	api/products	(brak dopasowania)

Zwróć uwagę, że segment {id} identyfikatora URI, jeśli istnieje, jest mapowany na parametr id akcji. W tym przykładzie kontroler definiuje dwie metody GET, jedną z parametrem id i jedną bez parametrów.

Należy również zauważyć, że żądanie POST zakończy się niepowodzeniem, ponieważ kontroler nie definiuje metody "Post...".

Odmiany routingu

W poprzedniej sekcji opisano podstawowy mechanizm routingu dla internetowego interfejsu API ASP.NET. W tej sekcji opisano pewne odmiany.

Czasowniki HTTP

Zamiast używać konwencji nazewnictwa dla czasowników HTTP, można jawnie określić czasownik HTTP dla akcji, dekorując metodę akcji za pomocą jednego z następujących atrybutów:

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

W poniższym przykładzie FindProduct metoda jest mapowana na żądania GET:

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

Aby zezwolić na wiele zleceń HTTP dla akcji lub zezwalać na czasowniki HTTP inne niż GET, PUT, POST, DELETE, HEAD, OPTIONS i PATCH, użyj atrybutu [AcceptVerbs] , który przyjmuje listę czasowników HTTP.

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

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

Routing według nazwy akcji

W przypadku domyślnego szablonu routingu internetowy interfejs API używa czasownika HTTP do wybrania akcji. Można jednak również utworzyć trasę, w której nazwa akcji jest uwzględniona w identyfikatorze URI:

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

W tym szablonie trasy parametr {action} nazywa metodę akcji na kontrolerze. W tym stylu routingu użyj atrybutów, aby określić dozwolone czasowniki HTTP. Załóżmy na przykład, że kontroler ma następującą metodę:

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

W takim przypadku żądanie GET dla metody "api/products/details/1" będzie mapować na metodę Details . Ten styl routingu jest podobny do ASP.NET MVC i może być odpowiedni dla interfejsu API w stylu RPC.

Nazwę akcji można zastąpić za pomocą atrybutu [ActionName] . W poniższym przykładzie istnieją dwie akcje mapowane na "api/products/thumbnail/id. Jedna z nich obsługuje metodę GET, a druga obsługuje funkcję POST:

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

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

Akcje inne niż akcje

Aby zapobiec wywoływaniu metody jako akcji, użyj atrybutu [NonAction] . To sygnalizuje strukturę, że metoda nie jest akcją, nawet jeśli w przeciwnym razie będzie zgodna z regułami routingu.

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

Dalsze informacje

Ten temat zawiera ogólny widok routingu. Aby uzyskać więcej szczegółów, zobacz Routing i wybór akcji, który opisuje dokładnie, jak struktura pasuje do identyfikatora URI trasy, wybiera kontroler, a następnie wybiera akcję do wywołania.