GitHub Actions를 사용하여 API 센터에 API 등록
이 문서에서는 API 사양 파일이 GitHub 리포지토리에 추가되면 조직의 API 센터에 API를 등록하기 위한 기본 GitHub Actions 워크플로를 설정하는 방법을 보여 줍니다.
GitHub Actions 워크플로를 사용하여 API 센터에 API를 등록하면 새 API나 업데이트된 API마다 일관되고 반복 가능한 CI/CD 프로세스가 제공됩니다. 워크플로는 API 등록에 메타데이터를 추가하는 등의 단계를 포함하도록 확장될 수 있습니다.
다음 다이어그램은 GitHub Actions 워크플로를 사용하여 API 센터에서 API 등록을 자동화하는 방법을 보여 줍니다.
- API 정의 파일을 추가하는 끌어오기 요청이 병합될 때 트리거되는 GitHub Actions 워크플로를 리포지토리에 설정합니다.
- GitHub 리포지토리의 기본 분기에서 분기를 만듭니다.
- API 정의 파일을 추가하고, 변경 내용을 커밋한 다음 새 분기에 푸시합니다.
- 새로운 분기를 기본 분기에 병합하기 위한 끌어오기 요청을 만듭니다.
- 끌어오기 요청을 병합합니다.
- 병합은 API 센터에 API를 등록하는 GitHub Actions 워크플로를 트리거합니다.
필수 조건
Azure 구독의 API 센터입니다. 아직 API 센터를 만들지 않았다면 빠른 시작: API 센터 만들기를 참조하세요.
Microsoft Entra ID 테넌트에서 서비스 주체를 만들기 위한 권한
비밀과 GitHub Actions 워크플로를 구성할 수 있는 GitHub 계정 및 GitHub 리포지토리
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-extensionAzure CLI 확장이 필요합니다.az apic명령을 사용하지 않은 경우 첫 번째az apic명령을 실행할 때 확장을 동적으로 설치하거나 확장을 수동으로 설치할 수 있습니다. Azure CLI 확장에 대해 자세히 알아보세요.apic-extension의 최신 변경 내용 및 업데이트는 릴리스 정보를 참조하세요.참고 항목
이 문서의 Azure CLI 명령 예제는 PowerShell 또는 bash 셸에서 실행할 수 있습니다. 변수 구문이 다르기 때문에 필요한 경우 두 셸에 대해 별도의 명령 예가 제공됩니다.
GitHub Actions 워크플로 설정
이 섹션에서는 이 시나리오에 대한 GitHub Actions 워크플로를 설정합니다.
- 워크플로에서 Azure 자격 증명에 사용할 서비스 주체를 만듭니다.
- GitHub 리포지토리에 자격 증명을 비밀로 추가합니다.
- API 정의 파일을 추가하는 끌어오기 요청이 병합될 때 트리거되는 GitHub Actions 워크플로를 구성합니다. 워크플로 YAML 파일에는 Azure CLI를 사용하여 정의 파일에서 API 센터에 API를 등록하는 단계가 포함되어 있습니다.
서비스 주체 비밀 설정
다음 단계에서는 Azure에서 인증하기 위한 자격 증명을 워크플로에 추가하는 데 사용되는 Microsoft Entra ID 서비스 주체를 만듭니다.
참고 항목
서비스 주체를 구성하는 방법은 데모 목적으로 표시됩니다. GitHub Actions에서 Azure를 인증하는 데 권장되는 방법은 단기 토큰을 사용하는 인증 방법인 OpenID Connect를 사용하는 것입니다. GitHub Actions로 OpenID Connect를 설정하는 것은 더 복잡하지만 강화된 보안을 제공합니다. 자세한 정보
az ad sp create-for-rbac 명령을 사용하여 서비스 사용자를 만듭니다. 다음 예에서는 먼저 az apic show 명령을 사용하여 API 센터의 리소스 ID를 검색합니다. 그런 다음 API 센터에 대한 Azure API 센터 서비스 기여자 역할을 사용하여 서비스 주체를 만듭니다.
#! /bin/bash
apiCenter=<api-center-name>
resourceGroup=<resource-group-name>
spName=<service-principal-name>
apicResourceId=$(az apic show --name $apiCenter --resource-group $resourceGroup --query "id" --output tsv)
az ad sp create-for-rbac --name $spName --role "Azure API Center Service Contributor" --scopes $apicResourceId --json-auth
다음과 비슷하게 보이는 JSON 출력을 복사합니다.
{
"clientId": "<GUID>",
"clientSecret": "<GUID>",
"subscriptionId": "<GUID>",
"tenantId": "<GUID>",
"activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
"resourceManagerEndpointUrl": "https://management.azure.com/",
[...other endpoints...]
}
서비스 주체를 GitHub 비밀로 추가
GitHub에서 리포지토리를 찾습니다. 설정을 선택합니다.
보안에서 비밀 및 변수>Actions 선택
새 리포지토리 비밀을 선택합니다.
Azure CLI 명령의 전체 JSON 출력을 비밀의 값 필드에 붙여넣습니다. 비밀
AZURE_CREDENTIALS의 이름을 지정합니다. 비밀 추가를 선택합니다.비밀은 리포지토리 비밀에 나열되어 있습니다.
나중에 GitHub 워크플로 파일을 구성할 때 비밀을 Azure/login 작업의 입력 creds에 사용합니다. 예시:
- uses: azure/login@v1
with:
creds: ${{ secrets.AZURE_CREDENTIALS }}
GitHub 리포지토리에 워크플로 파일 추가
GitHub Actions 워크플로는 YAML(.yml) 정의 파일로 표현됩니다. 이 정의는 워크플로를 구성하는 다양한 단계와 매개 변수를 포함합니다. 자세한 정보
다음은 이 예에 대한 기본 워크플로 파일이며, 사용하거나 수정할 수 있습니다.
이 예에서는 다음이 적용됩니다.
APIs경로에 JSON 정의를 추가하는 끌어오기 요청이 기본 분기에서 닫히면 워크플로가 트리거됩니다.- 정의 위치는 기본 GitHub 토큰으로 인증된 GitHub 스크립트를 사용하여 끌어오기 요청에서 추출됩니다.
- 리포지토리에 저장된 Azure 자격 증명은 Azure에 로그인하는 데 사용됩니다.
- az apic register 명령은 환경 변수에 지정된 API 센터에 API를 등록합니다.
워크플로 파일을 구성하려면 다음을 수행합니다.
- 파일을 복사하여
register-api.yml과 같은 이름으로 저장합니다. - Azure의 API 센터와 일치하도록 환경 변수의 값을 업데이트합니다.
- API 정의 파일을 추가할 리포지토리 폴더(
APIs)의 이름을 확인하거나 업데이트합니다. - GitHub 리포지토리의
/.github/workflows/경로에 이 워크플로 파일을 추가합니다.
팁
Azure API Center용 Visual Studio Code 확장을 사용하면 확장 명령을 실행하여 시작 워크플로 파일을 생성할 수 있습니다. 명령 팔레트에서 Azure API Center: API 등록을 선택합니다. CI/CD>GitHub를 선택합니다. 그런 다음 시나리오에 맞게 파일을 수정할 수 있습니다.
name: Register API Definition to Azure API Center
on:
pull_request:
types: [closed]
branches:
- main
paths:
- "APIs/**/*.json"
permissions:
contents: read
pull-requests: read
env:
# set this to your Azure API Center resource group name
RESOURCE_GROUP: <YOUR_RESOURCE_GROUP>
# set this to your Azure API Center service name
SERVICE_NAME: <YOUR_API_CENTER>
jobs:
register:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v2
- name: Get specification file path in the PR
id: get-file-location
uses: actions/github-script@v5
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const pull_number = context.payload.pull_request.number;
const owner = context.repo.owner;
const repo = context.repo.repo;
const files = await github.rest.pulls.listFiles({
owner,
repo,
pull_number
});
if (files.data.length === 1) {
const filename = files.data[0].filename;
core.exportVariable('API_FILE_LOCATION', hfilename);
console.log(`API_FILE_LOCATION: ${{ env.API_FILE_LOCATION }}`);
}
else {
console.log('The PR does not add exactly one specification file.');
}
- name: Azure login
uses: azure/login@v1
with:
creds: ${{ secrets.AZURE_CREDENTIALS }}
- name: Register to API Center
uses: azure/CLI@v2
with:
azcliversion: latest
inlineScript: |
az apic api register -g ${{ env.RESOURCE_GROUP }} -n ${{ env.SERVICE_NAME }} --api-location ${{ env.API_FILE_LOCATION }}
API 정의 파일을 리포지토리에 추가
리포지토리에 API 정의 파일을 추가하여 워크플로를 테스트합니다. 개발 워크플로에서 일반적으로 나타나는 개략적인 단계를 따릅니다. GitHub 분기 작업에 대한 자세한 내용은 GitHub 설명서를 참조하세요.
리포지토리의 기본 분기에서 새로운 작업 분기를 만듭니다.
API 정의 파일을
APIs경로의 리포지토리에 추가합니다. 예들 들어APIs/catfacts-api/07-15-2024.json입니다.변경 내용을 커밋하고 작업 분기에 푸시합니다.
작업 분기를 기본 분기에 병합하기 위해 끌어오기 요청을 만듭니다.
검토 후 끌어오기 요청을 병합합니다. 병합은 API 센터에 API를 등록하는 GitHub Actions 워크플로를 트리거합니다.
API 등록 확인
API가 API 센터에 등록되어 있는지 확인합니다.
- Azure Portal에서 API 센터로 이동합니다.
- 왼쪽 메뉴의 자산에서 API를 선택합니다.
- 새로 등록된 API가 API 목록에 나타나는지 확인합니다.
새로운 API 버전 추가
API 센터의 기존 API에 새 버전을 추가하려면 약간 수정하여 이전 단계를 따릅니다.
- 리포지토리에서 동일한 작업 분기로 변경하거나 새로운 작업 분기를 만듭니다.
- 기존 API에 대한 폴더의
APIs경로에 있는 리포지토리에 새 API 정의 파일을 추가합니다. 예를 들어, 이전에 Cat Facts API 정의를 추가한 경우APIs/catfacts-api/07-22-2024.json과 같은 새 버전을 추가합니다. - 변경 내용을 커밋하고 작업 분기에 푸시합니다.
- 작업 분기를 기본 분기에 병합하기 위해 끌어오기 요청을 만듭니다.
- 검토 후 끌어오기 요청을 병합합니다. 병합을 실행하면 API 센터에 새 API 버전을 등록하는 GitHub Actions 워크플로가 트리거됩니다.
- Azure Portal에서 API 센터로 이동하여 새 버전이 등록되었는지 확인합니다.
시나리오 확장
API 등록에 대한 메타데이터를 추가하는 등의 다른 단계를 포함하도록 GitHub Actions 워크플로를 확장할 수 있습니다. 예시:
API 센터의 메타데이터 스키마를 사용하여 API 등록에 메타데이터 값을 적용하는 메타데이터 JSON 파일을 만듭니다.
예를 들어, 메타데이터 스키마에
approver,team,cost center와 같은 속성이 포함된 경우 메타데이터 JSON 파일은 다음과 같습니다.{ "approver": "diego@contoso.com", "team": "Store API dev team", "costCenter": "12345" }리포지토리의 각 API 폴더에 메타데이터 JSON 파일을 업로드합니다.
az apic api update 명령을 사용하여 API 등록에 메타데이터를 적용하는 워크플로 단계를 추가합니다. 다음 예에서 API ID와 메타데이터 파일은 환경 변수로 전달되며, 이 환경 변수는 워크플로 파일의 다른 곳에 설정됩니다.
[...] - name: Apply metadata to API in API Center uses: azure/CLI@v2 with: azcliversion: latest inlineScript: | az apic api update -g ${{ env.RESOURCE_GROUP }} -n ${{ env.SERVICE_NAME }} --api-id {{ env.API_ID }} --custom-properties {{ env.METADATA_FILE }}