Migración de DownstreamWebApi a DownstreamApi

Revisión del historial de la interfaz

Microsoft. Identity.Web 1.x introdujo IDownstreamWebApi, una interfaz que controla los detalles de autenticación (adquisición de tokens, encabezados de autorización) al llamar a las API. A medida que la interfaz creció en función de las solicitudes de características, los cambios importantes se hicieron necesarios para admitir todos los escenarios solicitados.

En lugar de modificar la API existente, el equipo creó una nueva interfaz: IDownstreamApi. La interfaz antigua está en desuso y todo el desarrollo futuro se centra en la nueva implementación. Puede migrar a su propio ritmo.

En este artículo, se explica lo siguiente:

• Migración de IDownstreamWebApi a IDownstreamApi
• Diferencias entre IDownstreamWebApi e IDownstreamApi

Migración de IDownstreamWebApi a IDownstreamApi

Para migrar de IDownstreamWebApi a Microsoft. Identity.Web 2.x y IDownstreamApi:

1. Agregue una referencia al paquete NuGet Microsoft.Identity.Web.DownstreamApi.

2. En el código de inicialización de la aplicación (normalmente Startup.cs o Program.cs), reemplace la llamada de registro anterior:

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

   con la nueva solicitud de registro:

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

3. En el archivo de configuración (appsettings.json), en la sección que representa la API web de bajada, cambie el valor Scopes de una cadena a una matriz de cadenas. En el ejemplo siguiente se muestra el formato de cadena delimitado por espacio original:

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

   Actualice los ámbitos para usar el nuevo formato de matriz:

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

   Advertencia

   Si olvida cambiar los ámbitos a una matriz, cuando intente usar IDownstreamApi, los ámbitos aparecerán nulos y IDownstreamApi intentará una llamada anónima (sin autenticar) a la API de nivel inferior, lo que dará como resultado una llamada 401/no autenticada.

4. En el controlador:

   • Agregar using namespace Microsoft.Identity.Abstractions

   • Insertar IDownstreamApi en lugar de IDownstreamWebApi

   • Reemplazar CallWebApiForUserAsync con CallApiForUserAsync

   • Si ha usado uno de los métodos GetForUser, PutForUser o PostForUser, cambie la cadena que expresó la ruta de acceso relativa a un delegado que establece esta ruta de acceso relativa. En el ejemplo siguiente se muestra el enfoque del parámetro de cadena original:

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

     Actualice el código para usar un delegado que establezca la ruta de acceso relativa:

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

Revisión del código de ejemplo

En el ejemplo siguiente se muestra cómo usar IDownstreamApi en una aplicación en funcionamiento.

Consulte el ejemplo completo: ASP.NET Core aplicación web que llama a la API web/TodoListController.

Comparar IDownstreamWebApi y IDownstreamApi

En la tabla siguiente se resumen las diferencias clave entre el en desuso IDownstreamWebApi y el nuevo IDownstreamApi:

Descripción de las ventajas de la migración

La migración a IDownstreamApi proporciona acceso a mejoras continuas y a una superficie de API más flexible.

• IDownstreamWebApi está en desuso y no recibirá nuevas características ni correcciones de errores.
• IDownstreamApi proporciona una superficie de API más limpia, una mejor compatibilidad con la serialización y la personalización de opciones completas.
• La capa de abstracción (Microsoft.Identity.Abstractions) significa que el código de API de bajada no está estrechamente acoplado a una biblioteca de identidades específica.

Exploración del contenido relacionado

Use estos recursos para obtener más información sobre cómo llamar a las API de bajada.

• Visión general de las llamadas a APIs descendentes
• Llamar a APIs personalizadas