Ten post pokaże, jak tworzyć niestandardowe punkty końcowe WordPress REST i różne metody wykonywania żądań do nich. Będą przykłady zarówno w PHP, jQuery, jak i waniliowym JavaScript.
Zakładam, że wiesz już, czym jest WP REST API, ale oto krótkie podsumowanie. WordPress REST API to interfejs JSON do wysyłania i odbierania danych z Twojej witryny WordPress. Możesz uzyskać dostęp do punktów końcowych (określonych ścieżek/adresów URL) zarówno zewnętrznie, jak i wewnętrznie. WordPress ma już kilka dostępnych punktów końcowych, np. do pobierania postów, kategorii, przeszukiwania witryny i nie tylko. Zobacz przegląd domyślnych punktów końcowych WordPressa tutaj. Ale programiści mają pełną swobodę w tworzeniu własnych niestandardowych punktów końcowych za pomocą tego interfejsu API, zarówno do wykonywania działań, jak i pobierania danych.
Zaczniemy od pierwszego kroku; czyli tworzenie niestandardowych punktów końcowych. Jeśli interesuje Cię tylko sposób składania próśb, przejdź do drugiej części.
Twórz niestandardowe punkty końcowe
Rejestracja niestandardowych punktów końcowych odbywa się w PHP. Możesz dodać kod do functions.phppliku kodu motywu lub aktywnej wtyczki. Podłącz funkcję rest_api_initi użyj jej [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()dla każdego punktu końcowego, który chcesz dodać.
Jako pierwszy parametr register_rest_route()musisz podać unikalną przestrzeń nazw, aby upewnić się, że punkty końcowe nie są w konflikcie z żadnym innym. Użyj ślimaka swojego motywu lub wtyczki. Powszechną praktyką jest następnie dołączanie a /po nim numeru wersji kodu. Jako przykład użyję przestrzeni nazw awhitepixel/v1. Drugim parametrem jest ścieżka (która następuje po przestrzeni nazw). Na koniec możesz opcjonalnie podać tablicę jako trzeci parametr z opcjami. W tej tablicy można na przykład zdefiniować metodę żądania (GET, POST lub dowolną inną), zdefiniować parametry i, co najważniejsze, zdefiniować funkcję, która ma zostać uruchomiona, gdy zostanie zażądany ten punkt końcowy.
Jako minimum należy podać argumenty „metoda" i „odwołanie zwrotne” (czyli funkcja do obsługi danych punktu końcowego) jako trzeci parametr. W przypadku „metody” możesz ustawić je jako „ GET', 'POST', 'PUT', lub dowolną inną prawidłową metodę żądania (lub tablicę wielu), ale polecam do tego używać domyślnych ustawień WordPressa. Są to:
WP_REST_Server::READABLEmetoda ‘GET‘WP_REST_Server::EDITABLEmetody ‘POST‘, ‘PUT‘ i ‘PATCH‘WP_REST_Server::DELETABLEmetoda ‘DELETE‘WP_REST_Server::ALLMETHODSwszystkie powyższe metody
Stwórzmy podstawowy niestandardowy punkt końcowy, do którego można dotrzeć za pomocą żądań GET:
W wierszu #2zdefiniowaliśmy nasz niestandardowy punkt końcowy jako „ awhitepixel/v1/getsomedata“. Pełny adres URL będzie zawierał prefiks głównego adresu URL interfejsu API REST WordPressa, którym jest <yourdomain>/wp-json. Tak więc pełny adres URL do powyższego punktu końcowego to „ <yourdomain>/wp-json/awhitepixel/v1/getsomedata“. W linii #4podaliśmy nazwę funkcji jako callback, którą dodamy wkrótce.
Podczas rejestrowania (lub zmieniania) tras REST API za pomocą register_rest_route(), musisz usunąć swoje permalinki, aby to zadziałało. Możesz to zrobić, odwiedzając Ustawienia> Permalinki w admin i po prostu kliknij Zapisz.
Nie zdefiniowaliśmy jeszcze funkcji wywołania zwrotnego – czyli funkcji dla kodu obsługującego reakcję na użycie tego punktu końcowego. Musi zwrócić prawidłową odpowiedź REST (w formacie JSON), więc musisz coś zwrócić, nawet jeśli punkt końcowy nie powinien zwracać danych. Możesz użyć funkcji [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()funkcji lub utworzyć instancję WP_REST_Responseobiektu jako zwrot wywołania zwrotnego. Jako parametr funkcji zwrotnej otrzymujemy WP_REST_Requestobiekt, który zawiera wszystkie informacje o żądaniu – w tym dowolne parametry. Stwórzmy prostą funkcję zwrotną, która po prostu wysyła tekst jako odpowiedź:
function awhitepixel_rest_route_getsomedata( $request) {
$response = 'Hello there!';
return rest_ensure_response( $response );
}Jest to najbardziej podstawowy sposób napisania wywołania zwrotnego. Funkcja rest_ensure_response()upewnia się, że wszelkie podane przez nas dane (ciąg znaków) zostaną przekonwertowane na poprawną odpowiedź REST. Oczywiście będziesz chciał dodać tutaj więcej kodu, aby albo zrobić coś w WordPressie, albo pobrać i odesłać dane.
Za pomocą powyższego kodu (rejestrując endpoint i funkcję callback) możesz spróbować przejść do adresu URL w przeglądarce i zobaczyć, co otrzymujesz. (Pamiętaj, aby opróżnić swoje permalinki). Przejście do <domain>/wp-json/awhitepixel/v1/getsomedataprzeglądarki spowoduje wyświetlenie ciągu „Hello there!”.
Akceptacja parametrów
Zezwalanie punktom końcowym na akceptowanie parametrów jest bardzo powszechne i przydatne. Na przykład, jeśli Twoja witryna zawiera np. dane produktu, potrzebujesz punktu końcowego, w którym możesz podać identyfikator produktu, aby uzyskać dane tego produktu. Można to zrobić na dwa sposoby. Najpopularniejszym sposobem jest użycie ciągu zapytania GET (które jest dodawane po adresie URL po znaku ?, oddzielone znakami &w formacie klucz=wartość, na przykład „ <endpoint>/product/?product_id=14“). Możesz też zdefiniować „ładniejszy” wzorzec adresu URL, w którym parametry są częścią ścieżki. Na przykład „ <endpoint>/product/14/“. Ta ostatnia metoda wymaga jednak pewnej wiedzy, aby regexesy. Którą metodę wybierzesz, zależy od Ciebie, pokażę obie poniżej.
POBIERZ parametry
Definiowanie możliwych parametrów GET do punktu końcowego odbywa się za pomocą argsklucza „ ” w register_rest_route()trzecim parametrze. Dla każdego parametru, który chcesz zezwolić, zdefiniuj wartość klucza (w powyższym przykładzie „ product_id“) oraz tablicę opcji dla tego parametru. Jako opcje możesz zdefiniować format parametru (jeśli oczekuje na przykład liczby lub łańcucha), a także zdecydować, czy parametr jest wymagany, czy nie.
Jako przykład chcemy, aby nasz punkt końcowy akceptował „ product_id” jako liczbę niewymaganą.
Jeśli zdefiniujesz parametr jako true w required, WordPress będzie obsługiwał przekazywanie odpowiedzi błędu 400. Podobnie w przypadku przekazania nieprawidłowego formatu, na przykład „hello” jako wartości do parametru, który oczekuje liczby.
W wierszu #15funkcji wywołania zwrotnego zobaczysz, jak uzyskać wartość parametru z żądania; przy użyciu metody get_param()w przekazanym WP_REST_Requestobiekcie. Jako przykład pokażę różne odpowiedzi w zależności od tego, czy product_idpodano, czy nie (pamiętaj, że zdefiniowaliśmy to jako opcjonalne). Logika modyfikacji kodu zgodnie z podanymi parametrami zależy wyłącznie od Ciebie i Twojego projektu. Możesz mieć mniej punktów końcowych, które akceptują wiele parametrów, lub wiele więcej oddzielnych punktów końcowych dla każdego konkretnego przypadku.
Z powyższym kodem otrzymam „Witaj!” kiedy odwiedzam <yourdomain>/awhitepixel/v1/getsomedatai „Zwróć dane produktu dla ID 14″, kiedy przechodzę do <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.
Parametry jako część ścieżki
Jeśli chcesz, aby parametry były częścią ścieżki, a nie GET ciągu zapytania, możesz to zrobić. Następnie w ścieżce podasz wzorzec wyrażenia regularnego – drugi parametr do register_rest_route().
Tworzenie wzorców regex może wyglądać dość tajemniczo, ale ponieważ jest to cały temat, łatwo znajdziesz przykłady dla konkretnych przypadków, jeśli je wygooglujesz. Pokażę przykład definiowania wyrażenia regularnego, które akceptuje liczbę o dowolnej długości;
Jak widać w wierszu #2 dodałem (?P<product_id>[d]+)na końcu wzór regex. Ten wzorzec oznacza, że mamy zebrać liczbę (d) o dowolnej długości (+) i przypisać zebraną wartość do klucza parametru product_id. A w naszej funkcji zwrotnej używamy dokładnie tej samej metody, co podczas konfigurowania parametrów GET; get_param()w WP_REST_Requestobiekcie przekazanym do funkcji.
Za pomocą powyższego kodu (po opróżnieniu permalinków) możemy odwiedzić adres URL <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14, aby uzyskać naszą odpowiedź. Ta metoda z pewnością skutkuje „ładniejszymi” adresami URL, ale kod może łatwo stać się trudniejszy do odczytania i naprawiać błędy. Wybór metody zależy od Ciebie.
Zwracanie prawidłowej odpowiedzi
Wcześniej krótko wspomniałem, jak funkcja callback musi zwrócić poprawną odpowiedź REST. Do tej pory używaliśmy prostszego rest_ensure_response(). Ale czasami możesz potrzebować większej kontroli nad zwrotem punktu końcowego. Możesz na przykład chcieć kontrolować kod statusu odpowiedzi HTTP. Załóżmy, że tworzysz punkt końcowy, w którym możesz podać identyfikator produktu i uzyskać dane dla tego produktu. Ale jeśli ten identyfikator produktu nie istnieje lub jakiekolwiek inne parametry powodują zamieszanie, możesz chcieć zwrócić kod stanu, na przykład 400 (złe żądanie) lub 404 (nie znaleziono). A może 500 (błąd serwera). Zawsze przekazywanie 200 (Sukces), nawet jeśli żądanie było złe, może powodować problemy po stronie nadawcy.
Poleciłbym wtedy twoją funkcję zwrotną zwracającą WP_REST_Responseobiekt. Za pomocą tego obiektu możesz kontrolować kilka rzeczy, w tym kod statusu. To prostsze niż myślisz! W najprostszej formie można utworzyć nową instancję WP_REST_Response, podać tablicę danych do zwrócenia jako pierwszy parametr, a kod stanu jako drugi parametr. Jako przykład:
W powyższym przykładzie przechowujemy zwrot awhitepixel_get_product()funkcji w zmiennej. Ta funkcja nie istnieje i powinieneś ją zastąpić funkcją, która powinna pobierać (lub wykonywać) działania, które chcesz w projekcie. Ale powiedzmy, że funkcja zwraca pustą tablicę, a to oznacza, że coś poszło nie tak (na przykład produkt nie istniał). Moglibyśmy wtedy zwrócić WP_REST_Responseobiekt z kodem statusu 400 i opcjonalnie komunikat jako dane wyjaśniające przyczynę niepowodzenia (line #5-9). W przeciwnym razie zwracamy dane z kodem statusu 200 Success (linia #10).
Wysyłanie żądań do (niestandardowych) punktów końcowych
Przejdźmy na drugą stronę, część dotyczącą wysyłania: Jak wysyłać żądania do naszych niestandardowych punktów końcowych. Zwykle wysyłasz żądania WP REST API za pomocą JavaScript, a tutaj znajdziesz przykłady użycia jQuery, biblioteki WordPress i waniliowego JavaScript. Jest to rzadkie, ale możliwe, aby wykonać żądanie REST również za pomocą PHP – więc podałem przykład.
Pierwszą rzeczą, o której należy pamiętać, jest to, że oczywiście musisz znać pełny adres URL, aby wysłać żądanie. Nie polecam kodowania domeny na sztywno (przed punktem końcowym), ponieważ istnieje wiele sposobów uzyskania tego, jeśli Twój Javascript działa w WordPress. W starszych wersjach WordPressa należałoby użyć [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()PHP i przekazać rdzeń URL REST jako globalną zmienną JavaScript. Ale poniższe przykłady pokazują nowszy i lepszy sposób na uzyskanie głównego adresu URL REST witryny WordPress.
Inną rzeczą, na którą należy zwrócić uwagę, jest to, że w przypadku swojego projektu prawdopodobnie zawinąłbyś żądania w wyniku jakiegoś działania. Aby uprościć sprawę, przygotowuję wszystkie żądania w DOM, więc powinieneś upewnić się, że kod żądania jest zawinięty, np. w wyniku kliknięcia przez odwiedzającego przycisku.
Korzystanie z jQuery
Jeśli masz i chcesz korzystać z biblioteki jQuery, możesz skorzystać z jej [$.ajax](https://api.jquery.com/jquery.ajax/)()funkcji.
Ale najpierw uwaga na temat zależności twojego pliku JavaScript. Oczywiście twój skrypt potrzebowałby 'jquery'zależności w kolejkowaniu go. Aby jednak łatwo uzyskać dostęp do głównego adresu URL REST WordPressa, dodaj kolejną zależność; ‘wp-api-żądanie’. Dzięki temu zmienna JavaScript wpApiSettings.rootjest dostępna i zawiera główny adres URL interfejsu API REST. Oto przykład, jak umieścić skrypt w kolejce, aby zilustrować tę zależność;
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
);
} );Linia #5jest interesująca; gdzie definiujemy zarówno jQuery, wp-api-requestjak i zależność. Następnie w naszym pliku JavaScript możemy wykonać żądanie WP REST API, takie jak:
( function( $) {
// Send request
$.ajax( {
url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
method: 'GET',
data: {
product_id: 14
},
success: function( data) {
console.log( data );
}
} );
} )( jQuery );To jest tak podstawowe, jak to tylko możliwe. Używamy $.ajax()do wysłania żądania GET na zdefiniowany adres URL. Jako adres URL używamy wpApiSettings.rootdo uzyskania głównego adresu URL interfejsu API REST, a następnie dołączamy po nim żądany punkt końcowy; w naszym przypadku niestandardowy punkt końcowy, który stworzyliśmy wcześniej. Opcjonalnie możemy przekazać parametry w ‘data’. Powyższy przykład przekazuje product_idwartość 14 do punktu końcowego. W końcu w successfunkcji otrzymujemy (pomyślne) żądanie jako parametr i możemy zrobić z nim, co chcemy. W powyższym przykładzie po prostu wypisujemy go na konsoli.
Korzystanie z biblioteki WordPress (nie jQuery)
Jeśli Twoja witryna WordPress nie ma lub może korzystać z biblioteki jQuery, możesz użyć biblioteki JavaScript WordPress, aby łatwo wykonać żądanie REST API. Ta funkcja jest apiFetchdostępna w globalnej wpprzestrzeni nazw WordPressa. wp.apiFetch()to metoda opakowująca dla standardowej fetch()funkcji przeglądarki (która jest pokazana dalej).
Nasz Javascript będzie potrzebował zależności ‘wp-api’, aby użyć wp.apiFetch(). Na przykład możemy umieścić skrypt w kolejce w ten sposób:
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
);
} );Krytyczną zależność znajdziesz w line #5. Dzięki temu upewniliśmy się, że nasz plik JavaScript jest wp.apiFetch()dostępny. Oto podstawowy przykład jego użycia:
Pamiętaj, że wiersze #9-13są po prostu logiczne, aby uruchomić funkcję, gdy DOM jest gotowy.
Jedną z zalet używania wp.apiFetch()w stosunku do normalnego fetch()jest to, że możemy użyć „ścieżki”, która wymaga tylko punktu końcowego, zamiast „url”, który wymaga pełnego adresu URL. Kolejną korzyścią jest to, że pierwszy „łańcuch” .then()zwraca dane już sformatowane w formacie JSON. Kiedy używasz oryginału .fetch(), potrzebujesz więcej łańcuchów „.then()”. Spójrz na następny przykład („Korzystanie z waniliowego JavaScript”), aby zobaczyć, co mam na myśli.
Należy pamiętać, że fetch()(i w konsekwencji wp.apiFetch()) nie zapewnia „czystego” sposobu przekazywania parametrów. Będziemy musieli ręcznie skonstruować ciąg zapytania GET w „ścieżce”, tak jak zrobiłem powyżej: '../getsomedata?product_id=14'.
Jeśli interesuje Cię, jak włączyć wp.apiFetchi niestandardowe punkty końcowe w bloku Gutenberga, napisałem osobny samouczek na ten temat:
Korzystanie z waniliowego JavaScript
Ostatnim przykładem metod Javascript do wysyłania żądań do WP REST API jest czysto waniliowy, nie-WordPress sposób, przy użyciu fetch(). Pamiętaj, że używam zmiennej globalnej WordPress w celu uzyskania głównego adresu URL REST. Jeśli dodajesz ten skrypt poza WordPress, prawdopodobnie będziesz musiał zakodować cały adres URL.
Ponieważ nadal chcę mieć dostęp do zmiennej globalnej dla głównego adresu URL WP REST, dodaję 'wp-api-request'zależność do mojej funkcji kolejkowania JavaScript, na przykład:
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
);
} );A potem w naszym pliku JavaScript najbardziej podstawowym przykładem będzie:
Jak wspomniano powyżej („Korzystanie z biblioteki WordPress”) .fetch()nie obsługuje ładnego, czystego sposobu podawania parametrów. Musisz więc ręcznie utworzyć ciąg zapytania („?product_id=14″) w adresie URL.
Pamiętaj, że żądanie pobrania nie zwraca bezpośrednio z danymi – zwraca obietnicę. Dlatego musimy połączyć „ .then()” zanim będziemy mogli obsłużyć dane. Jeśli brzmi to dla Ciebie nieznajomo, polecam sprawdzić, jak pracować fetch()– w Google jest wiele wyjaśnień i przykładów, które mogą to wyjaśnić lepiej niż ja.
Jeśli chcesz sprawdzić kod statusu odpowiedzi REST na swoje żądanie, możesz to zrobić w ten sposób;
W powyższym przykładzie rejestracji niestandardowych punktów końcowych wspomniałem, jak można zwrócić różne kody statusu HTTP. Powyższy kod pokazuje przykład jak sprawdzić kod statusu odpowiedzi, który jest dostępny we właściwości zwracanego obiektu .status. W powyższym przykładzie sprawdzam, czy kod statusu jest inny niż 200 (Sukces) w linii #5. Tylko jeśli kod statusu to 200, konwertuję zwrot danych obietnicy na JSON (linia #9).
Korzystanie z PHP
Rzadsze, ale nadal możliwe jest wykonanie żądania REST wewnętrznie w WordPressie za pomocą PHP. Oto jak.
W celu wysłania żądania WP REST API w PHP tworzymy WP_REST_Requestobiekt (dokładnie taki, jaki został przekazany do naszej funkcji zwrotnej wcześniej w tym poście). W tej instancji obiektu definiujemy metodę (np. GET) oraz ścieżkę do punktu końcowego. Opcjonalnie możemy również dodać parametry. Następnie używamy funkcji WordPressa [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()z tą instancją żądania. W końcu otrzymujemy odpowiedź z [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()funkcją dostępną w WP_REST_Server'klasie s.
Wywołanie funkcji set_query_params()(line #3-5) jest opcjonalne i konieczne tylko wtedy, gdy chcesz przekazać parametry. Podążając za czerwonym wątkiem w tym poście, dołączę przykład przekazywania parametru funkcji do klucza parametru REST product_id.
Linia #6to miejsce, w którym wysyłamy zapytanie. W wierszu #7zwracamy dane odpowiedzi. Więc gdybyśmy mieli wywołać tę funkcję PHP, na przykład awp_do_php_rest_request( 14 )otrzymalibyśmy odpowiedź, którą zdefiniowaliśmy w tym punkcie końcowym (tablica z łańcuchem, jeśli nadal używasz tego samego przykładu, co na początku tego postu).