Конечные точки GraphQL узла в построителе API данных

Статья
07/10/2024

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

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

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

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

{
    "data": {}    
}

Заметка

По умолчанию возвращаются только первые 100 элементов.

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

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

запросы мутаций

Запросов

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

разбивки на страницы
запрос по первичному ключу
универсальных запросов

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

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

Этот запрос возвращает все книги со словом Foundation в заголовке.

Операторы, поддерживаемые параметром filter, :

Оператор	Тип	Описание	Пример
`eq`	Сравнение	Равный	`books(filter: { title: { eq: "Foundation" } })`
`neq`	Сравнение	Не равно	`books(filter: { title: { neq: "Foundation" } })`
`gt`	Сравнение	Больше	`books(filter: { year: { gt: 1990 } })`
`gte`	Сравнение	Больше или равно	`books(filter: { year: { gte: 1990 } })`
`lt`	Сравнение	Менее	`books(filter: { year: { lt: 1990 } })`
`lte`	Сравнение	Меньше или равно	`books(filter: { year: { lte: 1990 } })`
`isNull`	Сравнение	Имеет значение NULL	`books(filter: { year: { isNull: true} })`
`contains`	Струна	Содержит	`books(filter: { title: { contains: "Foundation" } })`
`notContains`	Струна	Не содержит	`books(filter: { title: { notContains: "Foundation" } })`
`startsWith`	Струна	Начинается с	`books(filter: { title: { startsWith: "Foundation" } })`
`endsWith`	Струна	Конец	`books(filter: { title: { endsWith: "Empire" } })`
`and`	Логический	Логические и	`authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] })`
`or`	Логический	Логические или	`authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] })`

`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.

В следующей таблице перечислены уровни изоляции, с которыми создаются транзакции для каждого типа базы данных.

Тип базы данных	Уровень изоляции	Дополнительные сведения
SQL Azure (или) SQL Server	Чтение зафиксировано	SQL Azure
MySQL	Повторяемое чтение	MySQL
PostgreSQL	Чтение зафиксировано	PostgreSQL

Справочник по конфигурации GraphQL
OpenAPI

Поделиться через

Конечные точки GraphQL узла в построителе API данных

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

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

Запросов

Запрос по первичному ключу

Универсальный запрос

`filter`

`orderBy`

`first` и `after`

Мутаций

Создавать

Обновлять

Удалить

Транзакции базы данных для изменения

Обратная связь

Дополнительные ресурсы

Поделиться через

Конечные точки GraphQL узла в построителе API данных

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

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

Запросов

Нумерация страниц

Запрос по первичному ключу

Универсальный запрос

filter

orderBy

first и after

Мутаций

Создавать

Обновлять

Удалить

Транзакции базы данных для изменения

Связанное содержимое

Обратная связь

Дополнительные ресурсы

`filter`

`orderBy`

`first` и `after`