Azure API Management의 GraphQL API 개요

아티클
05/09/2024

적용 대상: 모든 API Management 계층

API Management를 사용하여 GraphQL 쿼리 언어에 기반을 둔 API인 GraphQL API를 관리할 수 있습니다. GraphQL은 API의 데이터에 대한 완전하고 이해하기 쉬운 설명을 제공하여 클라이언트가 필요한 데이터를 정확하게 효율적으로 검색할 수 있도록 합니다. GraphQL에 대한 자세한 정보

API Management는 GraphQL API를 가져오고, 관리하고, 보호하고, 테스트하고, 게시하고, 모니터링하는 데 도움이 됩니다. 두 가지 API 모델 중 하나를 선택할 수 있습니다.

통과 GraphQL	가상 GraphQL
▪️ 기존 GraphQL 서비스 엔드포인트에 대한 통과 API ▪️ GraphQL 쿼리, 변형, 구독 지원	▪️ 사용자 지정 GraphQL 스키마에 기반을 둔 API ▪️ GraphQL 쿼리, 변형, 구독 지원 ▪️ 예를 들어 HTTP 데이터 원본에 대한 사용자 지정 확인자 구성 ▪️ 레거시 API에서 데이터를 사용하는 동안 GraphQL 스키마 및 GraphQL 기반 클라이언트 개발

가용성

GraphQL API는 모든 API Management 서비스 계층에서 지원됩니다.
현재 API Management 작업 영역에서는 가상 GraphQL API가 지원되지 않습니다.
가상 GraphQL API의 GraphQL 구독에 대한 지원은 현재 미리 보기 중이며 소비 계층에서는 사용할 수 없습니다.

GraphQL은 무엇인가요?

GraphQL은 API에 대한 오픈 소스 업계 표준 쿼리 언어입니다. 리소스에 대한 작업을 중심으로 설계된 REST 스타일 API와 달리 GraphQL API는 더 광범위한 사용 사례를 지원하고 데이터 형식, 스키마, 쿼리에 중점을 둡니다.

GraphQL 사양은 REST API를 사용하는 클라이언트 웹앱에서 발생하는 일반적인 문제를 명시적으로 해결합니다.

단일 페이지에 대한 데이터 요구 사항을 충족하려면 많은 수의 요청이 필요할 수 있음
REST API는 렌더링되는 페이지에서 필요한 것보다 많은 데이터를 반환하는 경우가 많음
클라이언트 앱은 새로운 정보를 얻기 위해 폴링해야 함

GraphQL API를 사용하면 클라이언트 앱은 GraphQL 서비스에 대한 단일 요청으로 전송되는 쿼리 문서에서 페이지를 렌더링하는 데 필요한 데이터를 지정할 수 있습니다. 클라이언트 앱은 GraphQL 서비스에서 푸시된 데이터 업데이트를 실시간으로 구독할 수도 있습니다.

스키마 및 형식

API Management에서 백 엔드 GraphQL API 엔드포인트에서 검색되거나 사용자가 업로드한 GraphQL 스키마의 GraphQL API를 추가합니다. GraphQL 스키마는 다음을 설명합니다.

클라이언트가 GraphQL API에서 요청할 수 있는 데이터 개체 유형 및 필드
데이터에 허용되는 작업 유형(예: 쿼리)
데이터에 대한 추가적인 유연성과 제어를 제공하는 공용 구조체 및 인터페이스와 같은 기타 형식

예를 들어 사용자 데이터에 대한 기본 GraphQL 스키마와 모든 사용자에 대한 쿼리는 다음과 같습니다.

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

작업 유형

API Management는 GraphQL 스키마에서 다음 작업 유형을 지원합니다. 이러한 작업 유형에 대한 자세한 내용은 GraphQL 사양을 참조하세요.

쿼리 - REST의 GET 작업과 유사하게 데이터를 가져옵니다.
변형 - REST의 PUT 또는 PATCH 작업과 유사한 서버 쪽 데이터를 수정합니다.
구독 - GraphQL 서비스의 데이터 변경 내용에 대해 구독 클라이언트에게 실시간으로 알릴 수 있습니다.

예를 들어 GraphQL 변형을 통해 데이터가 수정되면 구독 클라이언트는 변경 내용에 대해 자동으로 알림을 받을 수 있습니다.

Important

API Management는 graphql-ws WebSocket 프로토콜을 사용하여 구현된 구독을 지원합니다. 쿼리 및 변형은 WebSocket을 통해 지원되지 않습니다.

기타 형식

API Management는 GraphQL 스키마에서 공용 구조체 및 인터페이스 형식을 지원합니다.

확인자

확인자는 GraphQL 스키마를 백 엔드 데이터에 매핑하여 개체 형식의 각 필드에 대한 데이터를 생성합니다. 데이터 원본은 API, 데이터베이스 또는 다른 서비스일 수 있습니다. 예를 들어 확인자 함수는 이전 예제의 users 쿼리에 대한 데이터를 반환하는 역할을 합니다.

API Management 개체 형식의 필드를 백 엔드 데이터 원본에 매핑하는 확인자를 만들 수 있습니다. 가상 GraphQL API 스키마의 필드에 대해 확인자를 구성하지만 통과 GraphQL API에서 사용하는 기본 필드 확인자를 재정의하도록 구성할 수도 있습니다.

API Management는 현재 HTTP API, Cosmos DB, Azure SQL 데이터 원본을 기반으로 하는 확인자를 지원하여 GraphQL 스키마의 필드에 대한 데이터를 반환합니다. 각 확인자는 맞춤형 정책을 사용하여 데이터 원본에 연결하고 데이터를 검색하도록 구성됩니다.

데이터 원본	확인자 정책
HTTP 기반 데이터 원본(REST 또는 SOAP API)	http-data-source
Cosmos DB 데이터베이스	cosmosdb-data-source
Azure SQL Database	sql-data-source

예를 들어 이전 users 쿼리에 대한 HTTP API 기반 확인자는 백 엔드 REST API의 GET 작업에 매핑될 수 있습니다.

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

확인자 설정에 대한 자세한 내용은 GraphQL 확인자 구성을 참조하세요.

GraphQL API 관리

GraphQL 관련 공격으로부터 보안을 유지하고 보호하는 기존 액세스 제어 정책과 GraphQL 유효성 검사 정책을 모두 적용하여 GraphQL API를 보호합니다.
Azure 및 개발자 포털에서 GraphQL API에 대해 GraphQL 스키마를 검색하고 테스트 쿼리를 실행합니다.

다음을 통해 공유