Eseguire la migrazione da DownstreamWebApi a DownstreamApi

Esaminare la cronologia dell'interfaccia

Microsoft. Identity.Web 1.x ha introdotto IDownstreamWebApi, un'interfaccia che gestisce i dettagli di autenticazione (acquisizione del token, intestazioni di autorizzazione) durante la chiamata delle API. Man mano che l'interfaccia è cresciuta in base alle richieste di funzionalità, le modifiche di rilievo sono diventate necessarie per supportare tutti gli scenari richiesti.

Anziché modificare l'API esistente, il team ha creato una nuova interfaccia: IDownstreamApi. L'interfaccia precedente è deprecata e tutto lo sviluppo futuro è incentrato sulla nuova implementazione. È possibile eseguire la migrazione in base al proprio ritmo.

In questo articolo viene descritto quanto segue:

  • Come eseguire la migrazione da IDownstreamWebApi a IDownstreamApi
  • Differenze tra IDownstreamWebApi e IDownstreamApi

Eseguire la migrazione da IDownstreamWebApi a IDownstreamApi

Per eseguire la migrazione da IDownstreamWebApi a Microsoft. Identity.Web 2.x e IDownstreamApi:

  1. Aggiungere un riferimento al pacchetto NuGet Microsoft.Identity.Web.DownstreamApi.

  2. Nel codice di inizializzazione dell'applicazione (in genere Startup.cs o Program.cs), sostituire la precedente chiamata di registrazione:

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

    con la nuova chiamata di registrazione:

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

  3. Nel file di configurazione (appsettings.json), nella sezione che rappresenta l'API Web downstream modificare il valore Scopes da una stringa a una matrice di stringhe. L'esempio seguente mostra il formato di stringa delimitato dallo spazio originale:

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

    Aggiornare gli ambiti per usare il nuovo formato di matrice:

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

    Avvertimento

    Se si dimentica di modificare gli ambiti in una matrice, quando si tenta di usare IDownstreamApi gli ambiti verranno visualizzati null e IDownstreamApi tenterà una chiamata anonima (non autenticata) all'API downstream, che comporterà un errore 401/non autenticato.

  4. Nel controller:

    • Aggiungere using namespace Microsoft.Identity.Abstractions

    • IDownstreamApi Inserire invece diIDownstreamWebApi

    • Sostituire CallWebApiForUserAsync con CallApiForUserAsync

    • Se hai utilizzato uno dei metodi GetForUser, PutForUser o PostForUser, modifica la stringa che esprime il percorso relativo in un delegato che lo imposta. L'esempio seguente illustra l'approccio del parametro stringa originale:

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

      Aggiornare il codice per usare un delegato che imposta il percorso relativo:

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

Esaminare il codice di esempio

L'esempio seguente illustra come usare IDownstreamApi in un'applicazione funzionante.

Vedere l'esempio completo: app web ASP.NET Core che chiama web API/TodoListController.

Confrontare IDownstreamWebApi e IDownstreamApi

La tabella seguente riepiloga le differenze principali tra il deprecato IDownstreamWebApi e il nuovo IDownstreamApi:

Feature IDownstreamWebApi (deprecato) IDownstreamApi
Pacchetto NuGet Microsoft.Identity.Web.DownstreamWebApi Microsoft.Identity.Web.DownstreamApi
Registrazione AddDownstreamWebApi() AddDownstreamApi()
Configurazione degli ambiti Stringa delimitata da spazi Matrice di stringhe
Modello di opzioni Limitato Supporto completo Action<DownstreamApiOptions> dei delegati
Percorso relativo Parametro stringa Configurare tramite delegato di opzioni (options.RelativePath)
Serialization Gestione manuale di JSON Serializzazione predefinita con <TInput, TOutput> generics
Metodi HTTP GetForUserAsync, PostForUserAsynce così via. Unified CallApiForUserAsync con metodo HTTP nelle opzioni, oltre a helper tipizzati
** Chiamate esclusivamente tramite app CallWebApiForAppAsync CallApiForAppAsync
Messaggio HTTP personalizzato Non supportato options.CustomizeHttpRequestMessage delegato
Opzioni di clonazione/override Non supportato L'opzione per chiamata esegue l'override tramite delegato
Astrazione del protocollo Associato a Microsoft. Identity.Web Basato su Microsoft.Identity.Abstractions (riutilizzabile tra le librerie di identità)

Informazioni sui vantaggi della migrazione

La migrazione a IDownstreamApi consente di accedere ai miglioramenti continui e a una superficie API più flessibile.

  • IDownstreamWebApi è deprecato e non riceverà nuove funzionalità o correzioni di bug.
  • IDownstreamApi offre una superficie API più pulita, un supporto migliore per la serializzazione e una personalizzazione completa delle opzioni.
  • Il livello di astrazione (Microsoft.Identity.Abstractions) indica che il codice dell'API downstream non è strettamente associato a una libreria di identità specifica.

Esplorare il contenuto correlato

Usare queste risorse per altre informazioni sulla chiamata alle API downstream.

  • Last updated on