✅ Новости WEB и WordPress, темы, плагины. Здесь мы делимся советами и лучшими решениями для веб-сайтов.

Подробное руководство по созданию и получению пользовательских конечных точек WP REST API

248

В этом посте будет показано, как создавать пользовательские конечные точки WordPress REST и различные методы выполнения запросов к ним. Будут примеры и на PHP, и на jQuery, и на ванильном Javascript.

Я предполагаю, что вы уже знакомы с тем, что такое WP REST API, но вот краткое описание. WordPress REST API — это интерфейс JSON для отправки и получения данных с вашего сайта WordPress. Вы можете получить доступ к конечным точкам (конкретным путям/URL-адресам) как извне, так и изнутри. WordPress уже имеет множество доступных конечных точек, например, для получения сообщений, категорий, поиска по сайту и многого другого. См. обзор конечных точек WordPress по умолчанию здесь. Но разработчики могут свободно создавать свои собственные конечные точки с помощью этого API для выполнения действий или получения данных.

Мы начнем с первого шага; который создает пользовательские конечные точки. Если вас интересует только то, как делать запросы, переходите ко второй части.

Создание пользовательских конечных точек

Регистрация пользовательских конечных точек выполняется в PHP. Вы можете добавить код в файл кода вашей темы functions.phpили активного плагина. Привяжите функцию rest_api_initи используйте ее [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()для каждой конечной точки, которую хотите добавить.

В качестве первого параметра register_rest_route()вам необходимо предоставить уникальное пространство имен, чтобы убедиться, что ваши конечные точки не конфликтуют ни с какими другими. Используйте слаг вашей темы или плагина. Обычной практикой является включение /после этого номера версии вашего кода. В качестве примера я буду использовать пространство имен awhitepixel/v1. Второй параметр — это путь (который следует за пространством имен). Наконец, вы можете дополнительно указать массив в качестве третьего параметра с параметрами. В этом массиве вы можете, например, определить метод запроса (GET, POST или любой другой), определить параметры и, что наиболее важно, определить функцию, которая будет выполняться при запросе этой конечной точки.

Как минимум, вы должны предоставить аргументы «метод» и «обратный вызов» (который является функцией для обработки данных конечной точки) в качестве третьего параметра. Для «метода» вы можете установить их как «GET', 'POST', 'PUT'или любой другой допустимый метод запроса (или массив из нескольких), но я рекомендую использовать для этого значения по умолчанию WordPress. Они следующие:

  • WP_REST_Server::READABLE метод ‘ GET
  • WP_REST_Server::EDITABLE методы ‘ POST‘, ‘ PUT‘ и ‘ PATCH
  • WP_REST_Server::DELETABLE метод ‘ DELETE
  • WP_REST_Server::ALLMETHODS все вышеперечисленные методы

Давайте создадим базовую пользовательскую конечную точку, доступ к которой можно получить с помощью запросов GET:

В строке #2мы определили нашу пользовательскую конечную точку как ‘ awhitepixel/v1/getsomedata‘. Полный URL-адрес будет корневым URL-адресом REST API WordPress с префиксом, то есть <yourdomain>/wp-json. Таким образом, полный URL-адрес указанной выше конечной точки будет ‘ <yourdomain>/wp-json/awhitepixel/v1/getsomedata‘. В строке #4мы указали имя функции в качестве обратного вызова, которое вскоре добавим.

При регистрации (или изменении) маршрутов REST API с помощью register_rest_route(), вам нужно будет сбросить ваши постоянные ссылки, чтобы он работал. Вы можете сделать это, посетив «Настройки»> «Постоянные ссылки» в админке и просто нажав «Сохранить».

Мы еще не определили функцию обратного вызова, которая является функцией кода, обрабатывающего реакцию на использование этой конечной точки. Он должен возвращать действительный ответ REST (в формате JSON), поэтому вам нужно что-то вернуть, даже если конечная точка не должна возвращать данные. Вы можете использовать функциональную [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()функцию или создать экземпляр WP_REST_Responseобъекта в качестве возврата обратного вызова. В качестве параметра функции обратного вызова мы получаем WP_REST_Requestобъект, который содержит всю информацию о запросе, включая любые параметры. Давайте создадим простую функцию обратного вызова, которая просто отправляет некоторый текст в качестве ответа:

function awhitepixel_rest_route_getsomedata( $request) { $response = 'Hello there!'; return rest_ensure_response( $response ); }

Это самый простой способ написания обратного вызова. Функция rest_ensure_response()гарантирует, что любые предоставленные нами данные (строка) будут преобразованы в действительный ответ REST. Очевидно, вы захотите добавить сюда больше кода, чтобы либо сделать что-то в WordPress, либо получить и отправить данные.

С помощью приведенного выше кода (регистрация конечной точки и функция обратного вызова) вы можете попытаться перейти по URL-адресу в своем браузере и посмотреть, что вы получите. (Не забудьте очистить свои постоянные ссылки). Переход <domain>/wp-json/awhitepixel/v1/getsomedataв браузере покажет строку «Hello there!».

Принятие параметров

Очень часто и полезно разрешать конечным точкам принимать параметры. Например, если на вашем сайте есть данные о продукте, вам понадобится конечная точка, в которой вы можете указать идентификатор продукта, чтобы получить данные об этом продукте. Есть два способа сделать это. Наиболее распространенным способом является использование строки запроса GET (которая добавляется после URL-адреса после символа ?, разделенного &в формате ключ = значение. Например, ‘ <endpoint>/product/?product_id=14‘). В качестве альтернативы вы можете определить «более красивый» шаблон URL, где параметры являются частью пути. Например ‘ <endpoint>/product/14/‘. Однако этот последний метод требует некоторых знаний для регулярных выражений. Какой метод вы выберете, зависит от вас, я продемонстрирую оба ниже.

ПОЛУЧИТЬ параметры

Определение возможных параметров GET для вашей конечной точки осуществляется с помощью argsключа ‘ ‘ в register_rest_route()третьем параметре. Для каждого параметра, который вы хотите разрешить, определите значение ключа (в приведенном выше примере ‘ product_id‘) и массив опций для этого параметра. В качестве опций вы можете определить формат параметра (если он ожидает, например, число или строку), а также решить, требуется ли этот параметр или нет.

Например, мы хотим, чтобы наша конечная точка принимала ‘ product_id‘ как необязательный номер.

Если вы определите параметр как true в required, WordPress обработает возврат ответа с ошибкой 400. Аналогично, если вы передаете недопустимый формат, например, «привет» в качестве значения параметра, который ожидает число.

В строке #15функции обратного вызова вы видите, как получить значение параметра из запроса; используя метод get_param()в переданном WP_REST_Requestобъекте. В качестве примера я покажу разные ответы в зависимости от того, был ли product_idон предоставлен или нет (помните, что мы определили его как необязательный). Логика изменения вашего кода в соответствии с предоставленными параметрами полностью зависит от вас и вашего проекта. У вас может быть меньше конечных точек, которые принимают множество параметров, или гораздо больше отдельных конечных точек для каждого конкретного случая.

С приведенным выше кодом я получу «Привет!» при посещении <yourdomain>/awhitepixel/v1/getsomedataи «Вернуть данные о продукте для ID 14», когда я перехожу к <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Параметры как часть пути

Если вы хотите, чтобы параметры были частью пути, а не строки запроса GET, вы можете сделать это. Затем вы предоставите шаблон регулярного выражения в пути — второй параметр для register_rest_route().

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

Как видите, в строке № 2 я добавил шаблон регулярного выражения (?P<product_id>[d]+)в конце. Этот шаблон означает, что мы должны собрать число (d) любой длины (+) и присвоить собранное значение ключу параметра product_id. И в нашей функции обратного вызова мы используем тот же метод, что и при настройке параметров GET; get_param()в WP_REST_Requestобъекте, предоставленном функции.

С помощью приведенного выше кода (после сброса постоянных ссылок) мы можем перейти по URL-адресу <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14, чтобы получить ответ. Этот метод, безусловно, приводит к «красивым» URL-адресам, но код может легко стать более трудным для чтения и исправления. Какой бы метод вы ни выбрали, решать вам.

Возврат правильного ответа

Ранее я кратко упомянул, как функция обратного вызова должна возвращать правильный ответ REST. До сих пор мы использовали более простой rest_ensure_response(). Но иногда вам может понадобиться больше контроля над возвратом вашей конечной точки. Например, вы можете захотеть управлять кодом состояния ответа HTTP. Допустим, вы создаете конечную точку, где вы можете указать идентификатор продукта и получить данные для этого продукта. Но если этот идентификатор продукта не существует или какие-либо другие параметры вызывают путаницу, вы можете вернуть код состояния, например, 400 (неверный запрос) или 404 (не найден). Или, возможно, 500 (ошибка сервера). Всегда передача 200 (Успех), даже если запрос был плохим, может вызвать проблемы на стороне отправителя.

Затем я бы порекомендовал вашу функцию обратного вызова, возвращающую WP_REST_Responseобъект. С помощью этого объекта вы можете управлять несколькими вещами, включая код состояния. Это проще, чем вы думаете! В простейшей форме вы должны создать новый экземпляр WP_REST_Response, предоставить массив данных для возврата в качестве первого параметра и код состояния в качестве второго параметра. В качестве примера:

В приведенном выше примере мы сохраняем результат awhitepixel_get_product()функции в переменной. Этой функции не существует, и вы должны заменить ее функцией, которая должна получать (или выполнять) нужные вам действия в вашем проекте. Но скажем, функция возвращает пустой массив, а это значит, что что-то пошло не так (например, товар не существует). Затем мы могли бы вернуть WP_REST_Responseобъект с кодом состояния 400 и, возможно, сообщение в виде данных, объясняющих, почему он не прошел (строка #5-9). В противном случае мы возвращаем данные с кодом состояния 200 Success (строка #10).

Отправка запросов на (настраиваемые) конечные точки

Давайте перейдем к другой стороне, части отправки: как отправлять запросы на наши пользовательские конечные точки. Обычно вы отправляете запросы WP REST API, используя Javascript, и здесь вы найдете примеры использования jQuery, библиотеки WordPress и ванильного Javascript. Редко, но возможно выполнить запрос REST и с PHP, поэтому я также включил пример этого.

Первое, что нужно знать, это то, что вам, очевидно, нужно знать полный URL-адрес, чтобы отправить запрос. Я не рекомендую жестко кодировать домен (перед конечной точкой), поскольку есть несколько способов получить это, если ваш Javascript работает в WordPress. В более старых версиях WordPress вам нужно будет использовать [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()в PHP и передать основной URL-адрес REST в качестве глобальной переменной Javascript. Но приведенные ниже примеры показывают более новый и лучший способ получения корневого URL-адреса REST сайта WordPress.

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

Использование jQuery

Если у вас есть и вы хотите использовать библиотеку jQuery, вы можете использовать ее [$.ajax](https://api.jquery.com/jquery.ajax/)()функцию.

Но сначала примечание о зависимостях вашего файла Javascript. Очевидно, что вашему сценарию потребуется 'jquery'зависимость при его постановке в очередь. Но чтобы легко получить доступ к корневому URL REST вашего WordPress, добавьте еще одну зависимость; ‘wp-api-запрос’. Это гарантирует, что переменная Javascript wpApiSettings.rootдоступна и содержит корневой URL REST API. Вот пример того, как вы могли бы поставить свой сценарий в очередь, чтобы проиллюстрировать эту зависимость;

add_action( 'wp_enqueue_scripts', function() { wp_enqueue_script( 'awp-javascript-wp-rest', get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', [ 'jquery', 'wp-api-request' ], null, true ); } );

Линия #5интересная; где мы определяем как jQuery, так и wp-api-requestзависимость. Затем в нашем файле Javascript мы можем выполнить запрос WP REST API следующим образом:

( function( $) { // Send request $.ajax( { url: wpApiSettings.root + 'awhitepixel/v1/getsomedata', method: 'GET', data: { product_id: 14 }, success: function( data) { console.log( data ); } } ); } )( jQuery );

Это настолько просто, насколько это возможно. Мы используем $.ajax()для отправки запроса GET на определенный URL-адрес. В качестве URL-адреса мы используем wpApiSettings.rootкорневой URL-адрес REST API, а затем добавляем желаемую конечную точку после него; в нашем случае пользовательская конечная точка, которую мы создали ранее. При желании мы можем передать параметры в «данные». Пример выше проходит product_idсо значением 14 в конечную точку. Наконец, в successфункции мы получаем (успешный) запрос в качестве параметра и можем делать с ним все, что хотим. В приведенном выше примере мы просто выводим его на консоль.

Использование библиотеки WordPress (не jQuery)

Если на вашем сайте WordPress нет или может использоваться библиотека jQuery, вы можете использовать библиотеку Javascript WordPress, чтобы легко выполнить запрос REST API. Эта функция apiFetchдоступна в глобальном wpпространстве имен WordPress. wp.apiFetch()является методом-оболочкой для стандартной fetch()функции браузера (которая демонстрируется далее).

Нашему Javascript потребуется зависимость «wp-api», чтобы использовать wp.apiFetch(). Например, мы могли бы поставить скрипт в очередь следующим образом:

add_action( 'wp_enqueue_scripts', function() { wp_enqueue_script( 'javascript-wp-rest', get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', [ 'wp-api' ], null, true ); } );

Вы найдете критическую зависимость в строке #5. Благодаря этому мы удостоверились, что наш файл Javascript wp.apiFetch()доступен. Вот основной пример его использования:

Имейте в виду, что строка #9-13— это просто логика для запуска функции после того, как DOM будет готов.

Одним из преимуществ использования wp.apiFetch()по сравнению с обычным fetch()является то, что мы можем использовать «путь», для которого требуется только конечная точка, вместо «url», для которого требуется полный URL-адрес. Еще одним преимуществом является то, что первая «цепочка» .then()возвращает данные, уже отформатированные в формате JSON. Когда вы используете оригинал .fetch(), вам нужно больше цепочек «.then()». Взгляните на следующий пример («Использование ванильного Javascript»), чтобы понять, что я имею в виду.

Имейте в виду, что fetch()(и как следствие wp.apiFetch()) не обеспечивает «чистый» способ передачи параметров. Нам нужно будет вручную построить строку запроса GET в ‘path’, как я сделал выше: '../getsomedata?product_id=14'.

Если вам интересно, как включить wp.apiFetchи настроить конечные точки в блоке Гутенберга, я написал об этом отдельный учебник:

Использование ванильного Javascript

В качестве последнего примера методов Javascript для отправки запроса в WP REST API есть чистый ванильный способ, отличный от WordPress, с использованием fetch(). Обратите внимание, что я использую глобальную переменную WordPress, чтобы получить корневой URL-адрес REST. Если вы добавляете этот скрипт вне WordPress, вам, вероятно, потребуется жестко указать полный URL-адрес.

Поскольку мне по-прежнему нужен доступ к глобальной переменной для корневого URL-адреса WP REST, я добавляю 'wp-api-request'зависимость к своей функции постановки в очередь Javascript, например так:

add_action( 'wp_enqueue_scripts', function() { wp_enqueue_script( 'awp-javascript-wp-rest', get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', [ 'wp-api-request' ], null, true ); } );

И тогда в нашем файле Javascript самым простым примером будет:

Как упоминалось выше («Использование библиотеки WordPress») .fetch(), не поддерживается хороший и чистый способ предоставления параметров. Поэтому вам нужно будет вручную встроить строку запроса («?product_id=14») в URL-адрес.

Имейте в виду, что запрос на выборку не возвращает данные напрямую — он возвращает обещание. Вот почему нам нужно связать «.then()», прежде чем мы сможем обрабатывать данные. Если это звучит для вас незнакомо, я рекомендую посмотреть, как с этим работать fetch()— в Google есть множество объяснений и примеров, которые могут объяснить это лучше, чем я.

Если вы хотите проверить код состояния ответа REST на ваш запрос, вы можете сделать это так:

В приведенном выше примере при регистрации пользовательских конечных точек я упомянул, как вы можете возвращать разные коды состояния HTTP. В приведенном выше коде показан пример проверки кода состояния ответа, который доступен в свойстве возвращаемого объекта .status. В приведенном выше примере я проверяю, отличается ли код состояния от 200 (Успех) в строке #5. Только если код состояния был 200, я преобразовываю возврат данных обещания в JSON (строка #9).

Использование PHP

Менее распространено, но все же возможно выполнение запроса REST внутри WordPress с использованием PHP. Вот как.

Чтобы отправить запрос WP REST API в PHP, мы создаем WP_REST_Requestобъект (точно такой же, как тот, который передается нашей функции обратного вызова ранее в этом посте). В этом экземпляре объекта мы определяем метод (например, GET) и путь к конечной точке. При желании мы также можем добавить параметры. Затем мы используем функцию WordPress [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()с этим экземпляром запроса. Наконец, мы получаем ответ с помощью [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()функции, доступной в WP_REST_Server'классе s.

Вызов функции set_query_params()(строка #3-5) необязателен и необходим только в том случае, если вы хотите передать параметры. Вслед за красной нитью в этом посте я приведу пример передачи параметра функции в ключ параметра REST product_id.

Строка #6— это место, куда мы отправляем запрос. И в строке #7мы возвращаем данные ответа. Итак, если бы мы вызвали эту функцию PHP, например, awp_do_php_rest_request( 14 )мы бы получили ответ, который мы определили в этой конечной точке (массив со строкой, если вы все еще используете тот же пример, что и в начале этого поста).

Источник записи: awhitepixel.com

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