데이터 API 작성기에서 GraphQL 엔드포인트 호스트

GraphQL을 통해 사용할 수 있도록 구성된 엔터티는 기본 경로인 https://{base_url}//graphql.에서 사용할 수 있습니다. 데이터 API 작성기에서는 구성된 모든 엔터티에 대한 쿼리 및 변형 필드가 있는 GraphQL 스키마를 자동으로 생성합니다. GraphQL 스키마는 자동 완성과 같은 기능을 포함하는 최신 GraphQL 클라이언트를 사용하여 탐색할 수 있습니다.

시작 예제(GraphQL 액세스를 위해 구성된 books 및 authors 엔터티가 있는 경우 GraphQL을 사용하는 것이 얼마나 쉬운지 확인할 수 있습니다.

결과 집합 형식

반환된 결과는 다음 형식의 JSON 개체입니다.

{
    "data": {}    
}

지원되는 루트 형식

데이터 API 작성기에서 지원하는 GraphQL 루트 형식은 다음과 같습니다.

쿼리변형

쿼리

각 엔터티는 다음 작업을 지원합니다.

• 페이지 매김
• 기본 키 쿼리
• 제네릭 쿼리

달리 지정하지 않는 한 데이터 API 작성기는 쿼리가 단일 항목을 반환해야 할 때마다 엔터티의 단수 이름을 사용합니다. 반대로 데이터 API 작성기는 쿼리가 항목 목록을 반환해야 할 때마다 엔터티의 복수 이름을 사용합니다. 예를 들어 book 엔터티에는 다음이 있습니다.

• book_by_pk(): 0개 또는 1개의 엔터티를 반환하려면
• books(): 0개 이상의 엔터티 목록을 반환하려면

페이지 매김

0개 이상의 항목을 반환하는 모든 쿼리 형식은 페이지 매김을 지원합니다.

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

• item 개체를 사용하여 엔터티 필드에 액세스할 수 있습니다.
• 반환할 항목이 더 있는 경우 hasNextPage true로 설정됩니다.
• endCursor first 및 after 쿼리 매개 변수와 함께 사용하여 항목의 다음 집합(또는 페이지)을 가져오는 데 사용할 수 있는 불투명 커서 문자열을 반환합니다.

기본 키로 쿼리

모든 엔터티는 다음 쿼리 형식을 사용하여 기본 키를 통해 특정 항목의 검색을 지원합니다.

<entity>_by_pk(<pk_colum>:<pk_value>)
{
    <fields>
}

예를 들어:

{
  book_by_pk(id:1010) {
    title
  }
}

일반 쿼리

모든 엔터티는 다음 매개 변수를 사용하여 원하는 순서대로 원하는 항목만 요청할 수 있도록 제네릭 쿼리 패턴도 지원합니다.

• filter: 반환된 항목을 필터링합니다.
• orderBy: 반환된 데이터를 정렬하는 방법을 정의합니다.
• first 및 after: 상위 n 항목만 반환합니다.

예를 들어:

{
  authors(
    filter: {
        or: [
          { first_name: { eq: "Isaac" } }
          { last_name: { eq: "Asimov" } }
        ]
    }
  ) {
    items {
      first_name
      last_name
      books(orderBy: { year: ASC }) {
        items {
          title
          year
        }
      }
    }
  }
}

filter

filter 매개 변수의 값은 엔터티의 필드를 사용하는 조건자 식(부울 값을 반환하는 식)입니다. 식이 'True'로 평가되는 항목만 응답에 포함됩니다. 예를 들어:

{
  books(filter: { title: { contains: "Foundation" } })
  {
    items {
      id
      title
      authors {
        items {
          first_name
          last_name
        }
      }
    }
  }
}

이 쿼리는 제목에 Foundation 단어가 포함된 모든 책을 반환합니다.

filter 매개 변수에서 지원하는 연산자는 다음과 같습니다.

orderBy

orderby 값은 결과 집합의 항목이 반환되는 순서를 설정합니다. 예를 들어:

{
  books(orderBy: {title: ASC} )
  {
    items {
      id
      title
    }
  }
}

이 쿼리는 title정렬된 책을 반환합니다.

first 및 after

매개 변수 first 반환되는 항목 수를 제한합니다. 예를 들어:

query {
  books(first: 5)
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

이 쿼리는 처음 다섯 권의 책을 반환합니다. orderBy 지정하지 않으면 기본 기본 키를 기준으로 항목이 정렬됩니다. orderBy 제공된 값은 양의 정수여야 합니다.

book 엔터티에 first통해 요청된 엔터티보다 더 많은 항목이 있는 경우 hasNextPage 필드는 true평가되고 endCursor 다음 항목에 액세스하기 위해 after 매개 변수와 함께 사용할 수 있는 문자열을 반환합니다. 예를 들어:

query {
  books(first: 5, after: "W3siVmFsdWUiOjEwMDQsIkRpcmVjdGlvbiI6MCwiVGFibGVTY2hlbWEiOiIiLCJUYWJsZU5hbWUiOiIiLCJDb2x1bW5OYW1lIjoiaWQifV0=")
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

돌연변이

각 엔터티에 대해 만들기, 업데이트 및 삭제 작업을 지원하는 변형이 자동으로 생성됩니다. 변경 작업은 다음 이름 패턴을 사용하여 생성됩니다. <operation><entity>. 예를 들어 book 엔터티의 경우 변형은 다음과 같습니다.

• createbook: 새 책 만들기
• updatebook: 기존 책 업데이트
• deletebook: 지정한 책 삭제

창조하다

원하는 엔터티의 새 요소를 만들기 위해 create<entity> 변형이 제공됩니다. 생성된 변형을 사용하려면 새 항목을 만들 때 엔터티의 필수 필드에 대한 값을 지정하는 item 매개 변수가 필요합니다.

create<entity>(item: <entity_fields>)
{
    <fields>
}

예를 들어:

mutation {
  createbook(item: {
    id: 2000,
    title: "Leviathan Wakes"    
  }) {
    id
    title
  }  
}

업데이트

원하는 엔터티의 요소를 업데이트하기 위해 update<entity> 변형이 제공됩니다. 업데이트 변경에는 다음 두 개의 매개 변수가 필요합니다.

• <primary_key>, 업데이트할 요소를 식별하기 위한 기본 키 열 및 관련 값의 키-값 목록
• item: 지정된 항목을 업데이트할 때 사용할 엔터티의 필수 필드 값이 있는 매개 변수

update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
    <fields>
}

예를 들어:

mutation {
  updatebook(id: 2000, item: {
    year: 2011,
    pages: 577    
  }) {
    id
    title
    year
    pages
  }
}

삭제하다

원하는 엔터티의 요소를 삭제하기 위해 delete<entity> 변형이 제공됩니다. 삭제할 요소의 기본 키는 필수 매개 변수입니다.

delete<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,])
{
    <fields>
}

예를 들어:

mutation {
  deletebook(id: 1234)
  {
    id
    title
  }  
}

변형에 대한 데이터베이스 트랜잭션

일반적인 GraphQL 변형 요청을 처리하기 위해 Data API Builder는 두 개의 데이터베이스 쿼리를 생성합니다. 데이터베이스 쿼리 중 하나는 변경과 관련된 업데이트(또는) 삽입(또는) 삭제 작업을 수행합니다. 다른 데이터베이스 쿼리는 선택 집합에서 요청된 데이터를 가져옵니다.

데이터 API 작성기에서는 트랜잭션에서 두 데이터베이스 쿼리를 모두 실행합니다. 트랜잭션은 SQL 데이터베이스 형식에 대해서만 생성됩니다.

다음 표에서는 각 데이터베이스 유형에 대해 트랜잭션이 만들어지는 격리 수준을 나열합니다.

관련 콘텐츠

• GraphQL 구성 참조
• OpenAPI