GraphQL API 가져오기

적용 대상: 모든 API Management 계층

API Management에서는 두 가지 모델 중 하나에 GraphQL API를 추가할 수 있습니다. 즉, 기존 GraphQL 엔드포인트로 통과하거나 GraphQL 스키마를 가져오고 사용자 지정 필드 해결 프로그램을 사용하여 가상 GraphQL API를 만듭니다. 자세한 내용은 GraphQL 개요를 참조하세요.

이 문서에서는 다음을 수행합니다.

• API Management 인스턴스에 통과 GraphQL API를 추가합니다.
• GraphQL API를 테스트합니다.

GraphQL 스키마를 가져오고 REST 또는 SOAP API 엔드포인트를 사용하여 필드 확인자를 설정하려면 GraphQL 스키마 가져오기 및 필드 확인자 설정을 참조하세요.

필수 조건

• 기존 API Management 인스턴스. 구독이 아직 없다면 하나를 만듭니다.

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

• Azure PowerShell

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

GraphQL API 추가

포털

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

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

3. 새 API 정의 아래에서 GraphQL 아이콘을 선택합니다.

   

4. 대화 상자에서 전체를 선택하고 필요한 양식 필드를 작성합니다.

   

   필드	Description
   표시 이름	GraphQL API가 표시되는 이름입니다.
   이름	GraphQL API의 원시 이름입니다. 표시 이름을 입력하면 자동으로 채워집니다.
   GraphQL 형식	기존 GraphQL API 엔드포인트에서 가져오려면 통과 GraphQL을 선택합니다.
   GraphQL API 엔드포인트	GraphQL API 엔드포인트 이름이 있는 기준 URL입니다. 예: https://example.com/your-GraphQL-name https://swapi-graphql.azure-api.net/graphql과 같은 일반적인 "swapi" GraphQL 엔드포인트를 데모로 사용할 수도 있습니다.
   스키마 업로드	필요에 따라 스키마 파일을 찾아 업로드하여 GraphQL 엔드포인트에서 검색된 스키마를 바꿉니다(사용 가능한 경우).
   설명	API에 대한 설명을 추가합니다.
   URL 구성표	GraphQL 엔드포인트를 기반으로 선택합니다. GraphQL API에 구독 유형이 포함된 경우 WebSocket 구성표(WS 또는 WSS)가 포함된 옵션 중 하나를 선택합니다. 기본 선택: HTTP(S).
   API URL 접미사	URL 접미사를 추가하여 이 API Management 인스턴스에서 이 API를 식별합니다. 접미사는 이 API Management 인스턴스에서 고유해야 합니다.
   기준 URL	API 기준 URL을 표시하는 편집 불가능한 필드입니다.
   태그	GraphQL API를 새 태그 또는 기존 태그와 연결합니다.
   제품	GraphQL API를 제품과 연결하여 게시합니다.
   API 버전 관리	GraphQL API에 버전 관리 체계를 적용하려면 선택합니다.

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

6. API가 만들어진 후 디자인 탭에서 스키마를 찾아보거나 수정합니다.

Azure CLI

다음 예에서는 az apim api import 명령을 사용하여 지정된 URL에서 apim-hello-world라는 API Management 인스턴스로 GraphQL 통과 API를 가져옵니다.

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

# API-specific details
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

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

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

PowerShell

다음 예에서는 Import-AzApiManagementApi Azure PowerShell cmdlet을 사용하여 지정된 URL에서 apim-hello-world라는 API Management 인스턴스로 GraphQL 통과 API를 가져옵니다.

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

# API-specific details
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# 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을 사용하여 설정을 업데이트할 수 있습니다.

GraphQL API 테스트

1. API Management 인스턴스로 이동합니다.

2. 측면 탐색 메뉴의 API 섹션 아래에서 API를 선택합니다.

3. 모든 API 아래에서 GraphQL API를 선택합니다.

4. 테스트 탭을 선택하여 테스트 콘솔에 액세스합니다.

5. 헤더 아래에서 다음을 수행합니다.

   1. 이름 드롭다운 메뉴에서 헤더를 선택합니다.
   2. 값 필드에서 값을 입력합니다.
   3. + 헤더 추가를 선택하여 헤더를 더 추가합니다.
   4. 휴지통 아이콘을 사용하여 헤더를 삭제합니다.

6. 제품을 GraphQL API에 추가한 경우 제품 범위 적용 아래에서 제품 범위를 적용합니다.

7. 쿼리 편집기 아래에서 다음 중 하나를 수행합니다.

   1. 측면 메뉴의 목록에서 하나 이상의 필드 또는 하위 필드를 선택합니다. 선택한 필드와 하위 필드가 쿼리 편집기에 표시됩니다.

   2. 쿼리 편집기에서 입력을 시작하여 쿼리를 작성합니다.

      

8. 쿼리 변수 아래에서 동일한 쿼리 또는 변형을 다시 사용하고 다른 값을 전달하는 변수를 추가합니다.

9. 보내기를 선택합니다.

10. 응답을 봅니다.

    

11. 이전 단계를 반복하여 다른 페이로드를 테스트합니다.

12. 테스트가 완료되면 테스트 콘솔을 종료합니다.

구독 테스트

GraphQL API가 구독을 지원하는 경우 테스트 콘솔에서 테스트할 수 있습니다.

1. API가 API에 적합한 WebSocket URL 구성표(WS 또는 WSS)를 허용하는지 확인합니다. 설정 탭에서 이 설정을 사용하도록 설정할 수 있습니다.

2. 쿼리 편집기에서 구독 쿼리를 설정한 다음, 연결을 선택하여 백 엔드 서비스에 대한 WebSocket 연결을 설정합니다.

   

3. 구독 창에서 연결 세부 정보를 검토합니다.

   

4. 구독한 이벤트는 구독 창에 표시됩니다. WebSocket 연결은 연결을 끊거나 새 WebSocket 구독에 연결할 때까지 유지됩니다.

   

GraphQL API 보호

GraphQL 관련 공격으로부터 보호하기 위해 기존 인증 및 권한 부여 정책과 GraphQL 유효성 검사 정책을 모두 적용하여 GraphQL 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 편집

다음 단계

게시된 API 변환 및 보호