GraphQL 사용

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

GraphQL 정책은 GraphQL 요청 페이로드를 메시지 흐름 변수로 파싱하거나 GraphQL 스키마에 대해 요청을 확인하거나 둘 다 수행할 수 있습니다.

GraphQL 정책은 GraphQL 페이로드를 메시지 흐름 변수로 파싱하거나 스키마에 대해 GraphQL 요청을 확인하거나 둘 다 수행할 수 있습니다.

GraphQL 정책을 사용하여 다음을 수행할 수 있습니다.

API가 제공된 스키마를 준수하는 요청만 처리하도록 합니다.
허용되는 최대 조각 수를 설정하여 페이로드에 대해 제한사항을 지정합니다.
GraphQL을 API 제품과 연결합니다.
REST에서와 같이 Oauth2, VerifyAPIKey, Quota 정책 기능을 활용합니다.

GraphQL에서는 다음 유형의 페이로드를 지원합니다.

Content-Type : application/graphql을 사용한 graphQL 페이로드 POST
Content-Type: applcation/json을 사용한 graphQL 페이로드 POST
페이로드가 쿼리 매개변수인 graphQL 페이로드의 GET

참고: application/json 페이로드 형식은 다음과 같습니다.

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee는 현재 선택사항인 operationName 및 variables 필드를 무시합니다.

GraphQL 정책 옵션에 대한 빠른 요약은 아래의 GraphQL 옵션을 참조하세요.

GraphQL에 대한 자세한 내용은 GraphQL.org를 참조하세요.

예시

다음 예시는 GraphQL 스키마를 Apigee에 업로드하고 이를 사용하여 GraphQL 콘텐츠가 있는 요청을 검증하는 방법을 보여줍니다.

스키마 파일 만들기

예시를 실행하려면 먼저 다음 콘텐츠로 GraphQL 스키마 파일을 만듭니다.

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

사용하려는 이름을 지정하고 그 뒤에 확장자 .graphql을 추가하여 파일을 저장합니다.

Apigee UI로 GraphQL 정책 추가

새 프록시 편집기

먼저 다음과 같이 GraphQL 정책을 만듭니다.

Apigee UI에 로그인합니다.
탐색 메뉴에서 개발 > API 프록시를 선택합니다.
프록시 목록에서 GraphQL 정책을 사용할 API 프록시를 선택합니다.
개발 탭을 클릭합니다.
왼쪽 창의 정책 폴더 옆에 있는 + 버튼을 클릭합니다.
정책 만들기 대화상자에서 정책 유형 선택 필드를 클릭하고 미디에이션으로 스크롤하고 GraphQL을 선택합니다.

표시 이름과 이름을 입력합니다.

그런 후 다음과 같이 GraphQL 스키마 파일을 선택합니다.
1. 스키마 파일 필드를 클릭합니다. 그러면 다음 옵션이 표시됩니다.
  - 스키마 없음. 이 옵션을 선택하면 Apigee가 스키마를 사용하여 요청을 검증하지 않습니다.
  - GraphQL 스키마 가져오기(.graphql)
2. GraphQL 스키마 가져오기(.graphql)를 선택합니다. 그러면 다음이 표시됩니다.
3. 파일 선택을 클릭하고 이전에 만든 스키마 파일(확장자가 .graphql이어야 함)을 선택합니다. 스키마 이름 필드에 파일이 표시됩니다.
만들기를 클릭하여 정책을 만듭니다.

이제 GraphQL 정책을 만들었으므로 PreFlow의 단계에 연결할 수 있습니다.

왼쪽 창에서 프록시 엔드포인트 > 기본값 > PreFlow를 선택합니다.
비주얼 편집기 하단의 응답 창에서 PreFlow 옆에 있는 + 버튼을 클릭합니다.
정책 단계 추가 대화상자에서 GQL- 정책을 선택합니다.
참고: 이 예시에는 GraphQL 정책의 기본 이름인 GQL이 사용됩니다. 정책 XML의 DisplayName 요소에서 GQL- 다음에 설명 문구를 추가하여 이름을 변경할 수 있습니다. 정책 이름 변경을 참조하세요.
추가를 클릭하여 정책을 연결합니다.
저장을 클릭하여 변경사항과 함께 현재 수정 버전을 저장합니다.
변경사항을 배포하려면 개요 탭을 클릭하고 배포를 선택합니다.

GraphQL 정책에 대해 설정할 수 있는 옵션은 아래의 GraphQL 옵션을 참조하세요.

기본 프록시 편집기

Apigee UI에 로그인합니다.
탐색 메뉴에서 개발 > API 프록시를 선택합니다.
프록시 목록에서 GraphQL 정책을 사용할 API 프록시를 선택합니다.
개발 탭을 클릭합니다.
흐름: PreFlow 창에서 + 단계 버튼을 클릭합니다.
단계 추가 창에서 미디에이션 섹션으로 스크롤하고 GraphQL을 선택합니다.

단계 추가 창에 다음 옵션이 표시됩니다.
- 표시 이름: 정책의 표시 이름입니다.
- 이름: 정책의 내부 이름입니다.
- 스키마 파일: Apigee가 GraphQL 콘텐츠가 포함된 요청을 검증하기 위해 사용할 GraphQL 스키마가 포함된 파일을 업로드하는 옵션입니다.
스키마를 사용하려면 다음 안내를 따르세요.
1. 스키마 파일 필드를 클릭합니다. 그러면 다음 옵션이 표시됩니다.
  - 스키마 없음. 이 옵션을 선택하면 Apigee가 스키마를 사용하여 요청을 검증하지 않습니다.
  - GraphQL 스키마 가져오기(.graphql)
2. GraphQL 스키마 가져오기(.graphql)를 선택합니다. 그러면 다음이 표시됩니다.
3. 파일 선택을 클릭하고 이전에 만든 스키마 파일(확장자가 .graphql이어야 함)을 선택합니다. 스키마 이름 필드에 파일이 표시됩니다.
추가를 클릭합니다. 흐름: PreFlow 창이 이제 아래 표시된 것처럼 나타납니다.

GraphQL 정책에 대해 설정할 수 있는 옵션은 아래의 GraphQL 옵션을 참조하세요. 이 예시에서는 이를 있는 그대로 둡니다.
프록시를 배포하려면 개요 탭을 클릭하고 배포를 선택합니다.

이제 다음 curl 명령어를 사용하여 GraphQL 정책을 테스트할 수 있습니다.

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

여기서 PROXY_BASEPATH는 프록시 기본 경로이고 HOST_NAME은 최신 개정 번호를 포함한 프록시의 이름입니다. 명령어를 실행하면 Apigee가 스키마에 대해 요청을 검증하고 다음 출력을 반환합니다.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

이것은 요청의 또 다른 예시입니다

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

이번에는 다음 오류 메시지와 함께 요청 검증이 실패합니다.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

GraphQL 옵션

GraphPolicy에는 다음 옵션이 있습니다.

OperationType: 작업 유형입니다. 옵션은 다음과 같습니다.
- query: REST GET 작업에 상응하는 GraphQL 작업입니다.
- mutation: REST PUT 작업에 상응하는 GraphQL 작업입니다.
- query_mutation: query 및 mutation 모두입니다.
MaxDepth: 트리로 표현되는 쿼리의 최대 깊이입니다. MaxDepth를 사용하면 페이로드에서 깊은 쿼리를 차단하여 Apigee가 값을 저장하기 위해 매우 큰 흐름 변수를 만들 필요가 없도록 할 수 있습니다. 하지만 페이로드는 MaxDepth 값에 관계없이 있는 그대로 전송됩니다.
MaxCount: 페이로드에 있을 수 있는 조각의 최대 개수입니다. 이를 사용하면 고객의 GraphQL 백엔드 서버가 매우 복잡한 쿼리를 실행하지 않도록 방지하고 클라이언트가 논리를 더 작은 페이로드로 강제로 분할하도록 할 수 있습니다.
Action: 다음 GraphQL 작업 중 하나입니다.
- parseApigee는 GraphQL 페이로드를 흐름 변수로 파싱합니다. 그러면 JavaCallout과 같은 정책에서 흐름 변수의 콘텐츠를 사용할 수 있습니다. parse도 페이로드를 확인합니다.
- verify: Apigee는 GraphQL 페이로드가 프록시에 업로드된 스키마를 준수하는지 확인합니다. verify를 사용하면 스키마를 준수하지 않는 요청이 수신되지 않습니다. 이렇게 하면 백엔드에서 가치 있는 CPU 시간을 절약할 수 있습니다.
- parse_verify: 페이로드를 파싱하고 확인합니다.
ResourceURL: Apigee에서 GraphQL 요청을 확인하는 데 사용하는 GraphQL 스키마 파일의 경로입니다.

이러한 옵션에 대한 자세한 내용은 GraphQL 정책 참조 페이지를 참조하세요.