자습서: 수정 버전을 사용하여 작업을 중단하지 않는 API 변경을 안전하게 수행

적용 대상: 모든 API Management 계층

API가 준비되고 개발자가 사용하면 결국 해당 API를 변경하고 동시에 API 호출자를 방해하지 않아야 합니다. 이렇게 하면 개발자에게 변경 내용을 알릴 때도 유용합니다.

Azure API Management에서 변경 내용을 안전하게 모델링하고 테스트할 수 있도록 수정 버전을 사용하여 작업을 중단하지 않는 API 변경을 수행합니다. 준비가 되면 현재 수정 버전을 만들고 현재 API를 바꿀 수 있습니다.

배경 정보는 버전 및 수정 버전을 참조하세요.

이 자습서에서는 다음을 하는 방법을 알아볼 수 있습니다.

• 새 수정 버전 추가
• 작업을 중단하지 않고 수정 버전 변경
• 수정 버전을 현재 항목으로 설정하고 변경 로그 항목 추가
• 개발자 포털로 이동하여 변경 내용과 변경 로그 확인
• API 수정 버전에 액세스

필수 조건

• Azure API Management 용어를 익힙니다.
• 다음 빠른 시작 Azure API Management 인스턴스 만들기를 완료합니다.
• 또한, 다음 자습서 첫 번째 API 가져오기 및 게시를 완료합니다.

새 수정 버전 추가

1. Azure Portal에 로그인하고 API Management 인스턴스로 이동합니다.

2. 왼쪽 메뉴의 API 아래에서 API를 선택합니다.

3. API 목록에서 데모 회의 API(또는 수정 버전을 추가하려는 다른 API)를 선택합니다.

4. 수정 버전 탭을 선택합니다.

5. + 수정 버전 추가를 선택합니다.

   

   팁

   API의 바로 가기 메뉴(...)에서 수정 버전 추가를 선택할 수도 있습니다.

6. 새 수정 버전의 용도를 기억하는 데 도움이 되도록 설명을 입력합니다.

7. 만들기를 실행합니다.

8. 이제 새 수정 버전이 작성되었습니다.

   참고 항목

   원본 API는 수정 버전 1로 유지됩니다. 다른 수정 버전을 현재 항목으로 설정할 때까지는 사용자가 이 수정 버전을 계속 호출합니다.

작업을 중단하지 않고 수정 버전 변경

1. API 목록에서 데모 회의 API를 선택합니다.

2. 화면 상단 근처에서 디자인 탭을 선택합니다.

3. 디자인 탭 바로 위에 있는 수정 버전 선택기를 보시면 현재 수정 버전 2를 선택한 것으로 표시됩니다.

   팁

   수정 버전 선택기를 사용하여 작업하려는 수정 버전 간을 전환합니다.

4. + 작업 추가를 선택합니다.

5. 새 작업을 POST로 설정하고 작업의 표시 이름, 이름 및 URL을 테스트로 설정합니다.

6. 새 작업을 저장합니다.

   

7. 이제 수정 버전 2를 변경했습니다. 페이지 상단 근처에 있는 수정 버전 선택기를 사용하여 수정 버전 1로 다시 전환합니다.

8. 새 작업은 수정 버전 1에 표시되지 않습니다.

수정 버전을 현재 항목으로 설정하고 변경 로그 항목 추가

포털

1. 페이지 상단 근처의 메뉴에서 수정 버전 탭을 선택합니다.

2. 수정 버전 2의 상황에 맞는 메뉴(...)를 엽니다.

3. 현재로 설정을 선택합니다.

4. 이 변경 내용에 대한 정보를 게시하려는 경우 이 API에 대한 공용 변경 로그에 게시 확인란을 선택합니다. 개발자가 볼 수 있는 변경 내용에 대한 설명을 제공합니다. 예: 수정 버전 테스트. 새로운 "테스트" 작업이 추가되었습니다.

5. 이제 수정 버전 2가 현재 항목으로 설정되었습니다.

   

Azure CLI

Azure CLI 사용을 시작하려면 다음을 수행합니다.

• Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

  

• CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

  • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

  • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

  • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

이 절차를 통해 릴리스를 만들고 업데이트합니다.

1. az apim api list 명령을 실행하여 API ID를 확인합니다.

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   다음 명령에서 사용할 API ID는 Name 값입니다. API 수정 버전은 ApiRevision 열에 있습니다.

2. 릴리스 정보를 사용하여 릴리스를 만들려면 az apim api release create 명령을 실행합니다.

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   릴리스한 수정 버전은 현재 수정 버전이 됩니다.

3. 릴리스를 보려면 az apim api release list 명령을 사용합니다.

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   지정한 메모가 변경 로그에 나타납니다. 이전 명령의 출력에서 볼 수 있습니다.

4. 릴리스를 생성할 때 --notes 매개 변수는 선택 사항입니다. az apim api release update 명령을 사용하여 나중에 메모를 추가하거나 변경할 수 있습니다.

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   릴리스 ID에 대한 Name 열의 값을 사용합니다.

az apim api release delete 명령을 실행하여 모든 릴리스를 제거할 수 있습니다.

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

개발자 포털로 이동하여 변경 내용과 변경 로그 확인

개발자 포털을 사용해 본 경우 API 변경 내용을 검토하고 여기에서 로그를 변경할 수 있습니다.

1. Azure Portal에서 API Management 인스턴스로 이동합니다.
2. 왼쪽 메뉴의 API 아래에서 API를 선택합니다.
3. 상단 메뉴에서 개발자 포털을 선택합니다.
4. 개발자 포털에서 API를 선택한 다음, 데모 회의 API를 선택합니다.
5. 이제 새 테스트 작업을 사용할 수 있습니다.
6. API 이름 근처에 있는 변경 로그를 선택합니다.
7. 변경 로그 항목이 목록에 나타납니다.

API 수정 버전에 액세스

API에 대한 각 수정 버전에는 특별한 형식의 URL을 사용하여 액세스할 수 있습니다. API URL 경로의 끝에(쿼리 문자열 앞에) ;rev={revisionNumber}을(를) 추가하여 해당 API의 특정 수정 버전에 액세스합니다. 예를 들어 다음 URL을 사용하여 데모 컨퍼런스 API의 수정 버전 2에 액세스할 수 있습니다.

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

Azure Portal의 수정 버전 탭에서 API 수정 버전에 대한 URL 경로를 찾을 수 있습니다.

팁

API 경로에 ;rev={revisionNumber}을(를) 추가하는 전체 URL 외에도 ;rev 문자열 없이 API 경로를 사용하여 API의 현재 수정 버전에 액세스할 수 있습니다.

요약

이 자습서에서는 다음 작업 방법을 알아보았습니다.

• 새 수정 버전 추가
• 작업을 중단하지 않고 수정 버전 변경
• 수정 버전을 현재 항목으로 설정하고 변경 로그 항목 추가
• 개발자 포털로 이동하여 변경 내용과 변경 로그 확인
• API 수정 버전에 액세스

다음 단계

다음 자습서를 진행합니다.

여러 버전의 API 게시