Вызов конечных точек GraphQL

Конечные точки GraphQL в построителе API данных (DAB) позволяют запрашивать и изменять данные с точностью. Каждый запрос указывает, какие именно поля нужны, и поддерживает аргументы для фильтрации, упорядочивания и постраничной навигации.

По умолчанию DAB размещает конечную точку GraphQL по адресу:

https://{base_url}/graphql

Сущности, предоставляемые с помощью конфигурации, автоматически включаются в схему GraphQL. Например, если у вас есть books и authors сущности, оба отображаются в качестве корневых полей в схеме.

Замечание

Используйте любой современный клиент GraphQL или интегрированную среду разработки (например, Apollo, Бессонница или VS Code GraphQL) для изучения схемы и полей автозаполнения.

Ключевые слова, поддерживаемые в построителе API данных

Понятие	GraphQL	Цель
Projection	items	Выберите возвращаемые поля
Filtering	фильтр	Ограничение строк по условию
Сортировка	orderBy	Определение порядка сортировки
Размер страницы	first	Ограничение элементов на страницу
Продолжение	после	Продолжить с последней страницы

Базовая структура

Каждый запрос GraphQL начинается с корневого поля, представляющего сущность.

{
  books {
    items {
      id
      title
      price
    }
  }
}

Результатом является объект JSON с той же фигурой, что и набор выбора:

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune", "price": 20 },
        { "id": 2, "title": "Foundation", "price": 18 }
      ]
    }
  }
}

Замечание

По умолчанию DAB возвращает до 100 элементов на запрос, если не настроено в противном случае (runtime.pagination.default-page-size).

Типы запросов

Каждая сущность поддерживает два стандартных корневых запроса:

Query	Описание
entity_by_pk	Возвращает одну запись по первичному ключу
entities	Возвращает список записей, соответствующих фильтрам

Пример возврата одной записи:

{
  book_by_pk(id: 1010) {
    title
    year
  }
}

Пример возврата множества:

{
  books {
    items {
      id
      title
    }
  }
}

Фильтрация результатов

filter Используйте аргумент, чтобы ограничить возвращаемые записи.

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

Этот запрос возвращает все книги, название которых содержит "Foundation".

Фильтры могут объединять сравнения с логическими операторами:

{
  authors(filter: {
    or: [
      { first_name: { eq: "Isaac" } }
      { last_name: { eq: "Asimov" } }
    ]
  }) {
    items { first_name last_name }
  }
}

См. ссылку на аргумент фильтра для поддерживаемых операторов, таких как eq, neq, ltи lteisNull.

Сортировка результатов

Аргумент orderBy определяет порядок сортировки записей.

{
  books(orderBy: { year: DESC, title: ASC }) {
    items { id title year }
  }
}

Возвращаются книги, упорядоченные по year по убыванию, а затем по title.

См. справочник по аргументу orderBy для подробностей.

Ограничение результатов

Аргумент first ограничивает количество записей, возвращаемых в одном запросе.

{
  books(first: 5) {
    items { id title }
  }
}

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

Дополнительные сведения см. в первом справочнике по аргументам.

Продолжение результатов

Чтобы получить следующую страницу, используйте after аргумент с курсором из предыдущего запроса.

{
  books(first: 5, after: "eyJpZCI6NX0=") {
    items { id title }
  }
}

Маркер after помечает место окончания предыдущей страницы. Дополнительные сведения см. в справочнике по аргументам .

Выбор поля (проекция)

В GraphQL вы выбираете точно, какие поля отображаются в ответе. Такого подстановочного знака, как SELECT *, не существует. Запросить только то, что вам нужно.

{
  books {
    items { id title price }
  }
}

Вы также можете использовать псевдонимы для переименования полей в ответе:

{
  books {
    items {
      bookTitle: title
      cost: price
    }
  }
}

См. справочник по проекции полей для получения подробной информации.