Migrera från DownstreamWebApi till DownstreamApi

Granska gränssnittshistoriken

Microsoft. Identity.Web 1.x introducerade IDownstreamWebApi, ett gränssnitt som hanterade autentiseringsinformation (tokenförvärv, auktoriseringshuvuden) när API:er anropas. När gränssnittet växte baserat på funktionsbegäranden blev icke-bakåtkompatibla ändringar nödvändiga för att stödja alla begärda scenarier.

I stället för att ändra det befintliga API:et skapade teamet ett nytt gränssnitt: IDownstreamApi. Det gamla gränssnittet är inaktuellt och all framtida utveckling fokuserar på den nya implementeringen. Du kan migrera i din egen takt.

Den här artikeln förklarar:

• Migrera från IDownstreamWebApi till IDownstreamApi
• Skillnaderna mellan IDownstreamWebApi och IDownstreamApi

Migrera från IDownstreamWebApi till IDownstreamApi

Migrera från IDownstreamWebApi till Microsoft. Identity.Web 2.x och IDownstreamApi:

1. Lägg till en referens till Microsoft.Identity.Web.DownstreamApi NuGet-paketet.

2. Ersätt det gamla registreringsanropet i programmets initieringskod (vanligtvis Startup.cs eller Program.cs):

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

   med det nya registreringsanropet:

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

3. I konfigurationsfilen (appsettings.json) i avsnittet som representerar det underordnade webb-API:et ändrar du värdet Scopes från en sträng till en matris med strängar. I följande exempel visas det ursprungliga blankstegsavgränsade strängformatet:

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

   Uppdatera omfången så att de använder det nya matrisformatet:

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

   Varning

   Om du glömmer att ändra omfången till en matris visas omfången null när du försöker använda IDownstreamApi, och IDownstreamApi försöker göra ett anonymt (oautentiserat) anrop till det underordnade API:et, vilket resulterar i ett 401/oautentiserat.

4. I styrenheten:

   • Lägg till using namespace Microsoft.Identity.Abstractions

   • Mata in IDownstreamApi i stället för IDownstreamWebApi

   • Ersätt CallWebApiForUserAsync med CallApiForUserAsync

   • Om du använde någon av metoderna GetForUser, PutForUser eller PostForUser ändrar du den sträng som uttrycker den relativa sökvägen till en delegat som anger den här relativa sökvägen. I följande exempel visas den ursprungliga metoden för strängparameter:

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

     Uppdatera koden så att den använder en delegerad som anger den relativa sökvägen.

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

Granska exempelkod

Följande exempel visar hur du använder IDownstreamApi i ett fungerande program.

Se det fullständiga exemplet: ASP.NET Core webbapp som anropar webb-API/TodoListController.

Jämför IDownstreamWebApi och IDownstreamApi

I följande tabell sammanfattas de viktigaste skillnaderna mellan den inaktuella IDownstreamWebApi och den nya IDownstreamApi:

Förstå migreringsfördelar

Om du migrerar till IDownstreamApi får du tillgång till pågående förbättringar och en mer flexibel API-yta.

• IDownstreamWebApi är inaktuell och får inga nya funktioner eller felkorrigeringar.
• IDownstreamApi ger en renare API-yta, bättre serialiseringsstöd och fullständig anpassning av alternativ.
• Abstraktionsskiktet (Microsoft.Identity.Abstractions) innebär att din underordnade API-kod inte är nära kopplad till ett specifikt identitetsbibliotek.

Utforska relaterat innehåll

Använd dessa resurser för att lära dig mer om att anropa underordnade API:er.

• Översikt över anrop till underordnade API:er
• Anropa anpassade API:erna