Odesílání dat formuláře HTML ve webovém rozhraní API ASP.NET: Data s kódem url formuláře

Část 1: Data ve formátu urlencoded

Tento článek ukazuje, jak publikovat data s kódem urlencoded formuláře do kontroleru webového rozhraní API.

• Přehled formulářů HTML
• Odesílání komplexních typů
• Odesílání dat formuláře přes AJAX
• Odesílání jednoduchých typů

Přehled formulářů HTML

Formuláře HTML používají k odesílání dat na server příkaz GET nebo POST. Atribut method elementu form poskytuje metodu HTTP:

<form action="api/values" method="post">

Výchozí metoda je GET. Pokud formulář používá funkci GET, data formuláře se kódují v identifikátoru URI jako řetězec dotazu. Pokud formulář používá post, data formuláře se umístí do textu požadavku. Pro posted data určuje atribut enctype formát textu požadavku:

Část 1 tohoto článku se zabývá formátem x-www-form-urlencoded. Část 2 popisuje vícedílné MIME.

Odesílání komplexních typů

Obvykle odešlete komplexní typ, který se skládá z hodnot převzatých z několika ovládacích prvků formuláře. Představte si následující model, který představuje aktualizaci stavu:

namespace FormEncode.Models
{
    using System;
    using System.ComponentModel.DataAnnotations;

    public class Update
    {
        [Required]
        [MaxLength(140)]
        public string Status { get; set; }

        public DateTime Date { get; set; }
    }
}

Tady je kontroler webového rozhraní API, který přijímá Update objekt přes POST.

namespace FormEncode.Controllers
{
    using FormEncode.Models;
    using System;
    using System.Collections.Generic;
    using System.Net;
    using System.Net.Http;
    using System.Web;
    using System.Web.Http;

    public class UpdatesController : ApiController
    {
        static readonly Dictionary<Guid, Update> updates = new Dictionary<Guid, Update>();

        [HttpPost]
        [ActionName("Complex")]
        public HttpResponseMessage PostComplex(Update update)
        {
            if (ModelState.IsValid && update != null)
            {
                // Convert any HTML markup in the status text.
                update.Status = HttpUtility.HtmlEncode(update.Status);

                // Assign a new ID.
                var id = Guid.NewGuid();
                updates[id] = update;

                // Create a 201 response.
                var response = new HttpResponseMessage(HttpStatusCode.Created)
                {
                    Content = new StringContent(update.Status)
                };
                response.Headers.Location = 
                    new Uri(Url.Link("DefaultApi", new { action = "status", id = id }));
                return response;
            }
            else
            {
                return Request.CreateResponse(HttpStatusCode.BadRequest);
            }
        }

        [HttpGet]
        public Update Status(Guid id)
        {
            Update update;
            if (updates.TryGetValue(id, out update))
            {
                return update;
            }
            else
            {
                throw new HttpResponseException(HttpStatusCode.NotFound);
            }
        }

    }
}

Teď napíšeme formulář HTML, který uživatelům umožní odeslat aktualizaci stavu.

<h1>Complex Type</h1>
<form id="form1" method="post" action="api/updates/complex" 
    enctype="application/x-www-form-urlencoded">
    <div>
        <label for="status">Status</label>
    </div>
    <div>
        <input name="status" type="text" />
    </div>
    <div>
        <label for="date">Date</label>
    </div>
    <div>
        <input name="date" type="text" />
    </div>
    <div>
        <input type="submit" value="Submit" />
    </div>
</form>

Všimněte si, že atribut action ve formuláři je identifikátorem URI akce kontroleru. Tady je formulář s některými zadanými hodnotami:

Když uživatel klikne na Odeslat, prohlížeč odešle požadavek HTTP podobný následujícímu:

POST http://localhost:38899/api/updates/complex HTTP/1.1
Accept: text/html, application/xhtml+xml, */*
User-Agent: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)
Content-Type: application/x-www-form-urlencoded
Content-Length: 47

status=Shopping+at+the+mall.&date=6%2F15%2F2012

Všimněte si, že text požadavku obsahuje data formuláře formátovaná jako páry název/hodnota. Webové rozhraní API automaticky převede páry název/hodnota na instanci Update třídy.

Odesílání dat formuláře přes AJAX

Když uživatel odešle formulář, prohlížeč přejde mimo aktuální stránku a vykreslí text zprávy s odpovědí. To je v pořádku, pokud je odpovědí stránka HTML. U webového rozhraní API je ale tělo odpovědi obvykle buď prázdné, nebo obsahuje strukturovaná data, například JSON. V takovém případě je vhodnější odeslat data formuláře pomocí požadavku AJAX, aby stránka mohl zpracovat odpověď.

Následující kód ukazuje, jak publikovat data formuláře pomocí jQuery.

<script type="text/javascript">
    $("#form1").submit(function () {
        var jqxhr = $.post('api/updates/complex', $('#form1').serialize())
            .success(function () {
                var loc = jqxhr.getResponseHeader('Location');
                var a = $('<a/>', { href: loc, text: loc });
                $('#message').html(a);
            })
            .error(function () {
                $('#message').html("Error posting the update.");
            });
        return false;
    });
</script>

Funkce jQuery submit nahradí akci formuláře novou funkcí. Tím se přepíše výchozí chování tlačítka Odeslat. Funkce serializace serializuje data formuláře do dvojic název/hodnota. Pokud chcete odeslat data formuláře na server, zavolejte .$.post()

Po dokončení požadavku zobrazí obslužná rutina .success() nebo .error() uživateli příslušnou zprávu.

Odesílání jednoduchých typů

V předchozích částech jsme odeslali komplexní typ, který webové rozhraní API deserializovalo do instance třídy modelu. Můžete také posílat jednoduché typy, například řetězec.

Základní kroky pro odeslání jednoduchého typu jsou stejné, ale existují dva drobné rozdíly. Nejprve v kontroleru musíte název parametru opatřovat atributem FromBody .

[HttpPost]
[ActionName("Simple")]
public HttpResponseMessage PostSimple([FromBody] string value)
{
    if (value != null)
    {
        Update update = new Update()
        {
            Status = HttpUtility.HtmlEncode(value),
            Date = DateTime.UtcNow
        };

        var id = Guid.NewGuid();
        updates[id] = update;

        var response = new HttpResponseMessage(HttpStatusCode.Created)
        {
            Content = new StringContent(update.Status)
        };
        response.Headers.Location = 
            new Uri(Url.Link("DefaultApi", new { action = "status", id = id }));
        return response;
    }
    else
    {
        return Request.CreateResponse(HttpStatusCode.BadRequest);
    }

Ve výchozím nastavení se webové rozhraní API pokusí získat jednoduché typy z identifikátoru URI požadavku. Atribut FromBody říká webovému rozhraní API, aby přečetlo hodnotu z textu požadavku.

Za druhé, klient musí odeslat hodnotu v následujícím formátu:

=value

Konkrétně musí být část názvu v páru název/hodnota pro jednoduchý typ prázdná. Ne všechny prohlížeče to podporují pro formuláře HTML, ale tento formát vytvoříte ve skriptu následujícím způsobem:

$.post('api/updates/simple', { "": $('#status1').val() });

Tady je příklad formuláře:

<h1>Simple Type</h1>
<form id="form2">
    <div>
        <label for="status">Status</label>
    </div>
    <div>
        <input id="status1" type="text" />
    </div>
    <div>
        <input type="submit" value="Submit" />
    </div>
</form>

A tady je skript pro odeslání hodnoty formuláře. Jediným rozdílem oproti předchozímu skriptu je argument předaný do funkce post .

$('#form2').submit(function () {
    var jqxhr = $.post('api/updates/simple', { "": $('#status1').val() })
        .success(function () {
            var loc = jqxhr.getResponseHeader('Location');
            var a = $('<a/>', { href: loc, text: loc });
            $('#message').html(a);
        })
        .error(function () {
            $('#message').html("Error posting the update.");
        });
    return false;
});

Stejný přístup můžete použít k odeslání pole jednoduchých typů:

$.post('api/updates/postlist', { "": ["update one", "update two", "update three"] });

Další materiály

Část 2: Nahrávání souborů a vícedílné mime