WP REST API: получение данных

В предыдущих частях этой серии мы рассматривали, что такое API-интерфейс WP REST и как он может помочь нам создавать лучшие приложения с помощью серверной части WordPress.

Затем мы рассмотрели два способа настройки аутентификации на сервере для генерации аутентифицированных запросов. Первый — это базовый метод аутентификации, который полезен в средах разработки и позволяет быстро создавать прототипы, поскольку для его настройки не требуется много времени. Второй метод аутентификации — OAuth 1.0a, который рекомендуется для производственных сред, поскольку он намного более безопасен, чем базовый метод аутентификации.

Теперь, когда мы узнали, как настроить аутентификацию, мы готовы генерировать аутентифицированные запросы, чтобы раскрыть всю мощь WP REST API. В этой серии мы будем использовать базовую аутентификацию из-за ее простоты использования, но рекомендуется использовать аутентификацию OAuth 1.0a, как это предусмотрено плагином OAuth 1.0a , для ваших производственных серверов.

В текущей части серии мы впервые получим практический опыт работы с плагином WP REST API. Мы будем:

• проанализировать структуру запроса GET
• посмотрите, как запрос OPTIONS самодокументирует API
• отправлять запросы на сервер для поиска данных
• проанализировать ответ сервера, который включает в себя свойства, схему и ссылки

Итак, начнем с анализа структуры простого запроса GET .

Анатомия GET запроса

Прежде чем углубляться в детали получения каких-либо данных с помощью API REST WP, нам необходимо ознакомиться с синтаксисом запроса, отправляемого на сервер. Это заложит прочную основу для нашего будущего взаимодействия с WP REST API.

Рассмотрим следующий запрос, отправленный на сервер:

Тип запроса, который мы отправляем, — GET один из шести HTTP-глаголов, которые мы рассмотрели в начальной части этой серии. Запрос GET используется для получения данных с сервера. Следовательно, при выполнении на сервере вышеупомянутый запрос извлекает коллекцию всех объектов post в форме данных JSON.

Рассматривая URI запроса, мы можем разбить его на следующие части:

• http://localserver/ : URL моего локального сервера разработки. Это может быть любой URL в зависимости от того, где находится ваша установка WordPress.
• /wp-json : это префикс конечной точки API REST WP.
• /wp : пространство имен плагина WP REST API.
• /v2 : это версия плагина WP REST API.
• /posts : это ресурс, который мы хотим получить с сервера.

Пространство имен предотвращает переопределение, которое может возникнуть при запуске нескольких плагинов, каждый из которых предоставляет свой собственный уровень абстракции для API RESTful. Следовательно, каждая абстракция работает на своей собственной границе, не затрагивая методы и свойства, принадлежащие какой-либо другой абстракции.

Пространство имен и версия отсутствовали в устаревшей версии 1.2 плагина. Таким образом, в устаревшей версии приведенный выше запрос будет выглядеть так:

Но мы не будем говорить о обратной совместимости здесь. Если вы хотите узнать обо всех изменениях, произошедших между версиями 1.x и 2.x, вы можете найти их на официальной странице .

В дополнение к извлечению коллекции ресурсов (публикаций) с использованием вышеуказанного URI, мы также можем извлечь конкретный ресурс, указав его идентификатор:

Приведенный выше запрос вернет объект публикации, так как он ищет ресурс публикации с идентификатором 100.

В других случаях нам также необходимо искать сообщения, которые соответствуют определенным критериям. Для этого API-интерфейс WP REST предоставляет способ с использованием синтаксиса filter[] :

Отправляя указанный выше запрос, мы можем получить все сообщения, относящиеся к категории идентификатора 1. Синтаксис фильтра может быть особенно полезен при запросах к сообщениям или навигации по различным ресурсам, например сообщениям и категориям, с использованием их отношений.

Наконец, когда мы имеем дело с аргументами, которые принимают массивы в качестве входных данных в синтаксисе filter[] , мы можем добавить пустой набор квадратных скобок для выражения массивов следующим образом:

Приведенный выше синтаксис эквивалентен следующему WP_Query () :

Следовательно, вышеупомянутый GET будет получать список сообщений, которые принадлежат обеим категориям, имеющим идентификаторы 1 и 2. Тот же синтаксис может также использоваться для аргументов массива, имеющих более двух элементов. Обратите внимание, что использование параметра category__and требует аутентификации пользователя с правами edit_posts .

Мы рассмотрим синтаксис filter[] более подробно в следующем разделе.

Теперь, когда мы узнали о форматировании запроса GET и предоставлении его параметров, пришло время взглянуть на запрос OPTIONS . Запрос OPTIONS упрощает навигацию по API и фактически служит самодокументируемым способом сделать API более доступным, документируя все доступные методы HTTP на конечной точке и, в свою очередь, аргументы, которые они поддерживают.

Навигация по API с использованием запроса OPTIONS

Как упоминалось ранее, запрос OPTIONS может быть чрезвычайно полезен при изучении API. В нем упоминаются все конечные точки, принадлежащие определенному маршруту, и приводится список параметров, которые эти конечные точки поддерживают для операций CRUD.

Давайте отправим запрос OPTIONS на маршрут /wp/v2/posts чтобы проверить, какие конечные точки он поддерживает и какие параметры мы можем передать по запросу GET для запроса данных:

Я использовал cURL для отправки вышеуказанного запроса, но вы можете использовать любой инструмент по вашему выбору, включая Почтальон. Обязательно укажите полный путь к указанному выше маршруту, включая путь к вашему серверу.

Приведенный выше запрос OPTIONS к маршруту /wp/v2/posts возвращает данные в формате JSON, который содержит пять свойств:

1. namespace
2. methods
3. endpoints
4. schema
5. _links

Свойство namespace идентифицирует пространство имен текущего плагина. В нашем случае это wp/v2 , что означает версию 2 API REST WP. Мы уже рассмотрели пространство имен и его назначение в предыдущем разделе.

Свойство methods содержит массив всех методов, поддерживаемых текущим маршрутом. Посмотрев на ответ, полученный вышеупомянутым запросом, становится ясно, что маршрут /wp/v2/posts поддерживает два метода, а именно GET и POST . Это означает, что мы можем использовать маршрут /wp/v2/posts для получения сообщений, а также для создания нового сообщения. Мы будем иметь дело с методом POST в следующей части этой серии, так что давайте пока сосредоточимся на методе GET .

Следующее свойство — endpoints содержит массив поддерживаемых конечных точек для текущего маршрута. Это свойство напрямую связано с ранее упомянутым свойством methods поскольку оно перечисляет конечные точки для поддерживаемых методов.

Свойство endpoints содержит значения объекта, которые, в свою очередь, содержат два свойства, а именно methods и args . Свойство methods содержит массив методов HTTP, а следующее свойство args содержит все поддерживаемые аргументы для этих методов. Это аргументы, которые мы отправляем по запросу в форме параметров URI.

Рассматривая аргументы, поддерживаемые методом GET , мы сталкиваемся с девятью аргументами, которые включают context , page , per_page и т. Д. Эти объекты аргументов содержат два свойства: required и default . Обязательное свойство указывает, является ли аргумент обязательным, а свойство по умолчанию представляет значение аргумента по умолчанию.

Свойство schema в возвращенном ответе документирует все свойства текущего ресурса. Схема определяет структуру данных в формате JSON. Формат схемы, используемый в WP REST API, основан на черновом варианте 4 спецификаций схемы JSON .

Последнее свойство _links содержит массив объектов, содержащих ссылки связанных ресурсов. Ключ в объекте указывает тип отношения (например, author , collection , self , comments и т. Д.), Причем его значение является ссылкой на этот связанный ресурс. Этот стандарт связывания основан на HAL (языке приложений гипертекста). Вы можете узнать больше о HAL, прочитав спецификации, написанные Майком Келли .

Аналогичным образом мы можем отправить запрос OPTIONS другим маршрутам, включая маршруты пользователей, комментариев, медиа, страниц и т. Д., Чтобы проверить их поддерживаемые методы и аргументы. Запросы OPTIONS — ваш лучший друг при работе с WP REST API.

WP REST API предоставляет еще один способ оценки доступности API путем отправки запроса GET на индексный маршрут /wp-json . Это перечислит все маршруты и их конечные точки вместе с их поддерживаемыми методами и аргументами.

Приведенный выше запрос вернет объект ответа, содержащий свойство маршрутов, следующим образом:

Эта функция является чрезвычайно мощной, поскольку она перечисляет все маршруты и их поддерживаемые методы и аргументы, тем самым устраняя необходимость документирования всех этих данных извне. Мы будем ссылаться на этот объект ответа при выполнении операций CRUD на разных ресурсах.

Посмотрев на наши опции для изучения API, давайте теперь начнем работать с WP REST API для получения данных с сервера.

Работа с постами

К настоящему времени мы ознакомились с запросом OPTIONS , который представляет собой самодокументированный способ оценки доступности API. Мы также посмотрели, как отображаются поддерживаемые методы и аргументы для данного маршрута. Используя эти знания, мы теперь готовы получать различные ресурсы с сервера с помощью API WP REST.

Ресурс, с которого мы начнем, это ресурс Posts , так как он является основным строительным блоком WordPress. Мы будем заниматься поиском постов с использованием разных фильтров. Применив эти знания, вы сможете запрашивать сообщения, используя WP REST API, так же, как и класс WP_Query () .

На протяжении всей этой серии мы работали с ресурсом « Посты», чтобы продемонстрировать примеры запросов и их ответов, и мы уже знаем, как получить коллекцию постов и отдельный пост по его идентификатору. Таким образом, мы не будем освещать это снова. Вместо этого мы рассмотрим некоторые более продвинутые способы получения сообщений с использованием параметров верхнего уровня и синтаксиса filter[] .

Работа с параметрами верхнего уровня

WP REST API предоставляет некоторые из наиболее часто используемых переменных запроса для сообщений непосредственно в конечной точке GET . Эти параметры:

1. context : объем запроса. Возможные значения: view , embed или edit .
2. page : текущая страница коллекции сообщений.
3. per_page : общее количество сообщений на странице.
4. search : поисковый запрос. Ограничьте результаты соответствующей строкой.
5. author : идентификатор автора. Используется для ограничения результатов, принадлежащих конкретному автору.
6. exclude : массив идентификаторов записей, которые нужно исключить из результатов поиска.
7. include : ограничить результаты пост-идентификаторами, указанными в этом массиве.
8. offset : смещение результатов поиска по указанному номеру.
9. order : заказ коллекции. Может быть asc или desc .
10. orderby : сортировка атрибута коллекции. Возможные значения: id , title или slug .
11. slug : Ограничьте результаты постом, имеющим определенный слаг.
12. status : Используется для ограничения коллекции сообщений, имеющих определенный статус.

Параметр context используется для извлечения сообщений в зависимости от области действия, в которой мы работаем. Если мы просто размещаем сообщения на какой-либо странице индекса, то мы можем использовать контекст представления. Но если мы извлекаем сообщения для их редактирования, тогда нам нужно использовать контекст edit :

Параметр контекста edit вводит дополнительное raw поле в такие поля, как title , content , excerpt и т. Д. Значение этого raw поля можно отобразить в редакторе для редактирования содержимого.

Использование контекста edit требует, чтобы вы edit_posts аутентификацию как пользователь с правами edit_posts .

Использование embed в качестве значения параметра context извлекает коллекцию сообщений с минимальным подмножеством их свойств.

Другие параметры, упомянутые выше, говорят сами за себя, и вы можете поиграть с ними в своем HTTP-клиенте.

Это были основные параметры, которые позволяют запрашивать сообщения на основе определенных критериев. Чтобы сузить наши возможности запросов, API REST WP предоставляет синтаксис filter[] который поддерживает подмножество WP_Query() .

Использование filter[] Синтаксис

Помимо получения коллекции сообщений с использованием некоторых основных параметров верхнего уровня, API-интерфейс WP REST предоставляет некоторые переменные WP_Query() с использованием синтаксиса filter[] . Используя этот синтаксис, мы можем запрашивать сообщения так же, как и при работе с WP_Query() .

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

По умолчанию GET получает коллекцию из 10 сообщений на страницу. Давайте посмотрим, как мы можем отправить запрос GET чтобы получить только пять сообщений на странице:

Приведенный выше запрос использует переменную posts_per_page которой вы, возможно, знакомы, если вы работали с WP_Query() .

Параметр paged используется вместе с параметром posts_per_page и используется для перехода к определенному количеству страниц. Получив пять сообщений на страницу, мы сделаем следующий запрос для перехода на вторую страницу:

posts_per_page и paged posts_per_page могут быть чрезвычайно полезны при работе над постраничной разбивкой на страницах posts_per_page с использованием WP REST API. Эти два параметра эквивалентны параметрам верхнего уровня per_page и page . Следовательно, следующий запрос выполняет ту же работу, что и предыдущий:

В дополнение к коллекции сообщений, которые возвращает вышеуказанный запрос, сервер также возвращает несколько заголовков с ответом, который содержит полезную информацию, включая общее количество сообщений и количество страниц. Эти значения содержатся в заголовках ответов X-WP-TotalPages и X-WP-Total .

Заголовки ответов X-WP-TotalPages и X-WP-Total чрезвычайно полезны при создании нумерации страниц с использованием API REST WP, поскольку в них перечисляется общее количество страниц и общее количество сообщений соответственно.

Помимо фильтров разбиения на страницы, другим наиболее важным использованием синтаксиса filter[] является возможность запрашивать сообщения по их датам. Для этого синтаксис filter[] поддерживает восемь параметров, таких же, как в WP_Query() учебный класс:

1. year : год из четырех цифр (например, 2015 или 2016)
2. monthnum : номер месяца от 1 до 12
3. m : шестизначный год-месяц (например, 201601)
4. w : неделя года с 0 до 53
5. day : день месяца с 1 по 31
6. hour : час дня от 0 до 23
7. minute : минута часа от 0 до 60
8. second : секунда минуты от 0 до 60

Поэтому, если мы ищем публикации, опубликованные на дату 2015-10-15 (гггг / мм / дд), это можно сделать с помощью следующего запроса:

1	$ GET /wp/v2/posts?filter[year]=2015&filter[monthnum]=10&filter[day]=15

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

Мы уже видели в предыдущем разделе этого урока, как можно получать сообщения, относящиеся к определенной категории или нескольким категориям, используя параметры filter[cat] и filter[category__and] . Теперь мы будем использовать параметр filter[category__in] чтобы показать сообщения, принадлежащие категориям с идентификаторами 5 и 6:

1	$ GET /wp/v2/posts?filter[category__in][]=5&filter[category__in][]=6

Приведенный выше запрос извлечет список всех сообщений, относящихся к категориям с идентификаторами 5 и 6.

Обратного эффекта можно добиться, используя параметр filter[category__not_in] следующим образом:

1	$ GET /wp/v2/posts?filter[category__not_in][]=5&filter[category__not_in][]=6

Это приведет к получению списка сообщений, исключая все сообщения, принадлежащие категориям с идентификатором 5 или 6.

Можно было бы написать больше об использовании синтаксиса filter[] , но я не буду описывать все это здесь. Вы можете найти список всех переменных запроса, поддерживаемых синтаксисом filter[] в официальной документации версии 1 плагина. Большая часть этой информации все еще действительна для версии 2 API REST WP, но в некоторых областях ее все еще не хватает. На момент написания этого руководства в официальной документации версии 2 ничего не говорится о синтаксисе filter[] и поддерживаемых им вариантах запросов, но мы можем надеяться увидеть улучшения в официальной документации в ближайшем будущем, поскольку есть несколько человек (включая меня) вносят свой вклад в разработку плагина и документацию.

Теперь, когда мы рассмотрели различные варианты запросов к сообщениям с помощью WP REST API, мы готовы продолжить наше путешествие и взглянуть на некоторые другие ресурсы, поддерживаемые WP REST API.

Работа с ревизиями, категориями, тегами и мета-записями

Изменения в публикации позволяют просматривать и восстанавливать изменения, внесенные в сообщение. API-интерфейс WP REST позволяет просматривать все ревизии сообщения, запрашивая конечную точку /posts/<id>/revisions . Следовательно, для данного сообщения, имеющего идентификатор 10, все ревизии можно получить, отправив следующий запрос:

Приведенный выше запрос вернет массив, содержащий объекты ревизии. Объект ревизий содержит подмножество свойств, найденных в объекте post. Ниже приведен пример объекта ревизии в Почтальоне:

Конкретная ревизия может быть получена, если мы знаем ее идентификатор. Таким образом, ревизия с идентификатором 2 с постом с идентификатором 10 может быть получена с помощью следующего объекта:

Приведенный выше запрос вернет один объект ревизии.

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

А для тегов мы используем следующий запрос:

С <post_id> идентификатором поста.

Если нам нужно получить метаданные поста для поста с идентификатором 10, мы отправим следующий запрос как аутентифицированный пользователь:

Это вернет массив мета-объектов.

Обратите внимание, что для работы с мета-статьями и страницами в WP REST API вам необходимо иметь установленный подключаемый модуль, доступный на GitHub командой WP REST API.

Работа с другими ресурсами

К настоящему времени мы получили довольно прочную основу для работы с WP REST API для извлечения данных. Мы уже рассмотрели запрос опций и то, как он помогает нам исследовать API без необходимости внешней документации.

Вы всегда можете отправить запрос OPTIONS конкретному ресурсу и проверить, какие конечные точки и параметры он поддерживает. Если вам нужно перечислить все маршруты, которые предоставляет API-интерфейс WP REST, вы можете отправить GET запрос к конечной точке индекса в /wp-json как мы научились делать в начале этого урока.

Учитывая это преимущество самодокументирования, я не думаю, что нам нужно дополнительно исследовать каждый отдельный ресурс в этом учебном пособии, поскольку теперь вы можете сделать это самостоятельно.

Что дальше?

В этом длинном руководстве мы научились исследовать API с помощью запроса OPTIONS, а также получать данные с сервера с помощью API REST WP. Мы только что рассмотрели несколько ресурсов, в том числе посты, пост-ревизию и пост-мета, поскольку мы не смогли охватить все поддерживаемые ресурсы в одном учебнике. Но теперь вы сможете самостоятельно изучить API, используя методы, которые мы изучили в этом руководстве.

WordPress обладает невероятно активной экономикой. Существуют темы, плагины, библиотеки и многие другие продукты, которые помогут вам создать свой сайт и проект. Платформа с открытым исходным кодом также делает ее отличным вариантом, с помощью которого вы можете улучшить свои навыки программирования. В любом случае, вы можете увидеть, что у нас есть на рынке Envato .

В следующей части этой серии мы научимся выполнять три другие операции CRUD, а именно: создавать, обновлять и удалять ресурсы. Так что следите за обновлениями …