이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
제목
GraphQL 정책은 GraphQL 페이로드를 메시지 흐름 변수로 파싱하거나 스키마에 대해 GraphQL 요청을 확인하거나 둘 다 수행할 수 있습니다.
GraphQL 정책을 사용하여 다음을 수행할 수 있습니다.
- API가 제공된 스키마를 준수하는 요청만 처리하도록 합니다.
- 허용되는 최대 조각 수를 설정하여 페이로드에 대해 제한사항을 지정합니다.
- GraphQL을 API 제품과 연결합니다.
- REST에서와 같이 Oauth2, VerifyAPIKey, Quota 정책 기능을 활용합니다.
GraphQL에서는 다음 유형의 페이로드를 지원합니다.
Content-Type : application/graphql
을 사용한 graphQL 페이로드 POSTContent-Type: applcation/json
을 사용한 graphQL 페이로드 POST- 페이로드가 쿼리 매개변수인 graphQL 페이로드의 GET
자세한 내용은 다음 리소스를 참조하세요.
이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 모든 사용자가 정책 및 환경 유형에 대해 알아야 할 필요는 없습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.
이 정책을 사용하는 예시는 GraphQL 사용을 참조하세요.
<GraphQL>
요소
<GraphQL>
정책을 정의합니다.
기본값 | 아래의 기본 정책 탭을 참조하세요. |
필수 여부 | 필수 |
유형 | 유형 |
상위 요소 | 해당 사항 없음 |
하위 요소 | <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</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 |
해당 없음 | 필수 |
정책의 내부 이름입니다. 원하는 경우 |
continueOnError |
false | 선택 | 정책이 실패할 경우 오류가 반환되도록 하려면 false 로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true 로 설정합니다. 참조:
|
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입니다.
기본값 | 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 작업의 이름입니다. 이 이름은 메시지 흐름의 이름과 관련이 없습니다. |
definition | 문자열 - 작업 | 여기에 쿼리 요청의 기본 메시지 본문이 포함됨을 나타냅니다. |
operationType | 쿼리 또는 변형 | 수행 중인 작업 유형입니다. |
variableDefinition | 정수 | 입력된 언어로 함수의 인수 정의와 같이 작동합니다. $ 프리픽스와 해당 유형이 표시된 모든 변수를 나열합니다. |
directives | 정수 | @include 및 @skip은 현재 제공된 2가지 지시어이며, 동적으로 전달되는 값을 기준으로 필터링될 수 있습니다. |
selectionSet | 정수 | 객체와 연관된 모든 속성의 한 수준의 논리적 그룹입니다. |
조각 정의의 메시지 흐름 표현
메시지 흐름 변수 이름 | 유형 | 설명 |
---|---|---|
name | 문자열 | 조각의 이름입니다. |
definition | 문자열 - 조각 | 요청의 본문이 기본 요청에 대한 조각임을 나타냅니다. |
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 } }
아래 테이블에서는 해당하는 메시지 흐름 변수 표현을 보여줍니다.
메시지 흐름 변수 | 값 |
---|---|
graphql.operation.operationType |
QUERY |
graphql.operation.selectionSet.count |
2 |
graphql.operation.selectionSet.1.name |
users |
graphql.operation.selectionSet.1.alias |
admins |
graphql.operation.variableDefinitions.count |
0 |
graphql.operation.selectionSet.1.argument.count |
1 |
graphql.operation.selectionSet.1.argument.1.name |
role |
graphql.operation.selectionSet.1.argument.1.value |
EnumValue{name='ADMIN'} |
graphql.operation.selectionSet.1.argument.2.name |
null |
graphql.operation.selectionSet.1.argument.2.value |
null |
graphql.operation.selectionSet.1.selectionSet.count |
1 |
graphql.operation.selectionSet.1.selectionSet.count |
1 |
graphql.operation.selectionSet.1.selectionSet.1.name |
lastName |
graphql.operation.selectionSet.1.selectionSet.1.alias |
null |
graphql.operation.selectionSet.1.selectionSet.2.name |
null |
graphql.operation.selectionSet.1.selectionSet.2.alias |
null |
graphql.operation.selectionSet.1.directive.count |
0 |
graphql.operation.selectionSet.1.directive.1.argument.1.name |
null |
graphql.operation.selectionSet.1.directive.1.argument.1.value |
null |
graphql.operation.selectionSet.2.name |
users |
graphql.operation.selectionSet.2.alias |
accountants |
graphql.operation.selectionSet.2.argument.count |
1 |
graphql.operation.selectionSet.2.argument.1.name |
role |
graphql.operation.selectionSet.2.argument.1.value |
EnumValue{name='ACCOUNTANT'} |
graphql.operation.selectionSet.2.selectionSet.count |
1 |
graphql.operation.selectionSet.2.selectionSet.1.name |
firstName |
graphql.operation.selectionSet.2.directive.count |
0 |
graphql.operation.selectionSet.2.selectionSet.1.alias |
null |
graphql.operation.selectionSet.2.selectionSet.2.name |
null |
graphql.operation.selectionSet.2.selectionSet.2.alias |
null |
graphql.operation.selectionSet.2.directive.count |
0 |