GraphQL 정책

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

GraphQL 정책 아이콘

대상

The GraphQL policy can parse GraphQL payloads into message flow variables, verify GraphQL requests against a schema, or both.

You can use the GraphQL policy to:

Ensure that your APIs only process requests that conform to the schema you provide.
Impose restrictions on the payload by setting a maximum on the number of fragments allowed.
Associate GraphQL with API products.
Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.

GraphQL supports the following types of payloads:

POST of graphQL payloads with Content-Type : application/graphql
POST of graphQL payloads with Content-Type: applcation/json
GET of graphQL payloads where the payload is a query parameter

Note: For application/json payloads of the form

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

Apigee currently ignores the optional operationName and variables fields.

자세한 내용은 다음 리소스를 참조하세요.

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

이 정책을 사용하는 예시는 GraphQL 사용을 참조하세요.

`<GraphQL>` 요소

<GraphQL> 정책을 정의합니다.

기본값	아래의 기본 정책 탭을 참조하세요.
필수 여부	필수
유형	TYPE
상위 요소	해당 사항 없음
하위 요소	`<Action>` `<MaxDepth>` `<MaxCount>` `<MaxPayloadSizeInBytes>` `<OperationType>` `<Source>` `<ResourceURL>`

구문

<GraphQL> 요소는 다음 문법을 사용합니다.

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES&lt/MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

기본 정책

다음 예시에서는 Apigee UI에서 흐름에 <GraphQL> 정책을 추가할 때의 기본 설정을 보여줍니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성	기본	필수 여부	설명
`name`	해당 없음	필수	정책의 내부 이름입니다. `name` 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 `<DisplayName>` 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
`continueOnError`	false	선택	정책이 실패할 경우 오류가 반환되도록 하려면 `false`로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 `true`로 설정합니다. 참조: 오류 규칙이 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 정책 오류 처리
`enabled`	true	선택	정책을 시행하려면 `true`로 설정합니다. 정책을 중지하려면 `false`로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
`async`	false	지원 중단됨	이 속성은 지원이 중단되었습니다.

다음 표에서는 <GraphQL>의 하위 요소에 대한 대략적인 설명을 제공합니다.

하위 요소	필수 여부	설명
일반적인 작업
`<Action>`	선택사항	요청에 수행할 작업을 `parse`, `verify`, `parse_verify`(둘 다)로 지정합니다.
`<MaxCount>`	선택사항	GraphQL 요청이 발생시킬 수 있는 쿼리 또는 조각의 최대 개수입니다. 기본값은 10입니다.
`<MaxDepth>`	선택사항	쿼리의 최대 트리 깊이입니다. 기본값은 4입니다.
`<MaxPayloadSizeInBytes>`	선택사항	페이로드의 최대 크기(킬로바이트)입니다.
`<OperationType>`	필수	파싱할 수 있는 요청 유형을 `query`, `mutation`, `query_mutation`(둘 중 하나)을 지정합니다.
`<ResourceURL>`	선택사항	설명. GraphQL 스키마 파일의 위치입니다.
`<Source>`	필수	`request`

각 하위 요소는 다음 섹션에 설명되어 있습니다.

하위 요소 참조

이 섹션에서는 <GraphQL>의 하위 요소를 설명합니다.

`<Action>`

작업은 다음 GraphQL 작업 중 하나를 나타냅니다.

parse: Apigee가 GraphQL 페이로드를 메시지 흐름 변수로 파싱합니다. Action이 parse로 설정될 때 설정되는 변수에 대한 설명은 메시지 흐름 변수 표현의 예시를 참조하세요. 이렇게 하면 백엔드에서 가치 있는 CPU 시간을 절약할 수 있습니다. verify도 페이로드를 파싱합니다.
verify: Apigee는 GraphQL 페이로드가 프록시에 업로드된 스키마를 준수하는지 확인합니다.
parse_verify: Apigee가 GraphQL 요청을 파싱하고 확인합니다.

기본값	`parse`
필수 여부	선택사항
유형	문자열
상위 요소	`<GraphQL>`
하위 요소	없음

<Action> 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

`<MaxCount>`

페이로드에 있을 수 있는 조각의 최대 개수입니다. 이를 사용하여 고객의 GraphQL 백엔드 서버가 매우 복잡한 쿼리를 실행하지 않도록 방지하고, 클라이언트가 논리를 더 작은 페이로드로 분할하도록 강제할 수 있습니다.

기본값	`10`
필수 여부	선택사항
유형	문자열
상위 요소	`<GraphQL>`
하위 요소	없음

<MaxCount> 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

`<MaxDepth>`

트리로 표현되는 쿼리의 최대 깊이입니다. MaxDepth를 사용하면 페이로드에서 깊은 쿼리를 차단하여 Apigee가 값을 저장하기 위해 매우 큰 흐름 변수를 만들 필요가 없도록 할 수 있습니다. 하지만 페이로드는 MaxDepth 값에 관계없이 있는 그대로 전송됩니다. 기본값은 10입니다.

참고: MaxDepth는 Action 요소가 parse 또는 parse-verify로 설정된 경우에만 작동합니다. 더 비용이 많이 드는 verify 작업 대신 이러한 작업에 MaxDepth를 사용하여 깊이를 확인하는 것이 좋습니다.

기본값	`10`
필수 여부	선택사항
유형	정수
상위 요소	`<GraphQL>`
하위 요소	없음

<MaxDepth> 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

`<MaxPayloadSizeInBytes>`

페이로드의 최대 크기(킬로바이트)입니다. 이를 통해 페이로드 크기를 제한하여 성능 문제를 방지할 수 있습니다.

참고: MaxPayloadSizeInByte가 정책에 제공되지 않았으면 크기 제한이 적용되지 않습니다.

기본값	`request`
필수 여부	선택사항
유형	문자열
상위 요소	`<GraphQL>`
하위 요소	없음

<MaxPayloadSizeInBytes> 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

`<OperationType>`

파싱될 수 있는 요청 유형을 나타냅니다.

query: GraphQL 쿼리입니다.
mutation: GraphQL 변형입니다.
query_mutation: GraphQL 쿼리 또는 변형입니다.

범위가 query이고 변형 요청이 전달되었으면 요청이 실패하고 4xx 오류가 반환됩니다.

기본값	`query`
필수 여부	선택사항
유형	문자열
상위 요소	`<GraphQL>`
하위 요소	없음

<OperationType> 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

`<ResourceURL>`

GraphQL 정책이 요청을 확인할 기준이 되는 GraphQL 스키마 파일의 경로입니다. Apigee에 GraphQL 스키마를 업로드하는 예시를 참조하세요.

업로드한 스키마 파일 이름이 my-schema.graphql일 때 <ResourceURL> 요소는 다음과 같습니다.

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

기본값	해당 사항 없음
필수 여부	선택사항
유형	문자열
상위 요소	`<GraphQL>`
하위 요소	없음

ResourceURL 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

`<Source>`

이 정책이 실행되는 소스입니다.

기본값	`request`
필수 여부	선택사항
유형	문자열
상위 요소	`<GraphQL>`
하위 요소	없음

<Source> 요소는 다음 구문을 사용합니다.

구문

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

GraphQL 파서

graphQL 파서는 graphQL 쿼리의 모든 기능을 지원하며 메시지 흐름 점선 표기법을 사용한 그래프로 표현합니다. 쿼리는 작업 정의 및 선택적으로 조각 정의로 식별되는 조각들로 구성될 수 있습니다. GraphQL 사양을 참조하세요.

graphQL 요청 심층 분석

아래 다이어그램은 graphQL 요청에 대한 심층 분석을 보여줍니다.

작업 정의의 메시지 흐름 표현

파서 구현에는 쿼리 및 변형 지원을 포함하여 graphQL 구문의 모든 특성이 포함됩니다. 메시지 흐름 변수를 참조하세요.

메시지 흐름 변수는 다음 규칙을 따릅니다.

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

각 항목의 의미는 다음과 같습니다.

graphql: 이를 나타내는 정적 프리픽스는 graphQL 관련 메시지 흐름 변수입니다.
root-Index: 루트 수준 쿼리 정의 색인을 나타내는 기본 색인입니다(기본적으로 요청당 최대 4개).
root-definition: 루트 수준의 graphQL 요청 메시지 본문, 인수, 해당 값입니다.
sub-indices: 하위 색인입니다.
child-definitions: 특정 필드 및 해당 값과 관련된 리프 수준 정의입니다.

작업 정의의 메시지 흐름 변수 표현

메시지의 필드	유형	설명
name	문자열	graphQL 작업의 이름입니다. 이 이름은 메시지 흐름의 이름과 관련이 없습니다.
정의	문자열 - 작업	여기에 쿼리 요청의 기본 메시지 본문이 포함됨을 나타냅니다.
operationType	쿼리 또는 변형	수행 중인 작업 유형입니다.
variableDefinition	정수	입력된 언어로 함수의 인수 정의와 같이 작동합니다. $ 프리픽스와 해당 유형이 표시된 모든 변수를 나열합니다.
지시어	정수	@include 및 @skip은 현재 제공된 2가지 지시어이며, 동적으로 전달되는 값을 기준으로 필터링될 수 있습니다.
selectionSet	정수	객체와 연관된 모든 속성의 한 수준의 논리적 그룹입니다.

조각 정의의 메시지 흐름 표현

메시지 흐름 변수 이름	유형	설명
name	문자열	조각의 이름입니다.
정의	문자열 - 조각	요청의 본문이 기본 요청에 대한 조각임을 나타냅니다.
typeCondition	문자열	조각이 호출되는 조건입니다.
variableDefinition	정수	조각에 인수로 전달된 변수 정의입니다.

메시지 흐름 변수 표현의 예시

다음 예시는 샘플 요청 페이로드의 메시지 흐름 변수 표현을 보여줍니다.

샘플 쿼리 1

이 예시는 입력으로 전달된 인수를 사용하여 작성된 쿼리를 보여주며, 직원에 대한 속성 3개를 쿼리합니다.

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

테이블에는 해당하는 메시지 흐름 변수 표현이 표시됩니다.

메시지 흐름 변수	값
`graphql.operation.operationType`	`QUERY`
`graphql.fragment.count`	`1`
`graphql.operation.selectionSet.count`	`1`
`graphql.operation.variableDefinitions.count`	`0`
`graphql.operation.selectionSet.1.name`	`employee`
`graphql.operation.selectionSet.1.argument.count`	`1`
`graphql.operation.selectionSet.1.argument.1.name`	`id`
`graphql.operation.selectionSet.1.argument.1.value`	`IntValue{value=123}`
`graphql.operation.selectionSet.1.directive.count`	`0`
`graphql.operation.selectionSet.1.selectionSet.count`	`3`
`graphql.operation.selectionSet.1.selectionSet.1.name`	`id`
`graphql.operation.selectionSet.1.selectionSet.2.name`	`firstName`
`graphql.operation.selectionSet.1.selectionSet.3.name`	`lastName`

샘플 쿼리 2

이 예시는 입력으로 전달된 인수를 사용하여 작성된 쿼리를 보여주며, 친구의 이름을 쿼리합니다.

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

아래 테이블에서는 해당하는 메시지 흐름 변수 표현을 보여줍니다.

메시지 흐름 변수	값
`graphql.operation.operationType`	`QUERY`
`graphql.operation.selectionSet.count`	`1`
`graphql.operation.name`	`Characters`
`graphql.fragment.count`	`0`
`graphql.operation.selectionSet.1.name`	`friends`
`graphql.operation.variableDefinitions.count`	`2`
`graphql.operation.variableDefinitions.1.name`	`episode`
`graphql.operation.variableDefinitions.1.type`	`TypeName{name='Episode'}`
`graphql.operation.variableDefinitions.2.name`	`withFriends`
`graphql.operation.variableDefinitions.2.type`	`NonNullType{type=TypeName{name='Boolean'}}`
`graphql.operation.selectionSet.1.argument.count`	`0`
`graphql.operation.selectionSet.1.selectionSet.count`	`1`
`graphql.operation.selectionSet.1.selectionSet.1.name`	`friendsName`
`graphql.operation.selectionSet.1.directive.count`	`1`
`graphql.operation.selectionSet.1.directive.1.argument.1.name`	`if`
`graphql.operation.selectionSet.1.directive.1.argument.1.value`	`VariableReference{name='withFriends'}`

샘플 쿼리 3

이 예시는 별칭이 포함된 변수 정의가 있습니다.

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}