API 거버넌스
API 거버넌스는 모든 조직 API에서 표준, 정책, 프로세스를 대규모로 정의하고 적용하는 방식으로 정의됩니다. API 센터를 사용하여 다음을 통해 이를 수행할 수 있습니다.
- API 제목, 설명, 버전, 정의 및 배포를 포함한 API 메타데이터 추적. 또한 라이브 사이트 정보, 소스 제어 리포지토리 등과 같은 사용자 지정 API 메타데이터를 지정하여 조직에 중요한 메타데이터를 추적할 수 있습니다(이전 모듈에서 설명).
- 모든 API가 조직 API 디자인 규칙을 준수하게 디자인되도록 보장
- API 소비자의 원활한 롤아웃 및 통신을 위해 호환성이 손상되는 변경이 있는 API 버전을 적시에 검색하도록 보장
이 단원에서는 API 센터가 API 거버넌스를 대규모로 구성하도록 어떻게 지원하는지 살펴보겠습니다.
필수 조건
API 센터를 사용하여 API를 관리하려면 다음이 필요합니다.
- Azure CLI를 설치합니다.
- Azure 개발자 CLI(azd)를 설치합니다.
- 구독에 Event Grid 리소스 공급자를 등록합니다. Event Grid 리소스 공급자를 등록해야 하는 경우 Azure Event Grid를 사용하여 파트너가 게시한 이벤트 구독을 참조하세요.
API 디자인 적합성
API 플랫폼 팀에는 종종 API 생산자에 대한 일련의 지침을 정의하는 책임이 주어집니다. API 센터를 사용하면 Spectral 오픈 소스 린팅 엔진으로 규칙을 정의하여 API 지침을 체계화할 수 있습니다. 기본적으로 API 센터에는 제공된 Spectral 규칙이 있지만 사용자는 언제든지 자체적으로 규칙을 빌드하거나 오픈 소스 규칙 세트의 대규모 커뮤니티를 활용할 수 있습니다. API 정의가 업로드될 때마다 API 센터는 제공된 규칙 집합을 사용하여 Spectral 린터를 실행하여 API 정의가 규칙을 준수하는지 확인합니다. API 센터에서 볼 수 있는 API 준수 보고서가 생성됩니다.
조직에 대한 API 디자인 준수를 구성하려면 다음을 수행합니다.
GitHub 리포지토리를 복제하고 Visual Studio Code에서 엽니다.
디렉터리를 리포지토리의
APICenter-Analyzer폴더로 변경합니다.resources/rulesets폴더에서oas.yaml파일을 찾을 수 있습니다. 이 파일은 현재 API 스타일 가이드를 반영하며 조직의 필요 및 요구 사항에 따라 수정할 수 있습니다.다음 명령을 사용하여 Azure Developer CLI 및 Azure CLI로 인증합니다.
azd auth login az login다음 명령을 실행하여 린팅 인프라를 Azure 구독에 배포합니다.
azd up프롬프트에 따라 환경 이름, API 센터 이름 등 필수 배포 정보 및 설정을 제공합니다. 자세한 내용은 Azure Developer CLI(azd)를 사용하여 샘플 실행을 참조하세요.
참고 항목
배포에 몇 분 정도 걸릴 수 있습니다.
배포가 완료되면 Azure Portal에서 API 센터로 이동합니다. 왼쪽 메뉴에서 이벤트>이벤트 구독을 선택하여 만들어진 이벤트 구독을 확인합니다.
이제 API 정의 파일을 API 센터에 업로드하여 이벤트 구독을 트리거하고 린팅 엔진을 실행할 수 있습니다.
Shift-left API 거버넌스
가장 성공적인 거버넌스 이니셔티브에는 항상 개발자가 포함됩니다. API 플랫폼 팀은 기존의 Shift-left 원칙을 적용하여 API 생산자로 하여금 개발 주기 초기에 API를 게시하려면 어떤 요구 사항을 충족해야 하는지를 정확히 알게 할 수 있습니다. 이렇게 하면 개발 주기 후반부에서 비 준수 API를 수정할 필요가 없어 귀중한 개발 시간을 절약할 수 있습니다.
Visual Studio Code용 API 센터 확장은 API 생산자에게 API가 빌드되는 중에 Visual Studio Code에서 직접 API 디자인 준수 검사를 실행할 수 있는 환경을 제공합니다. 또한 API 생산자는 호환성이 손상되는 변경 검색 기능을 사용하여 변경이 API 소비자의 채팅 중단으로 이어질 수 있는 경우를 감지할 수 있습니다.
Visual Studio Code의 API 디자인 준수
API 센터 확장은 OpenAPI 및 사용자 지정 규칙 집합을 지원하는 JSON/YAML 린터인 Spectral과 통합됩니다. 이 확장을 통해 개발자는 제공되거나 권장되는 API 스타일 가이드를 엄격하게 준수하여 여러 팀에서 개발하고 있는 모든 API의 일관성을 보장할 수 있습니다.
활성화하려면,
- 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 사용합니다. Azure API Center: 활성 API 스타일 가이드 설정을 입력하고 Enter 키를 누릅니다.
- 제공된 기본 규칙 중 하나를 선택하거나, 조직에 이미 사용 가능한 스타일 가이드가 있는 경우 로컬 파일 선택 또는 원격 URL 입력을 사용하여 Visual Studio Code에서 활성 규칙 집합을 지정합니다. Enter 키를 누릅니다.
활성 API 스타일 가이드가 설정된 후에는 OpenAPI 또는 AsyncAPI 기반 사양 파일을 열면 Visual Studio Code에서 로컬 린팅 작업이 트리거됩니다. 결과는 편집기와 문제 창에서 모두 인라인으로 표시됩니다(> 문제 보기 또는 Ctrl+Shift+M).
Visual Studio Code에서 호환성이 손상되는 변경 검색
소비자 프로덕션 워크플로가 중단되는 API 버전을 출하하면 안정성이 떨어지고 신뢰를 읽게 됩니다. API 센터 확장을 통해 개발자는 Optic을 사용하여 두 API 버전을 쉽게 비교하고 배포 전에 API에 발생한 호환성이 손상되는 변경을 검색할 수 있습니다.
참고 항목
이 기능을 사용하려면 Optic을 설치해야 합니다. 다음 명령을 사용하여 설치합니다.
*npm install -g @useoptic/optic*
그런 다음
- 명령 팔레트를 열려면 Ctrl+Shift+P 바로 가기 키를 사용합니다. Azure API Center: 호환성이 손상되는 변경 검색를 입력하고 Enter 키를 누릅니다.
- 비교할 첫 번째 API 사양 문서를 선택합니다. 유효한 옵션에는 API 센터, 로컬 파일 또는 Visual Studio Code의 활성 편집기에 있는 API 사양이 포함됩니다.
- 비교할 두 번째 API 사양 문서를 선택합니다. 유효한 옵션에는 API 센터, 로컬 파일 또는 Visual Studio Code의 활성 편집기에 있는 API 사양이 포함됩니다.
Visual Studio Code는 두 API 사양 간에 차이점 보기를 엽니다. 호환성이 손상되는 변경은 편집기와 문제 창에서 모두 인라인으로 표시됩니다(> 문제 보기 또는 Ctrl+Shift+M).