Создание сохранённого запроса
Сохранённый запрос — это комбинация GraphQL и REST API: это обычный GraphQL-запрос, опубликованный на сайте и доступный по собственному URL, аналогично REST-эндпоинту.
Например, мы можем предоставлять данные для сайта через следующие сохранённые queries:
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contentи выполнять его, передав ID записи:?post=1/graphql-query/post-content/esдля перевода содержимого записи на испанский язык- Другие
Выполнение сохранённого запроса
После публикации сохранённого запроса его можно выполнить по постоянной ссылке (permalink).
Сохранённый запрос можно выполнить непосредственно в браузере, поскольку он доступен через GET, и мы получим запрошенные данные в формате JSON:
Выполнение сохранённого запроса в приложении
Следуйте инструкциям в руководстве Подключение к серверу GraphQL из клиента.
Просмотр всех сохранённых запросов
Нажав «Persisted Queries» в меню плагина, вы увидите список всех созданных сохранённых запросов:
Создание нового сохранённого запроса
Нажмите кнопку «Add New GraphQL persisted query», чтобы открыть редактор WordPress:
Укажите заголовок и убедитесь, что постоянная ссылка соответствует ожидаемой, введите GraphQL-запрос, выберите конфигурацию схемы и настройте параметры. Когда всё будет готово, нажмите кнопку Publish, и постоянная ссылка станет эндпоинтом сохранённого запроса.
Ссылка на эндпоинт (и на исходный код) отображается в боковой панели «Persisted Query Endpoint Overview»:
По умолчанию эндпоинт сохранённого запроса имеет путь /graphql-query/, и это значение можно изменить в Настройках:
Редактор запросов
Клиент GraphiQL в редакторе — это место для ввода сохранённого GraphQL-запроса:
Редактор поставляется с дополнением Explorer, которое позволяет составлять запрос, нажимая на поля в левой боковой панели. Нажатие кнопки «Run» выполняет запрос для предварительного просмотра ответа:
Конфигурация схемы
То, кто может получить доступ к полям, запрошенным в сохранённом запросе, определяется в конфигурации схемы.
Поэтому необходимо создать конфигурацию схемы, а затем выбрать её из выпадающего списка (или не использовать ни одну, или использовать стандартную):
Приватные сохранённые запросы
Установив статус сохранённого запроса как private, эндпоинт будет доступен только пользователю-администратору. Это предотвращает непреднамеренный доступ к данным со стороны пользователей, которым он не должен быть открыт.
Например, можно создать приватные сохранённые queries для управления приложением, например, для получения данных с целью формирования отчётов по метрикам.
Сохранённые запросы с защитой паролем
Если мы создаём сохранённый запрос для конкретного клиента, можно назначить ему пароль, чтобы обеспечить дополнительный уровень безопасности и гарантировать, что только этот клиент получит доступ к эндпоинту.
При первом обращении к сохранённому запросу с защитой паролем появляется экран с запросом пароля:
Только после ввода и подтверждения пароля пользователь получит доступ к нужному эндпоинту.
Создание динамического сохранённого запроса через параметры URL
Значение каждой переменной можно задать через параметр URL (с именем переменной) при выполнении сохранённого запроса. Если включена опция «Do URL params override variables?», параметр URL будет иметь приоритет. В противном случае приоритет будет у значения, определённого в словаре переменных (если оно задано).
Например, в этом запросе количество результатов управляется переменной $limit со значением по умолчанию 3:
При выполнении этого сохранённого запроса передача ?limit=5 приведёт к тому, что запрос вернёт 5 результатов вместо этого:
Создание иерархии сохранённых запросов
Прочитайте инструкции по созданию иерархии API.
Отключение сохранённого запроса
В параметрах установите «Enabled» в значение false, чтобы отключить сохранённый запрос.
Эта функция может быть полезна, когда сохранённый запрос является частью иерархии API и обеспечивает общее поведение для дочерних сохранённых запросов, но при этом сам по себе не должен выполняться.
Описание сохранённого запроса
Используйте поле «Excerpt» на панели настроек документа, чтобы добавить описание к сохранённому запросу.
Дополнительную информацию можно найти в руководстве Добавление описания к API.
Тестирование сохранённого запроса перед публикацией
Сохранённый запрос со статусом draft (черновик) или pending (на рассмотрении) доступен только редакторам схемы.
Таким образом, можно создать сохранённый запрос, назначить ему конфигурацию схемы, опубликовать его как draft или pending и протестировать (например, проверив, что правила контроля доступа настроены корректно).
После утверждения устанавливаем статус publish, делая сохранённый запрос доступным для всех.
Просмотр исходного кода
Добавив ?view=source к эндпоинту, можно увидеть конфигурацию сохранённого запроса (при условии, что пользователь авторизован и его роль имеет соответствующий доступ):
Настройка в редакторе WordPress
Ниже перечислены поля в теле редактора:
| Поле | Описание |
|---|---|
| Title | Заголовок сохранённого запроса |
| GraphiQL client | Редактор для написания и выполнения GraphQL-запроса:
GraphiQL Explorer включён) позволяет кликать по полям, и они автоматически добавляются в запрос |
| Schema configuration | Из выпадающего списка выберите конфигурацию схемы, применяемую к сохранённому запросу, или один из следующих вариантов:
|
| Options | Настройка поведения сохранённого запроса:
|
Ниже перечислены поля в настройках документа:
| Поле | Описание |
|---|---|
| Permalink | Эндпоинт, по которому будет доступен сохранённый запрос |
| Categories | Позволяет категоризировать сохранённый запрос. Например: mobile, app и т.д. |
| Excerpt | Описание сохранённого запроса. Это поле доступно, если модуль Excerpt as Description включён |
| Page attributes | Выбор родительского сохранённого запроса. Это поле доступно, если модуль API Hierarchy включён |