API 센터 시작
이 연습에서 다음을 수행합니다.
API Center 서비스를 만듭니다.
메타데이터 속성을 정의합니다.
API 센터에 API를 추가합니다.
배포와 환경을 추가합니다.
필수 조건
API 센터를 통해 API 관리를 시작하려면 다음이 필요합니다.
- Azure 구독
- 구독에 등록된 Microsoft.ApiCenter 리소스 공급자입니다.
- Azure 구독에서 기여자 역할 할당 또는 동등한 권한.
참고 항목
아직 등록하지 않았다면 구독에 Microsoft.ApiCenter 리소스 공급자를 등록해야 합니다.
- Azure Portal에 로그인합니다.
- 검색 창에 구독을 입력합니다.
- API Center를 만들려는 구독을 선택합니다.
- 왼쪽 메뉴의 리소스에서 리소스 공급자를 선택합니다.
- 리소스 공급자 목록에서 Microsoft.ApiCenter를 검색합니다. 등록되지 않은 경우 등록을 선택합니다.
1단계: API Center 서비스 만들기
Azure Portal에 로그인합니다.
검색 창에 API 센터를 입력합니다.
+ 만들기를 선택합니다.
기본 사항 탭에서 다음 설정을 선택하거나 입력합니다.
a. Azure 구독을 선택합니다.
b. 기존 리소스 그룹을 선택하거나 새로 만들기를 선택하여 새 리소스 그룹을 만듭니다.
c. API 센터의 이름을 입력합니다. API 센터를 만드는 지역에서 고유해야 합니다.
d. 지역에서 API 센터에 대해 사용 가능한 지역 중 하나를 선택합니다.
e. 가격 책정 플랜의 경우 평가판(90일 동안 $0)을 선택합니다.
f. 검토 + 만들기를 선택합니다.
h. 유효성 검사가 완료되면 만들기를 선택합니다.
배포 후에는 API 센터를 사용할 준비가 된 것입니다.
CLI 참조 명령을 로컬로 실행하려면 Azure CLI를 설치하고 다음 명령을 사용하여 로그인합니다.
az login
참고 항목
아직 등록하지 않았다면 구독에 Microsoft.ApiCenter 리소스 공급자를 등록해야 합니다.
리소스 공급자를 등록하려면 다음 명령 실행
az provider register –namespace Microsoft.ApiCenter
1단계: API Center 서비스 만들기
다음 명령을 실행하여 다음을 전달하는 리소스 그룹을 만듭니다.
- 리소스 그룹 이름 --name 예. Contoso
- 위치 --location 예. Eastus
az group create –-name contoso –-location eastus
참고 항목
az apic 명령에는 apic-extension Azure CLI 확장이 필요합니다. az apic 명령을 사용하지 않은 경우 첫 번째 az apic 명령을 실행할 때 확장이 동적으로 설치되거나 확장을 수동으로 설치할 수 있습니다. Azure CLI 확장에 대해 자세히 알아보세요.
다음 명령을 실행하여 API 센터를 만들고 다음을 전달합니다.
- API Center 서비스 이름 -n 예. contoso-apis
- 리소스 그룹 -g 예. Contoso
- 위치 --l 예. Eastus
az apic create -n contoso-apis -g contoso -l eastus
참고 항목
기본적으로 API 센터는 무료 가격 책정 계층에서 만들어집니다.
참고 항목
현재 VS Code에서는 API Center 서비스를 만들 수 없습니다. Azure CLI 또는 Azure Portal을 사용하여 만듭니다.
2단계: 메타데이터 속성 정의
API 센터는 메타데이터 속성을 사용하여 인벤토리에서 API를 구성하고 필터링, 검색 등과 같은 작업을 사용하도록 설정합니다.
참고 항목
메타데이터 속성 제목/이름에 중요한, 기밀 또는 개인 정보를 포함하지 마세요.
Contoso는 다른 많은 조직과 마찬가지로 모든 API가 사용 가능해지기 전에 승인자를 통과하고 모든 API에 대해 규정 준수 검토가 수행되도록 하고 싶습니다. 또한 조직에는 공용 API와 내부 전용으로만 빌드된 API가 있습니다. 모든 API에서 대규모로 이를 적용하기 위해 세 가지 사용자 지정 메타데이터 속성을 추가합니다.
- 문자열 유형의 API 승인자
- 미리 정의된 선택 유형의 규정 준수 검토
- 부울 유형의 공용
왼쪽 메뉴에서 자산 > 메타데이터 > + 새 메타데이터를 선택합니다.
세부 정보 탭에서 속성에 대한 정보를 입력합니다.
a. 제목에 API 승인자를 입력합니다.
b. 설명에 기본 API 승인자를 입력합니다.
c. 문자열 유형을 선택하고 다음을 선택합니다.
할당 탭에서 API에 필수를 선택합니다. 배포 및 환경에 대해 선택 사항을 선택합니다. 다음을 선택합니다.
만들기를 선택합니다.
아래 이미지와 같이 공용 속성에 대해 동일한 단계를 반복합니다. 유형에 부울을 선택합니다.
할당 탭에서 API에 필수를 선택합니다. 배포 및 환경에 대해 적용할 수 없음을 선택합니다. 다음을 선택합니다.
만들기를 선택합니다.
아래 이미지와 같이 규정 준수 검토 속성에 대해 동일한 단계를 반복합니다. 유형에 미리 정의된 선택을 선택하고 시작 안 됨, 진행 중 및 완료의 선택 항목 3개를 추가합니다
할당 탭에서 API에 필수를 선택합니다. 배포 및 환경에 해당 없음을 선택합니다.
다음을 선택합니다.
이제 API에 대한 JSON 메타데이터 스키마를 보고, 편집하고, 다운로드할 수 있습니다. 보려면 메타데이터 스키마 보기를 선택하고 드롭다운에서 API를 선택합니다.
이렇게 하면 메타데이터 세부 정보가 있는 모달이 오른쪽에 열립니다. 여기에는 LifecycleStage, Name, Description, TermsOfService 같은 API 센터의 기본 제공 속성이 포함됩니다. 파일 아래쪽으로 스크롤하면 아래와 같이 이전 단계에서 추가한 사용자 지정 메타데이터가 표시됩니다.
참고 항목
언제든지 스키마의 속성을 추가하고 편집하고 API 센터의 모든 API에 즉시 적용할 수 있습니다.
다음 명령을 실행하여 새 메타데이터 스키마를 만들어 다음을 설정합니다.
- 이름이 api-approver인 메타데이터
- 속성 형식이 문자열이고 제목이 API 승인자인 스키마
- 할당은 API의 경우 필수이고 환경 및 배포의 경우 선택 사항입니다.
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
다음에 대해 동일한 단계를 반복합니다.
- 이름이 public-facing인 메타데이터
- 속성 형식이 부울이고 제목이 공용인 스키마
- 할당은 API의 경우 필수이고 환경 및 배포의 경우 선택 사항입니다.
다음 명령을 실행합니다.
az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
마지막으로 다음에 대해 동일한 단계를 반복합니다.
- 이름이 compliance-review인 메타데이터
- 속성 형식이 문자열이고 제목이 규정 준수 검토인 스키마
- 할당은 API의 경우 필수이고 환경 및 배포의 경우 선택 사항입니다.
다음 명령을 실행합니다.
az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
다음 명령을 실행하여 API Center에 정의된 모든 메타데이터 목록을 볼 수 있습니다.
az apic metadata list -g <resource-group-name> -n <api-center-name>
참고 항목
언제든지 스키마의 속성을 추가하고 편집하고 API 센터의 모든 API에 즉시 적용할 수 있습니다.
참고 항목
이 작업은 현재 VS Code에서 지원되지 않습니다. Azure CLI 또는 Azure Portal을 사용하여 만듭니다.
3단계: 인벤토리에 API 추가
Contoso 조직은 내부 기술 드라이브의 일부로 엔지니어링 팀에 대한 기술 컨퍼런스를 추천하려고 합니다. 발표자, 세션 및 토픽이 포함된 컨퍼런스 API를 추가합니다.
컨퍼런스 API URL: https://bigconference.azurewebsites.net/
다음 단계에서는 위 웹 사이트에서 OpenAPI 정의를 복사하여 로컬 컴퓨터에 JSON 파일로 저장할 수 있습니다. 또는 인벤토리에 API를 추가할 때 다른 API 정의로 대체합니다.
포털에서 API 센터로 이동합니다.
왼쪽 메뉴에서 자산 > API > + API 등록을 선택합니다.
API 등록 페이지에서 API에 대해 다음 필수 정보를 추가합니다. 페이지 맨 아래에 있는 이전 단계에서 정의한 사용자 지정 API 승인자, *공용 및 규정 준수 검토 메타데이터 속성이 표시됩니다.
만든 API를 보려면 왼쪽 메뉴에서 자산 > API > 컨퍼런스 API를 선택합니다.
개요 탭은 API 구성의 보기를 제공합니다. 세부 정보를 확장하여 API 버전 및 배포와 같은 추가 정보를 보고 편집합니다(현재 배포 없음).
일반적으로 API 버전에 대한 API 정의를 추가하려고 하며 API 센터는 OpenAPI 2, REST용 OpenAPI 3을 비롯한 텍스트 사양 형식을 지원합니다.
정의를 추가하려면,
- 왼쪽 메뉴에서 자산 > API > API(컨퍼런스 API) 선택을 선택합니다.
- 세부 정보를 확장하고 버전을 선택합니다.
- 버전(v1)을 선택하고 세부 정보를 확장합니다.
- 세부 정보에서 정의 > 정의 추가를 선택합니다.
Visual Studio Code용 Azure API 센터 확장을 사용하여 API 인스턴스에 API를 등록할 수 있습니다.
1단계: 확장 설치
2단계: ‘Ctrl + Shift + P’로 명령 팔레트를 열고 API 센터: API 등록을 입력합니다.
프롬프트에 따라 API에 대해 다음 정보를 제공합니다.
| API 등록 | 단계별 |
|---|---|
| API 센터 서비스 선택 | API 센터 인스턴스 선택 |
| API 제목 | API (컨퍼런스 API)의 이름 입력 |
| API 형식 | REST |
| API 버전 제목 | API (v1) 버전 이름 입력 |
| API 버전 수명 주기 | 드롭다운 (개발)에서 수명 주기 선택 |
| API 정의 제목 | 정의 (컨퍼런스 API 정의)의 이름 입력 |
| API 사양 이름 | 드롭다운 (OpenAPI 2)에서 사양 선택 |
| 가져올 API 정의 파일 선택 | 스토리지에서 정의 파일 찾아 선택 |
API 센터 확장 탭을 새로 고치면 새로 만든 API가 해당 APIC 인스턴스/리소스에 표시됩니다.
다음 명령을 사용하여 새 API를 만들고 다음을 전달합니다.
- 리소스 그룹 -g 예. Contoso
- API Center 서비스 이름 -n 예. contoso-api-center
- 제목 --title 예. 컨퍼런스 API
- API ID --api-id 예. conference-api
- 형식 --type 예. REST (영문)
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
다음 명령을 사용하여 API 버전을 만들고 다음을 전달합니다.
- 리소스 그룹 -g 예. contoso
- API Center 서비스 이름 -n 예. contoso-apis
- API ID --api-id 예. conference-api
- 제목 --title 예. v1.2.2
- 버전 ID --version-id 예. 2024-07-03
- 수명 주기 단계 --lifecycle-stage 예. 설계
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design
API 버전에 대한 API 정의를 추가할 수도 있으며 API Center는 REST용 OpenAPI 2, OpenAPI 3을 비롯한 텍스트 사양 형식을 지원합니다.
정의를 추가하려면 다음 명령을 사용하여 다음을 전달합니다.
- 리소스 그룹 -g 예. contoso
- API Center 서비스 이름 -n 예. contoso-apis
- API ID --api-id 예. conference-api
- 버전 ID --version-id 예. 2024-07-03
- 제목 --title 예. OpenAPI
- 정의 ID --definition-id 예. openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi
URL에서 OpenAPI 정의 파일을 가져오려면 az apic api definition import-specification 명령을 사용하여 가져옵니다. 예: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples
az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'
4단계: 배포 및 환경 추가
환경
환경(개발, 테스트, 스테이징 또는 프로덕션)은 API 런타임이 배포되는 위치를 나타냅니다. Contoso의 API 플랫폼 엔지니어는 API Center 인스턴스에서 테스트와 프로덕션이라는 두 가지 환경을 정의하여 조직의 다양한 API 런타임을 관리하고 추적합니다.
환경을 만들려면,
왼쪽 메뉴에서 자산 > 환경 > + 새 환경을 선택합니다.
다음 정보를 추가합니다.
만들기를 실행합니다.
프로덕션 환경에 대해 동일한 단계를 반복합니다.
환경을 만들려면 다음 CLI 명령 실행
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
프로덕션 환경에 대해 동일한 작업 반복
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
참고 항목
환경 만들기는 현재 VS Code에서 지원되지 않습니다. 이 단계에서는 Azure CLI 또는 Azure Portal 옵션을 사용하세요.
배포
사용자가 API와 상호 작용할 수 있는 고유한 위치(주소)는 지정된 환경의 각 API 런타임에 대해 제공됩니다. 이 위치를 배포라고 하며 단일 API 버전에는 스테이징 및 프로덕션 배포라는 두 개의 배포가 있을 수 있습니다.
Contoso에는 만든 환경과 연결하는 하나의 API인 컨퍼런스 API가 있습니다.
포털에서 API 센터로 이동합니다.
왼쪽 메뉴에서 API를 선택한 다음 API(예: 컨퍼런스 API)를 선택합니다.
컨퍼런스 API 페이지에서 세부 정보 > 배포 > + 배포 추가를 확장합니다.
다음 정보를 추가합니다.
a. 환경 필드의 드롭다운에서 Contoso 테스트를 선택합니다.
b. 정의에 대해 선택을 클릭하고, 드롭다운에서 API 버전 v1을 선택하고 이전에 추가한 정의를 선택합니다. 선택을 클릭합니다.
c. 정의를 성공적으로 추가한 후 선택한 환경에서 API에 특정한 기본 런타임 URL을 추가합니다.
배포를 만들고 이를 위 단계에서 만든 환경과 연결하려면 다음 CLI 명령 실행
az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'
참고 항목
현재 VS Code에서는 배포 만들기가 지원되지 않습니다. 이 단계에서는 Azure CLI 또는 Azure Portal 옵션을 사용하세요.