Perusteellinen opas mukautettujen WP REST API -päätepisteiden luomiseen ja hakemiseen

Tämä viesti näyttää kuinka luoda mukautettuja WordPress REST -päätepisteitä ja erilaisia ​​​​menetelmiä pyyntöjen suorittamiseksi niille. Esimerkkejä löytyy sekä PHP:stä, jQuerystä että vanilla Javascriptistä.

Oletan, että tunnet jo WP REST API:n, mutta tässä on lyhyt yhteenveto. WordPress REST API on JSON-käyttöliittymä tietojen lähettämiseen ja vastaanottamiseen WordPress-sivustostasi. Voit käyttää päätepisteitä (tiettyjä polkuja/URL-osoitteita) sekä ulkoisesti että sisäisesti. WordPressillä on jo valmiiksi joukko päätepisteitä, kuten esimerkiksi viestien, luokkien hakemiseen, sivuston hakemiseen ja muuhun. Katso yleiskatsaus WordPressin oletuspäätepisteistä täältä. Mutta kehittäjät voivat täysin vapaasti luoda omia mukautettuja päätepisteitään tämän API:n avulla joko toimintojen suorittamista tai tietojen hakemista varten.

Aloitamme ensimmäisestä vaiheesta; joka luo mukautettuja päätepisteitä. Jos olet kiinnostunut vain pyyntöjen tekemisestä, siirry eteenpäin toiseen osaan.

Luo mukautettuja päätepisteitä

Mukautettujen päätepisteiden rekisteröinti tapahtuu PHP:ssä. Voit lisätä koodin teemasi functions.phptai aktiivisen laajennuksen kooditiedostoon. Tee funktio kiinni rest_api_initja käytä sitä [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()jokaisessa lisättävässä päätepisteessä.

Ensimmäisenä parametrina register_rest_route()sinun on annettava yksilöllinen nimiavaruus varmistaaksesi, että päätepisteesi eivät ole ristiriidassa muiden kanssa. Käytä teemasi tai laajennuksen slug. On yleinen käytäntö lisätä /koodiin sen jälkeen versionumero. Esimerkkinä käytän nimiavaruutta awhitepixel/v1. Toinen parametri on polku (joka seuraa nimiavaruutta). Lopuksi voit valinnaisesti tarjota taulukon kolmantena parametrina vaihtoehtoineen. Tässä taulukossa voit esimerkiksi määrittää pyyntömenetelmän (GET, POST tai mikä tahansa muu), määrittää parametreja ja mikä tärkeintä, määrittää funktion, joka suoritetaan, kun kyseistä päätepistettä pyydetään.

Vähintään argumentit ‘method’ ja ‘callback’ (joka on päätepistetietojen käsittelytoiminto) tulee antaa kolmantena parametrina. ‘Method’-kohdassa voit asettaa ne ‘ GET', 'POST', 'PUT', tai minkä tahansa muun kelvollisen pyyntömenetelmän (tai usean joukon), mutta suosittelen käyttämään WordPressin oletusasetuksia tähän. Ne ovat seuraavat:

• WP_REST_Server::READABLE menetelmä ‘ GET‘
• WP_REST_Server::EDITABLE menetelmät ‘ POST‘, ‘ PUT‘ ja ‘ PATCH‘
• WP_REST_Server::DELETABLE menetelmä ‘ DELETE‘
• WP_REST_Server::ALLMETHODS kaikki edellä mainitut menetelmät

Luodaan mukautettu peruspäätepiste, joka voidaan saavuttaa GET-pyyntöjen avulla:

Rivillä #2olemme määrittäneet mukautetun päätepisteemme muodossa " awhitepixel/v1/getsomedata". Täysi URL-osoite olisi WordPressin REST API -juuri-URL-osoite etuliitteenä, joka on <yourdomain>/wp-json. Joten koko URL-osoite yllä olevaan päätepisteeseen olisi " <yourdomain>/wp-json/awhitepixel/v1/getsomedata". Rivillä #4olemme antaneet takaisinsoittona funktion nimen, jonka lisäämme pian.

Kun rekisteröit (tai muutat) REST API -reittejä käyttämällä register_rest_route(), sinun on huuhdeltava pysyvät linkit  , jotta se toimisi. Voit tehdä tämän siirtymällä kohtaan Asetukset > Pysyvät linkit järjestelmänvalvojassa ja napsauttamalla Tallenna.

Emme ole vielä määrittäneet takaisinkutsun funktiota – joka on funktio koodille, joka käsittelee tämän päätepisteen käytön reaktion. Sen on palautettava kelvollinen REST-vastaus (JSONissa), joten sinun on palautettava jotain, vaikka päätepisteen ei pitäisi palauttaa tietoja. Voit käyttää [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()funktiofunktiota tai luoda WP_REST_Responseobjektin esiintymän takaisinkutsun palautuksena. Takaisinsoittofunktion parametriksi saamme WP_REST_Requestobjektin, joka sisältää kaikki tiedot pyynnöstä – mukaan lukien kaikki parametrit. Luodaan yksinkertainen takaisinsoittotoiminto, joka lähettää vastauksena tekstiä:

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

Tämä on yksinkertaisin tapa kirjoittaa takaisinsoitto. Toiminto rest_ensure_response()varmistaa, että kaikki antamamme tiedot (merkkijono) muunnetaan kelvollisiksi REST-vastauksiksi. Ilmeisesti haluat lisätä koodia tänne joko tehdäksesi jotain WordPressissä tai hakeaksesi ja lähettääksesi takaisin tietoja.

Yllä olevalla koodilla (päätepisteen ja takaisinsoittotoiminnon rekisteröinti) voit yrittää mennä selaimesi URL-osoitteeseen ja katsoa, ​​mitä saat. (Muista huuhdella pysyvät linkit). Kun siirryt <domain>/wp-json/awhitepixel/v1/getsomedataselaimessa kohtaan "Hei!" -merkkijono.

Parametrien hyväksyminen

On hyvin yleistä ja hyödyllistä sallia päätepisteiden hyväksyä parametreja. Jos sivustollasi on esimerkiksi tuotetietoja, haluat päätepisteen, jossa voit antaa tuotetunnuksen saadaksesi kyseisen tuotteen tiedot. On kaksi tapaa edetä asiassa. Yleisin tapa on käyttää GET-kyselymerkkijonoa (jotka liitetään URL-osoitteen perään :n ?jälkeen erotettuina &avain=arvo-muodossa. Esimerkiksi ‘ <endpoint>/product/?product_id=14‘). Vaihtoehtoisesti voit määrittää "kaunimman" URL-mallin, jossa parametrit ovat osa polkua. Esimerkiksi ‘ <endpoint>/product/14/‘. Tämä viimeinen menetelmä vaatii kuitenkin jonkin verran tietoa regexesistä. Kumpi menetelmä valitsee, on sinun päätettävissäsi, esitän molemmat alla.

GET-parametrit

Mahdollisten GET-parametrien määrittäminen päätepisteeseen tapahtuu kolmannen parametrin argsnäppäimen avulla. register_rest_route()Määritä kullekin sallittavalle parametrille avainarvo (edellä olevassa esimerkissä ‘ product_id‘) ja joukko vaihtoehtoja tälle parametrille. Vaihtoehtoina voit määrittää parametrin muodon (jos se odottaa esimerkiksi numeroa tai merkkijonoa) ja myös päättää, tarvitaanko parametria vai ei.

Esimerkkinä haluamme antaa päätepisteemme hyväksyä ‘ product_id‘ ei-pakollisena numerona.

Jos määrität parametrin tosi requiredarvoksi, WordPress käsittelee 400 virhevastauksen palauttamisen. Samoin jos annat väärän muodon, esimerkiksi "hello" arvona parametrille, joka odottaa numeroa.

Takaisinsoittotoiminnon rivillä #15näet kuinka saada parametriarvo pyynnöstä; käyttämällä menetelmää get_param()ohitetussa WP_REST_Requestobjektissa. Esimerkkinä näytän erilaisia ​​​​vastauksia sen mukaan, product_idannettiinko niitä vai ei (muista, että olemme määritelleet sen valinnaiseksi). Koodisi muokkaamisen logiikka annettujen parametrien mukaan on täysin sinun ja projektisi päätettävissä. Sinulla voi olla vähemmän päätepisteitä, jotka hyväksyvät paljon parametreja, tai useampia erillisiä päätepisteitä jokaisessa erityistapauksessa.

Yllä olevalla koodilla saan "Hei siellä!" käydessäni <yourdomain>/awhitepixel/v1/getsomedataja "Palauta tuotetiedot tunnukselle 14", kun menen osoitteeseen <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Parametrit osana polkua

Jos haluat sallia parametrien olevan osa polkua GET-kyselymerkkijonon sijaan, voit tehdä niin. Tämän jälkeen annat säännöllisen lausekkeen mallin polulle – toinen parametri register_rest_route().

Regex-kuvioiden luominen voi näyttää melko salaiselta, mutta koska kyseessä on kokonainen aihe, löydät helposti esimerkkejä tiettyihin tapauksiin googlettamalla. Näytän esimerkin sellaisen säännöllisen lausekkeen määrittämisestä, joka hyväksyy minkä tahansa pituisen luvun;

Kuten näet riviltä 2, olen lisännyt regex-kuvion (?P<product_id>[d]+)loppuun. Tämä kuvio tarkoittaa, että meidän on kerättävä dminkä tahansa pituinen luku (+) ja määritettävä kerätty arvo parametriavaimeen product_id. Ja takaisinsoittotoiminnossamme käytämme täsmälleen samaa menetelmää kuin GET-parametreja määritettäessä; get_param()toiminnolle tarjotussa WP_REST_Requestobjektissa.

Yllä olevalla koodilla (pysyvien linkkien huuhtelun jälkeen) voimme käydä URL-osoitteessa <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14saadaksemme vastauksemme. Tämä menetelmä johtaa varmasti "kaunimpiin" URL-osoitteisiin, mutta koodista voi helposti tulla vaikeampaa lukea ja korjata virheitä. Kumman menetelmän valitset, on sinun päätettävissäsi.

Oikean vastauksen palauttaminen

Aiemmin mainitsin lyhyesti, kuinka takaisinsoittotoiminnon on palautettava oikea REST-vastaus. Toistaiseksi olemme käyttäneet yksinkertaisempaa rest_ensure_response(). Mutta joskus saatat haluta hallita päätepisteesi palautusta paremmin. Voit esimerkiksi hallita HTTP-vastauksen tilakoodia. Oletetaan, että luot päätepisteen, jossa voit antaa tuotetunnuksen ja saada tietoja kyseisestä tuotteesta. Mutta jos kyseistä tuotetunnusta ei ole olemassa tai muut parametrit aiheuttavat sekaannusta, saatat haluta palauttaa tilakoodin, esimerkiksi 400 (Virheellinen pyyntö) tai 404 (Ei löytynyt). Tai ehkä 500 (palvelinvirhe). Aina 200 (Onnistuminen), vaikka pyyntö oli huono, voi aiheuttaa ongelmia lähettäjälle.

Suosittelen sitten takaisinsoittotoimintoa palauttamaan WP_REST_Responseobjektin. Tämän objektin avulla voit hallita useita asioita, mukaan lukien tilakoodia. Se on helpompaa kuin luulet! Yksinkertaisimmassa muodossa luot uuden ilmentymän WP_REST_Response, tarjoat joukon tietoja, jotka palautetaan ensimmäisenä parametrina, ja tilakoodin toiseksi parametriksi. Esimerkiksi:

Yllä olevassa esimerkissä tallennetaan awhitepixel_get_product()funktion palautus muuttujaan. Tätä funktiota ei ole olemassa, ja sinun tulee korvata se funktiolla, jonka pitäisi noutaa (tai tehdä) haluamasi toiminnot projektissasi. Mutta sanotaan, että funktio palauttaa tyhjän taulukon ja se tarkoittaa, että jotain meni pieleen (esimerkiksi tuotetta ei ollut olemassa). Voisimme sitten palauttaa WP_REST_Responseobjektin tilakoodilla 400 ja valinnaisesti viestin, joka selittää, miksi se epäonnistui (rivi #5-9). Muussa tapauksessa palautamme tiedot tilakoodilla 200 Success (rivi #10).

Pyyntöjen lähettäminen (mukautettuihin) päätepisteisiin

Siirrytään toiselle puolelle, lähetysosaan: Kuinka lähettää pyyntöjä mukautetuille päätepisteillemme. Normaalisti lähetät WP REST API -pyynnöt Javascriptin avulla, ja täältä löydät esimerkkejä jQueryn, WordPress-kirjaston ja vanilja Javascriptin käytöstä. On harvinaista, mutta mahdollista suorittaa REST-pyyntö myös PHP:llä – joten olen sisällyttänyt siihen myös esimerkin.

Ensimmäinen asia, joka on huomioitava, on se, että sinun on luonnollisesti tiedettävä koko URL-osoite, jotta voit lähettää pyynnön. En suosittele verkkotunnuksen kovakoodausta (ennen päätepistettä), koska on olemassa useita tapoja saada tämä, jos Javascript toimii WordPressissä. WordPressin vanhemmissa versioissa sinun on käytettävä [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()PHP:tä ja välitettävä ydin REST URL globaalina Javascript-muuttujana. Mutta alla olevat esimerkit osoittavat uudemman ja paremman tavan saada WordPress-sivuston REST-juuri-URL-osoite.

Toinen huomioitava asia on se, että projektisi pyynnöt luultavasti kääriisit jonkin toiminnan seurauksena. Jotta asiat olisivat yksinkertaisia, teen kaikki pyynnöt DOM:ssa valmiiksi, joten sinun tulee muistaa kääriä pyyntökoodi esimerkiksi vierailijan napsautuksen seurauksena.

jQueryn käyttö

Jos sinulla on ja haluat käyttää jQuery-kirjastoa, voit käyttää sen [$.ajax](https://api.jquery.com/jquery.ajax/)()toimintoa.

Mutta ensin huomautus Javascript-tiedostosi riippuvuuksista. Ilmeisesti komentosarjasi tarvitsisi 'jquery'riippuvuutta sen jonossa. Mutta jotta pääset helposti WordPressin REST-juuri-URL-osoitteeseen, lisää toinen riippuvuus; ‘wp-api-request’. Tämä varmistaa, että Javascript-muuttuja wpApiSettings.rooton saatavilla ja sisältää REST API -juuriosoitteen. Tässä on esimerkki siitä, kuinka voit asettaa komentosarjasi jonoon havainnollistamaan tätä riippuvuutta;

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
    );
} );

Linja #5on mielenkiintoinen; jossa määritämme sekä jQueryn wp-api-requestettä riippuvuutena. Sitten Javascript-tiedostossamme voimme suorittaa WP REST API -pyynnön seuraavasti:

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

Tämä on niin perustavaa kuin se voi olla. Käytämme $.ajax()GET-pyynnön lähettämistä määritettyyn URL-osoitteeseen. URL-osoitteena käytämme wpApiSettings.rootREST API -juuri-URL-osoitteen saamiseen ja liitämme sen jälkeen halutun päätepisteen; meidän tapauksessamme aiemmin luomamme mukautettu päätepiste. Vaihtoehtoisesti voimme välittää parametreja "datassa". Yllä oleva esimerkki siirtyy product_idarvolla 14 päätepisteeseen. Lopuksi successfunktiossa saamme (onnistunut) pyynnön parametrina ja voimme vapaasti tehdä sen kanssa mitä haluamme. Yllä olevassa esimerkissä yksinkertaisesti tulostamme sen konsoliin.

WordPress-kirjaston käyttäminen (ei jQuery)

Jos WordPress-sivustollasi ei ole tai voi käyttää jQuery-kirjastoa, voit käyttää WordPressin Javascript-kirjastoa REST API -pyynnön suorittamiseen helposti. Toiminto apiFetchon saatavilla WordPressin globaalissa wpnimiavaruudessa. wp.apiFetch()on kääremenetelmä selaimen vakiotoiminnolle fetch()(joka esitellään seuraavassa).

Javascriptimme tarvitsee riippuvuuden ‘wp-api’ voidakseen käyttää wp.apiFetch(:tä). Voisimme esimerkiksi laittaa skriptin jonoon näin:

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
    );
} );

Löydät kriittisen riippuvuuden riviltä #5. Tällä olemme varmistaneet, että Javascript-tiedostomme on wp.apiFetch()saatavilla. Tässä on perusesimerkki sen käytöstä:

Muista, että rivit #9-13ovat vain logiikkaa funktion suorittamiseksi sen jälkeen, kun DOM on valmis.

Yksi käytön etu wp.apiFetch()normaaliin verrattuna fetch()on, että voimme käyttää "polkua", joka vaatii vain päätepisteen, eikä "url"-osoitetta, joka vaatii täydellisen URL-osoitteen. Toinen etu on, että ensimmäinen "ketju" .then()palauttaa tiedot jo JSON-muotoiltuna. Kun käytät alkuperäistä .fetch(), tarvitset lisää ".then()-ketjuja". Katso seuraava esimerkki ("Vanilla Javascriptin käyttäminen") nähdäksesi mitä tarkoitan.

Muista, että fetch()(ja sen seurauksena wp.apiFetch()) ei tarjoa "puhdasta" tapaa siirtää parametreja. Meidän on muodostettava manuaalisesti GET-kyselymerkkijono ‘polussa’, kuten olen tehnyt edellä: '../getsomedata?product_id=14'.

Jos olet kiinnostunut sisällyttämään wp.apiFetchja mukautettuja päätepisteitä Gutenberg-lohkoon, olen kirjoittanut tästä erillisen opetusohjelman:

Vanilja Javascriptin käyttö

Viimeisenä esimerkkinä Javascript-menetelmistä pyynnön lähettämiseksi WP REST API:lle on puhdas vaniljainen, ei-WordPress-tapa käyttämällä fetch(). Huomaa, että käytän WordPressin globaalia muuttujaa saadakseni REST-juuriosoitteen. Jos lisäät tämän skriptin WordPressin ulkopuolelle, sinun on luultavasti koodattava koko URL-osoite.

'wp-api-request'Koska haluan edelleen pääsyn WP REST -juuri- URL-osoitteen yleiseen muuttujaan, lisään riippuvuuden Javascript-jonotoimintooni seuraavasti:

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
    );
} );

Ja sitten Javascript-tiedostossamme yksinkertaisin esimerkki olisi:

Kuten edellä mainittiin ("WordPress-kirjaston käyttäminen") .fetch()ei tue mukavaa, puhdasta tapaa tarjota parametreja. Joten sinun on rakennettava URL-osoitteeseen manuaalisesti kyselymerkkijono (?product_id=14).

Muista, että hakupyyntö ei palauta suoraan tietojen mukana – se palauttaa lupauksen. Siksi meidän on ketjutettava " .then()" ennen kuin voimme käsitellä tietoja. Jos tämä kuulostaa sinulle tuntemattomalta, suosittelen etsimään työskentelytapaa fetch()– googlesta löytyy paljon selityksiä ja esimerkkejä, jotka voivat selittää asian paremmin kuin minä.

Jos haluat tarkistaa REST-vastauksen tilakoodin pyyntöösi, voit tehdä sen näin;

Mainitsin yllä olevassa esimerkissä mukautettujen päätepisteiden rekisteröinnin yhteydessä, kuinka voit palauttaa erilaisia ​​HTTP-tilakoodeja. Yllä oleva koodi näyttää esimerkin vastauksen tilakoodin tarkistamisesta, joka on saatavilla palautetun objektin .statusominaisuudessa. Yllä olevassa esimerkissä tarkistan, onko tilakoodi jotain muuta kuin 200 (Onnistuminen) rivillä #5. Vain jos tilakoodi oli 200, muunnan lupauksen datapalautuksen JSONiksi (rivi #9).

PHP:n käyttö

On harvinaisempaa, mutta silti mahdollista suorittaa REST-pyyntö sisäisesti WordPressissä PHP:n avulla. Toimi näin.

WP REST API -pyynnön lähettämiseksi PHP:ssä luomme WP_REST_Requestobjektin (täsmälleen kuten se, joka välitetään takaisinsoittotoimintollemme aiemmin tässä viestissä). Tässä objektiinstanssissa määrittelemme menetelmän (esim. GET) ja päätepisteen polun. Vaihtoehtoisesti voimme myös lisätä parametreja. Sitten käytämme WordPress-toimintoa [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()tämän pyyntöesiintymän kanssa. Lopulta saamme vastauksen s-luokassa [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()käytettävissä olevalla funktiolla .WP_REST_Server'

Funktiokutsu set_query_params()(linja #3-5) on valinnainen ja tarpeen vain, jos haluat välittää parametreja. Tämän viestin punaisen säikeen jälkeen sisällytän esimerkin funktion parametrin välittämisestä REST-parametriavaimeen product_id.

#6Lähetämme pyynnön riville. Ja rivillä #7palautamme vastauksen tiedot. Joten jos kutsuisimme esimerkiksi tätä PHP-funktiota, awp_do_php_rest_request( 14 )saisimme sitten vastauksen, jonka määritimme kyseisessä päätepisteessä (jono, jos käytät edelleen samaa esimerkkiä kuin tämän viestin alussa).