Migrieren von DownstreamWebApi zu DownstreamApi

Überprüfen des Schnittstellenverlaufs

Microsoft.Identity.Web 1.x führte die Schnittstelle IDownstreamWebApi ein, die Authentifizierungsdetails wie Token-Akquisition und Autorisierungsheader beim Aufrufen von APIs verwaltet. Da die Schnittstelle auf der Grundlage von Featureanforderungen gewachsen ist, wurden einschneidende Änderungen erforderlich, um alle angeforderten Szenarien zu unterstützen.

Anstatt die vorhandene API zu ändern, hat das Team eine neue Schnittstelle erstellt: IDownstreamApi. Die alte Schnittstelle ist veraltet, und alle zukünftigen Entwicklungen konzentrieren sich auf die neue Implementierung. Sie können in Ihrem eigenen Tempo migrieren.

In diesem Artikel erfahren Sie:

• Migrieren von IDownstreamWebApi zu IDownstreamApi
• Die Unterschiede zwischen IDownstreamWebApi und IDownstreamApi

Migrieren von IDownstreamWebApi zu IDownstreamApi

Um von IDownstreamWebApi zu Microsoft zu migrieren. Identity.Web 2.x und IDownstreamApi:

1. Fügen Sie einen Verweis auf das Microsoft.Identity.Web.DownstreamApi NuGet-Paket hinzu.

2. Ersetzen Sie im Anwendungsinitialisierungscode (in der Regel Startup.cs oder Program.cs) den alten Registrierungsaufruf:

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

   mit dem neuen Registrierungsanruf:

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

3. In der Konfigurationsdatei (appsettings.json), im Abschnitt, der die Downstream-Web-API darstellt, ändern Sie den Wert von Scopes von einer Zeichenfolge in ein Array von Zeichenfolgen. Das folgende Beispiel zeigt das ursprüngliche durch Leerzeichen getrennte Zeichenfolgenformat:

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

   Aktualisieren Sie die Gültigkeitsbereiche, um das neue Array-Format zu verwenden.

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

   Warnung

   Wenn Sie vergessen, die Scopes in ein Array zu ändern, werden die Scopes beim Versuch, die IDownstreamApi zu verwenden, als null angezeigt, und IDownstreamApi wird versuchen, einen anonymen (nicht authentifizierten) Aufruf an die Downstream-API vorzunehmen, was zu einem 401/unauthenticated führt.

4. Im Controller:

   • Fügen Sie using namespace Microsoft.Identity.Abstractions hinzu.

   • Einfügen IDownstreamApi anstelle von IDownstreamWebApi

   • Ersetzen Sie CallWebApiForUserAsync durch CallApiForUserAsync

   • Wenn Sie eine der Methoden GetForUser, PutForUser oder PostForUser verwendet haben, ändern Sie die Zeichenfolge, die den relativen Pfad zu einem Delegaten ausgedrückt hat, der diesen relativen Pfad festlegt. Das folgende Beispiel zeigt den ursprünglichen Ansatz des Zeichenfolgenparameters:

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

     Aktualisieren Sie den Code, um einen Delegaten zu verwenden, der den relativen Pfad festlegt:

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

Beispielcode überprüfen

Das folgende Beispiel zeigt, wie IDownstreamApi in einer funktionierenden Anwendung verwendet wird.

Sehen Sie sich das vollständige Beispiel an: ASP.NET Core Web App calling web API/TodoListController.

Vergleich von IDownstreamWebApi und IDownstreamApi

In der folgenden Tabelle sind die wichtigsten Unterschiede zwischen der nicht mehr empfohlenen IDownstreamWebApi und der neuen IDownstreamApi zusammengefasst.

Grundlegendes zu den Migrationsvorteilen

Durch die Migration zu IDownstreamApi erhalten Sie Zugriff auf fortlaufende Verbesserungen und eine flexiblere API-Oberfläche.

• IDownstreamWebApi ist veraltet und erhält keine neuen Features oder Fehlerbehebungen.
• IDownstreamApi bietet eine übersichtlichere API-Oberfläche, bessere Serialisierungsunterstützung und vollständige Anpassungsoptionen.
• Die Abstraktionsebene (Microsoft.Identity.Abstractions) bedeutet, dass Der nachgeschaltete API-Code nicht eng mit einer bestimmten Identitätsbibliothek gekoppelt ist.

Durchsuchen verwandter Inhalte

Verwenden Sie diese Ressourcen, um mehr über das Aufrufen von downstream-APIs zu erfahren.

• Übersicht über nachgeschaltete APIs
• Aufrufen benutzerdefinierter APIs