GraphQL 해결 프로그램 구성

아티클
05/02/2024

적용 대상: 모든 API Management 계층

GraphQL 스키마에 지정된 개체 형식의 GraphQL 필드에 대한 데이터를 검색하거나 설정하는 해결 프로그램을 구성합니다. 스키마는 GraphQL API로 API Management에 가져와야 합니다.

현재 API Management는 다음 데이터 원본에 액세스할 수 있는 해결 프로그램을 지원합니다.

알아야 할 사항

해결 프로그램은 스키마에서 일치하는 개체 형식과 필드가 실행되는 경우에만 호출되는 정책 정의가 포함된 리소스입니다.
각 해결 프로그램은 단일 필드의 데이터를 확인합니다. 여러 필드의 확인하려면 필드마다 각각 해결 프로그램을 구성합니다.
해결 프로그램 범위 정책은 정책 실행 파이프라인의 inbound 및 backend 정책 다음에 평가됩니다. 다른 범위의 정책을 상속하지 않습니다. 자세한 내용은 API Management의 정책을 참조하세요.
해결 프로그램 범위 지정 정책과 별개로 GraphQL API의 API 범위 지정 정책을 구성할 수 있습니다. 예를 들어 validate-graphql-request 정책을 inbound 범위에 추가하여 해결 프로그램이 호출되기 전에 요청 유효성을 검사합니다. API의 API 정책 탭에서 API 범위 지정 정책을 구성합니다.
GraphQL 해결 프로그램에서 인터페이스 및 공용 구조체 형식을 지원하려면 백 엔드 응답에 이미 __typename 필드가 포함되어 있거나 set-body 정책을 사용하여 __typename을 포함하도록 변경되어야 합니다.

필수 조건

기존 API Management 인스턴스. 구독이 아직 없다면 하나를 만듭니다.
통과 또는 가상 GraphQL API를 가져옵니다.

해결 프로그램 만들기

다음 단계에서는 HTTP 기반 데이터 원본을 사용하여 해결 프로그램을 만듭니다. 일반 단계는 지원되는 데이터 원본을 사용하는 해결 프로그램과 비슷합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴에서 API를 선택한 다음, GraphQL API 이름을 선택합니다.
스키마 탭에서 해결 프로그램을 구성하려는 개체 형식의 필드에 대한 스키마를 검토합니다.
1. 필드를 선택한 다음, 왼쪽 여백에 포인터를 올려놓습니다.
2. + 해결 프로그램 추가를 선택합니다.
해결 프로그램 만들기 페이지에서 다음을 수행합니다.
1. 원하는 경우 Name 속성을 업데이트하고 선택적으로 설명을 입력하고 형식 및 필드 선택 항목을 확인하거나 업데이트합니다.
2. 해결 프로그램의 데이터 원본을 선택합니다. 이 예제에서는 HTTP API를 선택합니다.
해결 프로그램 정책 편집기에서 시나리오의 자식 요소로 http-data-source 정책을 업데이트합니다.
1. 필요한 http-request 요소를 정책으로 업데이트하여 GraphQL 작업을 HTTP 요청으로 변환합니다.
2. 필요한 경우 http-response 요소를 추가하고 자식 정책을 추가하여 해결 프로그램의 HTTP 응답을 변환합니다. http-response 요소를 지정하지 않으면 응답이 원시 문자열로 반환됩니다.
3. 만들기를 실행합니다.
해결 프로그램이 필드에 연결되고 해결 프로그램 탭에 나타납니다.

해결 프로그램 관리

API의 해결 프로그램 탭에서 GraphQL API의 해결 프로그램을 나열하고 관리합니다.

해결 프로그램 탭에서 다음을 수행합니다.

연결됨 열은 현재 GraphQL 스키마에 있는 필드에 해결 프로그램을 구성했는지 여부를 나타냅니다. 해결 프로그램이 연결되지 않으면 호출될 수 없습니다.
해결 프로그램의 바로 가기 메뉴(...)에서 해결 프로그램을 복제, 편집 또는 삭제하는 명령을 찾습니다. 나열된 해결 프로그램을 복제하여 다른 형식과 필드를 대상으로 하는 유사한 해결 프로그램을 빠르게 만듭니다.
+ 만들기를 선택하여 새 해결 프로그램을 만들 수 있습니다.

해결 프로그램 편집 및 테스트

단일 해결 프로그램을 편집하면 해결 프로그램 편집 페이지가 열립니다. 마케팅 목록의 구성원을 관리할 수 있습니다.

해결 프로그램 정책과 필요한 경우 데이터 원본을 업데이트합니다. 데이터 원본을 변경하면 현재 해결 프로그램 정책이 덮어쓰기됩니다.
해결 프로그램에서 대상으로 하는 형식과 필드를 변경합니다.
해결 프로그램 구성을 테스트하고 디버그합니다. 해결 프로그램 정책을 편집할 때 테스트 실행을 선택하여 스키마에 대해 유효성을 검사할 수 있는 데이터 원본에서 출력을 검사합니다. 오류가 발생하면 응답에 문제 해결 정보가 포함됩니다.

GraphQL 컨텍스트

해결 프로그램 요청과 응답(지정된 경우)의 컨텍스트는 원래 게이트웨이 API 요청의 컨텍스트와 다릅니다.
- context.GraphQL 속성은 현재 해결 프로그램 실행에 대한 인수(Arguments) 및 부모 개체(Parent)로 설정됩니다.
- 요청 컨텍스트에는 GraphQL 쿼리에서 본문으로 전달되는 인수가 포함되어 있습니다.
- 응답 컨텍스트는 게이트웨이 요청의 전체 응답에 대한 컨텍스트가 아닌 해결 프로그램에서 수행한 독립적인 호출의 응답입니다. 요청 및 응답 파이프라인을 통해 전달되는 context 변수는 GraphQL 해결 프로그램에서 사용될 때 GraphQL 컨텍스트로 확장됩니다.

context.GraphQL.parent

context.GraphQL.parent는 현재 해결 프로그램 실행에 대한 부모 개체로 설정됩니다. 다음 부분 스키마를 고려합니다.

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

또한 특정 블로그에 대한 모든 정보에 대한 GraphQL 쿼리를 고려합니다.

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

Blog 형식의 comments 필드에 대한 해결 프로그램을 설정하는 경우 사용할 블로그 ID를 이해하려고 합니다. 다음 해결 프로그램에 표시된 것처럼 context.GraphQL.Parent["id"]를 사용하여 블로그 ID를 가져올 수 있습니다.

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

context.GraphQL.Arguments

매개 변수화된 GraphQL 쿼리의 인수가 context.GraphQL.Arguments에 추가됩니다. 예를 들어 다음 두 쿼리를 고려합니다.

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

이러한 쿼리는 getComment 해결 프로그램을 호출하는 두 가지 방법입니다. GraphQL은 다음 JSON 페이로드를 전송합니다.

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

다음과 같이 해결 프로그램을 정의할 수 있습니다.

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

다음 단계

더 많은 해결 프로그램 예제는 다음을 참조하세요.

다음을 통해 공유