Интеграция 1С с сайтом (магазином) WordPress (WooCommerce) с помощью Rest API сайта. Часть 2. Категории постов/страниц WordPress.

Базовое руководство по REST API

*Расположенный ниже текст частью является моим вольным переводом документации разработчиков WordPress, расположенного по адресу «https://developer.wordpress.org/rest-api/». Весь перевод идет в контексте применимости к 1С. Надеюсь он вам поможет в понимании не только REST API WordPress’а, но других CMS, плагинов и так далее. В основном использовался Yandex переводчик.

    REST API WordPress предоставляет конечные точки API для типов данных WordPress, которые позволяют разработчикам удаленно взаимодействовать с сайтами, отправляя и получая объекты JSON (JavaScript Object Notation). JSON-это открытый стандартный формат данных, который является легким и удобочитаемым для человека и выглядит как объекты в JavaScript; отсюда и название. Когда вы отправляете контент или делаете запрос к API, ответ будет возвращен в JSON. Это позволяет нам, как разработчикам, создавать, читать и обновлять контент WordPress из клиентского JavaScript или из внешних приложений, даже тех, которые написаны на языках за отличными от PHP.

Зачем использовать WordPress REST API

REST API WordPress делает работу с контентом проще, чем когда-либо, чтобы использовать WordPress в новых и интересных способах разработки. Вам даже не придется писать приложения на PHP: любой язык программирования, который может делать HTTP-запросы и интерпретировать JSON, может взаимодействовать с WordPress через REST API.

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

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

Ключевые принципы (Key Concepts)

Чтобы начать работу с использованием WordPress REST API, мы разберем некоторые ключевые понятия и термины, связанные с API:
•    Routes/Endpoints   / Маршруты / Конечные точки
•    Requests  / Запросы
•    Responses  / Ответы
•    Schema  / Схема 
•    Controller Classes  / Классы контроллеров

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

Routes & Endpoints

    Маршрут (route), в контексте WordPress REST API, является URI, который может быть сопоставлен с различными методами HTTP. Сопоставление отдельного метода HTTP с маршрутом называется "конечной точкой" (endpoint). Чтобы быть точным: если мы сделаем запрос GET http://oursite.com/wp-json/, мы получим ответ JSON, показывающий нам, какие маршруты доступны, и в каждом маршруте, какие конечные точки доступны. /wp-json/ — это сам маршрут, и когда делается запрос GET, он соответствует конечной точке, которая отображает то, что известно, как индекс для WordPress REST API. 

    REST API предоставляет нам способ сопоставления URI с различными ресурсами в нашей WordPress. По умолчанию, если у вас есть и включены постоянные ссылки, WordPress REST API “живет” в /wp-json/. На нашем сайте WordPress https://ourawesomesite.com, мы можем получить доступ к индексу REST API, сделав запрос GET к https://ourawesomesite.com/wp-json/. Индекс предоставляет информацию о том, какие маршруты доступны для этой конкретной установки WordPress, а также о том, какие методы HTTP поддерживаются и какие конечные точки зарегистрированы.

В двух словах:

Маршрут (Route) — это «имя», которое отсылает работу API WordPress к определенным эндпоинтам. Если совсем просто, маршрут — это URL к которому можно обратиться разными HTTP методами. Маршрут может иметь несколько эндпоинтов.

Конечная точка (Endpoint) — это само обращение к маршруту отдельным HTTP методом. Эндпоинты выполняют конкретную задачу, принимают параметры и возвращают данные Клиенту.

Типовые (штатные) конечные точки WordPress:
GET — получает список (или отдельную позицию) и возвращает данные поста Клиенту.
PUT|PATCH|POST — обновляет данные и возвращает их Клиенту.
DELETE — удаляет что-либо и возвращает только что удаленные данные Клиенту.
Например,
•    GET /wp/v2/posts
•    POST /wp/v2/posts
•    POST /wp/v2/posts/<id>
•    DELETE /wp/v2/posts/<id>

Requests

Одним из основных классов в инфраструктуре REST API WordPress является класс WP_REST_Request. Этот класс используется для хранения и извлечения информации для текущего запроса; запросы могут быть отправлены удалённо через HTTP. WP_REST_Request объекты автоматически создаются для вас, когда вы делаете HTTP-запрос к зарегистрированному маршруту. Данные, указанные в запросе, определят, какой ответ вы получите обратно из API. Есть много изящных вещей, которые вы можете сделать с помощью класса запроса. 

Здесь мы запросили всё, что касается только WordPress, маршруты, конечные точки, аргументы для запросов и т.д.
 

Responses 

    Ответы — это данные, которые вы получаете от API. Класс WP_REST_Response предоставляет способ взаимодействия с данными ответа, возвращаемыми конечными точками. Ответы могут возвращать нужные данные, а также могут использоваться для возврата ошибок. 
В качестве примера введите в строке браузера маршрут «http://oursite.com/wp-json/» и вы получите ответ как на рисунке ниже (при условии конечно, что WordPress REST API не отключен каким-нибудь плагином или иным способом).

Здесь запросили вообще всё, что предоставляет WordPress, ответ получили в «сыром», необработанном виде. В удобочитаемом виде смотрите рисунки выше.
 

Schema

    Каждая конечная точка требует и предоставляет несколько разных структур данных, и эти структуры определены в схеме API. Схема структурирует данные API и предоставляет полный список всех свойств, которые API может возвращать, и входных параметров, которые он может принимать. Схема также обеспечивает преимущества безопасности для API, поскольку она позволяет нам проверять запросы, выполняемые к API. 

 

Controller Classes

     Как вы можете видеть, WordPress REST API имеет много движущихся частей, которые должны работать все вместе. Классы контроллеров объединяют все эти элементы в одном месте. С помощью класса контроллера вы можете управлять регистрацией маршрутов и конечных точек, обрабатывать запросы, использовать схему и генерировать ответы API. *Полагаю, что данный пункт необходим для разработчиков на PHP и по крайней мере в ближайшее время на не понадобится. Во всяком случае, сколько работаю с Rest API WordPress, до сих пор мне это было не нужно.

На этом базовая вводная окончена, надеюсь у вас не возникнут сложности с пониманием описанного.

Категории постов/страниц WordPress

    А теперь настала пора перейти к более интересному, чем чтение. В этой части рассмотрим примеры работы с категориями постов/страниц WordPress, как самым простым и легким образцом для экспериментов (по моему скромному мнению).

*Небольшая ремарка с пояснениями: в самом начале работы с Rest API WordPress столкнулся с тем, что 1С и схемы свойств данных Rest API WordPress имеют одинаковые написания на латинице. Например «title», «description», «name» и т.д., в следствии чего не мог задать реквизиты в 1С с подобными именами. В результате чего ввел две структуры «переводчики»:

— ВП_СтруктураСоответствийСРусскогоНаАнг – перевод с имен реквизитов с «русского» на английский 
(например: ВП_СтруктураСоответствийСРусскогоНаАнг.Вставить(Врег("Наименование"),"name"))
— ВП_СтруктураСоответствийСАнгНаРусского – обратный переводчик.

Это позволяет быстро сопоставлять реквизиты 1С и Rest API WordPress. И заполнять данные через штатную функцию «ЗаполнитьЗначенияСвойств(<Приемник>, <Источник>)»
 

Схема категорий постов/страниц

Посмотреть полностью можно тут: https://developer.wordpress.org/rest-api/reference/categories/

Конечные точки. Сопоставление с 1С.

Ниже приведенный код выполняет действие на сайте согласно конечной точке WordPress.

Функция рс_ПослатьГотовыйЗапросНаСайт(ТипЗапроса, СтрокаПодключенияСервера, Запрос) Экспорт
СоединениеССервером = онОбщегоНазначения_ПолучитьСоединениеHTTPS(СтрокаПодключенияСервера, , , , , ,);
Если ВРег(ТипЗапроса) = "POST" Тогда
Результат = СоединениеССервером.ОтправитьДляОбработки(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "GET" Тогда
Результат = СоединениеССервером.Получить(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "PUT" Тогда
////Результат = СоединениеССервером.Записать(Запрос);     /////Эта функция не работает
Результат = СоединениеССервером.Изменить(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "PATCH" Тогда
Результат = СоединениеССервером.Изменить(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "HEAD" Тогда
Результат = СоединениеССервером.ПолучитьЗаголовки(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "DELETE" Тогда
Результат = СоединениеССервером.Удалить(Запрос);
КонецЕсли;

Возврат Результат;
КонецФункции // 

Получение всех категорий списком.

Запрос для сайта будет выглядеть так: «GET /wp/v2/categories»
Конечная точка «GET». Маршрут «/wp/v2/categories». На данном этапе какие-либо дополнительные аргументы для вызова списка категорий не нужны, WordPress отработает запрос своими аргументами по умолчанию.

В программе категории/рубрики WordPress заведены как справочник «Категории/рубрики постов/страниц сайта WordPress». 

 

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

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

А вот так они выглядят на сайте

 

Возьмем для примера категорию «Тестовая категория1».

Так выглядит на сайте до изменения

 

И изменим наименование, описание и родителя и запишем. Запрос для сайта будет выглядеть так: «POST /wp/v2/categories/<id>»

 

Изменим на сайте выбрав «Обновить (текущий)» 

 

Так стало выглядеть на сайте

 

    Чтобы создать категорию/рубрику на сайте создайте элемент справочника, запишите и закройте его, после чего выбрав в списке пошлите запрос на сайт выбрав «Создать (один)».

Запрос для сайта будет выглядеть так: «POST /wp/v2/categories»

 

Так выглядит на сайте

 

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

Запрос для сайта будет выглядеть так: «DELETE /wp/v2/categories/<id>»

 

Соответственно с сайта они исчезли

Ну и запрос данных по конкретной категории выглядит так «GET /wp/v2/categories/<id>». Здесь пример приводить не стал, попробуйте сами.

И напоследок:

В обновленную конфигурацию добавлены демо-запросы к сайту.
Обновлена демо-обработка для тестов с новыми запросами, 

добавлена возможность посылать запросы «GET» к сайту по своим маршрутам.

 

На этом всё, вторая часть окончена.

Желаю приятных экспериментов на ниве обмена из 1С с сайтом WordPress. 

Продолжение следует.

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

Обработка тестировалась:

Тестировалось на моем сайте: перейти.

Версия WordPress: 5.2
MySQL Версия : 5.7.23-24
PHP Версия : 7.3.6
Платформа: 1С:Предприятие 8.3 (8.3.13.1644)

P.S. Если вам интересна описанная в публикации тема, вы готовы посвятить этому некоторое своё свободное время, есть желание, милости прошу присоединиться к моему проекту, пишите, не стесняйтесь.