Migrar de DownstreamWebApi para DownstreamApi

Rever o histórico da interface

Microsoft. O Identity.Web 1.x introduziu IDownstreamWebApi, uma interface que tratava dos detalhes de autenticação (aquisição de tokens, cabeçalhos de autorização) ao chamar APIs. À medida que a interface crescia com base nos pedidos de funcionalidades, tornaram-se necessárias alterações para suportar todos os cenários solicitados.

Em vez de modificar a API existente, a equipa construiu uma nova interface: IDownstreamApi. A interface antiga está obsoleta e todo o desenvolvimento futuro foca-se na nova implementação. Podes migrar ao teu 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 da sua candidatura (normalmente Startup.cs ou Program.cs), substitua a chamada de registo antiga:

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

   Com a nova chamada de registro:

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

3. No ficheiro de configuração (appsettings.json), na secção que representa a API web a jusante, altere o valor Scopes de uma string para um array de strings. O exemplo seguinte mostra o formato original de string delimitado por espaço:

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

   Atualize os telescópios para usar o novo formato de array:

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

   Advertência

   Se se esquecer de mudar os Scopes para um array, ao tentar usar o IDownstreamApi os scopes aparecerão nulos, e o IDownstreamApi tentará uma chamada anónima (não autenticada) para a API downstream, o que resultará num 401/unauthenticated.

4. No comando:

   • Adicionar using namespace Microsoft.Identity.Abstractions

   • Injetar IDownstreamApi em vez de IDownstreamWebApi

   • Substituir CallWebApiForUserAsync por CallApiForUserAsync

   • Se usar um dos métodos GetForUser, PutForUser ou PostForUser, altere a cadeia que expressava o caminho relativo para um delegado que define esse caminho relativo. O exemplo seguinte mostra a abordagem original dos parâmetros de string:

     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}";);
     

Revisão de código de exemplo

O exemplo seguinte mostra como usar o IDownstreamApi numa aplicação funcional.

Veja o exemplo completo: aplicação ASP.NET Core que chama a API Web/TodoListController.

Compare IDownstreamWebApi e IDownstreamApi

A tabela seguinte resume as principais diferenças entre o obsoleto IDownstreamWebApi e o novo IDownstreamApi:

Compreenda os benefícios da migração

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

• IDownstreamWebApi está obsoleto e não recebe novas funcionalidades nem correções de bugs.
• IDownstreamApi proporciona uma superfície API mais limpa, melhor suporte para serialização e personalização completa de opções.
• A camada de abstração (Microsoft.Identity.Abstractions) significa que o seu código API a jusante não está fortemente ligado a uma biblioteca de identidade específica.

Explorar conteúdo relacionado

Use estes recursos para aprender mais sobre como chamar APIs a jusante.

• Visão geral das APIs de chamada para downstream
• Chamar APIs personalizadas