API Center에서 API 분석 사용하도록 설정 - Microsoft 관리
이 문서에서는 직접 관리하지 않고도 Azure API Center에서 API 분석을 사용하도록 설정하는 방법을 설명합니다(미리 보기). API 분석은 조직의 API Center에서 API 정의를 분석하는 린팅 기능을 제공합니다. 린팅을 통해 API 정의가 조직 스타일 규칙을 준수하고 개별 보고서와 요약 보고서를 모두 생성합니다. API 분석을 사용하여 API 정의에서 일반적인 오류와 불일치 사항을 식별하고 수정합니다.
Important
API Center에서 관리되는 API 분석을 통해 린팅 엔진과 필요한 종속성이 자동으로 설정됩니다. 사용자 지정 Azure 함수를 사용하여 린팅 및 분석을 수동으로 사용하도록 설정할 수도 있습니다. 관리되는 API 분석을 사용하도록 설정하기 전에 수동 린팅에 사용되는 모든 함수를 사용하지 않도록 설정합니다.
이 시나리오에서는
- Azure API Center용 Visual Studio Code 확장을 사용하여 API Center에 린팅 규칙 집합(API 스타일 가이드)를 추가합니다.
- Azure API Center는 API 정의를 추가하거나 업데이트할 때 자동으로 린팅을 실행합니다. API Center에 규칙 집합을 배포하면 모든 API 정의에 대해서도 트리거됩니다.
- Azure Portal에서 API 분석 보고서를 검토하여 API 정의가 스타일 가이드를 준수하는지 확인합니다.
- 원하는 경우 조직의 API에 대한 규칙 집합을 사용자 지정합니다. API Center에 배포하기 전에 사용자 지정 규칙 집합을 로컬에서 테스트합니다.
제한 사항
- 현재는 JSON 또는 YAML 형식의 OpenAPI 사양 문서만 분석됩니다.
- 기본적으로
spectral:oas규칙 집합을 사용하여 분석을 사용하도록 설정합니다. 기본 제공 규칙에 대해 자세히 알아보려면 Spectral GitHub 리포지토리를 참조하세요. - 현재는 단일 규칙 집합을 구성하며, 이는 API Center의 모든 OpenAPI 정의에 적용됩니다.
- 분석된 최대 API 정의 수에는 제한이 있습니다. 분석을 완료하는 데 몇 분에서 최대 24시간이 걸릴 수 있습니다.
필수 조건
Azure 구독의 API 센터입니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.
다음 Visual Studio Code 확장:
Visual Studio Code용 Azure API 센터 확장
Important
API Center 확장의 사전 릴리스 버전을 사용하여 관리되는 API 분석을 사용하도록 설정합니다. 확장을 설치할 때 시험판 버전을 선택합니다. 확장 보기에서 확장의 관리 단추를 통해 언제든지 릴리스 버전과 사전 릴리스 버전 간에 전환할 수 있습니다.
Visual Studio Code를 사용하여 API 분석 사용
기본 린팅 규칙 집합을 사용하여 API 분석을 사용하도록 설정하려면:
Visual Studio Code에서 Azure API Center의 규칙 집합을 관리하는 데 사용할 폴더를 엽니다.
작업 막대에서 Azure API Center 아이콘을 선택합니다.
API Center 창에서 API 분석을 사용하도록 설정할 API Center 리소스를 확장합니다.
규칙을 마우스 오른쪽 단추로 클릭하고 API 분석 사용을 선택합니다.
API 분석이 성공적으로 사용하도록 설정되면 메시지가 표시됩니다. 작업 폴더 루트의 .api-center-rules에 API Center 폴더가 만들어집니다. API Center 폴더에는 다음이 포함됩니다.
- 린팅 엔진에서 사용하는 기본 API 스타일 가이드를 정의하는
ruleset.yml파일입니다. - 규칙 집합을 확장하는 데 사용할 수 있는 예 사용자 지정 함수가 있는
functions폴더입니다.
분석이 사용하도록 설정되면 린팅 엔진은 기본 규칙 집합을 기반으로 API Center의 API 정의를 분석하고 API 분석 보고서를 생성합니다.
API 분석 보고서 보기
Azure Portal에서 API 정의에 대한 분석 요약과 분석 보고서를 확인합니다. API 정의가 분석된 후, 구성된 API 스타일 가이드에 따라 오류, 경고 및 정보가 보고서에 나열됩니다.
API Center에서 분석 요약을 보려면:
포털에서 API 센터로 이동합니다.
왼쪽 메뉴의 거버넌스에서 API 분석을 선택합니다. 요약이 나타납니다.
선택적으로 API 정의에 대한 API 분석 보고서 아이콘을 선택합니다. 다음 스크린샷에 표시된 대로, 정의의 API 분석 보고서가 나타납니다.
팁
API 정의 메뉴 막대에서 분석을 선택하여 API 분석 보고서를 볼 수도 있습니다.
규칙 집합 사용자 지정
기본 규칙 집합을 사용자 지정하거나 조직의 API 스타일 가이드로 바꿀 수 있습니다. 예를 들어, 규칙 집합을 확장하거나 사용자 지정 함수를 추가할 수 있습니다.
규칙 집합을 사용자 지정하거나 바꾸려면:
- Visual Studio Code에서 작업 폴더의 루트에 있는
.api-center-rules폴더를 엽니다. - API Center 리소스 폴더에서
ruleset.yml파일을 엽니다. - 필요에 따라 콘텐츠를 수정하거나 바꿉니다.
- 변경 내용을
ruleset.yml에 저장합니다.
로컬에서 규칙 집합 테스트
사용자 지정 규칙 집합을 API Center에 배포하기 전에 로컬에서 유효성을 검사합니다. Visual Studio Code용 Azure API Center 확장은 Spectral을 사용하여 API 사양 린팅에 대한 통합 지원을 제공합니다.
Visual Studio Code에서 Ctrl+Shift+P 바로 가기 키를 사용하여 명령 팔레트를 엽니다.
Azure API Center: 활성 API 스타일 가이드 설정을 입력하고 Enter 키를 누릅니다.
로컬 파일 선택을 선택하고 사용자 지정한
ruleset.yml파일을 지정합니다. Enter 키를 누릅니다.이 단계에서는 사용자 지정 규칙 집합을 린팅을 위한 활성 API 스타일 가이드로 만듭니다.
이제 OpenAPI 기반 API 정의 파일을 열면 Visual Studio Code에서 로컬 린팅 작업이 자동으로 트리거됩니다. 결과는 편집기와 문제 창(보기 > 문제 또는 Ctrl+Shift+M)에 직접 표시됩니다.
린팅 결과를 검토합니다. 규칙집합에 필요한 조정을 하고 원하는 대로 수행될 때까지 로컬에서 계속 테스트합니다.
API Center에 규칙 집합 배포
API Center에 사용자 지정 규칙 집합을 배포하려면:
- Visual Studio Code의 작업 막대에서 Azure API Center 아이콘을 선택합니다.
- API Center 창에서 규칙 집합을 사용자 지정한 API Center 리소스를 확장합니다.
- 규칙을 마우스 오른쪽 단추로 클릭하고 API Center에 규칙 배포를 선택합니다.
규칙이 API Center에 성공적으로 배포되면 메시지가 표시됩니다. 린팅 엔진은 업데이트된 규칙 집합을 사용하여 API 정의를 분석합니다.
업데이트된 규칙 집합으로 린팅한 결과를 보려면 포털에서 API 분석 보고서를 확인합니다.