Sdílet prostřednictvím

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

  • Článek

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

  • ASP.NET Core je opensourcová multiplatformní architektura pro vytváření moderních cloudových webových aplikací ve Windows, macOS a Linuxu.
  • Řadiče ASP.NET Core MVC a řadiče webového rozhraní API jsou sjednocené.
  • Navrženo pro testování.
  • Schopnost vyvíjet a spouštět ve Windows, macOS a Linuxu
  • 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 Kestrel, 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 návratovou hodnotu z akce kontroleru na zprávu odpovědi HTTP.

Akce kontroleru webového rozhraní API může vrátit některou z následujících možností:

  1. void
  2. HttpResponseMessage
  3. IHttpActionResult
  4. Jiný typ

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

Návratový typ Jak webové rozhraní API vytvoří odpověď
void Vrácení prázdné verze 204 (bez obsahu)
HttpResponseMessage Převeďte přímo na zprávu odpovědi HTTP.
IHttpActionResult Volání ExecuteAsync vytvořit HttpResponseMessage a pak převést na zprávu odpovědi HTTP.
Jiný typ Zapište serializovanou návratovou hodnotu do textu odpovědi; return 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í HttpResponseMessage objektu naplnění odpovědi.

Tato možnost vám dává velkou kontrolu nad zprávou odpovědi. 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 k zápisu serializovaného modelu do textu odpovědi formátovací modul mé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átovače. Další informace naleznete 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 skrytím podrobností nízké úrovně při vytváření odpovědi.

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

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

Pokud akce kontroleru vrátí IHttpActionResult, webové rozhraní API volá ExecuteAsync metodu vytvořit 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žívají implementace IHttpActionResult definované v oboru názvů System.Web.Http.Results. Třída ApiController definuje pomocné metody, které vracejí tyto předdefinované výsledky akce.

Pokud požadavek v následujícím příkladu neodpovídá existujícímu ID produktu, řadič volá ApiController.NotFound k vytvoření odpovědi 404 (Nenalezeno). V opačném případě řadič volá 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 textu 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átovače. Další informace naleznete 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}]