チュートリアル: ASP.NET Core で Web API を作成するTutorial: Create a web API with ASP.NET Core

作成者: Rick AndersonMike WassonBy Rick Anderson and Mike Wasson

このチュートリアルでは、ASP.NET Core で Web API をビルドする方法の基本について説明します。This tutorial teaches the basics of building a web API with ASP.NET Core.

このチュートリアルでは、次の作業を行う方法について説明します。In this tutorial, you learn how to:

  • Web API プロジェクトを作成する。Create a web API project.
  • モデル クラスとデータベース コンテキストを追加する。Add a model class and a database context.
  • CRUD メソッドを使用してコントローラーのスキャフォールディング。Scaffold a controller with CRUD methods.
  • ルーティング、URL パス、戻り値を構成する。Configure routing, URL paths, and return values.
  • Postman で Web API を呼び出す。Call the web API with Postman.

最後に、データベースに格納されている "To Do" アイテムを管理できる Web API が作成されます。At the end, you have a web API that can manage "to-do" items stored in a database.

概要Overview

このチュートリアルでは、次の API を作成します。This tutorial creates the following API:

APIAPI 説明Description 要求本文Request body 応答本文Response body
GET /api/TodoItemsGET /api/TodoItems すべての To Do アイテムを取得します。Get all to-do items なしNone To Do アイテムの配列Array of to-do items
GET /api/TodoItems/{id}GET /api/TodoItems/{id} ID でアイテムを取得します。Get an item by ID なしNone To Do アイテムTo-do item
POST /api/TodoItemsPOST /api/TodoItems 新しいアイテムを追加します。Add a new item To Do アイテムTo-do item To Do アイテムTo-do item
PUT /api/TodoItems/{id}PUT /api/TodoItems/{id} 既存のアイテムを更新します。 Update an existing item   To Do アイテムTo-do item なしNone
DELETE /api/TodoItems/{id}    DELETE /api/TodoItems/{id}     アイテムを削除します    Delete an item     なしNone なしNone

次の図は、アプリのデザインを示しています。The following diagram shows the design of the app.

クライアントは、左側のボックスに表されます。

必須コンポーネントPrerequisites

Web プロジェクトの作成Create a web project

  • [ファイル] メニューで [新規作成] > [プロジェクト] の順に選択します。From the File menu, select New > Project.
  • [ASP.NET Core Web アプリケーション] テンプレートを選択して、 [次へ] をクリックします。Select the ASP.NET Core Web Application template and click Next.
  • プロジェクトに「TodoApi」という名前を付け、 [作成] をクリックします。Name the project TodoApi and click Create.
  • [新しい ASP.NET Core Web アプリケーションを作成する] ダイアログで、 [.NET Core][ASP.NET Core 3.0] が選択されていることを確認します。In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 3.0 are selected. API テンプレートを選択し、 [作成] をクリックします。Select the API template and click Create.

VS の [新しいプロジェクト] ダイアログ

API のテストTest the API

プロジェクト テンプレートによって WeatherForecast API が作成されます。The project template creates a WeatherForecast API. ブラウザーから Get メソッドを呼び出して、アプリをテストします。Call the Get method from a browser to test the app.

Ctrl キーを押しながら F5 キーを押して、アプリを実行します。Press Ctrl+F5 to run the app. Visual Studio でブラウザーが起動し、https://localhost:<port>/WeatherForecast にアクセスします。ここで、<port> はランダムに選択されたポート番号になります。Visual Studio launches a browser and navigates to https://localhost:<port>/WeatherForecast, where <port> is a randomly chosen port number.

IIS Express 証明書を信頼するかどうかを確認するダイアログ ボックスが表示された場合は、 [はい] を選択します。If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. 次に表示される [セキュリティ警告] ダイアログ ボックスで、 [はい] を選択します。In the Security Warning dialog that appears next, select Yes.

次のような JSON が返されます。JSON similar to the following is returned:

[
    {
        "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"
    }
]

モデル クラスの追加Add a model class

モデルは、アプリが管理するデータを表すクラスのセットです。A model is a set of classes that represent the data that the app manages. このアプリのモデルは、単一の TodoItem クラスです。The model for this app is a single TodoItem class.

  • ソリューション エクスプローラーで、プロジェクトを右クリックします。In Solution Explorer, right-click the project. [追加] > [新しいフォルダー] の順に選択します。Select Add > New Folder. フォルダーに「Models」という名前を付けます。Name the folder Models.

  • Models フォルダーを右クリックし、 [追加] > [クラス] の順にクリックします。Right-click the Models folder and select Add > Class. クラスに「TodoItem」という名前を付け、 [追加] を選択します。Name the class TodoItem and select Add.

  • テンプレート コードを次のコードに置き換えます。Replace the template code with the following code:

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

Id プロパティは、リレーショナル データベース内の一意のキーとして機能します。The Id property functions as the unique key in a relational database.

モデル クラスはプロジェクト内のどこでも使用できますが、慣例により Models フォルダーが使用されます。Model classes can go anywhere in the project, but the Models folder is used by convention.

データベース コンテキストの追加Add a database context

データベース コンテキストは、データ モデルに対して Entity Framework 機能を調整するメイン クラスです。The database context is the main class that coordinates Entity Framework functionality for a data model. このクラスは Microsoft.EntityFrameworkCore.DbContext クラスから派生させて作成します。This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

Microsoft.EntityFrameworkCore.SqlServer を追加するAdd Microsoft.EntityFrameworkCore.SqlServer

  • [ツール] メニューで [NuGet パッケージ マネージャー]、[ソリューションの NuGet パッケージの管理] の順に選択します。From the Tools menu, select NuGet Package Manager > Manage NuGet Packages for Solution.
  • [参照] タブを選択し、検索ボックスに「Microsoft.EntityFrameworkCore.SqlServer」と入力します。Select the Browse tab, and then enter Microsoft.EntityFrameworkCore.SqlServer in the search box.
  • 左側のウィンドウで、 [Microsoft.EntityFrameworkCore.SqlServer] を選択します。Select Microsoft.EntityFrameworkCore.SqlServer in the left pane.
  • 右側のウィンドウで [プロジェクト] チェックボックスをオンにして、 [インストール] を選択します。Select the Project check box in the right pane and then select Install.
  • 前の手順を使用して Microsoft.EntityFrameworkCore.InMemory NuGet パッケージを追加します。Use the preceding instructions to add the Microsoft.EntityFrameworkCore.InMemory NuGet package.

NuGet パッケージ マネージャー

TodoContext データベースコンテキストの追加Add the TodoContext database context

  • Models フォルダーを右クリックし、 [追加] > [クラス] の順にクリックします。Right-click the Models folder and select Add > Class. クラスに「TodoContext」という名前を付け、 [追加] をクリックします。Name the class TodoContext and click Add.
  • 次のコードを入力します。Enter the following code:

    using Microsoft.EntityFrameworkCore;
    
    namespace TodoApi.Models
    {
        public class TodoContext : DbContext
        {
            public TodoContext(DbContextOptions<TodoContext> options)
                : base(options)
            {
            }
    
            public DbSet<TodoItem> TodoItems { get; set; }
        }
    }
    

データベース コンテキストの登録Register the database context

ASP.NET Core で、サービス (DB コンテキストなど) を依存関係の挿入 (DI)コンテナーに登録する必要があります。In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. コンテナーは、コントローラーにサービスを提供します。The container provides the service to controllers.

次の強調表示されているコードを使用して、Startup.cs を更新します。Update Startup.cs with the following highlighted code:

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

上記のコードでは次の操作が行われます。The preceding code:

  • 不要な using 宣言を削除します。Removes unused using declarations.
  • DI コンテナーにデータベース コンテキストを追加します。Adds the database context to the DI container.
  • データベース コンテキストがメモリ内データベースを使用することを指定します。Specifies that the database context will use an in-memory database.

コントローラーのスキャフォールディングScaffold a controller

  • Controllers フォルダーを右クリックします。Right-click the Controllers folder.

  • [追加] > [新規スキャフォールディング アイテム] を選択します。Select Add > New Scaffolded Item.

  • [Entity Framework を使用したアクションがある API コントローラー] を選択してから、 [追加] を選択します。Select API Controller with actions, using Entity Framework, and then select Add.

  • [Entity Framework を使用したアクションがある API コントローラー] ダイアログで次を実行します。In the Add API Controller with actions, using Entity Framework dialog:

    • モデル クラス[TodoItem (TodoApi.Models)] を選択します。Select TodoItem (TodoApi.Models) in the Model class.
    • データ コンテキスト クラス[TodoContext (TodoApi.Models)] を選択します。Select TodoContext (TodoApi.Models) in the Data context class.
    • [追加] を選びます。Select Add.

生成されたコードでは次の操作が行われます。The generated code:

  • メソッドを使用せず、API コントローラー クラスを定義します。Defines an API controller class without methods.
  • クラスを [ApiController] 属性で修飾します。Decorates the class with the [ApiController] attribute. この属性は、コントローラーが Web API 要求に応答することを示します。This attribute indicates that the controller responds to web API requests. 属性によって有効化される特定の動作については、「ASP.NET Core を使って Web API を作成する」 を参照してください。For information about specific behaviors that the attribute enables, see ASP.NET Core を使って Web API を作成する.
  • DI を使用して、データベース コンテキスト (TodoContext) をコントローラーに挿入します。Uses DI to inject the database context (TodoContext) into the controller. データベース コンテキストは、コントローラーの各 CRUD メソッドで使用されます。The database context is used in each of the CRUD methods in the controller.

PostTodoItem 作成メソッドの確認Examine the PostTodoItem create method

nameof 演算子を使用するために、PostTodoItem で return ステートメントを置き換えます。Replace the return statement in the PostTodoItem to use the nameof operator:

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

上記のコードは、[HttpPost] 属性で示されるように、HTTP POST メソッドです。The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. このメソッドは、HTTP 要求の本文から To Do アイテムの値を取得します。The method gets the value of the to-do item from the body of the HTTP request.

CreatedAtAction メソッド:The CreatedAtAction method:

  • 成功すると、HTTP 201 状態コードが返されます。Returns an HTTP 201 status code if successful. HTTP 201 は、サーバーに新しいリソースを作成する HTTP POST メソッドに対する標準の応答です。HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.
  • 応答に Location ヘッダーが追加されます。Adds a Location header to the response. Location ヘッダーでは、新しく作成された To Do アイテムの URI が指定されます。The Location header specifies the URI of the newly created to-do item. 詳細については、「10.2.2 201 Created」を参照してください。For more information, see 10.2.2 201 Created.
  • GetTodoItem アクションを参照して Location ヘッダーの URI を作成します。References the GetTodoItem action to create the Location header's URI. C# の nameof キーワードを使って、CreatedAtAction 呼び出しでアクション名をハードコーディングすることを回避しています。The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

Postman のインストールInstall Postman

このチュートリアルでは、Postman を使用して Web API をテストします。This tutorial uses Postman to test the web API.

  • Postman をインストールします。Install Postman
  • Web アプリを起動します。Start the web app.
  • Postman を起動します。Start Postman.
  • [SSL 証明書の確認] を無効にします。Disable SSL certificate verification
  • [ファイル] > [設定] ( [全般] タブ) で、 [SSL 証明書の確認] を無効にします。From File > Settings (General tab), disable SSL certificate verification.

    警告

    コントローラーをテストした後、SSL 証明書の検証を再度有効にします。Re-enable SSL certificate verification after testing the controller.

Postman を使用した PostTodoItem のテストTest PostTodoItem with Postman

  • 新しい要求を作成します。Create a new request.

  • HTTP メソッドを POST に設定します。Set the HTTP method to POST.

  • [Body] タブを選択します。Select the Body tab.

  • [raw] ラジオ ボタンを選択します。Select the raw radio button.

  • 型を [JSON (application/json)] に設定します。Set the type to JSON (application/json).

  • 要求本文に、To Do アイテムの JSON を入力します。In the request body enter JSON for a to-do item:

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • [Send] を選択します。Select Send.

    Postman での Create 要求

場所ヘッダー URI のテストTest the location header URI

  • [Response] ウィンドウで、 [Headers] タブを選択します。Select the Headers tab in the Response pane.

  • [Location] ヘッダー値をコピーします。Copy the Location header value:

    Postman コンソールの [Headers] タブ

  • メソッドを GET に設定します。Set the method to GET.

  • URI を貼り付けます (たとえば、https://localhost:5001/api/TodoItems/1)。Paste the URI (for example, https://localhost:5001/api/TodoItems/1).

  • [Send] を選択します。Select Send.

GET メソッドの確認Examine the GET methods

これらのメソッドは、次の 2 つの GET エンドポイントを実装します。These methods implement two GET endpoints:

  • GET /api/TodoItems
  • GET /api/TodoItems/{id}

ブラウザーまたは Postman から 2 つのエンドポイントを呼び出すことによって、アプリをテストします。Test the app by calling the two endpoints from a browser or Postman. 次に例を示します。For example:

GetTodoItems への呼び出しによって、次のような応答が生成されます。A response similar to the following is produced by the call to GetTodoItems:

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

Postman を使用して Get をテストするTest Get with Postman

  • 新しい要求を作成します。Create a new request.
  • HTTP メソッドを GET に設定します。Set the HTTP method to GET.
  • 要求 URL を https://localhost:<port>/api/TodoItems に設定します。Set the request URL to https://localhost:<port>/api/TodoItems. たとえば、https://localhost:5001/api/TodoItems のようにします。For example, https://localhost:5001/api/TodoItems.
  • Postman で [Two pane view] を設定します。Set Two pane view in Postman.
  • [Send] を選択します。Select Send.

このアプリではメモリ内データベースが使用されます。This app uses an in-memory database. アプリが停止して開始された場合、上記の GET 要求はデータを返しません。If the app is stopped and started, the preceding GET request will not return any data. データが返されない場合は、アプリにデータを POST します。If no data is returned, POST data to the app.

ルーティングと URL パスRouting and URL paths

[HttpGet] 属性は、HTTP GET 要求に応答するメソッドを表します。The [HttpGet] attribute denotes a method that responds to an HTTP GET request. 各メソッドの URL パスは次のように構成されます。The URL path for each method is constructed as follows:

  • コントローラーの Route 属性でテンプレート文字列を使用します。Start with the template string in the controller's Route attribute:

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • [controller] をコントローラーの名前 (慣例では "Controller" サフィックスを除くコントローラー クラス名) に置き換えます。Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. このサンプルでは、コントローラー クラス名は TodoItemsController なので、コントローラー名は "TodoItems" です。For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core のルーティングでは、大文字と小文字が区別されません。ASP.NET Core routing is case insensitive.

  • [HttpGet] 属性にルート テンプレート (たとえば、[HttpGet("products")]) がある場合は、それをパスに追加します。If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. このサンプルではテンプレートを使用しません。This sample doesn't use a template. 詳細については、「Http[Verb] 属性を使用する属性ルーティング」を参照してください。For more information, see Attribute routing with Http[Verb] attributes.

次の GetTodoItem メソッドで、"{id}" は To Do アイテムの一意識別子に使用するプレースホルダーの変数です。In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. GetTodoItem が呼び出されると、その id パラメーター内のメソッドに URL の "{id}" の値が指定されます。When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in its id parameter.

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

戻り値Return values

GetTodoItems メソッドと GetTodoItem メソッドの戻り値の型は、ActionResult<T> 型ですThe return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core は自動的にオブジェクトを JSON にシリアル化して、応答メッセージの本文に JSON を書き込みます。ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. この戻り値の型の応答コードは 200 で、ハンドルされない例外がないものと想定します。The response code for this return type is 200, assuming there are no unhandled exceptions. ハンドルされない例外は 5xx エラーに変換されます。Unhandled exceptions are translated into 5xx errors.

ActionResult 戻り値の型は、幅広い範囲の HTTP 状態コードを表すことができます。ActionResult return types can represent a wide range of HTTP status codes. たとえば、GetTodoItem は、次の 2 つの異なる状態値を返す可能性があります。For example, GetTodoItem can return two different status values:

  • 要求された ID と一致するアイテムがない場合、メソッドは 404 NotFound エラー コードを返します。If no item matches the requested ID, the method returns a 404 NotFound error code.
  • それ以外の場合、メソッドは JSON 応答本文で 200 を返します。Otherwise, the method returns 200 with a JSON response body. 戻り値が item の場合、HTTP 200 応答が返されます。Returning item results in an HTTP 200 response.

PutTodoItem メソッドThe PutTodoItem method

PutTodoItem メソッドを検証します。Examine the PutTodoItem method:

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

PutTodoItemPostTodoItem と似ていますが、HTTP PUT を使用します。PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. 応答は 204 (No Content) となります。The response is 204 (No Content). HTTP 仕様に従って、PUT 要求では、変更だけでなく、更新されたエンティティ全体を送信するようクライアントに求めます。According to the HTTP specification, a PUT request requires the client to send the entire updated entity, not just the changes. 部分的な更新をサポートするには、HTTP PATCH を使用します。To support partial updates, use HTTP PATCH.

PutTodoItem 呼び出しでエラーが発生した場合、GET を呼び出してデータベース内にアイテムがあることを確認してください。If you get an error calling PutTodoItem, call GET to ensure there's an item in the database.

PutTodoItem メソッドのテストTest the PutTodoItem method

このサンプルでは、アプリを起動するたびに開始することが必要なメモリ内データベースが使われています。This sample uses an in-memory database that must be initialized each time the app is started. PUT 呼び出しを実行する前に、データベース内にアイテムが存在している必要があります。There must be an item in the database before you make a PUT call. GET を呼び出して、PUT 呼び出しを実行する前にデータベース内にアイテムが存在していることを確認します。Call GET to insure there's an item in the database before making a PUT call.

ID = 1 の To Do アイテムを更新し、その名前を "feed fish" に設定します。Update the to-do item that has ID = 1 and set its name to "feed fish":

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

次の図は、Postman の更新を示しています。The following image shows the Postman update:

204 (No Content) の応答を示す Postman コンソール

DeleteTodoItem メソッドThe DeleteTodoItem method

DeleteTodoItem メソッドを検証します。Examine the DeleteTodoItem method:

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

DeleteTodoItem の応答は 204 (No Content) となります。The DeleteTodoItem response is 204 (No Content).

DeleteTodoItem メソッドのテストTest the DeleteTodoItem method

Postman を使用して、To Do アイテムを削除します。Use Postman to delete a to-do item:

  • メソッドを DELETE に設定します。Set the method to DELETE.
  • 削除するオブジェクトの URI (たとえば、https://localhost:5001/api/TodoItems/1) を設定します。Set the URI of the object to delete (for example https://localhost:5001/api/TodoItems/1).
  • [Send] を選択します。Select Send.

JavaScript を使用した Web API の呼び出しCall the web API with JavaScript

手順については、「チュートリアル: JavaScript を使用して ASP.NET Core Web API を呼び出す」を参照してください。See Tutorial: Call an ASP.NET Core web API with JavaScript.

このチュートリアルでは、次の作業を行う方法について説明します。In this tutorial, you learn how to:

  • Web API プロジェクトを作成する。Create a web API project.
  • モデル クラスとデータベース コンテキストを追加する。Add a model class and a database context.
  • コントローラーを追加する。Add a controller.
  • CRUD メソッドを追加する。Add CRUD methods.
  • ルーティングと URL パスを構成する。Configure routing and URL paths.
  • 戻り値を指定する。Specify return values.
  • Postman で Web API を呼び出す。Call the web API with Postman.
  • JavaScript を使用した Web API の呼び出し。Call the web API with JavaScript.

最後に、リレーショナル データベースに格納されている "To Do" アイテムを管理できる Web API が作成されます。At the end, you have a web API that can manage "to-do" items stored in a relational database.

概要Overview

このチュートリアルでは、次の API を作成します。This tutorial creates the following API:

APIAPI 説明Description 要求本文Request body 応答本文Response body
GET /api/TodoItemsGET /api/TodoItems すべての To Do アイテムを取得します。Get all to-do items なしNone To Do アイテムの配列Array of to-do items
GET /api/TodoItems/{id}GET /api/TodoItems/{id} ID でアイテムを取得します。Get an item by ID なしNone To Do アイテムTo-do item
POST /api/TodoItemsPOST /api/TodoItems 新しいアイテムを追加します。Add a new item To Do アイテムTo-do item To Do アイテムTo-do item
PUT /api/TodoItems/{id}PUT /api/TodoItems/{id} 既存のアイテムを更新します。 Update an existing item   To Do アイテムTo-do item なしNone
DELETE /api/TodoItems/{id}    DELETE /api/TodoItems/{id}     アイテムを削除します    Delete an item     なしNone なしNone

次の図は、アプリのデザインを示しています。The following diagram shows the design of the app.

クライアントは、左側のボックスに表されます。

必須コンポーネントPrerequisites

警告

Visual Studio 2017 を使用している場合、Visual Studio で動作しない .NET Core SDK のバージョンについては、dotnet/sdk issue #3124 を参照してください。If you use Visual Studio 2017, see dotnet/sdk issue #3124 for information about .NET Core SDK versions that don't work with Visual Studio.

Web プロジェクトの作成Create a web project

  • [ファイル] メニューで [新規作成] > [プロジェクト] の順に選択します。From the File menu, select New > Project.
  • [ASP.NET Core Web アプリケーション] テンプレートを選択して、 [次へ] をクリックします。Select the ASP.NET Core Web Application template and click Next.
  • プロジェクトに「TodoApi」という名前を付け、 [作成] をクリックします。Name the project TodoApi and click Create.
  • [新しい ASP.NET Core Web アプリケーションを作成する] ダイアログで、 [.NET Core][ASP.NET Core 2.2] が選択されていることを確認します。In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 2.2 are selected. API テンプレートを選択し、 [作成] をクリックします。Select the API template and click Create. [Enable Docker Support](Docker サポートを有効にする)選択しないでください。Don't select Enable Docker Support.

VS の [新しいプロジェクト] ダイアログ

API のテストTest the API

プロジェクト テンプレートによって values API が作成されます。The project template creates a values API. ブラウザーから Get メソッドを呼び出して、アプリをテストします。Call the Get method from a browser to test the app.

Ctrl キーを押しながら F5 キーを押して、アプリを実行します。Press Ctrl+F5 to run the app. Visual Studio でブラウザーが起動し、https://localhost:<port>/api/values にアクセスします。ここで、<port> はランダムに選択されたポート番号になります。Visual Studio launches a browser and navigates to https://localhost:<port>/api/values, where <port> is a randomly chosen port number.

IIS Express 証明書を信頼するかどうかを確認するダイアログ ボックスが表示された場合は、 [はい] を選択します。If you get a dialog box that asks if you should trust the IIS Express certificate, select Yes. 次に表示される [セキュリティ警告] ダイアログ ボックスで、 [はい] を選択します。In the Security Warning dialog that appears next, select Yes.

次の JSON が返されます。The following JSON is returned:

["value1","value2"]

モデル クラスの追加Add a model class

モデルは、アプリが管理するデータを表すクラスのセットです。A model is a set of classes that represent the data that the app manages. このアプリのモデルは、単一の TodoItem クラスです。The model for this app is a single TodoItem class.

  • ソリューション エクスプローラーで、プロジェクトを右クリックします。In Solution Explorer, right-click the project. [追加] > [新しいフォルダー] の順に選択します。Select Add > New Folder. フォルダーに「Models」という名前を付けます。Name the folder Models.

  • Models フォルダーを右クリックし、 [追加] > [クラス] の順にクリックします。Right-click the Models folder and select Add > Class. クラスに「TodoItem」という名前を付け、 [追加] を選択します。Name the class TodoItem and select Add.

  • テンプレート コードを次のコードに置き換えます。Replace the template code with the following code:

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

Id プロパティは、リレーショナル データベース内の一意のキーとして機能します。The Id property functions as the unique key in a relational database.

モデル クラスはプロジェクト内のどこでも使用できますが、慣例により Models フォルダーが使用されます。Model classes can go anywhere in the project, but the Models folder is used by convention.

データベース コンテキストの追加Add a database context

データベース コンテキストは、データ モデルに対して Entity Framework 機能を調整するメイン クラスです。The database context is the main class that coordinates Entity Framework functionality for a data model. このクラスは Microsoft.EntityFrameworkCore.DbContext クラスから派生させて作成します。This class is created by deriving from the Microsoft.EntityFrameworkCore.DbContext class.

  • Models フォルダーを右クリックし、 [追加] > [クラス] の順にクリックします。Right-click the Models folder and select Add > Class. クラスに「TodoContext」という名前を付け、 [追加] をクリックします。Name the class TodoContext and click Add.
  • テンプレート コードを次のコードに置き換えます。Replace the template code with the following code:

    using Microsoft.EntityFrameworkCore;
    
    namespace TodoApi.Models
    {
        public class TodoContext : DbContext
        {
            public TodoContext(DbContextOptions<TodoContext> options)
                : base(options)
            {
            }
    
            public DbSet<TodoItem> TodoItems { get; set; }
        }
    }
    

データベース コンテキストの登録Register the database context

ASP.NET Core で、サービス (DB コンテキストなど) を依存関係の挿入 (DI)コンテナーに登録する必要があります。In ASP.NET Core, services such as the DB context must be registered with the dependency injection (DI) container. コンテナーは、コントローラーにサービスを提供します。The container provides the service to controllers.

次の強調表示されているコードを使用して、Startup.cs を更新します。Update Startup.cs with the following highlighted code:

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

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

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the 
        //container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
                opt.UseInMemoryDatabase("TodoList"));
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
        }

        // This method gets called by the runtime. Use this method to configure the HTTP 
        //request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for 
                // production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseMvc();
        }
    }
}

上記のコードでは次の操作が行われます。The preceding code:

  • 不要な using 宣言を削除します。Removes unused using declarations.
  • DI コンテナーにデータベース コンテキストを追加します。Adds the database context to the DI container.
  • データベース コンテキストがメモリ内データベースを使用することを指定します。Specifies that the database context will use an in-memory database.

コントローラーの追加Add a controller

  • Controllers フォルダーを右クリックします。Right-click the Controllers folder.

  • [追加] > [新しい項目] の順に選択します。Select Add > New Item.

  • [新しい項目の追加] ダイアログで、 [API コントローラー クラス] テンプレートを選択します。In the Add New Item dialog, select the API Controller Class template.

  • クラスに「TodoController」という名前を付け、 [追加] を選択します。Name the class TodoController, and select Add.

    [新しい項目の追加] ダイアログ。検索ボックスに「controller」と入力されています。Web API コントローラーが選択されています。

  • テンプレート コードを次のコードに置き換えます。Replace the template code with the following code:

    using Microsoft.AspNetCore.Mvc;
    using Microsoft.EntityFrameworkCore;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using TodoApi.Models;
    
    namespace TodoApi.Controllers
    {
        [Route("api/[controller]")]
        [ApiController]
        public class TodoController : ControllerBase
        {
            private readonly TodoContext _context;
    
            public TodoController(TodoContext context)
            {
                _context = context;
    
                if (_context.TodoItems.Count() == 0)
                {
                    // Create a new TodoItem if collection is empty,
                    // which means you can't delete all TodoItems.
                    _context.TodoItems.Add(new TodoItem { Name = "Item1" });
                    _context.SaveChanges();
                }
            }
        }
    }
    

上記のコードでは次の操作が行われます。The preceding code:

  • メソッドを使用せず、API コントローラー クラスを定義します。Defines an API controller class without methods.
  • クラスを [ApiController] 属性で修飾します。Decorates the class with the [ApiController] attribute. この属性は、コントローラーが Web API 要求に応答することを示します。This attribute indicates that the controller responds to web API requests. 属性によって有効化される特定の動作については、「ASP.NET Core を使って Web API を作成する」 を参照してください。For information about specific behaviors that the attribute enables, see ASP.NET Core を使って Web API を作成する.
  • DI を使用して、データベース コンテキスト (TodoContext) をコントローラーに挿入します。Uses DI to inject the database context (TodoContext) into the controller. データベース コンテキストは、コントローラーの各 CRUD メソッドで使用されます。The database context is used in each of the CRUD methods in the controller.
  • 追加データベースが空の場合、Item1 という名前のアイテムをデータベースにします。Adds an item named Item1 to the database if the database is empty. このコードはコンストラクター内にあるので、新しい HTTP 要求が行われるたびに実行されます。This code is in the constructor, so it runs every time there's a new HTTP request. すべてのアイテムを削除した場合、コンストラクターは、次回に API メソッドが呼び出されたときに Item1 をもう一度作成します。If you delete all items, the constructor creates Item1 again the next time an API method is called. そのため、削除が実際には機能していても、機能しなかったように見える場合があります。So it may look like the deletion didn't work when it actually did work.

Get メソッドの追加Add Get methods

To Do アイテムを取得する API を指定するには、TodoController クラスに次のメソッドを追加します。To provide an API that retrieves to-do items, add the following methods to the TodoController class:

// GET: api/Todo
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItem>>> GetTodoItems()
{
    return await _context.TodoItems.ToListAsync();
}

// GET: api/Todo/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;
}

これらのメソッドは、次の 2 つの GET エンドポイントを実装します。These methods implement two GET endpoints:

  • GET /api/todo
  • GET /api/todo/{id}

アプリがまだ実行中の場合は、停止します。Stop the app if it's still running. 次に、それを再度実行して、最新の変更を含めます。Then run it again to include the latest changes.

ブラウザーからこれらの 2 つのエンドポイントを呼び出すことによって、アプリをテストします。Test the app by calling the two endpoints from a browser. 次に例を示します。For example:

  • https://localhost:<port>/api/todo
  • https://localhost:<port>/api/todo/1

GetTodoItems への呼び出しによって、次の HTTP 応答が生成されます。The following HTTP response is produced by the call to GetTodoItems:

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

ルーティングと URL パスRouting and URL paths

[HttpGet] 属性は、HTTP GET 要求に応答するメソッドを表します。The [HttpGet] attribute denotes a method that responds to an HTTP GET request. 各メソッドの URL パスは次のように構成されます。The URL path for each method is constructed as follows:

  • コントローラーの Route 属性でテンプレート文字列を使用します。Start with the template string in the controller's Route attribute:

    namespace TodoApi.Controllers
    {
        [Route("api/[controller]")]
        [ApiController]
        public class TodoController : ControllerBase
        {
            private readonly TodoContext _context;
    
  • [controller] をコントローラーの名前 (慣例では "Controller" サフィックスを除くコントローラー クラス名) に置き換えます。Replace [controller] with the name of the controller, which by convention is the controller class name minus the "Controller" suffix. このサンプルでは、コントローラー クラス名は TodoController なので、コントローラー名は "todo" です。For this sample, the controller class name is TodoController, so the controller name is "todo". ASP.NET Core のルーティングでは、大文字と小文字が区別されません。ASP.NET Core routing is case insensitive.

  • [HttpGet] 属性にルート テンプレート (たとえば、[HttpGet("products")]) がある場合は、それをパスに追加します。If the [HttpGet] attribute has a route template (for example, [HttpGet("products")]), append that to the path. このサンプルではテンプレートを使用しません。This sample doesn't use a template. 詳細については、「Http[Verb] 属性を使用する属性ルーティング」を参照してください。For more information, see Attribute routing with Http[Verb] attributes.

次の GetTodoItem メソッドで、"{id}" は To Do アイテムの一意識別子に使用するプレースホルダーの変数です。In the following GetTodoItem method, "{id}" is a placeholder variable for the unique identifier of the to-do item. GetTodoItem が呼び出されると、その id パラメーター内のメソッドに URL の "{id}" の値が指定されます。When GetTodoItem is invoked, the value of "{id}" in the URL is provided to the method in itsid parameter.

// GET: api/Todo/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;
}

戻り値Return values

GetTodoItems メソッドと GetTodoItem メソッドの戻り値の型は、ActionResult<T> 型ですThe return type of the GetTodoItems and GetTodoItem methods is ActionResult<T> type. ASP.NET Core は自動的にオブジェクトを JSON にシリアル化して、応答メッセージの本文に JSON を書き込みます。ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. この戻り値の型の応答コードは 200 で、ハンドルされない例外がないものと想定します。The response code for this return type is 200, assuming there are no unhandled exceptions. ハンドルされない例外は 5xx エラーに変換されます。Unhandled exceptions are translated into 5xx errors.

ActionResult 戻り値の型は、幅広い範囲の HTTP 状態コードを表すことができます。ActionResult return types can represent a wide range of HTTP status codes. たとえば、GetTodoItem は、次の 2 つの異なる状態値を返す可能性があります。For example, GetTodoItem can return two different status values:

  • 要求された ID と一致するアイテムがない場合、メソッドは 404 NotFound エラー コードを返します。If no item matches the requested ID, the method returns a 404 NotFound error code.
  • それ以外の場合、メソッドは JSON 応答本文で 200 を返します。Otherwise, the method returns 200 with a JSON response body. 戻り値が item の場合、HTTP 200 応答が返されます。Returning item results in an HTTP 200 response.

GetTodoItems メソッドのテストTest the GetTodoItems method

このチュートリアルでは、Postman を使用して Web API をテストします。This tutorial uses Postman to test the web API.

  • Postman をインストールします。Install Postman.
  • Web アプリを起動します。Start the web app.
  • Postman を起動します。Start Postman.
  • [SSL 証明書の確認] を無効にします。Disable SSL certificate verification.
  • [ファイル] > [設定] ( [全般] タブ) で、 [SSL 証明書の確認] を無効にします。From File > Settings (General tab), disable SSL certificate verification.

警告

コントローラーをテストした後、SSL 証明書の検証を再度有効にします。Re-enable SSL certificate verification after testing the controller.

  • 新しい要求を作成します。Create a new request.
    • HTTP メソッドを GET に設定します。Set the HTTP method to GET.
    • 要求 URL を https://localhost:<port>/api/todo に設定します。Set the request URL to https://localhost:<port>/api/todo. たとえば、https://localhost:5001/api/todo のようにします。For example, https://localhost:5001/api/todo.
  • Postman で [Two pane view] を設定します。Set Two pane view in Postman.
  • [Send] を選択します。Select Send.

Postman での Get 要求

Create メソッドの追加Add a Create method

Controllers/TodoController.cs 内に次の PostTodoItem メソッドを追加します。Add the following PostTodoItem method inside of Controllers/TodoController.cs:

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

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

上記のコードは、[HttpPost] 属性で示されるように、HTTP POST メソッドです。The preceding code is an HTTP POST method, as indicated by the [HttpPost] attribute. このメソッドは、HTTP 要求の本文から To Do アイテムの値を取得します。The method gets the value of the to-do item from the body of the HTTP request.

CreatedAtAction メソッド:The CreatedAtAction method:

  • 成功すると、HTTP 201 状態コードが返されます。Returns an HTTP 201 status code, if successful. HTTP 201 は、サーバーに新しいリソースを作成する HTTP POST メソッドに対する標準の応答です。HTTP 201 is the standard response for an HTTP POST method that creates a new resource on the server.

  • Location ヘッダーを応答に追加します。Adds a Location header to the response. Location ヘッダーでは、新しく作成された To Do アイテムの URI を指定します。The Location header specifies the URI of the newly created to-do item. 詳細については、「10.2.2 201 Created」を参照してください。For more information, see 10.2.2 201 Created.

  • GetTodoItem アクションを参照して Location ヘッダーの URI を作成します。References the GetTodoItem action to create the Location header's URI. C# の nameof キーワードを使って、CreatedAtAction 呼び出しでアクション名をハードコーディングすることを回避しています。The C# nameof keyword is used to avoid hard-coding the action name in the CreatedAtAction call.

    // GET: api/Todo/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;
    }
    

PostTodoItem メソッドのテストTest the PostTodoItem method

  • プロジェクトをビルドします。Build the project.

  • Postman で、HTTP メソッド名を POST に設定します。In Postman, set the HTTP method to POST.

  • [Body] タブを選択します。Select the Body tab.

  • [raw] ラジオ ボタンを選択します。Select the raw radio button.

  • 型を [JSON (application/json)] に設定します。Set the type to JSON (application/json).

  • 要求本文に、To Do アイテムの JSON を入力します。In the request body enter JSON for a to-do item:

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • [Send] を選択します。Select Send.

    Postman での Create 要求

    405 (Method Not Allowed) エラーが発生した場合は、PostTodoItem メソッドの追加後にプロジェクトをコンパイルしていないことが原因である可能性があります。If you get a 405 Method Not Allowed error, it's probably the result of not compiling the project after adding the PostTodoItem method.

場所ヘッダー URI のテストTest the location header URI

  • [Response] ウィンドウで、 [Headers] タブを選択します。Select the Headers tab in the Response pane.

  • [Location] ヘッダー値をコピーします。Copy the Location header value:

    Postman コンソールの [Headers] タブ

  • メソッドを GET に設定します。Set the method to GET.

  • URI を貼り付けます (たとえば、https://localhost:5001/api/Todo/2)。Paste the URI (for example, https://localhost:5001/api/Todo/2).

  • [Send] を選択します。Select Send.

PutTodoItem メソッドの追加Add a PutTodoItem method

次の PutTodoItem メソッドを追加します。Add the following PutTodoItem method:

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

    _context.Entry(item).State = EntityState.Modified;
    await _context.SaveChangesAsync();

    return NoContent();
}

PutTodoItemPostTodoItem と似ていますが、HTTP PUT を使用します。PutTodoItem is similar to PostTodoItem, except it uses HTTP PUT. 応答は 204 (No Content) となります。The response is 204 (No Content). HTTP 仕様に従って、PUT 要求では、変更だけでなく、更新されたエンティティ全体を送信するようクライアントに求めます。According to the HTTP specification, a PUT request requires the client to send the entire updated entity, not just the changes. 部分的な更新をサポートするには、HTTP PATCH を使用します。To support partial updates, use HTTP PATCH.

PutTodoItem 呼び出しでエラーが発生した場合、GET を呼び出してデータベース内にアイテムがあることを確認してください。If you get an error calling PutTodoItem, call GET to ensure there's an item in the database.

PutTodoItem メソッドのテストTest the PutTodoItem method

このサンプルでは、アプリを起動するたびに開始することが必要なメモリ内データベースが使われています。This sample uses an in-memory database that must be initialized each time the app is started. PUT 呼び出しを実行する前に、データベース内にアイテムが存在している必要があります。There must be an item in the database before you make a PUT call. GET を呼び出して、PUT 呼び出しを実行する前にデータベース内にアイテムが存在していることを確認します。Call GET to insure there's an item in the database before making a PUT call.

ID = 1 の To Do アイテムを更新し、その名前を "feed fish" に設定します。Update the to-do item that has id = 1 and set its name to "feed fish":

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

次の図は、Postman の更新を示しています。The following image shows the Postman update:

204 (No Content) の応答を示す Postman コンソール

DeleteTodoItem メソッドの追加Add a DeleteTodoItem method

次の DeleteTodoItem メソッドを追加します。Add the following DeleteTodoItem method:

// DELETE: api/Todo/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();
}

DeleteTodoItem の応答は 204 (No Content) となります。The DeleteTodoItem response is 204 (No Content).

DeleteTodoItem メソッドのテストTest the DeleteTodoItem method

Postman を使用して、To Do アイテムを削除します。Use Postman to delete a to-do item:

  • メソッドを DELETE に設定します。Set the method to DELETE.
  • 削除するオブジェクトの URI (たとえば、https://localhost:5001/api/todo/1) を設定します。Set the URI of the object to delete (for example https://localhost:5001/api/todo/1).
  • [Send] を選択します。Select Send.

サンプル アプリではすべてのアイテムを削除することができます。The sample app allows you to delete all the items. ただし、最後のアイテムが削除されると、次回 API が呼び出されたときに、モデル クラス コンストラクターによって新しいアイテムが作成されます。However, when the last item is deleted, a new one is created by the model class constructor the next time the API is called.

JavaScript を使用した Web API の呼び出しCall the web API with JavaScript

このセクションでは、JavaScript を使用して Web API を呼び出す HTML ページを追加します。In this section, an HTML page is added that uses JavaScript to call the web API. jQuery によって要求が開始されます。jQuery initiates the request. JavaScript により、Web API の応答からの詳細を使ってページが更新されます。JavaScript updates the page with the details from the web API's response.

Startup.cs を次の強調表示されたコードで更新して、静的ファイルを提供し、既定のファイル マッピングを有効にするためのアプリを構成します。Configure the app to serve static files and enable default file mapping by updating Startup.cs with the following highlighted code:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // The default HSTS value is 30 days. You may want to change this for 
        // production scenarios, see https://aka.ms/aspnetcore-hsts.
        app.UseHsts();
    }

    app.UseDefaultFiles();
    app.UseStaticFiles();
    app.UseHttpsRedirection();
    app.UseMvc();
}

プロジェクト ディレクトリで wwwroot フォルダーを作成します。Create a wwwroot folder in the project directory.

index.html という名前の HTML ファイルを wwwroot ディレクトリに追加します。Add an HTML file named index.html to the wwwroot directory. その内容を次のマークアップに置き換えます。Replace its contents with the following markup:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>To-do CRUD</title>
    <style>
        input[type='submit'], button, [aria-label] {
            cursor: pointer;
        }

        #spoiler {
            display: none;
        }

        table {
            font-family: Arial, sans-serif;
            border: 1px solid;
            border-collapse: collapse;
        }

        th {
            background-color: #0066CC;
            color: white;
        }

        td {
            border: 1px solid;
            padding: 5px;
        }
    </style>
</head>
<body>
    <h1>To-do CRUD</h1>
    <h3>Add</h3>
    <form action="javascript:void(0);" method="POST" onsubmit="addItem()">
        <input type="text" id="add-name" placeholder="New to-do">
        <input type="submit" value="Add">
    </form>

    <div id="spoiler">
        <h3>Edit</h3>
        <form class="my-form">
            <input type="hidden" id="edit-id">
            <input type="checkbox" id="edit-isComplete">
            <input type="text" id="edit-name">
            <input type="submit" value="Save">
            <a onclick="closeInput()" aria-label="Close">&#10006;</a>
        </form>
    </div>

    <p id="counter"></p>

    <table>
        <tr>
            <th>Is Complete</th>
            <th>Name</th>
            <th></th>
            <th></th>
        </tr>
        <tbody id="todos"></tbody>
    </table>

    <script src="https://code.jquery.com/jquery-3.3.1.min.js"
            integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
            crossorigin="anonymous"></script>
    <script src="site.js"></script>
</body>
</html>

site.js という名前の JavaScript ファイルを wwwroot ディレクトリに追加します。Add a JavaScript file named site.js to the wwwroot directory. その内容を次のコードに置き換えます。Replace its contents with the following code:

const uri = "api/todo";
let todos = null;
function getCount(data) {
  const el = $("#counter");
  let name = "to-do";
  if (data) {
    if (data > 1) {
      name = "to-dos";
    }
    el.text(data + " " + name);
  } else {
    el.text("No " + name);
  }
}

$(document).ready(function() {
  getData();
});

function getData() {
  $.ajax({
    type: "GET",
    url: uri,
    cache: false,
    success: function(data) {
      const tBody = $("#todos");

      $(tBody).empty();

      getCount(data.length);

      $.each(data, function(key, item) {
        const tr = $("<tr></tr>")
          .append(
            $("<td></td>").append(
              $("<input/>", {
                type: "checkbox",
                disabled: true,
                checked: item.isComplete
              })
            )
          )
          .append($("<td></td>").text(item.name))
          .append(
            $("<td></td>").append(
              $("<button>Edit</button>").on("click", function() {
                editItem(item.id);
              })
            )
          )
          .append(
            $("<td></td>").append(
              $("<button>Delete</button>").on("click", function() {
                deleteItem(item.id);
              })
            )
          );

        tr.appendTo(tBody);
      });

      todos = data;
    }
  });
}

function addItem() {
  const item = {
    name: $("#add-name").val(),
    isComplete: false
  };

  $.ajax({
    type: "POST",
    accepts: "application/json",
    url: uri,
    contentType: "application/json",
    data: JSON.stringify(item),
    error: function(jqXHR, textStatus, errorThrown) {
      alert("Something went wrong!");
    },
    success: function(result) {
      getData();
      $("#add-name").val("");
    }
  });
}

function deleteItem(id) {
  $.ajax({
    url: uri + "/" + id,
    type: "DELETE",
    success: function(result) {
      getData();
    }
  });
}

function editItem(id) {
  $.each(todos, function(key, item) {
    if (item.id === id) {
      $("#edit-name").val(item.name);
      $("#edit-id").val(item.id);
      $("#edit-isComplete")[0].checked = item.isComplete;
    }
  });
  $("#spoiler").css({ display: "block" });
}

$(".my-form").on("submit", function() {
  const item = {
    name: $("#edit-name").val(),
    isComplete: $("#edit-isComplete").is(":checked"),
    id: $("#edit-id").val()
  };

  $.ajax({
    url: uri + "/" + $("#edit-id").val(),
    type: "PUT",
    accepts: "application/json",
    contentType: "application/json",
    data: JSON.stringify(item),
    success: function(result) {
      getData();
    }
  });

  closeInput();
  return false;
});

function closeInput() {
  $("#spoiler").css({ display: "none" });
}

ローカルで HTML ページをテストするために、ASP.NET Core プロジェクトの起動設定への変更が要求される場合があります。A change to the ASP.NET Core project's launch settings may be required to test the HTML page locally:

  • Properties\launchSettings.json を開きます。Open Properties\launchSettings.json.
  • アプリが強制的に index.html—プロジェクトの既定ファイルで開くようにするには、launchUrl プロパティを削除します。Remove the launchUrl property to force the app to open at index.html—the project's default file.

このサンプルでは、Web API のすべての CRUD メソッドを呼び出します。This sample calls all of the CRUD methods of the web API. 次に、API の呼び出しについて説明します。Following are explanations of the calls to the API.

To Do アイテムのリストの取得Get a list of to-do items

jQuery により HTTP GET 要求が Web API に送信され、API からは To Do アイテムの配列を表す JSON が返されます。jQuery sends an HTTP GET request to the web API, which returns JSON representing an array of to-do items. 要求が成功した場合、success コールバック関数が呼び出されます。The success callback function is invoked if the request succeeds. コールバックでは、DOM は To Do 情報で更新されます。In the callback, the DOM is updated with the to-do information.

$(document).ready(function() {
  getData();
});

function getData() {
  $.ajax({
    type: "GET",
    url: uri,
    cache: false,
    success: function(data) {
      const tBody = $("#todos");

      $(tBody).empty();

      getCount(data.length);

      $.each(data, function(key, item) {
        const tr = $("<tr></tr>")
          .append(
            $("<td></td>").append(
              $("<input/>", {
                type: "checkbox",
                disabled: true,
                checked: item.isComplete
              })
            )
          )
          .append($("<td></td>").text(item.name))
          .append(
            $("<td></td>").append(
              $("<button>Edit</button>").on("click", function() {
                editItem(item.id);
              })
            )
          )
          .append(
            $("<td></td>").append(
              $("<button>Delete</button>").on("click", function() {
                deleteItem(item.id);
              })
            )
          );

        tr.appendTo(tBody);
      });

      todos = data;
    }
  });
}

To Do アイテムの追加Add a to-do item

jQuery により、要求本文に To Do アイテムが含まれる HTTP POST 要求が送信されます。jQuery sends an HTTP POST request with the to-do item in the request body. accepts オプションと contentType オプションは application/json に設定されて、送受信されるメディアの種類を指定します。The accepts and contentType options are set to application/json to specify the media type being received and sent. To Do アイテムは、JSON.stringify を使用して JSON に変換されます。The to-do item is converted to JSON by using JSON.stringify. API で正常な状況コードが返された場合、getData 関数が呼び出され、HTML テーブルを更新します。When the API returns a successful status code, the getData function is invoked to update the HTML table.

function addItem() {
  const item = {
    name: $("#add-name").val(),
    isComplete: false
  };

  $.ajax({
    type: "POST",
    accepts: "application/json",
    url: uri,
    contentType: "application/json",
    data: JSON.stringify(item),
    error: function(jqXHR, textStatus, errorThrown) {
      alert("Something went wrong!");
    },
    success: function(result) {
      getData();
      $("#add-name").val("");
    }
  });
}

To Do アイテムの更新Update a to-do item

To Do アイテムの更新は、追加操作に似ています。Updating a to-do item is similar to adding one. アイテムの一意の識別子を追加するように url が変更され、typePUT となります。The url changes to add the unique identifier of the item, and the type is PUT.

$.ajax({
  url: uri + "/" + $("#edit-id").val(),
  type: "PUT",
  accepts: "application/json",
  contentType: "application/json",
  data: JSON.stringify(item),
  success: function(result) {
    getData();
  }
});

To Do アイテムの削除Delete a to-do item

To Do アイテムを削除するには、DELETE への AJAX 呼び出しで type を設定して、URL でアイテムの一意の識別子を指定します。Deleting a to-do item is accomplished by setting the type on the AJAX call to DELETE and specifying the item's unique identifier in the URL.

$.ajax({
  url: uri + "/" + id,
  type: "DELETE",
  success: function(result) {
    getData();
  }
});

Web API に認証サポートを追加Add authentication support to a web API

ASP.NET Core Identity では、ASP.NET Core Web アプリにユーザー インターフェイス (UI) ログイン機能が追加されます。ASP.NET Core Identity adds user interface (UI) login functionality to ASP.NET Core web apps. Web API と SPA をセキュリティで保護するには、次のいずれかを使用します。To secure web APIs and SPAs, use one of the following:

IdentityServer4 は、ASP.NET Core 3.0 用の OpenID Connect および OAuth 2.0 フレームワークです。IdentityServer4 is an OpenID Connect and OAuth 2.0 framework for ASP.NET Core 3.0. IdentityServer4 により、次のセキュリティ機能が有効になります。IdentityServer4 enables the following security features:

  • サービスとしての認証 (AaaS)Authentication as a Service (AaaS)
  • 複数のアプリケーションの種類でのシングル サインオン/オフ (SSO)Single sign-on/off (SSO) over multiple application types
  • API のアクセス制御Access control for APIs
  • Federation GatewayFederation Gateway

詳細については、「ようこそ! IdentityServer4」を参照してください。For more information, see Welcome to IdentityServer4.

その他の技術情報Additional resources

このチュートリアルのサンプル コードを表示またはダウンロードします。View or download sample code for this tutorial. ダウンロード方法に関するページを参照してください。See how to download.

詳細については、次のリソースを参照してください。For more information, see the following resources: