DownstreamWebApi から DownstreamApi への移行

インターフェイスの履歴を確認する

Microsoft。Identity.Web 1.x では、API の呼び出し時に認証の詳細 (トークン取得、承認ヘッダー) を処理するインターフェイスである IDownstreamWebApi が導入されました。 インターフェイスが機能要求に基づいて成長するにつれて、要求されたすべてのシナリオをサポートするために破壊的変更が必要になりました。

チームは、既存の API を変更する代わりに、新しいインターフェイス IDownstreamApi を構築しました。 古いインターフェイスは非推奨となり、今後の開発はすべて新しい実装に焦点を当てています。 自分のペースで移行できます。

この記事では、以下について説明しています。

  • IDownstreamWebApi から IDownstreamApi に移行する方法
  • IDownstreamWebApi と IDownstreamApi の違い

IDownstreamWebApi から IDownstreamApi への移行

IDownstreamWebApi から Microsoft に移行します。Identity.Web 2.x および IDownstreamApi:

  1. Microsoft.Identity.Web.DownstreamApi NuGet パッケージへの参照を追加します。

  2. アプリケーション初期化コード (通常 はStartup.cs または Program.cs) で、古い登録呼び出しを置き換えます。

    .AddDownstreamWebApi("serviceName", Configuration.GetSection("SectionName"))

    新しい登録呼び出しで次の手順を実行します。

    .AddDownstreamApi("serviceName", Configuration.GetSection("SectionName"))

  3. ダウンストリーム Web API を表すセクションの構成ファイル (appsettings.json) で、 Scopes の値を文字列から文字列の配列に変更します。 次の例は、元のスペース区切りの文字列形式を示しています。

    "DownstreamApi1": {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": "https://myapi.domain.com/read  https://myapi.domain.com/write"
},

    新しい配列形式を使用するようにスコープを更新します。

    "DownstreamApi1": {
    "BaseUrl": "https://myapi.domain.com",
    "Scopes": [
        "https://myapi.domain.com/read",
        "https://myapi.domain.com/write" 
    ]
},

    Warnung

    スコープを配列に変更することを忘れた場合、IDownstreamApi を使用しようとすると、スコープは null になり、IDownstreamApi はダウンストリーム API への匿名 (認証されていない) 呼び出しを試行し、結果として 401/認証なしになります。

  4. コントローラーで次の手順を実行します。

    • using namespace Microsoft.Identity.Abstractionsを追加する

    • IDownstreamWebApi の代わりにIDownstreamApi を挿入する

    • CallWebApiForUserAsync を CallApiForUserAsync に置き換えます。

    • GetForUser、PutForUser、または PostForUser のいずれかのメソッドを使用した場合は、相対パスを表す文字列を、この相対パスを設定するデリゲートに変更します。 次の例は、元の文字列パラメーターアプローチを示しています。

      Todo value = await _downstreamWebApi.GetForUserAsync<Todo>(ServiceName,
                                                            $"api/todolist/{id}");

      相対パスを設定するデリゲートを使用するようにコードを更新します。

      Todo value = await _downstreamWebApi.GetForUserAsync<Todo>(
      ServiceName,
      options => options.RelativePath = $"api/todolist/{id}";);

コード例を確認する

次の例は、動作しているアプリケーションで IDownstreamApi を使用する方法を示しています。

完全な例として、ASP.NET Core Web アプリの Web API/TodoListController を参照してください。

IDownstreamWebApi と IDownstreamApi の比較

次の表は、非推奨の IDownstreamWebApi と新しい IDownstreamApiの主な違いをまとめたものです。

特徴 IDownstreamWebApi (非推奨) IDownstreamApi
NuGet パッケージ Microsoft.Identity.Web.DownstreamWebApi Microsoft.Identity.Web.DownstreamApi
登録 AddDownstreamWebApi() AddDownstreamApi()
スコープの構成 スペース区切り文字列 文字列の配列
オプション パターン 制限あり 完全な Action<DownstreamApiOptions> デリゲートのサポート
相対パス 文字列パラメーター オプション デリゲートを使用して設定する (options.RelativePath)
Serialization JSON の手動処理 <TInput, TOutput> ジェネリックを使用した組み込みのシリアル化
HTTP メソッド GetForUserAsync、PostForUserAsync などです。 オプションとしての HTTP メソッドと型指定されたヘルパーを組み合わせた統合CallApiForUserAsync
アプリのみの呼び出し CallWebApiForAppAsync CallApiForAppAsync
カスタム HTTP メッセージ サポートしていません options.CustomizeHttpRequestMessage デリゲート
複製/上書きオプション サポートしていません デリゲートを使用して呼び出しごとのオプションを上書きする方法
プロトコルの抽象化 Microsoftに関連付けられています。Identity.Web Microsoft.Identity.Abstractions (ID ライブラリ間で再利用可能) に基づく

移行の利点を理解する

IDownstreamApiに移行すると、継続的な機能強化とより柔軟な API サーフェスにアクセスできます。

  • IDownstreamWebApi は非推奨 であり、新機能やバグ修正は受け取りません。
  • IDownstreamApi は、よりクリーンな API サーフェス、より優れたシリアル化のサポート、および完全なオプションのカスタマイズを提供します。
  • 抽象化レイヤー (Microsoft.Identity.Abstractions) は、ダウンストリーム API コードが特定の ID ライブラリに緊密に結合されていないことを意味します。

関連コンテンツを調べる

これらのリソースを使用して、ダウンストリーム API の呼び出しの詳細を確認してください。

  • Last updated on