複数バージョンのASPをサポートする.NET Core Web API

6063 ワード

基本構成と説明


バージョン管理は、既存のシステムを破壊することなく、機能をタイムリーに提供します.また、選択したお客様に追加の機能を提供することもできます.APIバージョンは、URLにバージョンを追加したり、ヘッダーをカスタマイズしたり、クエリー文字列パラメータとしてAccept-Headerを使用したりするなど、さまざまな方法で実行できます.この記事では、マルチバージョンのASPをサポートする方法を見てみましょう.NET Core Web API
ASPを作成する.NET Core Web APIアプリケーション.NuGetでこのパッケージをインストールします:Microsoft.AspNetCore.Mvc.Versioning、Startup.csを開いて、ConfigureServicesの方法を修正して、コードは以下の通りです:
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning(option =>
    {
        option.ReportApiVersions = true;
        option.AssumeDefaultVersionWhenUnspecified = true;
        option.DefaultApiVersion = new ApiVersion(1, 0);
    });
}

3つの異なるオプションが構成されていることがわかります.
  • ReportAPIVersions:これはオプションです.ただし、trueに設定すると、APIは応答ヘッダにサポートされているバージョン情報を返します.
  • AssumeDefaultVersionWhenUnspecified:このオプションは、バージョンなしで要求を提供するために使用されます.仮定APIバージョンのデフォルトは1.0
    • です.
  • DefaultApiVersion:このオプションは、要求でバージョンが指定されていない場合に使用するデフォルトのAPIバージョンを指定します.これにより、デフォルトバージョンは1.0
    • になります.
    これが構成と設定です.APIバージョンにアクセスする方法の違いを見てみましょう.

    Via Query String(クエリ文字列による)

    Controllerクラスを開き、ApiVersionプロパティでControllerクラスを装飾します.次のように、
    namespace MultipleAPIVersions.Controllers
{
    [ApiVersion("1.0")]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet]
        public IActionResult Get() => Ok(new string[] { "value1" });
    }
}

    上記のバージョンは1.0に設定されており、APIバージョンは2.0に設定することもできます.そのため、異なるネーミングスペースに同じ名前の別のControllerクラスを作成する必要があります.次のように、
    namespace AspNetCoreWebApi.Controllers2
{
    [ApiVersion("2.0")]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet]
        public IActionResult Get() => Ok(new string[] { "value2" });
    }
}

    ブラウザに行ってコントローラにアクセスします.デフォルトアクセスが1.0のバージョンであるため、APIバージョン1.0コントローラの出力が表示されます.URLにapi-version=2を添付すると、API 2.0版コントローラの出力が表示されます.

    Via URL Path Segment(URLパス経由)


    クエリ文字列パラメータは有用ですが、長いURLや他のクエリ文字列パラメータの場合は苦痛かもしれません.逆に、より良い方法はURLパスにバージョンを追加することです.このように、
  • api/v1/values
  • api/v2/values

    • これを行うには、routeプロパティにバージョンを配置する必要があります.
    namespace MultipleAPIVersions.Controllers
{
    [ApiVersion("1.0")]
    [Route("api/v{version:apiVersion}/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet]
        public IActionResult Get() => Ok(new string[] { "value1" });
    }
}

    同様に、ルーティングパラメータをすべてのリクエストに更新する必要があります.この変更により、APIエンドポイントには常にバージョン番号が必要になります.バージョン1.0に移動するには、api/v1/valuesを使用します.バージョン2.0にアクセスするには、URLのバージョン番号を変更します.簡単で、もっときれいに見えます

    Via HTTP Headers（HTTPヘッダ経由）


    上記の2つの方法では、バージョン管理をサポートするためにURLを変更する必要があります.ただし、APIのURLをきれいにしたい場合は、APIバージョン情報はHTTPヘッダを追加して渡すこともできます.動作させるには、ApiVersionReaderオプションを設定する必要があります.
    services.AddApiVersioning(option =>
{
    option.ReportApiVersions = true;
    option.ApiVersionReader = new HeaderApiVersionReader("api-version");
    option.DefaultApiVersion = new ApiVersion(1, 0);
    option.AssumeDefaultVersionWhenUnspecified = true;
});

    Postmanを開いてheader api-versionテストを追加
    2.0をapi-versionに値として提供すると、2.0バージョンControllerが呼び出され、出力が返されます.
    簡単で使いやすい設定.ただし、クエリ文字列パラメータ(query string parameter)は正常に動作しません.headerを設定すると、クエリー文字列パラメータ(query string parameter)を指定できません.サポートをご希望の場合は、ApiVersionReader.Combineをご利用ください
    option.ApiVersionReader = ApiVersionReader.Combine
            (
                new QueryStringApiVersionReader("api-version"),
                new HeaderApiVersionReader("api-version")
            );

    クエリー文字列パラメータとheaderがサポートされていることを覚えておいてください.ReportApiVersionsをtrueに設定し、応答ヘッダのバージョン情報を返します.下図を参照
    では、他のいくつかの選択肢を見てみましょう.

    MapToApiVersion

    MapToApiVersionプロパティにより、単一のAPI actionを任意のバージョンにマッピングできます.すなわち、複数のバージョンをサポートする単一のController
    namespace MultipleAPIVersions.Controllers
{
    [ApiVersion("1.0")]
    [ApiVersion("3.0")]
    [Route("api/v{version:apiVersion}/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet]
        public IActionResult Get() => Ok(new string[] { "value1" });

        [HttpGet, MapToApiVersion("3.0")]
        public IActionResult GetV3() => Ok(new string[] { "value3" });
    }
}

    Deprecated(廃棄)


    複数のAPIバージョンがサポートされている場合、一部のバージョンは最終的に淘汰されます.1つまたは複数のAPIバージョンが破棄されることを示すには、破棄の準備をしているAPIバージョンタグを使用します.これは、APIバージョンがサポートされていないことを意味するものではなく、これらのタグ付けされたAPIは依然として呼び出すことができる.これは,以降のバージョンが廃棄されることをユーザに認識させる一つの方法にすぎない[ApiVersion("1.0",Deprecated=true)]

    ApiVersionNeutral(バージョン中立)

    ApiVersionNeutralプロパティは、APIがバージョン中立であることを定義する.これは、APIバージョンをサポートするControllerであっても、APIバージョンをサポートしないControllerであっても、動作が全く同じAPIにとって非常に有用である.したがって、バージョン管理を終了するためにApiVersionNeutralのプロパティを追加できます.
    [ApiVersionNeutral]
[RoutePrefix( "api/[controller]" )]
public class SharedController : Controller
{
    [HttpGet]
    public IActionResult Get() => Ok();
}

    バージョン情報へのアクセス


    どのバージョンのクライアントがアクセスしようとしているかを知りたい場合は、次の情報を取得できます.
    public string Get() => HttpContext.GetRequestedApiVersion().ToString();

    記事元アドレスsupport-multiple-versions-of-asp-net-core-web-api関連記事API-Version-Reader
    転載先:https://www.cnblogs.com/MrNice/p/aspnet-core-api-version.html
    Problem with a inner layout and toolbar - Ext JS
    Asp.Net進級/値タイプと参照タイプ:復習