Migrar de DownstreamWebApi para DownstreamApi

Examinar o histórico da interface

Microsoft. O Identity.Web 1.x introduziu IDownstreamWebApi, uma interface que manipulava detalhes de autenticação (aquisição de token, cabeçalhos de autorização) ao chamar APIs. À medida que a interface evoluía com base em solicitações de funcionalidades, alterações drásticas se tornaram necessárias para dar suporte a todos os cenários solicitados.

Em vez de modificar a API existente, a equipe criou uma nova interface: IDownstreamApi. A interface antiga foi preterida e todo o desenvolvimento futuro se concentra na nova implementação. Você pode migrar em seu próprio ritmo.

Este artigo explica:

• Como migrar de IDownstreamWebApi para IDownstreamApi
• As diferenças entre IDownstreamWebApi e IDownstreamApi

Migrar de IDownstreamWebApi para IDownstreamApi

Para migrar de IDownstreamWebApi para Microsoft. Identity.Web 2.x e IDownstreamApi:

1. Adicione uma referência ao pacote NuGet Microsoft.Identity.Web.DownstreamApi.

2. No código de inicialização do aplicativo (normalmente Startup.cs ou Program.cs), substitua a chamada de registro antiga:

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

   com a nova chamada de registro:

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

3. No arquivo de configuração (appsettings.json), na seção que representa a API Web downstream, altere o valor de Escopos de uma cadeia de caracteres para uma matriz de cadeias de caracteres. O exemplo a seguir mostra o formato de cadeia de caracteres delimitado por espaço original:

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

   Atualize os escopos para usar o novo formato de matriz:

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

   Aviso

   Se você esquecer de alterar os Escopos para uma matriz, quando tentar usar o IDownstreamApi, os escopos serão exibidos nulos e o IDownstreamApi tentará uma chamada anônima (não autenticada) para a API downstream, o que resultará em um 401/não autenticado.

4. No controlador:

   • Adicionar using namespace Microsoft.Identity.Abstractions

   • Injetar IDownstreamApi em vez de IDownstreamWebApi

   • Substituir CallWebApiForUserAsync por CallApiForUserAsync

   • Se você usou um dos métodos GetForUser, PutForUser ou PostForUser, altere a cadeia de caracteres que expressou o caminho relativo para um delegado que define esse caminho relativo. O exemplo a seguir mostra a abordagem de parâmetro de cadeia de caracteres original:

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

     Atualize o código para usar um delegado que define o caminho relativo:

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

Examinar o código de exemplo

O exemplo a seguir mostra como usar iDownstreamApi em um aplicativo funcional.

Veja o exemplo completo: ASP.NET Core aplicativo Web chamando a API Web/TodoListController.

Comparar IDownstreamWebApi e IDownstreamApi

A tabela a seguir resume as principais diferenças entre os preteridos IDownstreamWebApi e os novos IDownstreamApi:

Entender os benefícios da migração

Migrar para IDownstreamApi fornecer acesso a melhorias contínuas e a uma superfície de API mais flexível.

• IDownstreamWebApi é preterido e não receberá novos recursos ou correções de bug.
• IDownstreamApi fornece uma superfície de API mais limpa, melhor suporte à serialização e personalização de opções completas.
• A camada de abstração (Microsoft.Identity.Abstractions) significa que o código da API downstream não está firmemente acoplado a uma biblioteca de identidade específica.

Explorar o conteúdo relacionado

Use esses recursos para saber mais sobre como chamar APIs downstream.

• Visão geral das APIs downstream
• Chamar APIs personalizadas