Git을 사용하여 API Management 서비스 구성을 저장 및 구성하는 방법

적용 대상: 개발자 | 기본 | 표준 | 프리미엄

각 API Management 서비스 인스턴스는 구성에 관한 정보 및 서비스 인스턴스에 대한 메타데이터를 포함하고 있는 구성 데이터베이스를 유지관리합니다. Azure Portal에서 설정을 변경하거나, Azure PowerShell 또는 Azure CLI와 같은 Azure 도구를 사용하거나, REST API 호출을 수행하여 서비스 인스턴스를 변경할 수 있습니다. 이러한 방법 외에도 Git을 사용하여 서비스 인스턴스 구성을 관리하고, 다음과 같은 시나리오를 지원할 수 있습니다.

• 구성 버전 관리 - 서비스 구성의 서로 다른 버전 다운로드 및 저장
• 대량 구성 변경 - 로컬 리포지토리에 있는 서비스 구성의 여러 부분을 변경하고 단일 작업으로 변경 내용을 서버에 다시 통합
• 친숙한 Git 도구 체인 및 워크플로 - 이미 익숙해진 Git 도구 및 워크플로 사용

다음 다이어그램에서는 API Management 서비스 인스턴스를 구성하는 다양한 방법을 간략하게 보여 줍니다.

Azure Portal, Azure PowerShell 또는 Azure CLI와 같은 Azure 도구, REST API를 사용하여 서비스를 변경할 때는 다이어그램 오른쪽에 표시된 것처럼 https://{name}.management.azure-api.net 엔드포인트를 사용하여 서비스 구성 데이터베이스를 관리합니다. 다이어그램의 왼쪽은 https://{name}.scm.azure-api.net에 있는 서비스에 Git 및 Git 리포지토리를 사용하여 서비스 구성을 관리할 수 있는 방법을 보여 줍니다.

다음 단계는 Git을 이용한 API Management 서비스 인스턴스 관리를 간략하게 보여 줍니다.

1. 서비스의 Git 구성에 액세스
2. Git 리포지토리에 서비스 구성 데이터베이스 저장
3. 로컬 컴퓨터에 Git 리포지토리 복제
4. 리포지토리를 로컬 컴퓨터에 풀하고 커밋한 다음 변경 내용을 리포지토리에 다시 푸시
5. 리포지토리의 변경 내용을 서비스 구성 데이터베이스에 배포

이 문서에서는 Git를 사용하도록 설정하고 이를 사용하여 서비스 구성을 관리하는 방법을 설명하며 Git 리포지토리의 파일 및 폴더에 대한 참조를 제공합니다.

Important

이 기능은 내보내기 크기가 10MB 미만이거나 항목 수가 10,000개 미만인 것과 같은 중소 규모의 API 관리 서비스 구성을 지원하도록 설계되었습니다. 제품, API, 작업, 스키마 등 항목 수가 많은 서비스는 Git 명령을 처리할 때 예기치 않은 오류가 발생할 수 있습니다. 이러한 오류가 발생하는 경우 서비스 구성의 크기를 줄이고 다시 시도하세요. 지원이 필요하면 Azure 지원에 문의하세요.

서비스의 Git 구성에 액세스

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

2. 왼쪽 메뉴에 있는 배포 및 인프라에서 리포지토리를 선택합니다.

Git 리포지토리에 서비스 구성 저장

주의

명명된 값으로 정의되지 않은 비밀은 리포지토리에 저장되고 기록에 유지됩니다. 명명된 값은 모든 API 구성 및 정책에 대해 비밀을 포함한 상수 문자열 값을 관리하는 안전한 장소를 제공하므로 정책을 정책 설명에 직접 저장할 필요가 없습니다. 자세한 내용은 Azure API Management 정책에서 명명된 값 사용을 참조하세요.

리포지토리를 복제하기 전에 서비스 구성의 현재 상태를 리포지토리에 저장합니다.

1. 리포지토리 페이지에서 리포지토리에 저장을 선택합니다.

2. 확인 화면에서 구성 저장을 위한 분기 이름과 같이 원하는 항목을 변경하고 저장을 선택합니다.

몇 분 후에 구성이 저장되며, 마지막 구성 변경 및 서비스 구성과 리포지토리 간 마지막 동기화의 날짜 및 시간을 비롯하여 리포지토리의 구성 상태가 표시됩니다.

구성이 리포지토리에 저장된 후 해당 구성을 복제할 수 있습니다.

REST API를 사용하는 서비스 구성 저장에 대한 자세한 내용은 테넌트 구성 - 저장을 참조하세요.

액세스 자격 증명 가져오기

리포지토리에 대한 URL 외에도 리포지토리를 복제하려면 사용자 이름과 암호가 필요합니다.

1. 리포지토리 페이지에서 페이지 상단 근처에 있는 액세스 자격 증명을 선택합니다.

2. 액세스 자격 증명 페이지에 제공된 사용자 이름을 확인합니다.

3. 암호를 생성하려면 먼저 만료가 원하는 만료 날짜 및 시간으로 설정되었는지 확인한 다음, 생성을 선택합니다.

Important

이 암호를 기록해 둡니다. 이 페이지를 떠나면 암호가 다시 표시되지 않습니다.

로컬 컴퓨터에 리포지토리를 복제합니다.

다음 예제에서는 Windows용 Git에서 Git Bash 도구가 사용되지만 자신에게 익숙한 아무 Git 도구나 사용할 수 있습니다.

원하는 폴더에서 Git 도구를 열고 다음 명령을 실행하여 Git 리포지토리를 로컬 머신에 복제합니다.

git clone https://{name}.scm.azure-api.net/

메시지가 표시되면 사용자 이름 및 암호를 제공합니다.

오류가 발생하면 다음 예제와 같이 git clone 명령을 사용자 이름 및 암호를 포함하도록 수정해 보십시오.

git clone https://username:password@{name}.scm.azure-api.net/

그래도 오류가 발생하면 명령의 암호 부분에 대해 URL 인코딩을 시도해 보십시오. 이렇게 하는 한 가지 빠른 방법은 Visual Studio를 열고 직접 실행 창에서 다음 명령을 실행하는 것입니다. 직접 실행 창을 열려면 Visual Studio에서 솔루션 또는 프로젝트를 열고(또는 비어 있는 새 콘솔 애플리케이션을 만들고) 디버그 메뉴에서 창, 직접 실행을 선택합니다.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

사용자 이름 및 리포지토리 위치와 함께 인코딩된 암호를 사용하여 Git 명령을 생성합니다.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

복제가 완료되면 다음과 같은 명령을 실행하여 디렉터리를 리포지토리로 변경합니다.

cd {name}.scm.azure-api.net/

기본 분기(master)가 아닌 다른 분기에 구성을 저장한 경우 해당 분기를 확인합니다.

git checkout <branch_name>

리포지토리가 복제된 후 로컬 파일 시스템에서 이를 보고 작업할 수 있습니다. 자세한 내용은 로컬 Git 리포지토리의 파일 및 폴더 구조 참조를 참조하세요.

최신 서비스 인스턴스 구성으로 로컬 리포지토리 업데이트

Azure Portal에서 또는 다른 Azure 도구를 사용하여 API Management 서비스 인스턴스를 변경하는 경우 변경 내용을 리포지토리에 저장해야 로컬 리포지토리를 최신 변경 내용으로 업데이트할 수 있습니다.

Azure Portal을 사용하여 변경 내용을 저장하려면 API Management 인스턴스에 대해 리포지토리 탭에서 리포지토리에 저장을 선택합니다.

그런 다음, 로컬 리포지토리를 업데이트합니다.

1. 현재 로컬 리포지토리의 폴더에 있는지 확인합니다. git clone 명령을 방금 완료한 경우 다음과 같은 명령을 실행하여 디렉터리를 리포지토리로 변경해야 합니다.

   cd {name}.scm.azure-api.net/
   

2. 로컬 리포지토리의 폴더에서 다음 명령을 실행합니다.

   git pull
   

로컬 리포지토리의 변경 내용을 서버 리포지토리 푸시

로컬 리포지토리의 변경 내용을 서버 리포지토리에 푸시하려면 변경 내용을 커밋한 다음 이를 서버 리포지토리에 게시해야 합니다. 변경 내용을 커밋하려면 Git 명령 도구를 열고 로컬 리포지토리의 디렉터리로 전환한 후 다음 명령을 실행합니다.

git add --all
git commit -m "Description of your changes"

모든 커밋을 서버에 푸시하려면 다음 명령을 실행합니다.

git push

서비스 구성 변경 내용을 API Management 서비스 인스턴스에 배포

로컬 변경 내용이 커밋되고 서버 리포지토리에 푸시된 후 이를 API Management 서비스 인스턴스에 배포할 수 있습니다.

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

2. 왼쪽 메뉴에 있는 배포 및 인프라에서 리포지토리>API Management에 배포를 선택합니다.

3. 리포지토리 구성 배포 페이지에서 원하는 구성 변경 내용이 포함된 분기 이름을 입력하고 선택적으로 삭제된 제품의 구독 제거를 선택합니다. 저장을 선택합니다.

REST API를 사용하여 이 작업을 수행하는 방법은 테넌트 구성 - 배포를 참조하세요.

로컬 Git 리포지토리의 파일 및 폴더 구조 참조

로컬 Git 리포지토리의 파일 및 폴더에는 서비스 인스턴스에 대한 구성 정보가 포함되어 있습니다.

항목	설명
루트 api 관리 폴더	서비스 인스턴스에 대한 최상의 구성 포함
apiReleases 폴더	서비스 인스턴스에서 API 릴리스의 구성 포함
apis 폴더	서비스 인스턴스에서 API의 구성 포함
apiVersionSets 폴더	서비스 인스턴스에서 API 버전 집합에 대한 구성 포함
backends 폴더	서비스 인스턴스에서 백엔드 리소스의 구성 포함
groups 폴더	서비스 인스턴스의 그룹에 대한 구성 포함
policies 폴더	서비스 인스턴스의 정책 포함
portalStyles 폴더	서비스 인스턴스의 개발자 포털 사용자 지정에 대한 구성 포함
portalTemplates 폴더	서비스 인스턴스에서 개발자 포털 템플릿에 대한 구성 포함
products 폴더	서비스 인스턴스의 제품에 대한 구성 포함
templates 폴더	서비스 인스턴스의 전자 메일 템플릿에 대한 구성 포함

각 폴더는 하나 이상의 파일 및 하나 이상의 폴더, 예를 들어 각 API, 제품 또는 그룹에 대한 폴더를 포함할 수 있습니다. 각 폴더 내의 파일은 폴더 이름에 의해 설명된 엔터티 유형에 대해 적용됩니다.

파일 형식	목적
json	해당 엔터티에 관한 구성 정보
html	대개 개발자 포털에 표시되는 엔터티에 관한 설명
xml	정책 설명
css	개발자 포털 사용자 지정에 대한 스타일 시트

이러한 파일은 로컬 파일 시스템에서 생성, 삭제, 편집 및 관리할 수 있으며 변경 내용을 API Management 서비스 인스턴스에 다시 배포할 수 있습니다.

참고 항목

다음 엔터티는 Git 리포지토리에 포함되지 않으며 Git를 사용하여 구성할 수 없습니다.

• 사용자
• 구독
• 명명된 값
• 스타일 및 템플릿 이외의 개발자 포털 엔터티
• 정책 조각

루트 api 관리 폴더

루트 api-management 폴더에는 다음과 같은 형식의 서비스 인스턴스에 관한 최상위 정보를 포함하고 있는 configuration.json 파일이 포함되어 있습니다.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

처음 네 설정(RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled, UserRegistrationTermsConsentRequired)은 개발자 포털 섹션의 ID 탭에 있는 다음 설정에 매핑됩니다.

Id 설정	다음에 맵핑
RegistrationEnabled	사용자 이름 및 암호 ID 공급자의 현재 상태
UserRegistrationTerms	사용자 등록 시 사용 약관 텍스트 상자
UserRegistrationTermsEnabled	등록 페이지에 사용 약관 표시 확인란
UserRegistrationTermsConsentRequired	동의 필요 확인란
RequireUserSigninEnabled	로그인 페이지로 익명 사용자 리디렉션 확인란

처음 네 설정(DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled, DelegationValidationKey)은 개발자 포털 섹션의 위임 탭에 있는 다음 설정에 매핑됩니다.

위임 설정	다음에 맵핑
DelegationEnabled	로그인 및 등록 위임 확인란
DelegationUrl	위임 엔드포인트 URL 텍스트 상자
DelegatedSubscriptionEnabled	제품 구독 위임 확인란
DelegationValidationKey	유효성 검사 키 위임 텍스트 상자

마지막 설정 $ref-policy은 서비스 인스턴스에 대한 전역 정책 설명 파일에 매핑됩니다.

apiReleases 폴더

apiReleases 폴더에는 프로덕션 API에 배포된 각 API 릴리스의 폴더와 다음 항목이 포함됩니다.

• apiReleases\<api release Id>\configuration.json - 릴리스 날짜 정보를 포함하는 릴리스 구성입니다. 이는 특정 릴리스 가져오기 작업을 호출하려는 경우에 반환되는 것과 동일한 정보입니다.

apis 폴더

apis 폴더에는 다음 항목을 포함한 서비스 인스턴스의 각 API에 대한 폴더가 포함되어 있습니다.

• apis\<api name>\configuration.json - 백엔드 서비스 URL 및 작업에 대한 정보를 포함하는 API 구성입니다. 이는 특정 API 가져오기 작업을 호출하려는 경우에 반환되는 것과 동일한 정보입니다.
• apis\<api name>\api.description.html - REST API에서 API 엔터티에 대한 description 속성에 해당하는 API에 대한 설명입니다.
• apis\<api name>\operations\ - API의 작업에 매핑되는 <operation name>.description.html 파일을 포함하는 폴더입니다. 각 파일은 REST API에서 작업 엔터티의 description 속성에 매핑되는 API의 단일 작업에 대한 설명을 포함하고 있습니다.

apiVersionSets 폴더

apiVersionSets 폴더에는 API에 대해 생성된 각 API 버전 집합의 폴더와 다음 항목이 포함됩니다.

• apiVersionSets\<api version set Id>\configuration.json - 버전 집합에 대한 구성입니다. 이는 특정 버전 집합 가져오기 작업을 호출하려는 경우에 반환되는 것과 동일한 정보입니다.

groups 폴더

groups 폴더는 서비스 인스턴스에 정의된 각 그룹에 대한 폴더를 포함하고 있습니다.

• groups\<group name>\configuration.json - 그룹에 대한 구성입니다. 이는 특정 그룹 가져오기 를 호출하려는 경우 반환되는 것과 같은 정보입니다.
• groups\<group name>\description.html - 그룹에 대한 설명이며 그룹 엔터티의 description 속성에 해당합니다.

policies 폴더

policies 폴더에는 서비스 인스턴스에 대한 정책 설명이 포함되어 있습니다.

• policies\global.xml - 서비스 인스턴스에 대해 전역 범위에 정의된 정책입니다.
• policies\apis\<api name>\ - API 범위에 정의된 정책이 있으면 이 폴더에 포함됩니다.
• policies\apis\<api name>\<operation name>\ 폴더 - 작업 범위에 정의된 정책이 있으면 각 작업에 대해 정책 설명에 매핑되는 <operation name>.xml 파일의 이 폴더에 포함됩니다.
• policies\products\ - 제품 범위에 정의된 정책이 있으면 각 제품에 대해 정책 설명에 매핑되는 <product name>.xml 파일이 들어 있는 이 폴더에 포함됩니다.

portalStyles 폴더

portalStyles 폴더에는 서비스 인스턴스의 사용되지 않는 개발자 포털을 사용자 지정하기 위한 구성 및 스타일 시트가 포함되어 있습니다.

• portalStyles\configuration.json - 개발자 포털에서 사용하는 스타일 시트의 이름이 포함되어 있습니다.
• portalStyles\<style name>.css - 각 <style name>.css 파일에는 개발자 포털에 대한 스타일(기본적으로 Preview.css 및 Production.css)이 포함되어 있습니다.

portalTemplates 폴더

portalTemplates 폴더에는 서비스 인스턴스의 사용되지 않는 개발자 포털을 사용자 지정하기 위한 템플릿이 포함되어 있습니다.

• portalTemplates\<template name>\configuration.json - 템플릿의 구성입니다.
• portalTemplates\<template name>\<page name>.html - 템플릿의 원본 및 수정된 HTML 페이지입니다.

products 폴더

products 폴더는 서비스 인스턴스에 정의된 각 제품에 대한 폴더를 포함하고 있습니다.

• products\<product name>\configuration.json - 제품에 대한 구성입니다. 이는 특정 제품 가져오기 를 호출하려는 경우 반환되는 것과 같은 정보입니다.
• products\<product name>\product.description.html - REST API에서 제품 엔터티의 description 속성에 해당하는 제품에 대한 설명입니다.

템플릿

templates 폴더에는 서비스 인스턴스의 전자 메일 템플릿 에 대한 구성이 포함되어 있습니다.

• <template name>\configuration.json - 이메일 템플릿에 대한 구성입니다.
• <template name>\body.html - 이메일 템플릿의 본문입니다.

다음 단계

서비스 인스턴스를 관리하는 다른 방법에 대한 자세한 내용은 다음을 참조하세요.

• Azure PowerShell cmdlet 참조
• Azure CLI 참조
• API Management REST API 참조
• Azure SDK 릴리스