Размещать конечные точки GraphQL в конструкторе API данных

Сущности, настроенные для доступности с помощью GraphQL, доступны по умолчанию по пути: https://{base_url}//graphql. Построитель данных автоматически создает схему GraphQL с полями запроса и мутации для всех настроенных сущностей. Схему GraphQL можно изучить с помощью современного клиента GraphQL, который включает такие функции, как автозавершение.

Если вы следовали примеру "Начало работы", где сущности books и authors настроены для доступа GraphQL, можно увидеть, как легко использовать GraphQL.

Формат результирующего набора данных

Возвращенный результат представляет собой объект JSON с таким форматом:

{
    "data": {}    
}

Поддерживаемые корневые типы

Построитель данных поддерживает следующие корневые типы GraphQL:

ЗапросыМутации

Запросы

Каждая сущность поддерживает следующие действия:

• Разбиение на страницы
• Запрос по первичному ключу
• Универсальный запрос

Построитель API данных, если иное не указано, использует единственное имя сущности, когда запрос должен возвращать один элемент. И наоборот, построитель данных использует множественное имя сущности всякий раз, когда запрос должен возвращать список элементов. Например, сущность book имеет:

• book_by_pk(): для возврата нуля или одной сущности
• books(): для возврата списка нулевых или более сущностей

Постраничная разбивка

Все типы запросов, возвращающие ноль или больше элементов, поддерживают разбиение на страницы:

{
  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 — предикатное выражение (выражение, возвращающее логическое значение), использующее поля сущности. В ответ включаются только элементы, в которых выражение оценивается как Истина. Рассмотрим пример.

{
  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, построитель данных создает два запроса базы данных. Один из запросов базы данных выполняет действие обновления (или) вставки (или) удаления, связанного с мутацией. Другой запрос базы данных извлекает данные, запрошенные в наборе данных для выбора.

Построитель API данных выполняет оба запроса базы данных в транзакции. Транзакции создаются только для типов баз данных SQL.

[! INCLUDE[Уровни изоляции базы данных.. /includes/database-isolation-levels.md)]