Kurz: Vytvoření webového rozhraní API pomocí ASP.NET Core

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Autoři: Rick Anderson a Kirk Larkin

V tomto kurzu se naučíte základy vytváření webového rozhraní API založeného na kontroleru, které používá databázi. Dalším přístupem k vytváření rozhraní API v ASP.NET Core je vytvoření minimálních rozhraní API. Nápovědu k výběru mezi minimálními rozhraními API a rozhraními API založenými na kontroleru najdete v přehledu rozhraní API. Kurz vytvoření minimálního rozhraní API najdete v kurzu : Vytvoření minimálního rozhraní API s ASP.NET Core.

Přehled

Tento kurz vytvoří následující rozhraní API:

API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Nic Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Nic Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Nic
DELETE /api/todoitems/{id}     Odstranění položky Nic Nic

Následující diagram znázorňuje návrh aplikace.

Klient je reprezentován polem vlevo. Odešle žádost a obdrží odpověď z aplikace, pole nakreslené vpravo. V poli aplikace představují tři pole kontroler, model a vrstvu přístupu k datům. Požadavek přichází do kontroleru aplikace a mezi kontrolerem a vrstvou přístupu k datům dochází k operacím čtení a zápisu. Model je serializován a vrácen klientovi v odpovědi.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>projekt.
  • Do vyhledávacího pole zadejte webové rozhraní API .
  • Vyberte šablonu ASP.NET Základní webové rozhraní API a vyberte Další.
  • V dialogovém okně Konfigurovat nový projekt pojmenujte projekt TodoApi a vyberte Další.
  • V dialogovém okně Další informace :
    • Ověřte, že rozhraní je .NET 8.0 (dlouhodobá podpora).
    • Ověřte, že je zaškrtnuté políčko Použít kontrolery (zrušení zaškrtnutí pro použití minimálních rozhraní API).
    • Ověřte, že je zaškrtnuté políčko Povolit podporu OpenAPI.
    • Vyberte Vytvořit.

Přidání balíčku NuGet

Pro podporu databáze použité v tomto kurzu je potřeba přidat balíček NuGet.

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet.
  • Do vyhledávacího pole zadejte Microsoft.EntityFrameworkCore.InMemory a pak vyberte Microsoft.EntityFrameworkCore.InMemory.
  • V pravém podokně zaškrtněte políčko Projekt a pak vyberte Nainstalovat.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Testování projektu

Šablona projektu vytvoří WeatherForecast rozhraní API s podporou Swaggeru.

Stisknutím kombinace kláves Ctrl+F5 spusťte bez ladicího programu.

Visual Studio zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný tak, aby používal PROTOKOL SSL:

Tento projekt je nakonfigurovaný tak, aby používal PROTOKOL SSL. Abyste se vyhnuli upozorněním SSL v prohlížeči, můžete se rozhodnout důvěřovat certifikátu podepsanému svým držitelem, který služba IIS Express vygenerovala. Chcete důvěřovat certifikátu SSL služby IIS Express?

Pokud důvěřujete certifikátu SSL služby IIS Express, vyberte Ano .

Zobrazí se následující dialogové okno:

Dialogové okno upozornění zabezpečení

Pokud souhlasíte s tím, že se má důvěřovat vývojovému certifikátu, vyberte Ano.

Informace o důvěřování prohlížeči Firefox naleznete v článku o chybě certifikátu aplikace Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio spustí výchozí prohlížeč a přejde na https://localhost:<port>/swagger/index.html, kde <port> je náhodně zvolené číslo portu nastavené při vytváření projektu.

Zobrazí se stránka /swagger/index.html Swagger. Vyberte GET>Try it out>Execute. Zobrazí se stránka:

  • Příkaz Curl k otestování rozhraní API WeatherForecast.
  • Adresa URL pro otestování rozhraní API WeatherForecast.
  • Kód odpovědi, text a hlavičky.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem

Pokud se stránka Swagger nezobrazí, podívejte se na tento problém na GitHubu.

Swagger se používá ke generování užitečné dokumentace a stránek nápovědy pro webová rozhraní API. V tomto kurzu se k otestování aplikace používá Swagger. Další informace o Swaggeru najdete v dokumentaci k webovému rozhraní API pro ASP.NET Core pomocí Swaggeru / OpenAPI.

Zkopírujte a vložte adresu URL požadavku v prohlížeči: https://localhost:<port>/weatherforecast

JSVrátí se funkce ON podobná následujícímu příkladu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.
  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoItem a vyberte Přidat.
  • Nahraďte kód šablony následujícím kódem:
namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelu můžou přejít kdekoli v projektu, ale Models složka se používá podle konvence.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoContext a klepněte na tlačítko Přidat.

  • Zadejte následující kód:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models;

public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options)
        : base(options)
    {
    }

    public DbSet<TodoItem> TodoItems { get; set; } = null!;
}

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službě kontrolery.

Aktualizujte Program.cs následujícím zvýrazněným kódem:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Předchozí kód:

  • Přidá using direktivy.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování uživatelského rozhraní kontroleru

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí entity Framework a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Ve třídě Model vyberte TodoItem (TodoApi.Models).
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

    Pokud operace generování uživatelského rozhraní selže, vyberte Přidat a pokuste se znovu vygenerovat generování.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními, které jsou součástí [action] šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony trasy.

[action] Pokud token není v šabloně trasy, název akce (název metody) není součástí koncového bodu. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Aktualizace metody vytvoření PostTodoItem

Aktualizujte návratový příkaz v operátoru PostTodoItemnameof :

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("PostTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(PostTodoItem), new { id = todoItem.Id }, todoItem);
}

Předchozí kód je HTTP POST metoda, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu TodoItem z textu požadavku HTTP.

Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

Metoda CreatedAtAction:

  • V případě úspěchu vrátí stavový kód HTTP 201. HTTP 201 je standardní odpověď metody HTTP POST , která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolu. Další informace naleznete v tématu 10.2.2 201 Vytvořeno.
  • Odkazuje na PostTodoItem akci pro vytvoření identifikátoru Location URI hlavičky. Klíčové slovo jazyka C# nameof slouží k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Test PostTodoItem

  • Stisknutím kombinace kláves Ctrl+F5 spusťte aplikaci.

  • V okně prohlížeče Swagger vyberte POST /api/TodoItems a pak vyberte Vyzkoušet.

  • V okně vstupu textu požadavku aktualizujte zapnutoJS. Příklad:

    {
  "name": "walk dog",
  "isComplete": true
}

  • Vyberte Execute (Provést).

    Swagger POST

Otestování identifikátoru URI hlavičky umístění

V předchozím POST se v uživatelském rozhraní Swaggeru zobrazí hlavička umístění pod hlavičkami Odpovědi. Například location: https://localhost:7260/api/TodoItems/1. V hlavičce umístění se zobrazí identifikátor URI vytvořeného prostředku.

Otestování hlavičky umístění:

  • V okně prohlížeče Swagger vyberte GET /api/TodoItems/{id} a pak vyberte Vyzkoušet.

  • Zadejte 1 do vstupního id pole a pak vyberte Spustit.

    Swagger GET

Prozkoumání metod GET

Implementují se dva koncové body GET:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Předchozí část ukázala příklad /api/todoitems/{id} trasy.

Podle pokynů POST přidejte další položku úkolu a pak trasu otestujte pomocí Swaggeru/api/todoitems.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty URL

Atribut [HttpGet] označuje metodu, která reaguje na HTTP GET požadavek. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase

  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET základní směrování nerozlišuje velká a malá písmena.

  • [HttpGet] Pokud má atribut šablonu trasy (například[HttpGet("products")]), připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání je hodnota "{id}" v adrese URL poskytována metodě v jeho id parametru.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je ActionResult<T> typ. ASP.NET Core automaticky serializuje objekt na JSON a zapíše JSho do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy mohou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavuNotFound 404.
  • V opačném případě vrátí metoda hodnotu 200 s tělem JSodpovědi ON. Vrácení item výsledků v HTTP 200 odpovědi

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem je podobný PostTodoItem, s výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek vyžaduje, PUT aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte HTTP PATCH.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Před voláním metody PUT zavolejte get a ujistěte se, že je v databázi položka.

Pomocí uživatelského rozhraní Swagger pomocí tlačítka PUT aktualizujte TodoItem ID = 1 a nastavte jeho název na "feed fish". Všimněte si, že odpověď je HTTP 204 No Content.

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Testování metody DeleteTodoItem

Pomocí uživatelského rozhraní Swagger odstraňte TodoItem ID = 1. Všimněte si, že odpověď je HTTP 204 No Content.

Testování s využitím jiných nástrojů

K testování webových rozhraní API je možné použít mnoho dalších nástrojů, například:

Další informace naleznete v tématu:

Prevence nadměrného účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožina modelu. Za tímto důvodem je několik důvodů a zabezpečení je hlavní. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto kurzu.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Vynecháte některé vlastnosti, aby se snížila velikost datové části.
  • Zploštěné grafy objektů, které obsahují vnořené objekty Grafy plochých objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala pole tajného kódu:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Pole tajného kódu musí být v této aplikaci skryté, ale aplikace pro správu by se mohla rozhodnout, že ho zveřejní.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Aktualizujte, TodoItemsController aby bylo možné použít TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Ověřte, že nemůžete publikovat nebo získat pole tajného kódu.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

Série videí webového rozhraní API

Podívejte se na video: Série začátečníků: Webová rozhraní API.

Spolehlivé vzory webových aplikací

Pokyny k vytvoření moderní, spolehlivé, výkonné, testovatelné, nákladově efektivní a škálovatelné aplikace ASP.NET Core, ať už od nuly nebo refaktoringu stávající aplikace, najdete v článku o modelu Reliable Web App Pattern for.NETYouTube.

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identity přidává do webových aplikací ASP.NET Core funkce přihlášení uživatelského rozhraní. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

Duende Identity Server je rozhraní OpenID Připojení a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční využití serveru Duende Identity Server. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Identity Serveru (web Duende Software).

Publikování do Azure

Informace o nasazení do Azure najdete v tématu Rychlý start: Nasazení webové aplikace ASP.NET.

Další materiály

Zobrazit nebo stáhnout ukázkový kód pro tento kurz Podívejte se, jak si stáhnout.

Další informace naleznete v následujících zdrojích:

V tomto kurzu se naučíte základy vytváření webového rozhraní API založeného na kontroleru, které používá databázi. Dalším přístupem k vytváření rozhraní API v ASP.NET Core je vytvoření minimálních rozhraní API. Nápovědu k výběru mezi minimálními rozhraními API a rozhraními API založenými na kontroleru najdete v přehledu rozhraní API. Kurz vytvoření minimálního rozhraní API najdete v kurzu : Vytvoření minimálního rozhraní API s ASP.NET Core.

Přehled

Tento kurz vytvoří následující rozhraní API:

API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Nic Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Nic Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Nic
DELETE /api/todoitems/{id}     Odstranění položky Nic Nic

Následující diagram znázorňuje návrh aplikace.

Klient je reprezentován polem vlevo. Odešle žádost a obdrží odpověď z aplikace, pole nakreslené vpravo. V poli aplikace představují tři pole kontroler, model a vrstvu přístupu k datům. Požadavek přichází do kontroleru aplikace a mezi kontrolerem a vrstvou přístupu k datům dochází k operacím čtení a zápisu. Model je serializován a vrácen klientovi v odpovědi.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>projekt.
  • Do vyhledávacího pole zadejte webové rozhraní API .
  • Vyberte šablonu ASP.NET Základní webové rozhraní API a vyberte Další.
  • V dialogovém okně Konfigurovat nový projekt pojmenujte projekt TodoApi a vyberte Další.
  • V dialogovém okně Další informace :
    • Ověřte, že je rozhraní .NET 7.0 (nebo novější).
    • Ověřte, že je zaškrtnuté políčko Použít kontrolery (zrušení zaškrtnutí pro použití minimálních rozhraní API).
    • Vyberte Vytvořit.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Testování projektu

Šablona projektu vytvoří WeatherForecast rozhraní API s podporou Swaggeru.

Stisknutím kombinace kláves Ctrl+F5 spusťte bez ladicího programu.

Visual Studio zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný tak, aby používal PROTOKOL SSL:

Tento projekt je nakonfigurovaný tak, aby používal PROTOKOL SSL. Abyste se vyhnuli upozorněním SSL v prohlížeči, můžete se rozhodnout důvěřovat certifikátu podepsanému svým držitelem, který služba IIS Express vygenerovala. Chcete důvěřovat certifikátu SSL služby IIS Express?

Pokud důvěřujete certifikátu SSL služby IIS Express, vyberte Ano .

Zobrazí se následující dialogové okno:

Dialogové okno upozornění zabezpečení

Pokud souhlasíte s tím, že se má důvěřovat vývojovému certifikátu, vyberte Ano.

Informace o důvěřování prohlížeči Firefox naleznete v článku o chybě certifikátu aplikace Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio spustí výchozí prohlížeč a přejde na https://localhost:<port>/swagger/index.html, kde <port> je náhodně zvolené číslo portu.

Zobrazí se stránka /swagger/index.html Swagger. Vyberte GET>Try it out>Execute. Zobrazí se stránka:

  • Příkaz Curl k otestování rozhraní API WeatherForecast.
  • Adresa URL pro otestování rozhraní API WeatherForecast.
  • Kód odpovědi, text a hlavičky.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem

Pokud se stránka Swagger nezobrazí, podívejte se na tento problém na GitHubu.

Swagger se používá ke generování užitečné dokumentace a stránek nápovědy pro webová rozhraní API. Tento kurz se zaměřuje na vytvoření webového rozhraní API. Další informace o Swaggeru najdete v dokumentaci k webovému rozhraní API pro ASP.NET Core pomocí Swaggeru / OpenAPI.

Zkopírujte a vložte adresu URL požadavku v prohlížeči: https://localhost:<port>/weatherforecast

JSVrátí se funkce ON podobná následujícímu příkladu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.
  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoItem a vyberte Přidat.
  • Nahraďte kód šablony následujícím kódem:
namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelu můžou přejít kdekoli v projektu, ale Models složka se používá podle konvence.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet a zadejte Microsoft.EntityFrameworkCore.InMemory do vyhledávacího pole.
  • Vyberte Microsoft.EntityFrameworkCore.InMemory v levém podokně.
  • V pravém podokně zaškrtněte políčko Projekt a pak vyberte Nainstalovat.

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoContext a klepněte na tlačítko Přidat.

  • Zadejte následující kód:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models;

public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options)
        : base(options)
    {
    }

    public DbSet<TodoItem> TodoItems { get; set; } = null!;
}

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službě kontrolery.

Aktualizujte Program.cs následujícím zvýrazněným kódem:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Předchozí kód:

  • Přidá using direktivy.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování uživatelského rozhraní kontroleru

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí entity Framework a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Ve třídě Model vyberte TodoItem (TodoApi.Models).
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

    Pokud operace generování uživatelského rozhraní selže, vyberte Přidat a pokuste se znovu vygenerovat generování.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními, které jsou součástí [action] šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony trasy.

[action] Pokud token není v šabloně trasy, název akce (název metody) není součástí koncového bodu. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Aktualizace metody vytvoření PostTodoItem

Aktualizujte návratový příkaz v operátoru PostTodoItemnameof :

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("PostTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(PostTodoItem), new { id = todoItem.Id }, todoItem);
}

Předchozí kód je HTTP POST metoda, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu TodoItem z textu požadavku HTTP.

Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

Metoda CreatedAtAction:

  • V případě úspěchu vrátí stavový kód HTTP 201. HTTP 201 je standardní odpověď metody HTTP POST , která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolu. Další informace naleznete v tématu 10.2.2 201 Vytvořeno.
  • Odkazuje na PostTodoItem akci pro vytvoření identifikátoru Location URI hlavičky. Klíčové slovo jazyka C# nameof slouží k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Test PostTodoItem

  • Stisknutím kombinace kláves Ctrl+F5 spusťte aplikaci.

  • V okně prohlížeče Swagger vyberte POST /api/TodoItems a pak vyberte Vyzkoušet.

  • V okně vstupu textu požadavku aktualizujte zapnutoJS. Příklad:

    {
  "name": "walk dog",
  "isComplete": true
}

  • Vyberte Execute (Provést).

    Swagger POST

Otestování identifikátoru URI hlavičky umístění

V předchozím POST se v uživatelském rozhraní Swaggeru zobrazí hlavička umístění pod hlavičkami Odpovědi. Například location: https://localhost:7260/api/TodoItems/1. V hlavičce umístění se zobrazí identifikátor URI vytvořeného prostředku.

Otestování hlavičky umístění:

  • V okně prohlížeče Swagger vyberte GET /api/TodoItems/{id} a pak vyberte Vyzkoušet.

  • Zadejte 1 do vstupního id pole a pak vyberte Spustit.

    Swagger GET

Prozkoumání metod GET

Implementují se dva koncové body GET:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Předchozí část ukázala příklad /api/todoitems/{id} trasy.

Podle pokynů POST přidejte další položku úkolu a pak trasu otestujte pomocí Swaggeru/api/todoitems.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty URL

Atribut [HttpGet] označuje metodu, která reaguje na HTTP GET požadavek. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase

  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET základní směrování nerozlišuje velká a malá písmena.

  • [HttpGet] Pokud má atribut šablonu trasy (například[HttpGet("products")]), připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání je hodnota "{id}" v adrese URL poskytována metodě v jeho id parametru.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je ActionResult<T> typ. ASP.NET Core automaticky serializuje objekt na JSON a zapíše JSho do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy mohou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavuNotFound 404.
  • V opačném případě vrátí metoda hodnotu 200 s tělem JSodpovědi ON. Vrácení item výsledků v HTTP 200 odpovědi

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem je podobný PostTodoItem, s výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek vyžaduje, PUT aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte HTTP PATCH.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Před voláním metody PUT zavolejte get a ujistěte se, že je v databázi položka.

Pomocí uživatelského rozhraní Swagger pomocí tlačítka PUT aktualizujte TodoItem ID = 1 a nastavte jeho název na "feed fish". Všimněte si, že odpověď je HTTP 204 No Content.

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Testování metody DeleteTodoItem

Pomocí uživatelského rozhraní Swagger odstraňte TodoItem ID = 1. Všimněte si, že odpověď je HTTP 204 No Content.

Testování pomocí http-repl, Postmanu nebo curl

Http-repl, Postman a curl se často používají k otestování rozhraní API. Swagger používá curl a zobrazí příkaz, který curl odeslal.

Pokyny k těmto nástrojům najdete na následujících odkazech:

Další informace najdete http-replv tématu Testování webových rozhraní API pomocí HttpRepl.

Prevence nadměrného účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožina modelu. Za tímto důvodem je několik důvodů a zabezpečení je hlavní. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto kurzu.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Vynecháte některé vlastnosti, aby se snížila velikost datové části.
  • Zploštěné grafy objektů, které obsahují vnořené objekty Grafy plochých objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala pole tajného kódu:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Pole tajného kódu musí být v této aplikaci skryté, ale aplikace pro správu by se mohla rozhodnout, že ho zveřejní.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Aktualizujte, TodoItemsController aby bylo možné použít TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Ověřte, že nemůžete publikovat nebo získat pole tajného kódu.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

Série videí webového rozhraní API

Podívejte se na video: Série začátečníků: Webová rozhraní API.

Spolehlivé vzory webových aplikací

Pokyny k vytvoření moderní, spolehlivé, výkonné, testovatelné, nákladově efektivní a škálovatelné aplikace ASP.NET Core, ať už od nuly nebo refaktoringu stávající aplikace, najdete v článku o modelu Reliable Web App Pattern for.NETYouTube.

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identity přidává do webových aplikací ASP.NET Core funkce přihlášení uživatelského rozhraní. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

Duende Identity Server je rozhraní OpenID Připojení a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční využití serveru Duende Identity Server. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Identity Serveru (web Duende Software).

Publikování do Azure

Informace o nasazení do Azure najdete v tématu Rychlý start: Nasazení webové aplikace ASP.NET.

Další materiály

Zobrazit nebo stáhnout ukázkový kód pro tento kurz Podívejte se, jak si stáhnout.

Další informace naleznete v následujících zdrojích:

V tomto kurzu se naučíte základy vytváření webového rozhraní API založeného na kontroleru, které používá databázi. Dalším přístupem k vytváření rozhraní API v ASP.NET Core je vytvoření minimálních rozhraní API. Nápovědu k výběru mezi minimálními rozhraními API a rozhraními API založenými na kontroleru najdete v přehledu rozhraní API. Kurz vytvoření minimálního rozhraní API najdete v kurzu : Vytvoření minimálního rozhraní API s ASP.NET Core.

V tomto kurzu se naučíte:

  • Vytvořte projekt webového rozhraní API.
  • Přidejte třídu modelu a kontext databáze.
  • Generování řídicího prvku pomocí metod CRUD
  • Nakonfigurujte směrování, cesty URL a návratové hodnoty.
  • Volání webového rozhraní API pomocí http-repl

Na konci máte webové rozhraní API, které může spravovat položky úkolů uložené v databázi.

Přehled

Tento kurz vytvoří následující rozhraní API:

API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Nic Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Nic Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Nic
DELETE /api/todoitems/{id}     Odstranění položky Nic Nic

Následující diagram znázorňuje návrh aplikace.

Klient je reprezentován polem vlevo. Odešle žádost a obdrží odpověď z aplikace, pole nakreslené vpravo. V poli aplikace představují tři pole kontroler, model a vrstvu přístupu k datům. Požadavek přichází do kontroleru aplikace a mezi kontrolerem a vrstvou přístupu k datům dochází k operacím čtení a zápisu. Model je serializován a vrácen klientovi v odpovědi.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>projekt.
  • Do vyhledávacího pole zadejte webové rozhraní API .
  • Vyberte šablonu ASP.NET Základní webové rozhraní API a vyberte Další.
  • V dialogovém okně Konfigurovat nový projekt pojmenujte projekt TodoApi a vyberte Další.
  • V dialogovém okně Další informace :
    • Ověřte, že rozhraní je .NET 6.0 (dlouhodobá podpora).
    • Ověřte, že je zaškrtnuté políčko Použít kontrolery (zrušení zaškrtnutí pro použití minimálních rozhraní API).
    • Vyberte Vytvořit.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Testování projektu

Šablona projektu vytvoří WeatherForecast rozhraní API s podporou Swaggeru.

Stisknutím kombinace kláves Ctrl+F5 spusťte bez ladicího programu.

Visual Studio zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný tak, aby používal PROTOKOL SSL:

Tento projekt je nakonfigurovaný tak, aby používal PROTOKOL SSL. Abyste se vyhnuli upozorněním SSL v prohlížeči, můžete se rozhodnout důvěřovat certifikátu podepsanému svým držitelem, který služba IIS Express vygenerovala. Chcete důvěřovat certifikátu SSL služby IIS Express?

Pokud důvěřujete certifikátu SSL služby IIS Express, vyberte Ano .

Zobrazí se následující dialogové okno:

Dialogové okno upozornění zabezpečení

Pokud souhlasíte s tím, že se má důvěřovat vývojovému certifikátu, vyberte Ano.

Informace o důvěřování prohlížeči Firefox naleznete v článku o chybě certifikátu aplikace Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio spustí výchozí prohlížeč a přejde na https://localhost:<port>/swagger/index.html, kde <port> je náhodně zvolené číslo portu.

Zobrazí se stránka /swagger/index.html Swagger. Vyberte GET>Try it out>Execute. Zobrazí se stránka:

  • Příkaz Curl k otestování rozhraní API WeatherForecast.
  • Adresa URL pro otestování rozhraní API WeatherForecast.
  • Kód odpovědi, text a hlavičky.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem

Pokud se stránka Swagger nezobrazí, podívejte se na tento problém na GitHubu.

Swagger se používá ke generování užitečné dokumentace a stránek nápovědy pro webová rozhraní API. Tento kurz se zaměřuje na vytvoření webového rozhraní API. Další informace o Swaggeru najdete v dokumentaci k webovému rozhraní API pro ASP.NET Core pomocí Swaggeru / OpenAPI.

Zkopírujte a vložte adresu URL požadavku v prohlížeči: https://localhost:<port>/weatherforecast

JSVrátí se funkce ON podobná následujícímu příkladu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Aktualizace adresy launchUrl

In Properties\launch Nastavení.json, update launchUrl from "swagger" to "api/todoitems":

"launchUrl": "api/todoitems",

Vzhledem k tomu, že se Swagger odebere, předchozí kód změní adresu URL, která je spuštěna na metodu GET kontroleru přidaného v následujících částech.

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoItem a vyberte Přidat.

  • Nahraďte kód šablony následujícím kódem:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelu můžou přejít kdekoli v projektu, ale Models složka se používá podle konvence.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet a zadejte Microsoft.EntityFrameworkCore.InMemory do vyhledávacího pole.
  • Vyberte Microsoft.EntityFrameworkCore.InMemory v levém podokně.
  • V pravém podokně zaškrtněte políčko Projekt a pak vyberte Nainstalovat.

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoContext a klepněte na tlačítko Přidat.

  • Zadejte následující kód:

    using Microsoft.EntityFrameworkCore;
using System.Diagnostics.CodeAnalysis;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; } = null!;
    }
}

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službě kontrolery.

Aktualizujte Program.cs následujícím kódem:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;


var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
//builder.Services.AddSwaggerGen(c =>
//{
//    c.SwaggerDoc("v1", new() { Title = "TodoApi", Version = "v1" });
//});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (builder.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    //app.UseSwagger();
    //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Předchozí kód:

  • Odebere volání Swaggeru.
  • Odebere nepoužívané using direktivy.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování uživatelského rozhraní kontroleru

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí entity Framework a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Ve třídě Model vyberte TodoItem (TodoApi.Models).
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

    Pokud operace generování uživatelského rozhraní selže, vyberte Přidat a pokuste se znovu vygenerovat generování.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními, které jsou součástí [action] šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony trasy.

[action] Pokud token není v šabloně trasy, název akce je z trasy vyloučený. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Aktualizace metody vytvoření PostTodoItem

Aktualizujte návratový příkaz v operátoru PostTodoItemnameof :

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("PostTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(PostTodoItem), new { id = todoItem.Id }, todoItem);
}

Předchozí kód je metoda HTTP POST, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu položky úkolu z textu požadavku HTTP.

Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

Metoda CreatedAtAction:

  • V případě úspěchu vrátí stavový kód HTTP 201. HTTP 201 je standardní odpověď pro metodu HTTP POST, která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolu. Další informace naleznete v tématu 10.2.2 201 Vytvořeno.
  • Odkazuje na GetTodoItem akci pro vytvoření identifikátoru Location URI hlavičky. Klíčové slovo jazyka C# nameof slouží k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Instalace http-repl

V tomto kurzu se k otestování webového rozhraní API používá http-repl .

  • Na příkazovém řádku spusťte následující příkaz:

    dotnet tool install -g Microsoft.dotnet-httprepl

    Poznámka:

    Ve výchozím nastavení architektura binárních souborů .NET, které se mají nainstalovat, představuje aktuálně spuštěnou architekturu operačního systému. Pokud chcete zadat jinou architekturu operačního systému, přečtěte si téma instalace nástroje dotnet, možnost --arch. Další informace najdete v tématu o problému GitHubu dotnet/AspNetCore.Docs #29262.

  • Pokud nemáte nainstalovanou sadu .NET 6.0 SDK nebo modul runtime, nainstalujte modul runtime .NET 6.0.

Test PostTodoItem

  • Stisknutím kombinace kláves Ctrl+F5 spusťte aplikaci.

  • Otevřete nové okno terminálu a spusťte následující příkazy. Pokud vaše aplikace používá jiné číslo portu, nahraďte 5001 v příkazu httprepl číslem portu.

    httprepl https://localhost:5001/api/todoitems
post -h Content-Type=application/json -c "{"name":"walk dog","isComplete":true}"

    Tady je příklad výstupu tohoto příkazu:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:39:47 GMT
Location: https://localhost:5001/api/TodoItems/1
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "name": "walk dog",
  "isComplete": true
}

Otestování identifikátoru URI hlavičky umístění

Pokud chcete otestovat záhlaví umístění, zkopírujte ho a vložte do příkazu httprepl get .

Následující příklad předpokládá, že jste stále v relaci httprepl. Pokud jste ukončili předchozí relaci httprepl, nahraďte connect ji následujícími httprepl příkazy:

connect https://localhost:5001/api/todoitems/1
get

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:48:10 GMT
Server: Kestrel
Transfer-Encoding: chunked

{
  "id": 1,
  "name": "walk dog",
  "isComplete": true
}

Prozkoumání metod GET

Implementují se dva koncové body GET:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Právě jste viděli příklad /api/todoitems/{id} trasy. Otestujte trasu /api/todoitems :

connect https://localhost:5001/api/todoitems
get

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:59:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

Vrácená funkce JSON je tentokrát polem jedné položky.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty URL

Atribut [HttpGet] označuje metodu, která reaguje na požadavek HTTP GET. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase

  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET základní směrování nerozlišuje velká a malá písmena.

  • [HttpGet] Pokud má atribut šablonu trasy (například[HttpGet("products")]), připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání je hodnota "{id}" v adrese URL poskytována metodě v jeho id parametru.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je ActionResult<T> typ. ASP.NET Core automaticky serializuje objekt na JSON a zapíše JSho do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy mohou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavuNotFound 404.
  • V opačném případě vrátí metoda hodnotu 200 s tělem JSodpovědi ON. item Vrácení výsledků v odpovědi HTTP 200

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem je podobný , PostTodoItems výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte HTTP PATCH.

Pokud se v následující části zobrazí chyba PutTodoItem , zavolejte, GET abyste měli jistotu, že je v databázi nějaká položka.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Před voláním metody PUT zavolejte get a ujistěte se, že je v databázi položka.

Aktualizujte položku úkolu s ID = 1 a nastavte její název na "feed fish":

connect https://localhost:5001/api/todoitems/1
put -h Content-Type=application/json -c "{"id":1,"name":"feed fish","isComplete":true}"

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:20:47 GMT
Server: Kestrel

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Testování metody DeleteTodoItem

Odstraňte položku úkolu, která má ID = 1:

connect https://localhost:5001/api/todoitems/1
delete

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:43:00 GMT
Server: Kestrel

Prevence nadměrného účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožina modelu. Za tímto důvodem je několik důvodů a zabezpečení je hlavní. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto kurzu.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Vynecháte některé vlastnosti, aby se snížila velikost datové části.
  • Zploštěné grafy objektů, které obsahují vnořené objekty Grafy plochých objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala pole tajného kódu:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
        public string? Secret { get; set; }
    }
}

Pole tajného kódu musí být v této aplikaci skryté, ale aplikace pro správu by se mohla rozhodnout, že ho zveřejní.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

namespace TodoApi.Models
{
    public class TodoItemDTO
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Aktualizujte, TodoItemsController aby bylo možné použít TodoItemDTO:

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;

        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }

        // GET: api/TodoItems
        [HttpGet]
        public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
        {
            return await _context.TodoItems
                .Select(x => ItemToDTO(x))
                .ToListAsync();
        }

        // GET: api/TodoItems/5
        [HttpGet("{id}")]
        public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            return ItemToDTO(todoItem);
        }
        // PUT: api/TodoItems/5
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPut("{id}")]
        public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
        {
            if (id != todoItemDTO.Id)
            {
                return BadRequest();
            }

            var todoItem = await _context.TodoItems.FindAsync(id);
            if (todoItem == null)
            {
                return NotFound();
            }

            todoItem.Name = todoItemDTO.Name;
            todoItem.IsComplete = todoItemDTO.IsComplete;

            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
            {
                return NotFound();
            }

            return NoContent();
        }
        // POST: api/TodoItems
        // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
        [HttpPost]
        public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
        {
            var todoItem = new TodoItem
            {
                IsComplete = todoItemDTO.IsComplete,
                Name = todoItemDTO.Name
            };

            _context.TodoItems.Add(todoItem);
            await _context.SaveChangesAsync();

            return CreatedAtAction(
                nameof(GetTodoItem),
                new { id = todoItem.Id },
                ItemToDTO(todoItem));
        }

        // DELETE: api/TodoItems/5
        [HttpDelete("{id}")]
        public async Task<IActionResult> DeleteTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);

            if (todoItem == null)
            {
                return NotFound();
            }

            _context.TodoItems.Remove(todoItem);
            await _context.SaveChangesAsync();

            return NoContent();
        }

        private bool TodoItemExists(long id)
        {
            return _context.TodoItems.Any(e => e.Id == id);
        }

        private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
            new TodoItemDTO
            {
                Id = todoItem.Id,
                Name = todoItem.Name,
                IsComplete = todoItem.IsComplete
            };
    }
}

Ověřte, že nemůžete publikovat nebo získat pole tajného kódu.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

Série videí webového rozhraní API

Podívejte se na video: Série začátečníků: Webová rozhraní API.

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identity přidává do webových aplikací ASP.NET Core funkce přihlášení uživatelského rozhraní. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

Duende Identity Server je rozhraní OpenID Připojení a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční využití serveru Duende Identity Server. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Identity Serveru (web Duende Software).

Publikování do Azure

Informace o nasazení do Azure najdete v tématu Rychlý start: Nasazení webové aplikace ASP.NET.

Další materiály

Zobrazit nebo stáhnout ukázkový kód pro tento kurz Podívejte se, jak si stáhnout.

Další informace naleznete v následujících zdrojích:

V tomto kurzu se naučíte základy vytváření webového rozhraní API založeného na kontroleru, které používá databázi. Dalším přístupem k vytváření rozhraní API v ASP.NET Core je vytvoření minimálních rozhraní API. Nápovědu k výběru mezi minimálními rozhraními API a rozhraními API založenými na kontroleru najdete v přehledu rozhraní API. Kurz vytvoření minimálního rozhraní API najdete v kurzu : Vytvoření minimálního rozhraní API s ASP.NET Core.

V tomto kurzu se naučíte:

  • Vytvořte projekt webového rozhraní API.
  • Přidejte třídu modelu a kontext databáze.
  • Generování řídicího prvku pomocí metod CRUD
  • Nakonfigurujte směrování, cesty URL a návratové hodnoty.
  • Volání webového rozhraní API pomocí nástroje Postman

Na konci máte webové rozhraní API, které může spravovat položky úkolů uložené v databázi.

Přehled

Tento kurz vytvoří následující rozhraní API:

API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Nic Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Nic Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Nic
DELETE /api/todoitems/{id}     Odstranění položky Nic Nic

Následující diagram znázorňuje návrh aplikace.

Klient je reprezentován polem vlevo. Odešle žádost a obdrží odpověď z aplikace, pole nakreslené vpravo. V poli aplikace představují tři pole kontroler, model a vrstvu přístupu k datům. Požadavek přichází do kontroleru aplikace a mezi kontrolerem a vrstvou přístupu k datům dochází k operacím čtení a zápisu. Model je serializován a vrácen klientovi v odpovědi.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>projekt.
  • Vyberte šablonu webového rozhraní API ASP.NET Core a klikněte na tlačítko Další.
  • Pojmenujte projekt TodoApi a klikněte na Vytvořit.
  • V dialogovém okně Vytvořit novou webovou aplikaci ASP.NET Core potvrďte, že jsou vybrané .NET Core a ASP.NET Core 5.0 . Vyberte šablonu rozhraní API a klikněte na Vytvořit.

Dialogové okno Nový projekt VS

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Testování projektu

Šablona projektu vytvoří WeatherForecast rozhraní API s podporou Swaggeru.

Stisknutím kombinace kláves Ctrl+F5 spusťte bez ladicího programu.

Visual Studio zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný tak, aby používal PROTOKOL SSL:

Tento projekt je nakonfigurovaný tak, aby používal PROTOKOL SSL. Abyste se vyhnuli upozorněním SSL v prohlížeči, můžete se rozhodnout důvěřovat certifikátu podepsanému svým držitelem, který služba IIS Express vygenerovala. Chcete důvěřovat certifikátu SSL služby IIS Express?

Pokud důvěřujete certifikátu SSL služby IIS Express, vyberte Ano .

Zobrazí se následující dialogové okno:

Dialogové okno upozornění zabezpečení

Pokud souhlasíte s tím, že se má důvěřovat vývojovému certifikátu, vyberte Ano.

Informace o důvěřování prohlížeči Firefox naleznete v článku o chybě certifikátu aplikace Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Spustí se Visual Studio:

  • Webový server SLUŽBY IIS Express.
  • Výchozí prohlížeč a přejde na https://localhost:<port>/swagger/index.html, kde <port> je náhodně zvolené číslo portu.

Zobrazí se stránka /swagger/index.html Swagger. Vyberte GET>Try it out>Execute. Zobrazí se stránka:

  • Příkaz Curl k otestování rozhraní API WeatherForecast.
  • Adresa URL pro otestování rozhraní API WeatherForecast.
  • Kód odpovědi, text a hlavičky.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem

Pokud se stránka Swagger nezobrazí, podívejte se na tento problém na GitHubu.

Swagger se používá ke generování užitečné dokumentace a stránek nápovědy pro webová rozhraní API. Tento kurz se zaměřuje na vytvoření webového rozhraní API. Další informace o Swaggeru najdete v dokumentaci k webovému rozhraní API pro ASP.NET Core pomocí Swaggeru / OpenAPI.

Zkopírujte a vložte adresu URL požadavku v prohlížeči: https://localhost:<port>/weatherforecast

JSVrátí se funkce ON podobná následujícímu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Aktualizace adresy launchUrl

In Properties\launch Nastavení.json, update launchUrl from "swagger" to "api/todoitems":

"launchUrl": "api/todoitems",

Vzhledem k tomu, že se Swagger odebere, předchozí kód změní adresu URL, která je spuštěna na metodu GET kontroleru přidaného v následujících částech.

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoItem a vyberte Přidat.

  • Nahraďte kód šablony následujícím kódem:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelu můžou přejít kdekoli v projektu, ale Models složka se používá podle konvence.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet a zadejte Microsoft.EntityFrameworkCore.InMemory do vyhledávacího pole.
  • Vyberte Microsoft.EntityFrameworkCore.InMemory v levém podokně.
  • V pravém podokně zaškrtněte políčko Projekt a pak vyberte Nainstalovat.

Správce balíčků NuGet

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoContext a klepněte na tlačítko Přidat.

  • Zadejte následující kód:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službě kontrolery.

Aktualizujte Startup.cs následujícím kódem:

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddDbContext<TodoContext>(opt =>
                                               opt.UseInMemoryDatabase("TodoList"));
            //services.AddSwaggerGen(c =>
            //{
            //    c.SwaggerDoc("v1", new OpenApiInfo { Title = "TodoApi", Version = "v1" });
            //});
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                //app.UseSwagger();
                //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
            }

            app.UseHttpsRedirection();
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Předchozí kód:

  • Odebere volání Swaggeru.
  • Odebere nepoužívané using deklarace.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování uživatelského rozhraní kontroleru

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí entity Framework a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Ve třídě Model vyberte TodoItem (TodoApi.Models).
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními, které jsou součástí [action] šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony trasy.

[action] Pokud token není v šabloně trasy, název akce je z trasy vyloučený. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Aktualizace metody vytvoření PostTodoItem

Aktualizujte návratový příkaz v operátoru PostTodoItemnameof :

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("PostTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(PostTodoItem), new { id = todoItem.Id }, todoItem);
}

Předchozí kód je metoda HTTP POST, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu položky úkolu z textu požadavku HTTP.

Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

Metoda CreatedAtAction:

  • V případě úspěchu vrátí stavový kód HTTP 201. HTTP 201 je standardní odpověď pro metodu HTTP POST, která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolu. Další informace naleznete v tématu 201 Vytvoření.
  • Odkazuje na GetTodoItem akci pro vytvoření identifikátoru Location URI hlavičky. Klíčové slovo jazyka C# nameof slouží k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Instalace nástroje Postman

Tento kurz používá Nástroj Postman k otestování webového rozhraní API.

  • Instalace nástroje Postman
  • Spusťte webovou aplikaci.
  • Spusťte Postman.
  • Zakažte ověření certifikátu SSL:
    • Postman pro Windows: Vyberte soubor> Nastavení (karta Obecné), zakažte ověření certifikátu SSL.
    • Postman pro macOS: Vyberte Postman> Nastavení (karta Obecné), zakažte ověření certifikátu SSL.

      Upozorňující

      Po otestování kontroleru znovu povolte ověření certifikátu SSL.

Testování PostTodoItem pomocí Nástroje Postman

  • Vytvořte novou žádost.

  • Nastavte metodu HTTP na POST.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems. Například https://localhost:5001/api/todoitems.

  • Vyberte kartu Text.

  • Vyberte nezpracovaný přepínač.

  • Nastavte typ na JSON (application/json).

  • V textu požadavku zadejte JSON pro položku úkolu:

    {
  "name":"walk dog",
  "isComplete":true
}

  • Vyberte Odeslat.

    Postman s žádostí o vytvoření

Otestování identifikátoru URI hlavičky umístění

Identifikátor URI hlavičky umístění je možné otestovat v prohlížeči. Zkopírujte a vložte identifikátor URI záhlaví umístění do prohlížeče.

Testování v Nástroji Postman:

  • V podokně Odpovědi vyberte kartu Záhlaví.

  • Zkopírujte hodnotu záhlaví Umístění:

    Karta Záhlaví konzoly Postman

  • Nastavte metodu HTTP na GET.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems/1. Například https://localhost:5001/api/todoitems/1.

  • Vyberte Odeslat.

Prozkoumání metod GET

Implementují se dva koncové body GET:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Otestujte aplikaci voláním dvou koncových bodů z prohlížeče nebo nástroje Postman. Příklad:

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

Voláním se vytvoří GetTodoItemspodobná následující odpověď:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Test Get with Postman

  • Vytvořte novou žádost.
  • Nastavte metodu HTTP na GET.
  • Nastavte identifikátor URI požadavku na https://localhost:<port>/api/todoitemshodnotu . Například https://localhost:5001/api/todoitems.
  • Nastavte v nástroji Postman zobrazení se dvěma podokny.
  • Vyberte Odeslat.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty URL

Atribut [HttpGet] označuje metodu, která reaguje na požadavek HTTP GET. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET základní směrování nerozlišuje velká a malá písmena.

  • [HttpGet] Pokud má atribut šablonu trasy (například[HttpGet("products")]), připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání je hodnota "{id}" v adrese URL poskytována metodě v jeho id parametru.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je ActionResult<T> typ. ASP.NET Core automaticky serializuje objekt na JSON a zapíše JSho do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy mohou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavuNotFound 404.
  • V opačném případě vrátí metoda hodnotu 200 s tělem JSodpovědi ON. item Vrácení výsledků v odpovědi HTTP 200

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem je podobný , PostTodoItems výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte HTTP PATCH.

Pokud se zobrazí chybová volání PutTodoItem, zavolejte GET , abyste měli jistotu, že je v databázi nějaká položka.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Před voláním metody PUT zavolejte get a ujistěte se, že je v databázi položka.

Aktualizujte položku úkolu s ID = 1 a nastavte její název na "feed fish":

  {
    "Id":1,
    "name":"feed fish",
    "isComplete":true
  }

Následující obrázek ukazuje aktualizaci Postman:

Konzola Postman zobrazující odpověď 204 (Bez obsahu)

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Testování metody DeleteTodoItem

Použití nástroje Postman k odstranění položky úkolu:

  • Nastavte metodu na DELETE.
  • Nastavte identifikátor URI objektu k odstranění (například https://localhost:5001/api/todoitems/1).
  • Vyberte Odeslat.

Prevence nadměrného účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožina modelu. Z tohoto důvodu existuje několik důvodů a zabezpečení je hlavním důvodem. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto článku.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Vynecháte některé vlastnosti, aby se snížila velikost datové části.
  • Zploštěné grafy objektů, které obsahují vnořené objekty Grafy plochých objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala pole tajného kódu:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
        public string Secret { get; set; }
    }
}

Pole tajného kódu musí být v této aplikaci skryté, ale aplikace pro správu by se mohla rozhodnout, že ho zveřejní.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Aktualizujte, TodoItemsController aby bylo možné použít TodoItemDTO:

// GET: api/TodoItems
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
{
    return await _context.TodoItems
        .Select(x => ItemToDTO(x))
        .ToListAsync();
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

[HttpPut("{id}")]
public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
{
    if (id != todoItemDTO.Id)
    {
        return BadRequest();
    }

    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    todoItem.Name = todoItemDTO.Name;
    todoItem.IsComplete = todoItemDTO.IsComplete;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
    {
        return NotFound();
    }

    return NoContent();
}

[HttpPost]
public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
{
    var todoItem = new TodoItem
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    return CreatedAtAction(
        nameof(GetTodoItem),
        new { id = todoItem.Id },
        ItemToDTO(todoItem));
}

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

private bool TodoItemExists(long id) =>
     _context.TodoItems.Any(e => e.Id == id);

private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
    new TodoItemDTO
    {
        Id = todoItem.Id,
        Name = todoItem.Name,
        IsComplete = todoItem.IsComplete
    };

Ověřte, že nemůžete publikovat nebo získat pole tajného kódu.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identity přidává do webových aplikací ASP.NET Core funkce přihlášení uživatelského rozhraní. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

Duende Identity Server je rozhraní OpenID Připojení a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční využití serveru Duende Identity Server. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Identity Serveru (web Duende Software).

Publikování do Azure

Informace o nasazení do Azure najdete v tématu Rychlý start: Nasazení webové aplikace ASP.NET.

Další materiály

Zobrazit nebo stáhnout ukázkový kód pro tento kurz Podívejte se, jak si stáhnout.

Další informace naleznete v následujících zdrojích:

V tomto kurzu se naučíte základy vytváření webového rozhraní API založeného na kontroleru, které používá databázi. Dalším přístupem k vytváření rozhraní API v ASP.NET Core je vytvoření minimálních rozhraní API. Nápovědu k výběru mezi minimálními rozhraními API a rozhraními API založenými na kontroleru najdete v přehledu rozhraní API. Kurz vytvoření minimálního rozhraní API najdete v kurzu : Vytvoření minimálního rozhraní API s ASP.NET Core.

V tomto kurzu se naučíte:

  • Vytvořte projekt webového rozhraní API.
  • Přidejte třídu modelu a kontext databáze.
  • Generování řídicího prvku pomocí metod CRUD
  • Nakonfigurujte směrování, cesty URL a návratové hodnoty.
  • Volání webového rozhraní API pomocí nástroje Postman

Na konci máte webové rozhraní API, které může spravovat položky úkolů uložené v databázi.

Přehled

Tento kurz vytvoří následující rozhraní API:

API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Nic Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Nic Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Nic
DELETE /api/todoitems/{id}     Odstranění položky Nic Nic

Následující diagram znázorňuje návrh aplikace.

Klient je reprezentován polem vlevo. Odešle žádost a obdrží odpověď z aplikace, pole nakreslené vpravo. V poli aplikace představují tři pole kontroler, model a vrstvu přístupu k datům. Požadavek přichází do kontroleru aplikace a mezi kontrolerem a vrstvou přístupu k datům dochází k operacím čtení a zápisu. Model je serializován a vrácen klientovi v odpovědi.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>projekt.
  • Vyberte šablonu ASP.NET Základní webová aplikace a klikněte na Tlačítko Další.
  • Pojmenujte projekt TodoApi a klikněte na Vytvořit.
  • V dialogovém okně Vytvořit novou webovou aplikaci ASP.NET Core potvrďte, že jsou vybrané .NET Core a ASP.NET Core 3.1 . Vyberte šablonu rozhraní API a klikněte na Vytvořit.

Dialogové okno Nový projekt VS

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Testování rozhraní API

Šablona projektu vytvoří WeatherForecast rozhraní API. Zavolejte metodu Get z prohlížeče a otestujte aplikaci.

Stisknutím kombinace kláves Ctrl+F5 spusťte aplikaci. Visual Studio spustí prohlížeč a přejde na https://localhost:<port>/weatherforecast, kde <port> je náhodně zvolené číslo portu.

Pokud se zobrazí dialogové okno s dotazem, jestli byste měli důvěřovat certifikátu SLUŽBY IIS Express, vyberte Ano. V dialogovém okně Upozornění zabezpečení, které se zobrazí dále, vyberte Ano.

JSVrátí se funkce ON podobná následujícímu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoItem a vyberte Přidat.

  • Nahraďte kód šablony následujícím kódem:

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelu můžou přejít kdekoli v projektu, ale Models složka se používá podle konvence.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet a do vyhledávacího pole zadejte Microsoft.EntityFrameworkCore.InMemory.
  • V levém podokně vyberte Microsoft.EntityFrameworkCore.InMemory .
  • V pravém podokně zaškrtněte políčko Projekt a pak vyberte Nainstalovat.

Správce balíčků NuGet

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem na Models složku a vyberte Přidat>třídu. Pojmenujte třídu TodoContext a klepněte na tlačítko Přidat.

  • Zadejte následující kód:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službě kontrolery.

Aktualizujte Startup.cs následujícím zvýrazněným kódem:

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
               opt.UseInMemoryDatabase("TodoList"));
            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Předchozí kód:

  • Odebere nepoužívané using deklarace.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování uživatelského rozhraní kontroleru

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí entity Framework a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Ve třídě Model vyberte TodoItem (TodoApi.Models).
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními, které jsou součástí [action] šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony trasy.

[action] Pokud token není v šabloně trasy, název akce je z trasy vyloučený. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Prozkoumání metody vytvoření PostTodoItem

Nahraďte příkaz return v operátoru PostTodoItemnameof :

// POST: api/TodoItems
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //return CreatedAtAction("PostTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(PostTodoItem), new { id = todoItem.Id }, todoItem);
}

Předchozí kód je metoda HTTP POST, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu položky úkolu z textu požadavku HTTP.

Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

Metoda CreatedAtAction:

  • V případě úspěchu vrátí stavový kód HTTP 201. HTTP 201 je standardní odpověď pro metodu HTTP POST, která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolu. Další informace naleznete v tématu 201 Vytvoření.
  • Odkazuje na GetTodoItem akci pro vytvoření identifikátoru Location URI hlavičky. Klíčové slovo jazyka C# nameof slouží k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Instalace nástroje Postman

Tento kurz používá Nástroj Postman k otestování webového rozhraní API.

  • Instalace nástroje Postman
  • Spusťte webovou aplikaci.
  • Spusťte Postman.
  • Zakažte ověření certifikátu SSL:
    • Postman pro Windows: Postman for Windows File> Nastavení (karta Obecné), zakažte ověření certifikátu SSL.
    • Postman pro macOS: Postman pro Windows Postman> Nastavení (karta Obecné), zakažte ověření certifikátu SSL.

      Upozorňující

      Po otestování kontroleru znovu povolte ověření certifikátu SSL.

Testování PostTodoItem pomocí Nástroje Postman

  • Vytvořte novou žádost.

  • Nastavte metodu HTTP na POST.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems. Například https://localhost:5001/api/todoitems.

  • Vyberte kartu Text.

  • Vyberte nezpracovaný přepínač.

  • Nastavte typ na JSON (application/json).

  • V textu požadavku zadejte JSON pro položku úkolu:

    {
  "name":"walk dog",
  "isComplete":true
}

  • Vyberte Odeslat.

    Postman s žádostí o vytvoření

Otestování identifikátoru URI hlavičky umístění pomocí nástroje Postman

  • V podokně Odpovědi vyberte kartu Záhlaví.

  • Zkopírujte hodnotu záhlaví Umístění:

    Karta Záhlaví konzoly Postman

  • Nastavte metodu HTTP na GET.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems/1. Například https://localhost:5001/api/todoitems/1.

  • Vyberte Odeslat.

Prozkoumání metod GET

Tyto metody implementují dva koncové body GET:

  • GET /api/todoitems
  • GET /api/todoitems/{id}

Otestujte aplikaci voláním dvou koncových bodů z prohlížeče nebo nástroje Postman. Příklad:

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

Voláním se vytvoří GetTodoItemspodobná následující odpověď:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Test Get with Postman

  • Vytvořte novou žádost.
  • Nastavte metodu HTTP na GET.
  • Nastavte identifikátor URI požadavku na https://localhost:<port>/api/todoitemshodnotu . Například https://localhost:5001/api/todoitems.
  • Nastavte v nástroji Postman zobrazení se dvěma podokny.
  • Vyberte Odeslat.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty URL

Atribut [HttpGet] označuje metodu, která reaguje na požadavek HTTP GET. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET základní směrování nerozlišuje velká a malá písmena.

  • [HttpGet] Pokud má atribut šablonu trasy (například[HttpGet("products")]), připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace naleznete v tématu Směrování atributů s atributy Http[Slovesa].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání je hodnota "{id}" v adrese URL poskytována metodě v jeho id parametru.

// GET: api/TodoItems/5
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        return NotFound();
    }

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je ActionResult<T> typ. ASP.NET Core automaticky serializuje objekt na JSON a zapíše JSho do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy mohou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby 404 NotFound .
  • V opačném případě vrátí metoda hodnotu 200 s tělem JSodpovědi ON. item Vrácení výsledků v odpovědi HTTP 200

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

// PUT: api/TodoItems/5
[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem je podobný , PostTodoItems výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte HTTP PATCH.

Pokud se zobrazí chybová volání PutTodoItem, zavolejte GET , abyste měli jistotu, že je v databázi nějaká položka.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Před voláním metody PUT zavolejte get a ujistěte se, že je v databázi položka.

Aktualizujte položku úkolu, která má ID = 1, a nastavte její název na "krmení ryb":

  {
    "id":1,
    "name":"feed fish",
    "isComplete":true
  }

Následující obrázek ukazuje aktualizaci Postman:

Konzola Postman zobrazující odpověď 204 (Bez obsahu)

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

// DELETE: api/TodoItems/5
[HttpDelete("{id}")]
public async Task<ActionResult<TodoItem>> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return todoItem;
}

Testování metody DeleteTodoItem

Použití nástroje Postman k odstranění položky úkolu:

  • Nastavte metodu na DELETE.
  • Nastavte identifikátor URI objektu k odstranění (například https://localhost:5001/api/todoitems/1).
  • Vyberte Odeslat.

Prevence nadměrného účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožina modelu. Z tohoto důvodu existuje několik důvodů a zabezpečení je hlavním důvodem. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto článku.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Vynecháte některé vlastnosti, aby se snížila velikost datové části.
  • Zploštěné grafy objektů, které obsahují vnořené objekty Grafy plochých objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala pole tajného kódu:

public class TodoItem
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
    public string Secret { get; set; }
}

Pole tajného kódu musí být v této aplikaci skryté, ale aplikace pro správu by se mohla rozhodnout, že ho zveřejní.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

public class TodoItemDTO
{
    public long Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

Aktualizujte, TodoItemsController aby bylo možné použít TodoItemDTO:

    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        return ItemToDTO(todoItem);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateTodoItem(long id, TodoItemDTO todoItemDTO)
    {
        if (id != todoItemDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoItemDTO.Name;
        todoItem.IsComplete = todoItemDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }

    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoItemDTO.IsComplete,
            Name = todoItemDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id) =>
         _context.TodoItems.Any(e => e.Id == id);

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
        new TodoItemDTO
        {
            Id = todoItem.Id,
            Name = todoItem.Name,
            IsComplete = todoItem.IsComplete
        };       
}

Ověřte, že nemůžete publikovat nebo získat pole tajného kódu.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identity přidává do webových aplikací ASP.NET Core funkce přihlášení uživatelského rozhraní. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

Duende Identity Server je rozhraní OpenID Připojení a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční využití serveru Duende Identity Server. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Identity Serveru (web Duende Software).

Publikování do Azure

Informace o nasazení do Azure najdete v tématu Rychlý start: Nasazení webové aplikace ASP.NET.

Další materiály

Zobrazit nebo stáhnout ukázkový kód pro tento kurz Podívejte se, jak si stáhnout.

Další informace naleznete v následujících zdrojích: