Výsledky akcí ve webovém rozhraní API 2

Článek
07/13/2023

Zvažte použití ASP.NET Core webového rozhraní API. Oproti webovému rozhraní API ASP.NET 4.x má následující výhody:

ASP.NET Core je opensourcová multiplatformní architektura pro vytváření moderních cloudových webových aplikací ve Windows, macOS a Linuxu.
Kontrolery ASP.NET Core MVC a kontrolery webového rozhraní API jsou sjednocené.
Navržena tak, aby byla testovatelnost.
Schopnost vyvíjet a spouštět v systémech Windows, macOS a Linux.
Architektura zaměřená na open-source a komunitu.
Integrace moderní architektury klienta a vývojových pracovních postupů
Konfigurační systém založený na prostředí, který je připravený pro cloud.
Integrovaná injektáž závislostí.
Odlehčený, vysoce výkonný, modulární kanál požadavků HTTP.
Schopnost hostovat v Kestrelu, IIS, HTTP.sys, Nginx, Apache a Dockeru.
Souběžná správa verzí.
Nabízí nástroje, které usnadňují vývoj moderních webů.

Toto téma popisuje, jak ASP.NET webové rozhraní API převede vrácenou hodnotu z akce kontroleru na zprávu odpovědi HTTP.

Akce kontroleru webového rozhraní API může vrátit následující:

void
HttpResponseMessage
IHttpActionResult
Nějaký jiný typ

V závislosti na tom, která z těchto vrácených hodnot se vrátí, použije webové rozhraní API k vytvoření odpovědi HTTP jiný mechanismus.

Návratový typ	Jak webové rozhraní API vytvoří odpověď
void	Vrátit prázdné 204 (bez obsahu)
HttpResponseMessage	Převod přímo na zprávu odpovědi HTTP.
IHttpActionResult	Voláním metody ExecuteAsync vytvořte zprávu HttpResponseMessage a pak ji převeďte na zprávu odpovědi HTTP.
Jiný typ	Zapište serializovanou návratovou hodnotu do těla odpovědi; vrátit hodnotu 200 (OK).

Zbývající část tohoto tématu popisuje jednotlivé možnosti podrobněji.

void

Pokud je voidnávratový typ , webové rozhraní API jednoduše vrátí prázdnou odpověď HTTP se stavovým kódem 204 (bez obsahu).

Příklad kontroleru:

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

Odpověď HTTP:

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

HttpResponseMessage

Pokud akce vrátí HttpResponseMessage, webové rozhraní API převede návratovou hodnotu přímo na zprávu odpovědi HTTP pomocí vlastností objektu HttpResponseMessage k naplnění odpovědi.

Tato možnost vám dává velkou kontrolu nad zprávou s odpovědí. Například následující akce kontroleru nastaví hlavičku Cache-Control.

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

Odpověď:

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

Pokud předáte doménový model metodě CreateResponse , webové rozhraní API použije formátovací modul médií k zápisu serializovaného modelu do těla odpovědi.

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

Webové rozhraní API používá hlavičku Accept v požadavku k výběru formátu. Další informace najdete v tématu Vyjednávání obsahu.

IHttpActionResult

Rozhraní IHttpActionResult bylo zavedeno ve webovém rozhraní API 2. V podstatě definuje továrnu httpResponseMessage . Tady jsou některé výhody použití rozhraní IHttpActionResult :

Zjednodušuje testování jednotek kontrolerů.
Přesune běžnou logiku pro vytváření odpovědí HTTP do samostatných tříd.
Zpřesní záměr akce kontroleru tím, že skryje podrobnosti nízké úrovně vytváření odpovědi.

IHttpActionResult obsahuje jednu metodu ExecuteAsync, která asynchronně vytvoří instanci HttpResponseMessage .

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

Pokud akce kontroleru vrátí IHttpActionResult, webové rozhraní API volá metodu ExecuteAsync k vytvoření HttpResponseMessage. Pak převede HttpResponseMessage na zprávu odpovědi HTTP.

Tady je jednoduchá implementace IHttpActionResult , která vytvoří odpověď ve formátu prostého textu:

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

Příklad akce kontroleru:

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

Odpověď:

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

Častěji se používá implementace IHttpActionResult definované v oboru názvů System.Web.Http.Results . Třída ApiController definuje pomocné metody, které vrací tyto integrované výsledky akce.

Pokud v následujícím příkladu požadavek neodpovídá id existujícího produktu, volá kontroler ApiController.NotFound a vytvoří odpověď 404 (Nenalezeno). V opačném případě volá kontroler ApiController.OK, který vytvoří odpověď 200 (OK), která obsahuje produkt.

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

Jiné návratové typy

Pro všechny ostatní návratové typy používá webové rozhraní API k serializaci návratové hodnoty formátovací modul médií . Webové rozhraní API zapíše serializovanou hodnotu do těla odpovědi. Stavový kód odpovědi je 200 (OK).

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

Nevýhodou tohoto přístupu je, že nemůžete přímo vrátit kód chyby, například 404. Pro kódy chyb však můžete vyvolat výjimku HttpResponseException . Další informace najdete v tématu Zpracování výjimek ve webovém rozhraní API ASP.NET.

Webové rozhraní API používá hlavičku Accept v požadavku k výběru formátu. Další informace najdete v tématu Vyjednávání obsahu.

Příklad požadavku

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

Příklad odpovědi

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