DownstreamWebApi에서 DownstreamApi로 마이그레이션

인터페이스 기록 검토

Microsoft. Identity.Web 1.x는 API를 호출할 때 인증 세부 정보(토큰 획득, 권한 부여 헤더)를 처리하는 인터페이스인 IDownstreamWebApi를 도입했습니다. 기능 요청에 따라 인터페이스가 증가함에 따라 요청된 모든 시나리오를 지원하기 위해 호환성이 손상되는 변경이 필요하게 되었습니다.

팀은 기존 API를 수정하는 대신 IDownstreamApi라는 새 인터페이스를 빌드했습니다. 이전 인터페이스는 더 이상 사용되지 않으며 이후의 모든 개발은 새 구현에 중점을 둡니다. 사용자 고유의 속도로 마이그레이션할 수 있습니다.

이 문서는 다음 사항을 설명합니다.

• IDownstreamWebApi에서 IDownstreamApi로 마이그레이션하는 방법
• IDownstreamWebApi와 IDownstreamApi의 차이점

IDownstreamWebApi에서 IDownstreamApi로 마이그레이션

IDownstreamWebApi에서 Microsoft.Identity.Web 2.x 및 IDownstreamApi로 마이그레이션합니다.

1. Microsoft.Identity.Web.DownstreamApi NuGet 패키지에 대한 참조를 추가합니다.

2. 애플리케이션 초기화 코드(일반적으로 Startup.cs 또는 Program.cs)에서 이전 등록 호출을 대체합니다.

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

   새 등록 호출을 사용하여 다음을 수행합니다.

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

3. 구성 파일(appsettings.json)에서 다운스트림 웹 API를 나타내는 섹션에서 범위 값을 문자열에서 문자열 배열로 변경합니다. 다음 예제에서는 원래 공백으로 구분된 문자열 형식을 보여줍니다.

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

   새 배열 형식을 사용하도록 범위를 업데이트합니다.

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

   경고

   범위를 배열로 변경하는 것을 잊어버린 경우 IDownstreamApi를 사용하려고 하면 범위가 null로 표시되고 IDownstreamApi는 다운스트림 API에 대한 익명(인증되지 않은) 호출을 시도하며, 이로 인해 401/인증되지 않습니다.

4. 컨트롤러에서:

   • using namespace Microsoft.Identity.Abstractions 추가

   • IDownstreamApi 대신 IDownstreamWebApi 삽입

   • CallWebApiForUserAsync를 CallApiForUserAsync로 교체하십시오.

   • GetForUser, PutForUser 또는 PostForUser 메서드 중 하나를 사용한 경우 상대 경로를 나타내는 문자열을 이 상대 경로를 설정하는 대리자에 대해 변경합니다. 다음 예제에서는 원래 문자열 매개 변수 접근 방식을 보여 줍니다.

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

     상대 경로를 설정하는 대리자를 사용하도록 코드를 업데이트합니다.

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

예제 코드 검토

다음 샘플에서는 작업 중인 애플리케이션에서 IDownstreamApi를 사용하는 방법을 보여줍니다.

전체 예제를 참조하세요. ASP.NET Core web API/TodoListController를 호출하는 웹앱.

IDownstreamWebApi 및 IDownstreamApi 비교

더 이상 사용되지 않는 IDownstreamWebApi와 새로운 IDownstreamApi 간의 주요 차이점을 다음 표에서 요약합니다.

마이그레이션 이점 이해

마이그레이션을 IDownstreamApi 통해 지속적인 개선 사항과 보다 유연한 API 화면에 액세스할 수 있습니다.

• IDownstreamWebApi 는 더 이상 사용되지 않으며 새 기능 또는 버그 수정을 받지 않습니다.
• IDownstreamApi 는 보다 깨끗한 API 표면, 더 나은 serialization 지원 및 전체 옵션 사용자 지정을 제공합니다.
• 추상화 계층(Microsoft.Identity.Abstractions)은 다운스트림 API 코드가 특정 ID 라이브러리와 긴밀하게 결합되지 않음을 의미합니다.

관련 콘텐츠 탐색

이러한 리소스를 사용하여 다운스트림 API 호출에 대해 자세히 알아보세요.

• 호출 다운스트림 API 개요
• 사용자 지정 API 호출