OpenAPI 사양 가져오기

적용 대상: 모든 API Management 계층

이 문서에서는 https://conferenceapi.azurewebsites.net?format=json에 있는 "OpenAPI 사양" 백 엔드 API를 가져오는 방법을 보여줍니다. 이 백 엔드 API는 Microsoft에서 제공하고 Azure에서 호스트됩니다. 또한 APIM API를 테스트하는 방법도 설명합니다.

이 문서에서는 다음 방법을 설명합니다.

• Azure Portal, Azure CLI 또는 Azure PowerShell을 사용하여 OpenAPI 사양 가져오기
• Azure Portal에서 API 테스트

참고 항목

API 가져오기 제한 사항은 API 가져오기 제한 사항 및 알려진 문제에 설명되어 있습니다.

필수 조건

• API Management 인스턴스. 아직 없는 경우 Azure API Management 인스턴스 만들기 빠른 시작을 완료합니다.

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

• Azure PowerShell

  • Azure PowerShell을 로컬로 사용하도록 선택하는 경우:
    • 최신 버전의 Az PowerShell 모듈을 설치합니다.
    • Connect-AzAccount cmdlet을 사용하여 Azure 계정에 로그인합니다.
  • Azure Cloud Shell을 사용하도록 선택하는 경우:
    • 자세한 내용은 Azure Cloud Shell 개요를 참조하세요.

백 엔드 API 가져오기

포털

1. Azure Portal에서 API Management 인스턴스로 이동합니다.

2. 왼쪽 메뉴에서 API>+ API 추가를 선택합니다.

3. 정의에서 만들기에서 OpenAPI를 선택합니다.

   

4. API 설정을 입력합니다. 생성 중에 값을 설정하거나 나중에 설정 탭으로 이동하여 값을 설정할 수 있습니다. 설정은 첫 번째 API 가져오기 및 게시 자습서에 설명되어 있습니다.

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

Azure CLI

다음 예에서는 az apim api import 명령을 사용하여 지정된 URL에서 apim-hello-world라는 API Management 인스턴스로 OpenAPI 사양을 가져옵니다. URL 대신 사양 경로를 사용해 가져오려면 --specification-path 매개 변수를 사용합니다.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="demo-conference-api"
APIPath="conference"
SpecificationFormat="OpenAPI"
SpecificationURL="https://conferenceapi.azurewebsites.net/?format=json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

API를 가져온 후 필요한 경우 az apim api update 명령을 사용하여 설정을 업데이트할 수 있습니다.

PowerShell

다음 예에서는 Import-AzApiManagementApi Azure PowerShell cmdlet을 사용하여 지정된 URL에서 apim-hello-world라는 API Management 인스턴스로 OpenAPI 사양을 가져옵니다. URL 대신 사양 경로를 사용해 가져오려면 -SpecificationPath 매개 변수를 사용합니다.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "demo-conference-api"
$apiPath = "conference"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://conferenceapi.azurewebsites.net/?format=json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

API를 가져온 후 필요한 경우 Set-AzApiManagementApi cmdlet을 사용하여 설정을 업데이트할 수 있습니다.

포털에서 새 API 테스트

포털에서 직접 작업을 호출할 수 있으며, 관리자들이 이 포털을 사용해 편리한 방법으로 API의 작업을 보고 테스트할 수 있습니다.

1. 이전 단계에서 만든 API를 선택합니다.

2. 테스트 탭을 선택합니다.

3. 작업을 선택합니다. 페이지에 쿼리 매개 변수에 대한 필드와 헤더 필드가 표시됩니다.

   참고 항목

   테스트 콘솔에서 API Management는 Ocp-Apim-Subscription-Key 헤더를 자동으로 채우고 기본 제공된 모든 액세스 구독의 구독 키를 구성합니다. 이 키를 사용하면 API Management 인스턴스의 모든 API에 액세스할 수 있습니다. 선택적으로 HTTP 요청 옆에 있는 "눈" 아이콘을 선택하여 Ocp-Apim-Subscription-Key 헤더를 표시합니다.

4. 작업에 따라 쿼리 매개 변수 값, 헤더 값 또는 요청 본문을 입력합니다. 보내기를 선택합니다.

   테스트가 성공하면 백 엔드는 성공적인 HTTP 응답 코드와 일부 데이터로 응답합니다.

   팁

   기본적으로 테스트 콘솔은 API Management의 CORS 프록시에 요청을 보냅니다. 그러면 API Management 인스턴스에 요청이 전달되고, 그런 다음 백 엔드로 전달됩니다. 이 프록시는 공용 IP 주소 13.91.254.72를 사용하며 공용 엔드포인트에만 연결할 수 있습니다. 브라우저에서 API Management 서비스로 직접 요청을 보내려면 CORS 프록시 무시를 선택합니다. 테스트 콘솔을 사용하고 API Management 게이트웨이가 네트워크로 격리되어 있거나 CORS 프록시의 트래픽을 허용하지 않는 경우 이 옵션을 사용합니다.

API를 디버그하려면 자습서: 요청 추적을 사용하여 API 디버그를 참조하세요.

다른 API 추가

다음을 포함하여 다양한 서비스에 의해 노출되는 API를 구성할 수 있습니다.

• OpenAPI 사양
• SOAP API
• GraphQL API
• Azure App Service에서 호스팅되는 웹앱
• Azure 함수 앱
• Azure Logic Apps
• Azure Service Fabric

다음 단계를 사용하여 기존 API에 다른 API를 추가합니다.

참고 항목

다른 API를 가져오면 작업이 현재 API에 추가됩니다.

1. Azure Portal에서 Azure API Management 인스턴스로 이동합니다.

   

2. 개요 페이지 또는 왼쪽 메뉴에서 API를 선택합니다.

   

3. 다른 API를 추가하려는 API 옆에 있는 ...를 클릭합니다.

4. 드롭다운 메뉴에서 가져오기를 선택합니다.

   

5. API를 가져올 서비스를 선택합니다.

   

관련 항목

• API 가져오기 제한 사항
• OpenAPI 사양 가져오기
• SOAP API 가져오기
• SOAP API를 가져와서 REST로 변환
• App Service API 가져오기
• 컨테이너 앱 API 가져오기
• WebSocket API 가져오기
• GraphQL API 가져오기
• GraphQL 스키마 가져오기 및 필드 확인자 설정
• Azure 함수 앱 가져오기
• Azure 논리 앱 가져오기
• Service Fabric 서비스 가져오기
• Azure OpenAI API 가져오기
• OData API 가져오기
• SAP OData 메타데이터 가져오기
• gRPC API 가져오기
• API 편집

OpenAPI 사양에 대해 유효성을 검사합니다.

OpenAPI 사양의 스키마에 대해 요청 및 응답(또는 그 요소)의 유효성을 검사하도록 API Management 유효성 검사 정책을 구성할 수 있습니다. 예를 들어, 요청 또는 응답 본문의 크기나 콘텐츠의 유효성을 검사하려면 validate-content 정책을 사용합니다.

다음 단계

• 제품 생성 및 게시
• 게시된 API 변환 및 보호