API Center에서 API 분석 사용 - 자체 관리

이 문서에서는 linting 엔진 및 트리거를 수동으로 설정하여 Azure API 센터에서 API 분석을 사용하도록 설정하는 방법을 설명합니다. API 분석은 조직의 API Center에서 API 정의를 분석하는 린팅 기능을 제공합니다. 린팅을 통해 API 정의가 조직 스타일 규칙을 준수하고 개별 보고서와 요약 보고서를 모두 생성합니다. API 분석을 사용하여 API 정의에서 일반적인 오류와 불일치 사항을 식별하고 수정합니다.

참고 항목

미리 보기에서 Azure API Center는 Linting 엔진 및 필요한 종속성 및 트리거를 자동으로 설정할 수도 있습니다. 자세히 알아보기.

시나리오 개요

이 시나리오에서는 Spectral 오픈 소스 린팅 엔진을 사용하여 API 센터에서 API 정의를 분석합니다. Azure Functions 앱은 API 센터의 이벤트에 대한 응답으로 린팅 엔진을 실행합니다. Spectral은 JSON 또는 YAML 사양 문서에 정의된 API가 사용자 지정 가능한 API 스타일 가이드의 규칙을 준수하는지 확인합니다. API 센터에서 볼 수 있는 분석 보고서가 생성됩니다.

다음 다이어그램은 API 센터에서 린팅 및 분석을 사용하도록 설정하는 단계를 보여 줍니다.

1. API 정의에서 Spectral 린팅 엔진을 실행하는 Azure Functions 앱을 배포합니다.

2. 함수 앱을 트리거하도록 Azure API Center에서 이벤트 구독을 구성합니다.

3. 이벤트는 API 센터에서 API 정의를 추가하거나 대체하여 트리거됩니다.

4. 이벤트를 수신할 때 함수 앱은 Spectral 린팅 엔진을 호출합니다.

5. 린팅 엔진은 정의에 정의된 API가 조직의 API 스타일 가이드를 준수하는지 확인하고 보고서를 생성합니다.

6. API 센터에서 분석 보고서를 봅니다.

린팅 엔진 및 이벤트 구독을 배포하는 옵션

이 문서에서는 API 센터에 린팅 엔진 및 이벤트 구독을 배포하는 두 가지 옵션을 제공합니다.

• 자동 배포 - 린팅 인프라의 1단계 배포를 위해 Azure 개발자 CLI(azd)를 사용합니다. 이 옵션은 효율적인 배포 프로세스를 위해 권장됩니다.

• 수동 배포 - 단계별 지침에 따라 Azure Functions 앱을 배포하고 이벤트 구독을 구성합니다. 리소스를 수동으로 배포하고 관리하려는 경우 이 옵션을 사용하는 것이 좋습니다.

제한 사항

• 린팅은 현재 OpenAPI 또는 AsyncAPI 사양 문서와 같은 JSON 또는 YAML 사양 파일만 지원합니다.
• 기본적으로 린팅 엔진은 기본 제공 spectral:oas 규칙 집합을 사용합니다. 규칙 집합을 확장하거나 사용자 지정 API 스타일 가이드를 만들려면 Spectral GitHub 리포지토리를 참조하세요.
• 린팅을 호출하는 Azure 함수 앱은 별도로 요금이 청구되며 사용자가 관리 및 유지 관리합니다.

필수 조건

• Azure 구독의 API 센터입니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.

• Event Grid 리소스 공급자는 구독에 등록되어 있어야 합니다. Event Grid 리소스 공급자를 등록해야 하는 경우 Azure Event Grid를 사용하여 파트너가 게시한 이벤트 구독을 참조하세요.

• 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를 실행합니다.

  참고 항목

  az apic 명령에는 apic-extension Azure CLI 확장이 필요합니다. az apic 명령을 사용하지 않은 경우 첫 번째 az apic 명령을 실행할 때 확장을 동적으로 설치하거나 확장을 수동으로 설치할 수 있습니다. Azure CLI 확장에 대해 자세히 알아보세요.

  apic-extension의 최신 변경 내용 및 업데이트는 릴리스 정보를 참조하세요.

  참고 항목

  이 문서의 Azure CLI 명령 예제는 PowerShell 또는 bash 셸에서 실행할 수 있습니다. 변수 구문이 다르기 때문에 필요한 경우 두 셸에 대해 별도의 명령 예가 제공됩니다.

azd Azure Functions 앱 배포 및 이벤트 구독

이 섹션에서는 API 센터에서 린팅 및 분석을 사용하도록 설정하는 Azure Functions 앱 및 이벤트 구독을 구성하기 위해 Azure Developer CLI를 사용하는 자동화된 단계를 제공합니다. 리소스를 수동으로 구성할 수도 있습니다.

이 옵션의 기타 필수 조건

• Azure 개발자 CLI(azd)

azd를 사용하여 샘플 실행

1. GitHub 리포지토리를 복제하고 Visual Studio Code에서 엽니다.

2. 디렉터리를 리포지토리의 APICenter-Analyzer 폴더로 변경합니다.

3. resources/rulesets 폴더에서 oas.yaml 파일을 찾을 수 있습니다. 이 파일은 현재 API 스타일 가이드를 반영하며 조직의 필요 및 요구 사항에 따라 수정할 수 있습니다.

4. 다음 명령을 사용하여 Azure Developer CLI 및 Azure CLI로 인증합니다.

   azd auth login
   
   az login
   

5. 다음 명령을 실행하여 린팅 인프라를 Azure 구독에 배포합니다.

   azd up
   

6. 프롬프트에 따라 환경 이름, API 센터 이름 등 필수 배포 정보 및 설정을 제공합니다. 자세한 내용은 Azure Developer CLI(azd)를 사용하여 샘플 실행을 참조하세요.

   참고 항목

   배포에 몇 분 정도 걸릴 수 있습니다.

7. 배포가 완료되면 Azure Portal에서 API 센터로 이동합니다. 왼쪽 메뉴에서 이벤트>이벤트 구독을 선택하여 만들어진 이벤트 구독을 확인합니다.

이제 API 정의 파일을 API 센터에 업로드하여 이벤트 구독을 트리거하고 린팅 엔진을 실행할 수 있습니다.

Azure Functions 앱 및 이벤트 구독을 구성하는 수동 단계

이 섹션에서는 API 센터에서 린팅 및 분석을 사용하도록 설정하도록 Azure Functions 앱 및 이벤트 구독을 구성하는 수동 배포 단계를 제공합니다. 자동 배포를 위해 Azure Developer CLI를 사용할 수도 있습니다.

이 옵션의 기타 필수 조건

• Azure Functions 확장 v1.10.4 이상을 사용하는 Visual Studio Code.

1단계. Azure Functions 앱 배포

API 정의에서 린팅 함수를 실행하는 Azure Functions 앱을 배포하려면 다음을 수행합니다.

1. GitHub 리포지토리를 복제하고 Visual Studio Code에서 엽니다.

2. resources/rulesets 폴더에서 oas.yaml 파일을 찾을 수 있습니다. 이 파일은 현재 API 스타일 가이드를 반영하며 조직의 필요 및 요구 사항에 따라 수정할 수 있습니다.

3. 필요에 따라 함수 앱을 로컬로 실행하여 테스트합니다. 자세한 내용은 리포지토리의 추가 정보 파일을 참조하세요.

4. Azure에 함수 앱을 배포합니다. 단계는 빠른 시작: Visual Studio Code를 통해 TypeScript를 사용하여 Azure에서 함수 만들기를 참조하세요.

   참고 항목

   함수 앱을 배포하는 데 몇 분 정도 걸릴 수 있습니다.

5. Azure Portal에 로그인하고 함수 앱으로 이동합니다.

6. 개요 페이지에서 다음 세부 정보를 확인합니다.

   • 함수 앱의 상태가 실행 중인지 확인합니다.
   • 함수에서 apicenter-analyzer 함수의 상태가 사용인지 확인합니다.

   

2단계. 함수 앱에서 관리 ID 구성

함수 앱이 API 센터에 액세스할 수 있도록 하려면 함수 앱에 대한 관리 ID를 구성합니다. 다음 단계에서는 Azure Portal 또는 Azure CLI를 사용하여 함수 앱에 대해 시스템 할당 관리 ID를 사용하도록 설정하고 구성하는 방법을 보여 줍니다.

포털

1. Azure Portal에서 함수 앱으로 이동하고 설정 섹션에서 ID를 선택합니다.
2. 시스템 할당 탭에서 상태를 켜기로 설정한 다음, 저장을 선택합니다.

이제 관리 ID를 사용하도록 설정했으므로 Azure API 센터 준수 관리자 역할을 할당하여 API 센터에 액세스합니다.

1. Azure Portal에서 API 센터로 이동하고 액세스 제어(IAM)를 선택합니다.
2. + 추가 > 역할 할당 추가를 선택합니다.
3. 작업 함수 역할을 선택한 다음, Azure API 센터 준수 관리자를 선택합니다. 다음을 선택합니다.
4. 구성원 페이지의 액세스 할당에서 관리 ID > + 구성원 선택을 선택합니다.
5. 관리 ID 선택 페이지에서 함수 앱의 관리 ID를 검색하고 선택합니다. 선택을 클릭한 후 다음을 클릭합니다.
6. 역할 할당을 검토하고 검토 + 할당을 선택합니다.

Azure CLI

1. az functionapp identity assign 명령을 사용하여 함수 앱의 시스템 할당 ID를 사용하도록 설정합니다. <function-app-name> 및 <resource-group-name>을 함수 앱 이름 및 리소스 그룹 이름으로 바꿉니다. 다음 명령은 시스템 할당 관리 ID의 보안 주체 ID를 principalID 변수에 저장합니다.

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

2. API 센터의 리소스 ID를 가져옵니다. <apic-name> 및 <resource-group-name>을 API 센터 이름 및 리소스 그룹 이름으로 바꿉니다.

   #! /bin/bash
   apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. az role assignment create 명령을 사용하여 API 센터에서 함수 앱의 관리 ID에 Azure API 센터 준수 관리자 역할을 할당합니다.

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

3단계 API 센터에서 이벤트 구독 구성

이제 API 정의 파일이 업로드되거나 업데이트될 때 함수 앱을 트리거하는 이벤트 구독을 API 센터에 만듭니다. 다음 단계에서는 Azure Portal 또는 Azure CLI를 사용하여 이벤트 구독을 만드는 방법을 보여 줍니다.

포털

1. Azure Portal에서 API 센터로 이동하고 이벤트를 선택합니다.

2. 시작 탭에서 Azure Function을 선택합니다.

3. 이벤트 구독 만들기 페이지에서 다음을 수행합니다.

   1. 이벤트 구독에 대한 설명이 포함된 이름을 입력하고 Event Grid 스키마를 선택합니다.

   2. 토픽 세부 정보에서 선택한 시스템 토픽 이름을 입력합니다.

   3. 이벤트 유형에서 다음 이벤트를 선택합니다.

      • 추가된 API 정의
      • 업데이트된 API 정의

   4. 엔드포인트 세부 정보에서 Azure Function > 엔드포인트 구성을 선택합니다.

   5. Azure Function 선택 페이지에서 구성한 함수 앱과 apicenter-linter 함수를 선택합니다. 선택 확인을 클릭합니다.

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

      

4. 이벤트 구독 탭을 선택하고 새로 고침을 선택합니다. 이벤트 구독의 프로비전 상태가 성공인지 확인합니다.

   

Azure CLI

1. API 센터의 리소스 ID를 가져옵니다. <apic-name> 및 <resource-group-name>을 API 센터 이름 및 리소스 그룹 이름으로 바꿉니다.

   #! /bin/bash
   apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

2. 함수 앱에서 함수의 리소스 ID를 가져옵니다. 이 예제에서 함수 이름은 apicenter-analyzer입니다. <function-app-name> 및 <resource-group-name>을 함수 앱 이름 및 리소스 그룹 이름으로 바꿉니다.

   #! /bin/bash
   functionID=$(az functionapp function show --name <function-app-name> \
       --function-name apicenter-analyzer --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $functionID=$(az functionapp function show --name <function-app-name> `
       --function-name apicenter-analyzer --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. az eventgrid event-subscription create 명령을 사용하여 이벤트 구독을 만듭니다. 만든 구독에는 API 정의를 추가하거나 업데이트하기 위한 이벤트가 포함됩니다.

   #! /bin/bash
   az eventgrid event-subscription create --name MyEventSubscription \
       --source-resource-id "$apicID" --endpoint "$functionID" \
       --endpoint-type azurefunction --included-event-types \
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   # PowerShell syntax
   az eventgrid event-subscription create --name MyEventSubscription `
       --source-resource-id "$apicID" --endpoint "$functionID" `
       --endpoint-type azurefunction --included-event-types `
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   명령 출력에는 이벤트 구독의 세부 정보가 표시됩니다. az eventgrid event-subscription show 명령을 사용하여 세부 정보를 가져올 수도 있습니다. 예시:

   az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"
   

참고 항목

이벤트 구독이 함수 앱에 전파되는 데 짧은 시간이 걸릴 수 있습니다.

API 센터에서 이벤트 트리거

이벤트 구독을 테스트하려면 API 센터의 API 버전과 연결된 API 정의 파일을 업로드하거나 업데이트해 보세요. 예를 들어 OpenAPI 또는 AsyncAPI 문서를 업로드합니다. 이벤트 구독이 트리거되면 함수 앱은 API 린팅 엔진을 호출하여 API 정의를 분석합니다.

• API, API 버전, API 정의를 API 센터에 추가하는 자세한 단계는 자습서: API 센터에 API 등록을 참조하세요.
• Azure CLI를 사용하여 API 정의 파일을 업로드하여 API를 만들려면 사양 파일에서 API 등록을 참조하세요.

이벤트 구독이 트리거되었는지 확인하려면 다음을 수행합니다.

1. API 센터로 이동하고 왼쪽 메뉴에서 이벤트를 선택합니다.

2. 이벤트 구독 탭을 선택하고 함수 앱에 대한 이벤트 구독을 선택합니다.

3. 메트릭을 검토하여 이벤트 구독이 트리거되었고 린팅이 성공적으로 호출되었는지 확인합니다.

   

   참고 항목

   메트릭이 표시되는 데 몇 분 정도 걸릴 수 있습니다.

API 정의를 분석한 후 린팅 엔진은 구성된 API 스타일 가이드를 기반으로 보고서를 생성합니다.

API 분석 보고서 보기

Azure Portal에서 API 정의에 대한 분석 보고서를 볼 수 있습니다. API 정의를 분석한 후 보고서는 구성된 API 스타일 가이드를 기반으로 오류, 경고, 정보를 나열합니다.

포털에서 API 센터의 모든 API 정의에 대한 분석 보고서의 요약을 볼 수도 있습니다.

API 정의에 대한 분석 보고서

API 센터에서 API 정의에 대한 분석 보고서를 보려면 다음을 수행합니다.

1. 포털에서 API 정의를 추가하거나 업데이트한 API 센터의 API 버전으로 이동합니다.
2. 왼쪽 메뉴의 세부 정보에서 정의를 선택합니다.
3. 업로드했거나 업데이트한 API 정의를 선택합니다.
4. 분석 탭을 선택합니다.

API 분석 보고서가 열리고 구성된 API 스타일 가이드를 기반으로 API 정의와 오류, 경고, 정보가 표시됩니다. 다음 스크린샷은 API 분석 보고서의 예제를 보여 줍니다.

API 분석 요약

API 센터의 모든 API 정의에 대한 분석 보고서의 요약을 보려면 다음을 수행합니다.

1. 포털에서 API 센터로 이동합니다.

2. 왼쪽 메뉴의 거버넌스에서 API 분석을 선택합니다. 요약이 나타납니다.

   

관련 콘텐츠

Event Grid에 대해 자세히 알아보세요.

• API Center에서 API 분석 사용 - Microsoft 관리
• Azure Event Grid의 시스템 토픽
• Event Grid 푸시 배달 - 개념
• Azure API Center용 Event Grid 스키마