Azure API Management에서 API 센터로 API 가져오기

이 문서에서는 Azure CLI를 사용하여 Azure API Management 인스턴스에서 API 센터로 API를 가져오는(추가) 방법을 보여줍니다. API Management의 API를 API 인벤토리에 추가하면 개발자, API 프로그램 관리자 및 조직의 기타 이해관계자가 API를 검색하고 액세스할 수 있게 됩니다.

이 문서에서는 Azure CLI를 사용하여 API Management에서 API 센터에 API를 추가하는 두 가지 옵션을 보여 줍니다.

• 옵션 1 - az apim api import 명령을 사용하여 API Management 인스턴스에서 API 정의를 내보냅니다. 그런 다음 정의를 API 센터로 가져옵니다.

  API Management에서 내보낸 API 정의를 가져오는 가능한 방법은 다음과 같습니다.

  • az apic api register를 실행하여 API 센터에 새 API를 등록합니다.
  • API 정의를 기존 API로 가져오려면 az apic api definition import-specification을 실행합니다.

• 옵션 2 - az apic import-from-apim 명령을 사용하여 API Management에서 API 센터로 직접 API를 가져옵니다.

API Management에서 API 정의 또는 API를 가져온 후 API 센터에 메타데이터 및 설명서를 추가하여 관련자가 API를 검색, 이해 및 사용하는 데 도움을 줄 수 있습니다.

팁

API Management에서 API 센터로의 API 자동 동기화를 설정할 수도 있습니다. 자세한 내용은 API Management 인스턴스 연결을 참조 하여 API 센터에 API를 동기화합니다.

필수 조건

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

• 동일하거나 다른 구독에 있는 하나 이상의 Azure API Management 인스턴스입니다. API Management에서 직접 API를 가져오는 경우 API Management 인스턴스와 API 센터가 동일한 디렉터리에 있어야 합니다. 아직 만들지 않은 경우 Azure API Management 인스턴스 만들기를 참조하세요.

• API 센터에 추가하려는 API Management 인스턴스에서 관리되는 하나 이상의 API.

• 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 셸에서 실행할 수 있습니다. 변수 구문이 다르기 때문에 필요한 경우 두 셸에 대해 별도의 명령 예가 제공됩니다.

옵션 1: API Management에서 API 정의를 내보내고 API 센터로 가져오기

먼저, az apim api import 명령을 사용하여 API Management 인스턴스에서 API 정의로 API를 내보냅니다. 시나리오에 따라 API 정의를 로컬 파일이나 URL로 내보낼 수 있습니다.

API를 로컬 API 정의 파일로 내보내기

다음 명령 예는 API의 myAPIManagement 인스턴스에서 식별자가 my-api인 API를 내보냅니다. API는 OpenApiJson 형식으로 사용자가 지정하는 경로의 로컬 OpenAPI 정의 파일로 내보내집니다.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

API를 URL로 내보내기

다음 예에서 az apim api import는 OpenApiJson 형식의 식별자가 my-api인 API를 Azure Storage의 URL로 내보냅니다. URL은 약 5분 동안 사용할 수 있습니다. 여기서 URL 값은 $link 변수에 저장됩니다.

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

내보낸 API 정의에서 API 센터에 API를 등록합니다.

az apic apiregister 명령을 사용하여 내보낸 정의에서 API 센터에 새 API를 등록할 수 있습니다.

다음 예에서는 definitionFile.json이라는 로컬 OpenAPI 정의 파일에서 myAPICenter API 센터에 API를 등록합니다.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

API 센터의 기존 API로 API 정의 가져오기

다음 예에서는 az apic api definition import-specification 명령을 사용하여 API 정의를 myAPICenter API 센터의 기존 API로 가져옵니다. 여기서 API 정의는 $link 변수에 저장된 URL에서 가져옵니다.

이 예에서는 API 센터에 my-api라는 API와 관련 API 버전 v1-0-0 및 정의 엔터티 openapi가 있다고 가정합니다. 그렇지 않은 경우 API 센터에 API 추가를 참조하세요.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

옵션 2: API Management 인스턴스에서 직접 API 가져오기

다음은 az apic import-from-apim 명령을 사용하여 API Management 인스턴스에서 API 센터로 API를 가져오는 단계입니다. 이 명령은 API Management에서 API 센터로 여러 API를 가져오려는 경우 유용하지만 단일 API를 가져오는 데 사용할 수도 있습니다.

az apic import-from-apim을 사용하여 API Management 인스턴스의 API를 API 센터에 추가하면 다음이 자동으로 발생합니다.

• 각 API의 버전, 정의 및 배포 정보가 API 센터에 복사됩니다.
• API는 API 센터에서 시스템 생성 API 이름을 받습니다. API Management의 표시 이름(제목)을 유지합니다.
• API의 수명주기 단계는 디자인으로 설정됩니다.
• Azure API Management가 환경으로 추가됩니다.

API 센터에서 관리 ID 추가

이 시나리오의 경우 API 센터는 관리 ID를 사용하여 API Management 인스턴스의 API에 액세스합니다. 필요에 따라 시스템 할당 또는 하나 이상의 사용자 할당 관리 ID를 구성합니다.

다음 예에서는 Azure Portal 또는 Azure CLI를 사용하여 시스템 할당 관리 ID를 구성하는 방법을 보여 줍니다. 높은 수준에서 구성 단계는 사용자 할당 관리 ID와 유사합니다.

포털

1. 포털에서 API 센터로 이동합니다.
2. 왼쪽 메뉴의 보안 아래에서 관리 ID를 선택합니다.
3. 시스템 할당을 선택하고 상태를 켬으로 설정합니다.
4. 저장을 선택합니다.

Azure CLI

다음 az apic update 명령을 사용하여 API 센터에서 시스템 할당 ID를 설정합니다. API 센터 및 리소스 그룹의 이름을 대체합니다.

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

관리 ID에 API Management 서비스 읽기 권한자 역할 할당

API 가져오기를 허용하려면 API Management 인스턴스의 API Management 서비스 읽기 권한자 역할에 API 센터의 관리 ID를 할당합니다. 포털 또는 Azure CLI를 사용할 수 있습니다.

포털

1. 포털에서 API Management 인스턴스로 이동합니다.
2. 왼쪽 메뉴에서 액세스 제어(IAM)를 선택합니다.
3. + 역할 할당 추가를 선택합니다.
4. 역할 할당 추가 페이지에서 다음과 같이 값을 설정합니다.
   1. 역할 탭에서 - API Management 서비스 읽기 권한자를 선택합니다.
   2. 구성원 탭의 액세스 할당에서 관리 ID>+ 구성원 선택을 선택합니다.
   3. 관리 ID 선택 페이지에서 - 이전 섹션에서 추가한 API 센터의 시스템 할당 관리 ID를 선택합니다. 선택을 클릭합니다.
   4. 검토 + 할당을 선택합니다.

Azure CLI

1. ID의 보안 주체 ID를 가져옵니다. 시스템 할당 ID의 경우 az apic show 명령을 사용합니다.

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. az apim show 명령을 사용하여 API Management 인스턴스의 리소스 ID를 가져옵니다.

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

   # Formatted for PowerShell
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. az role assignment create 명령을 사용하여 API Management 인스턴스에서 관리 ID에 API Management 서비스 읽기 권한자 역할을 할당합니다.

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

API Management에서 API 가져오기

az apic import-from-apim 명령을 사용하여 API Management 인스턴스에서 API 센터로 하나 이상의 API를 가져옵니다.

참고 항목

• 이 명령은 API Management 인스턴스에 대한 읽기 권한이 있는 API 센터에 구성된 관리 ID에 따라 달라집니다. 관리 ID를 추가하거나 구성하지 않은 경우 이 문서 앞부분의 API 센터에서 관리 ID 추가를 참조하세요.

• API 센터에 여러 관리 ID가 있는 경우 명령은 먼저 시스템 할당 ID를 검색합니다. 아무 것도 검색되지 않으면 목록에서 첫 번째 사용자 할당 ID를 선택합니다.

API Management 인스턴스에서 모든 API 가져오기

다음 명령에서 API 센터, API 센터 리소스 그룹, API Management 인스턴스 및 인스턴스 리소스 그룹의 이름을 대체합니다. API Management 인스턴스에서 모든 API를 지정하려면 *을 사용합니다.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

참고 항목

API Management 인스턴스에 API 수가 많은 경우 API 센터로 가져오는 데 다소 시간이 걸릴 수 있습니다.

API Management 인스턴스에서 특정 API 가져오기

API Management 인스턴스에서 해당 이름을 사용하여 가져올 API를 지정합니다.

다음 명령에서 API 센터, API 센터 리소스 그룹, API Management 인스턴스 및 인스턴스 리소스 그룹의 이름을 대체합니다. --apim-apis 매개 변수를 사용하여 petstore-api와 같은 API 이름을 전달합니다.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

참고 항목

표시 이름이 아닌 API Management 인스턴스의 API 리소스 이름을 사용하여 API 이름을 지정합니다. 예: Petstore API 대신 petstore-api.

API Management에서 API를 가져온 후 API 센터에서 가져온 API를 보고 관리할 수 있습니다.

관련 콘텐츠

• Azure API Center에 대한 Azure CLI 참조
• API Management에 대한 Azure CLI 참조
• Azure CLI 명령을 사용하여 API 인벤토리 관리
• 관리 ID에 Azure 역할 할당
• Azure API Management 설명서