Migreren van DownstreamWebApi naar DownstreamApi

De interfacegeschiedenis controleren

Microsoft. Identity.Web 1.x heeft IDownstreamWebApi geïntroduceerd, een interface waarmee verificatiegegevens (tokenverwerving, autorisatieheaders) worden verwerkt bij het aanroepen van API's. Naarmate de interface groeit op basis van functieaanvragen, zijn belangrijke wijzigingen nodig om alle aangevraagde scenario's te ondersteunen.

In plaats van de bestaande API te wijzigen, heeft het team een nieuwe interface gebouwd: IDownstreamApi. De oude interface is afgeschaft en alle toekomstige ontwikkeling is gericht op de nieuwe implementatie. U kunt in uw eigen tempo migreren.

In dit artikel worden het volgende uitgelegd:

• Migreren van IDownstreamWebApi naar IDownstreamApi
• De verschillen tussen IDownstreamWebApi en IDownstreamApi

Migreren van IDownstreamWebApi naar IDownstreamApi

Migreren van IDownstreamWebApi naar Microsoft. Identity.Web 2.x en IDownstreamApi:

1. Voeg een verwijzing toe naar de Microsoft. Identity.Web.DownstreamApi NuGet-pakket.

2. Vervang in de initialisatiecode van uw toepassing (meestal Startup.cs of Program.cs), de oude registratieoproep:

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

   met de nieuwe registratieoproep:

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

3. Wijzig in het configuratiebestand (appsettings.json) in de sectie die de downstream-web-API vertegenwoordigt de waarde Scopes van een tekenreeks in een matrix met tekenreeksen. In het volgende voorbeeld ziet u het oorspronkelijke spatie-gescheiden tekenreeksformaat:

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

   Werk de scopes bij om de nieuwe array-indeling te gebruiken.

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

   Waarschuwing

   Als u vergeet de scopes in een array te wijzigen, zullen de scopes null lijken wanneer u probeert de IDownstreamApi te gebruiken. IDownstreamApi zal dan proberen een anonieme (niet-geverifieerde) oproep naar de downstream-API te doen, wat zal resulteren in een 401/niet-geverifieerd.

4. In de controller:

   • using namespace Microsoft.Identity.Abstractions toevoegen

   • Injecteren IDownstreamApi in plaats van IDownstreamWebApi

   • CallWebApiForUserAsync vervangen door CallApiForUserAsync

   • Als u een van de methoden GetForUser, PutForUser of PostForUser hebt gebruikt, wijzigt u de tekenreeks die het relatieve pad heeft uitgedrukt in een functie of delegate die dit relatieve pad instelt. In het volgende voorbeeld ziet u de oorspronkelijke tekenreeksparameterbenadering:

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

     Werk de code bij om een gedelegeerde te gebruiken die het relatieve pad instelt.

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

Voorbeeldcode controleren

In het volgende voorbeeld ziet u hoe u IDownstreamApi gebruikt in een werkende toepassing.

Zie het volledige voorbeeld: ASP.NET Core web-app die web-API/TodoListController aanroept.

IDownstreamWebApi en IDownstreamApi vergelijken

De volgende tabel bevat een overzicht van de belangrijkste verschillen tussen de afgeschafte IDownstreamWebApi en de nieuwe IDownstreamApi:

Inzicht in migratievoordelen

Door over te stappen naar IDownstreamApi krijgt u toegang tot doorlopende verbeteringen en een flexibelere API-interface.

• IDownstreamWebApi is afgeschaft en ontvangt geen nieuwe functies of oplossingen voor fouten.
• IDownstreamApi biedt een schoner API-oppervlak, betere serialisatieondersteuning en volledige aanpassingsmogelijkheden.
• De abstractielaag (Microsoft.Identity.Abstractions) betekent dat uw downstream-API-code niet nauw is gekoppeld aan een specifieke identiteitsbibliotheek.

Verwante inhoud verkennen

Gebruik deze resources voor meer informatie over het aanroepen van downstream-API's.

• Overzicht van downstream-API's aanroepen
• Aangepaste API's aanroepen