Поглиблений посібник зі створення та отримання настроюваних кінцевих точок WP REST API
Ця публікація покаже, як створити власні кінцеві точки 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 або будь-який інший), визначити параметри та, найголовніше, визначити функцію, яка буде виконуватися, коли запитується ця кінцева точка.
Як мінімум ви повинні надати аргументи ‘method’ і ‘callback’ (це функція для обробки даних кінцевої точки) як третій параметр. Для «методу» ви можете встановити їх як «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_Responseobject як результат зворотного виклику. Як параметр функції зворотного виклику ми отримуємо 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у браузері покаже рядок «Привіт!».
Прийом параметрів
Дуже поширеним і корисним є дозволити кінцевим точкам приймати параметри. Наприклад, якщо на вашому сайті є, наприклад, дані про продукт, вам потрібна кінцева точка, де можна надати ідентифікатор продукту, щоб отримати дані про цей продукт. Є два способи зробити це. Найпоширенішим способом є використання рядка запиту 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 Успіх (рядок #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, а потім додаємо бажану кінцеву точку після неї; у нашому випадку призначена для користувача кінцева точка, яку ми створили раніше. За бажанням ми можемо передати параметри в ‘data’. Наведений вище приклад передає product_idкінцеву точку зі значенням 14. Нарешті у successфункції ми отримуємо (успішний) запит як параметр, і ми вільні робити з ним, що хочемо. У наведеному вище прикладі ми просто виводимо його на консоль.
Використання бібліотеки WordPress (не jQuery)
Якщо ваш сайт WordPress не має або не може використовувати бібліотеку jQuery, ви можете скористатися бібліотекою Javascript WordPress, щоб легко виконати запит REST API. Ця функція apiFetchдоступна в глобальному wpпросторі імен WordPress. wp.apiFetch()є методом оболонки для стандартної fetch()функції браузера (яка демонструється далі).
Щоб використовувати wp.apiFetch(), нашому Javascript знадобиться залежність ‘wp-api’. Наприклад, ми могли б поставити сценарій у чергу так:
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 у «шляху», як я зробив вище: '../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 )ми б отримали відповідь, яку ми визначили в цій кінцевій точці (масив із рядком, якщо ви все ще використовуєте той самий приклад, що й на початку цієї публікації).