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

Od Rick Anderson a Kirka Larkin

V tomto kurzu se naučíte základy vytváření webového rozhraní API pomocí 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í uživatelského rozhraní pro kontroler pomocí metod CRUD
  • Nakonfigurujte směrování, cesty URL a návratové hodnoty.
  • Zavolejte webové rozhraní API pomocí post.

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

Přehled

V tomto kurzu se vytvoří následující rozhraní API:

Rozhraní API Popis Text požadavku Text odpovědi
GET /api/todoitems Získat všechny položky úkolů Žádné Pole položek úkolů
GET /api/todoitems/{id} Získat položku podle ID Žádné Položka úkolů
POST /api/todoitems Přidat novou položku Položka úkolů Položka úkolů
PUT /api/todoitems/{id} Aktualizovat existující položku   Položka úkolů Žádné
DELETE /api/todoitems/{id}     Odstranění položky     Žádné Žádné

V následujícím diagramu vidíte návrh aplikace.

Klient je reprezentován polem vlevo. Odešle požadavek a přijme odpověď z aplikace, pole nakreslené na pravé straně. V poli aplikace tři čtverečky reprezentují kontroler, model a vrstvu přístupu k datům. Požadavek přichází do kontroleru aplikace a operace čtení/zápisu probíhají mezi kontrolérem a vrstvou přístupu k datům. Model je serializován a vrácen klientovi v odpovědi.

Požadavky

Vytvoření webového projektu

  • v nabídce soubor vyberte nový > Project.
  • Do vyhledávacího pole zadejte webové rozhraní API .
  • vyberte šablonu ASP.NET Core webového rozhraní API a vyberte další.
  • V dialogovém okně Konfigurovat nový projekt pojmenujte projekt TodoApi a vyberte Další.
  • V dialogovém okně Další informace potvrďte, že je rozhraní .NET 6,0 (Preview), a vyberte vytvořit.

Testování projektu

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

Stisknutím kombinace kláves CTRL + F5 spustíte bez ladicího programu.

Visual Studio se zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný na použití SSL:

Tento projekt je nakonfigurovaný tak, aby se používá protokol SSL. Pokud se chcete vyhnout upozorněním PROTOKOLU SSL v prohlížeči, můžete důvěřovat certifikátu podepsanému svým držitelem, IIS Express vygeneroval. Chcete důvěřovat certifikátu SSL IIS Express zabezpečení?

Vyberte Ano, pokud důvěřujete certifikátu IIS EXPRESS SSL.

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

Dialogové okno Upozornění zabezpečení

Pokud souhlasíte s důvěryhodností vývojového certifikátu, vyberte Ano.

Informace o důvěřování prohlížeči Firefox naleznete v tématu firefox SEC_ERROR_INADEQUATE_KEY_USAGE Chyba certifikátu.

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

Zobrazí se stránka Swagger /swagger/index.html . Vyberte Get > Try on > Execute. Stránka zobrazuje:

  • Příkaz složeného pro otestování rozhraní WeatherForecast API.
  • Adresa URL pro otestování rozhraní WeatherForecast API
  • Kód odpovědi, tělo a záhlaví.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem.

pokud se stránka swagger nezobrazuje, přečtěte si tento GitHub problém.

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

Zkopírujte a vložte adresu URL žádosti v prohlížeči: https://localhost:<port>/WeatherForecast

Vrátí se JSON 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 launchUrl

V Properties\launchSettings.JSON proveďte aktualizaci launchUrl z "swagger" na "api/todoitems" :

"launchUrl": "api/todoitems",

Protože Swagger bude odebrán, předchozí kód změní adresu URL, která se spustí do metody GET kontroleru přidané v následujících oddílech.

Přidat třídu modelu

Model je sada tříd, které reprezentují data, která aplikace spravuje. Model této aplikace je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem na projekt. Vyberte Add > New Folder (Přidat novou složku). Složku pojmnováte Models .

  • Klikněte pravým tlačítkem Models na složku a vyberte Přidat > třídu. Pojmnostete třídu TodoItem a vyberete Add (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.

Modelové třídy mohou jít kamkoli do projektu, ale Models složka se podle konvence používá.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje Entity Framework funkcí datového modelu. 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 NuGet balíčky pro řešení.
  • Vyberte kartu Procházet a do vyhledávacího Microsoft.EntityFrameworkCore.InMemory pole zadejte .
  • V Microsoft.EntityFrameworkCore.InMemory levém podokně vyberte .
  • V pravém Project zaškrtněte políčko Pro instalaci a pak vyberte Nainstalovat.

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem Models na složku a vyberte Přidat > třídu. Pojmete třídu TodoContext a klikněte na 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 například kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službu kontrolerům.

Aktualizujte soubor 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 na složku Kontrolery.

  • Vyberte Add > New Scaffolded Item (Přidat novou vy scaffolded item).

  • 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 rozhraní:

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

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

Vygenerovaný kód:

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

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními [action] zahrnují do šablony trasy.
  • Kontrolery rozhraní API se do [action] šablony trasy nezahrnují.

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

Aktualizace metody vytvoření PostTodoItem

Aktualizujte příkaz return v souboru PostTodoItem tak, aby se používá operátor nameof:

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

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

Předchozí kód je metoda HTTP POST, jak je označeno [HttpPost] atributem . Metoda získá hodnotu položky seznamu položek z textu požadavku HTTP.

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

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 Location. Hlavička Location určuje identifikátor URI nově vytvořené položky položek položek seznamu. Další informace najdete v tématu 10.2.2 201 Created.
  • Odkazuje na GetTodoItem akci pro vytvoření Location identifikátoru URI hlavičky. Klíčové slovo jazyka C# slouží k tomu, aby se zabránilo pevnému nameof kódování názvu akce ve CreatedAtAction 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
    
  • Pokud nemáte nainstalovanou sadu .NET 5.0 SDK nebo modul runtime, nainstalujte modul runtime .NET 5.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 vašeho 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 hlavičku umístění, zkopírujte ji a vložte do příkazu get httprepl.

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 v httprepl následujících příkazech za :

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

Implementovali jsme dva koncové body GET:

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

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

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

Tentokrát je vrácený json 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 žádná data nevrátila, postaplikovat data 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 Route kontroleru:

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    
  • Nahraďte názvem kontroleru, což je podle konvence název třídy kontroleru minus přípona [controller] Controller. Pro tuto ukázku je název třídy kontroleru TodoItems Controller, takže název kontroleru je TodoItems. ASP.NET Core směrování se nelišují malá a velká písmena.

  • Pokud [HttpGet] má atribut šablonu trasy (například [HttpGet("products")] ), připojte ji k cestě. V této ukázce se šablona nepodporuje. Další informace najdete v tématu Směrování atributů s atributy Http[Verb].

V následující GetTodoItem metodě "{id}" je proměnná zástupného symbolu pro jedinečný identifikátor položky seznamu. Při vyvolání se do metody v parametru zadá hodnota v GetTodoItem "{id}" adrese id URL.

[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ý typ metod a GetTodoItems GetTodoItem je ActionResult <T> typu. ASP.NET Core objekt automaticky serializuje do formátu JSON a zapíše JSON do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OKza předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají na chyby 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 stavový kód 404. NotFound
  • Jinak metoda vrátí 200 s textem odpovědi JSON. Vrácením item výsledků vrátíte odpověď 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 se podobá PostTodoItem metodě s tím rozdílem, že používá HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient poslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte http patch.

Pokud se zobrazí chyba s PutTodoItem voláním v následující části, zavolejte a ujistěte se, že databáze GET obsahuje položku.

Otestování metody PutTodoItem

Tato ukázka používá databázi v paměti, kterou je nutné inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Volejte GET, abyste před voláním PUT zajistili, že v databázi existuje položka.

Aktualizujte položku seznamu 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();
}

Otestování metody DeleteTodoItem

Odstraňte položku seznamu s 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 přeúčtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní a vrácená data pomocí podmnožiny modelu. To má 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í. V tomto kurzu se používá DTO.

DTO lze použít k:

  • Zabraňte přeúčtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Pokud chcete zmenšit velikost datové části, některé vlastnosti vypište.
  • Zploštěte grafy objektů, které obsahují vnořené objekty. Zploštěné grafy objektů mohou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby zahrnovala 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 klíče musí být před touto aplikací skryté, ale aplikace pro správu by ho mohla zveřejnit.

Ověřte, že můžete odeslat příspěvek a získat pole tajného klíče.

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 se používá 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 odeslat nebo získat pole tajného klíče.

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

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

V tomto kurzu se naučíte:

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

Na konci máte webové rozhraní API, které může spravovat položky "položek seznamu" uložených v databázi.

Přehled

V tomto kurzu se vytvoří následující rozhraní API:

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

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

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

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový > Project.
  • Vyberte šablonu webového ASP.NET Core API a klikněte na Další.
  • Projekt pojmechte TodoApi a klikněte na Create (Vytvořit).
  • V dialogovém okně Create a new ASP.NET Core Web Application (Vytvořit novou webovou aplikaci) zkontrolujte, ž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

Testování projektu

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

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

Visual Studio se zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný na použití SSL:

Tento projekt je nakonfigurovaný tak, aby se používá protokol SSL. Pokud se chcete vyhnout upozorněním PROTOKOLU SSL v prohlížeči, můžete důvěřovat certifikátu podepsanému svým držitelem, IIS Express vygeneroval. Chcete důvěřovat certifikátu SSL IIS Express zabezpečení?

Vyberte Ano, pokud důvěřujete certifikátu IIS EXPRESS SSL.

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

Dialogové okno Upozornění zabezpečení

Pokud souhlasíte s důvěryhodností vývojového certifikátu, vyberte Ano.

Informace o důvěřování prohlížeči Firefox naleznete v tématu firefox SEC_ERROR_INADEQUATE_KEY_USAGE Chyba certifikátu.

Visual Studio spuštění:

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

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

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

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

Swagger slouží 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 tématu ASP.NET Core webového rozhraní API pomocí Swaggeru / OpenAPI .

Zkopírujte adresu URL požadavku a vložte ji do prohlížeče: https://localhost:<port>/WeatherForecast

Vrátí se kód JSON 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 launchUrl

V souboru Properties\launchSettings.json launchUrl aktualizujte z na "swagger" "api/todoitems" :

"launchUrl": "api/todoitems",

Vzhledem k tomu, že Swagger se odebere, předchozí kód změní adresu URL, která se spustí, 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 této aplikace je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem na projekt. Vyberte Add > New Folder (Přidat novou složku). Složku pojmnováte Models .

  • Klikněte pravým tlačítkem Models na složku a vyberte Přidat > třídu. Pojmnostete třídu TodoItem a vyberete Add (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.

Modelové třídy mohou jít kamkoli do projektu, ale Models složka se podle konvence používá.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje Entity Framework funkcí datového modelu. 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 NuGet balíčky pro řešení.
  • Vyberte kartu Procházet a do vyhledávacího Microsoft.EntityFrameworkCore.InMemory pole zadejte .
  • V Microsoft.EntityFrameworkCore.InMemory levém podokně vyberte .
  • V pravém Project zaškrtněte políčko Pro instalaci a pak vyberte Nainstalovat.

Správce balíčků NuGet

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem Models na složku a vyberte Přidat > třídu. Pojmete třídu TodoContext a klikněte na 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žbu kontrolerům.

Aktualizujte soubor 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 using nepoužívané 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 na složku Kontrolery.

  • Vyberte Add > New Scaffolded Item (Přidat novou vy scaffolded item).

  • 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 Entity Framework:

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

Vygenerovaný kód:

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

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními [action] zahrnují do šablony trasy.
  • Kontrolery rozhraní API se do [action] šablony trasy nezahrnují.

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

Aktualizace metody vytvoření PostTodoItem

Aktualizujte příkaz return v souboru PostTodoItem tak, aby se používá operátor nameof:

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

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

Předchozí kód je metoda HTTP POST, jak je označeno [HttpPost] atributem . Metoda získá hodnotu položky seznamu položek z textu požadavku HTTP.

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

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 Location. Hlavička Location určuje identifikátor URI nově vytvořené položky položek položek seznamu. Další informace najdete v tématu 10.2.2 201 Created.
  • Odkazuje na GetTodoItem akci pro vytvoření Location identifikátoru URI hlavičky. Klíčové slovo jazyka C# slouží k tomu, aby se zabránilo pevnému nameof kódování názvu akce ve CreatedAtAction volání.

Instalace nástroje Postman

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

  • Instalace nástroje Postman
  • Spusťte webovou aplikaci.
  • Spusťte Postman.
  • Zákaz ověřování certifikátů SSL
    • V okně > Nastavení (karta Obecné) zakažte ověření certifikátu SSL.

      Upozornění

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

Testování PostTodoItem pomocí Postmana

  • 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 přepínač raw.

  • Nastavte typ na JSON (application/json).

  • Do textu požadavku zadejte JSON pro položku seznamu:

    {
      "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é testovat v prohlížeči. Zkopírujte identifikátor URI hlavičky umístění a vložte ho do prohlížeče.

Testování v aplikaci Postman:

  • V podokně Odpověď vyberte kartu Hlavičky.

  • Zkopírujte hodnotu hlavičky Location (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

Implementovali jsme dva koncové body GET:

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

Otestujte aplikaci voláním obou koncových bodů z prohlížeče nebo z postmanu. Například:

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

Voláním metody se vyprodukuje odpověď podobná GetTodoItems následující:

[
  {
    "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/todoitems . Například, https://localhost:5001/api/todoitems.
  • V postmanu nastavte 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 žádná data nevrátila, postaplikovat data 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 Route kontroleru:

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • Nahraďte názvem kontroleru, což je podle konvence název třídy kontroleru minus přípona [controller] Controller. Pro tuto ukázku je název třídy kontroleru TodoItems Controller, takže název kontroleru je TodoItems. ASP.NET Core směrování se malá a velká písmena nerozlišovat.

  • Pokud [HttpGet] má atribut šablonu trasy (například [HttpGet("products")] ), připojte ji k cestě. V této ukázce se šablona nepodporuje. Další informace najdete v tématu Směrování atributů s atributy Http[Verb].

V následující GetTodoItem metodě "{id}" je proměnná zástupného symbolu pro jedinečný identifikátor položky seznamu. Při vyvolání se do metody v parametru zadá hodnota v GetTodoItem "{id}" adrese id URL.

// 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ý typ metod a GetTodoItems GetTodoItem je ActionResult <T> typu. ASP.NET Core objekt automaticky serializuje do formátu JSON a zapíše JSON do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OKza předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají na chyby 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 stavový kód 404. NotFound
  • Jinak metoda vrátí 200 s textem odpovědi JSON. Vrácením item výsledků vrátíte odpověď 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 se podobá PostTodoItem metodě s tím rozdílem, že používá HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient poslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte http patch.

Pokud se zobrazí chyba s voláním , zavolejte a ujistěte se, PutTodoItem GET že databáze obsahuje položku.

Otestování metody PutTodoItem

Tato ukázka používá databázi v paměti, kterou je nutné inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Volejte GET, abyste před voláním PUT zajistili, že v databázi existuje položka.

Aktualizujte položku seznamu 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();
}

Otestování metody DeleteTodoItem

Odstranění položky položek:

  • Nastavte metodu na DELETE .
  • Nastavte identifikátor URI objektu, který chcete odstranit (například https://localhost:5001/api/todoitems/1 ).
  • Vyberte Odeslat.

Prevence přeúčtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní a vrácená data pomocí podmnožiny modelu. To má 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 článku.

DTO lze použít k:

  • Zabraňte přeúčtování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Pokud chcete zmenšit velikost datové části, některé vlastnosti vypište.
  • Zploštěte grafy objektů, které obsahují vnořené objekty. Zploštěné grafy objektů mohou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby zahrnovala 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 klíče musí být před touto aplikací skryté, ale aplikace pro správu by ho mohla zveřejnit.

Ověřte, že můžete odeslat příspěvek a získat pole tajného klíče.

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 se používá 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 odeslat nebo získat pole tajného klíče.

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

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

V tomto kurzu se naučíte:

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

Na konci máte webové rozhraní API, které může spravovat položky "položek seznamu" uložených v databázi.

Přehled

V tomto kurzu se vytvoří následující rozhraní API:

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

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

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

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový > Project.
  • Vyberte šablonu ASP.NET Core webovou aplikaci a klikněte na Další.
  • Projekt pojmechte TodoApi a klikněte na Create (Vytvořit).
  • V dialogovém okně Create a new ASP.NET Core Web Application (Vytvořit novou webovou aplikaci) zkontrolujte, ž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

Testování rozhraní API

Šablona projektu vytvoří rozhraní WeatherForecast API. Pokud chcete Get aplikaci otestovat, zavolejte z prohlížeče metodu .

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 IIS Express, vyberte Ano. V dialogovém okně Security Warning (Upozornění zabezpečení), které se zobrazí, vyberte Yes (Ano).

Vrátí se kód JSON 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 této aplikace je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem na projekt. Vyberte Add > New Folder (Přidat novou složku). Složku pojmnováte Models .

  • Klikněte pravým tlačítkem Models na složku a vyberte Přidat > třídu. Pojmnostete třídu TodoItem a vyberete Add (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.

Modelové třídy mohou jít kamkoli do projektu, ale Models složka se podle konvence používá.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje Entity Framework funkcí datového modelu. 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 NuGet balíčky 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 Project zaškrtněte políčko Pro instalaci a pak vyberte Nainstalovat.

Správce balíčků NuGet

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem Models na složku a vyberte Přidat > třídu. Pojmete třídu TodoContext a klikněte na 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 například kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službu kontrolerům.

Aktualizujte soubor 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 using nepoužívané 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 na složku Kontrolery.

  • Vyberte Add > New Scaffolded Item (Přidat novou vy scaffolded item).

  • 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 rozhraní:

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

Vygenerovaný kód:

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

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními [action] zahrnují do šablony trasy.
  • Kontrolery rozhraní API se do [action] šablony trasy nezahrnují.

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

Prozkoumání metody vytvoření PostTodoItem

Nahraďte příkaz return v , PostTodoItem aby se použije operátor nameof:

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

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

Předchozí kód je metoda HTTP POST, jak je označeno [HttpPost] atributem . Metoda získá hodnotu položky seznamu položek z textu požadavku HTTP.

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

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 Location. Hlavička Location určuje identifikátor URI nově vytvořené položky položek položek seznamu. Další informace najdete v tématu 10.2.2 201 Created.
  • Odkazuje na GetTodoItem akci pro vytvoření Location identifikátoru URI hlavičky. Klíčové slovo jazyka C# slouží k tomu, aby se zabránilo pevnému nameof kódování názvu akce ve CreatedAtAction volání.

Instalace nástroje Postman

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

  • Instalace nástroje Postman
  • Spusťte webovou aplikaci.
  • Spusťte Postman.
  • Zákaz ověřování certifikátů SSL
    • V okně > Nastavení (karta Obecné) zakažte ověření certifikátu SSL.

      Upozornění

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

Testování PostTodoItem pomocí Postmana

  • 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 přepínač raw.

  • Nastavte typ na JSON (application/json).

  • Do textu požadavku zadejte JSON pro položku seznamu:

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • Vyberte Odeslat.

    Postman s žádostí o vytvoření

Testování identifikátoru URI hlavičky umístění pomocí postman

  • V podokně Odpověď vyberte kartu Hlavičky.

  • Zkopírujte hodnotu hlavičky Location (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 obou koncových bodů z prohlížeče nebo z postmanu. Například:

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

Voláním metody se vyprodukuje odpověď podobná GetTodoItems následující:

[
  {
    "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/todoitems . Například, https://localhost:5001/api/todoitems.
  • V postmanu nastavte 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 žádná data nevrátila, postaplikovat data 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 Route kontroleru:

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • Nahraďte názvem kontroleru, což je podle konvence název třídy kontroleru minus přípona [controller] Controller. Pro tuto ukázku je název třídy kontroleru TodoItems Controller, takže název kontroleru je TodoItems. ASP.NET Core směrování se nelišují malá a velká písmena.

  • Pokud [HttpGet] má atribut šablonu trasy (například [HttpGet("products")] ), připojte ji k cestě. V této ukázce se šablona nepodporuje. Další informace najdete v tématu Směrování atributů s atributy Http[Verb].

V následující GetTodoItem metodě "{id}" je proměnná zástupného symbolu pro jedinečný identifikátor položky seznamu. Při vyvolání se do metody v parametru zadá hodnota v GetTodoItem "{id}" adrese id URL.

// 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ý typ metod a GetTodoItems GetTodoItem je ActionResult <T> typu. ASP.NET Core objekt automaticky serializuje do formátu JSON a zapíše JSON 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í na chyby 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 NotFound chyby 404.
  • Jinak metoda vrátí 200 s textem odpovědi JSON. Vrácením item výsledků vrátíte odpověď 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 se podobá PostTodoItem metodě s tím rozdílem, že používá HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient poslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte http patch.

Pokud se zobrazí chyba s voláním , zavolejte a ujistěte se, PutTodoItem GET že databáze obsahuje položku.

Otestování metody PutTodoItem

Tato ukázka používá databázi v paměti, kterou je nutné inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Voláním metody GET zajistěte, aby byla položka v databázi před provedením volání PUT.

Aktualizujte položku úkolů s ID = 1 a nastavte její název na "rybí ryby":

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

Na následujícím obrázku je znázorněná aktualizace po odeslání:

Konzola pro publikování zobrazující 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;
}

Test metody DeleteTodoItem

Odstranění položky úkolů pomocí metody post:

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

Zabránit navýšení příspěvků

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují zadaná data a vracejí je pomocí podmnožiny modelu. Je to několik důvodů na pozadí a zabezpečení je hlavní. Podmnožina modelu je obvykle označována jako objekt Přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto článku.

DTO se dá použít k těmto akcím:

  • Zabránit přeúčtování.
  • Skrytí vlastností, které klienti nemají zobrazovat.
  • Vynechejte některé vlastnosti, aby se snížila velikost datové části.
  • Ploché grafy objektů, které obsahují vnořené objekty. Ploché grafy objektů můžou být pro klienty pohodlnější.

Chcete-li předvést DTO přístup, aktualizujte TodoItem třídu tak, aby obsahovala tajné pole:

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 klíče musí být z této aplikace skryté, ale aplikace pro správu může tuto možnost vystavit.

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

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 se použil 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í ASP.NET Core webového rozhraní API pomocí javascriptu.

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

ASP.NET Core Identitypřidá funkci přihlášení uživatelského rozhraní (UI) k ASP.NET Core web apps. K zabezpečení webových rozhraní API a jednostránkové použijte jednu z následujících možností:

IdentityServer4 je OpenID Připojení a OAuth 2,0 framework pro ASP.NET Core. IdentityServer4 umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování/vypínání (SSO) nad více typy aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Další informace najdete v tématu Vítá vás Identity Server4.

Další zdroje informací

Zobrazit nebo stáhnout vzorový kód pro tento kurz. Viz Jak stáhnout.

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