Tässä viestissä yritän luoda yleiskatsauksen mukautettujen REST API -päätepisteiden luomisesta ja pyyntöjen suorittamisesta niille mukautetussa Gutenberg-lohkossa. Toisin sanoen pyyntöjen tekeminen sellaisilla fetchtavoilla, joita ei ole saatavilla WordPressin rekisteröidyissä tietovarastoissa.
Ystävällinen muistutus: useimmat perustiedot ovat jo saatavilla WordPressin tietovarastoista. Esimerkiksi viestien, sivujen, mukautettujen viestityyppien, taksonomioiden, kirjoittajien, median ja muiden peruskyselyt ovat käytettävissä sellaisenaan ilman, että sinun tarvitsee luoda omia mukautettuja päätepisteitä. Päästäksesi näihin kauppoihin käytät mieluummin WordPressin ydintietomoduulia (withSelectja select()). Alla on opetusohjelma, jossa käsitellään perusteellisesti, kuinka se tehdään.
WordPress REST API
Jos et jo tiennyt; WordPress REST API on JSON-käyttöliittymä tietojen lähettämiseen ja vastaanottamiseen WordPress-sivustostasi. Sitä voidaan käyttää ulkoisesti tai sisäisesti. Gutenberg-editorin ja Javascriptiin siirtymisen myötä REST API:n käyttö on lisääntynyt selvästi. WordPress REST API:lla on koko joukko päätepisteitä, joita voimme käyttää. Katso täydellinen viite kaikista REST API -päätepisteistä täältä. Löydät esimerkiksi päätepisteitä postauksille ja suurimmalle osalle muuta sisäistä sisältöä – sekä lukemista että päivittämistä varten. Teeman tai laajennuksen kehittäjät voivat rekisteröidä omia mukautettuja päätepisteitään.
WordPress-sivustollasi on juuri REST-sovellusliittymän URL-osoite, joka sijaitsee oletuksena osoitteessa <your domain>/wp-json. Esimerkiksi paikallinen WordPress URL-osoitteella http://localhost/wordpress/voi käyttää REST-sovellusliittymää osoitteessa http://localhost/wordpress/wp-json. Sieltä meidän on liitettävä päätepisteet. Viitaten yllä olevaan päätepisteiden viittaukseen voimme hakea luettelon päätepisteen viimeisimmistä viesteistä /wp/v2/posts. Tämä tarkoittaa, että jos siirryt http://localhost/wordpress/wp-json/wp/v2/postsselaimessasi kohtaan, saat JSON-muotoisen vastauksen WordPress-sivustosi uusimmista viesteistä.
Huomautus nimiavaruuksista on paikallaan. REST-sovellusliittymän URL-osoite alkaa nimiavaruudella (" wp/v2" on WordPress-nimiavaruus, kuten yllä olevista URL-esimerkeistä näkyy). Nimiavaruudet on konsepti, jolla vältetään ristiriidat ydinWordPressissä, teemoissa ja laajennuksissa, jotka lisäävät samannimiset päätepisteet. Luo oma ainutlaatuinen nimiavaruutesi – tyypillisesti teemasi tai laajennuksen nimesi sluug-muoto. Slugin jälkeen yleinen sääntö on versionumeron lisääminen, yleensä alkaen v1. Esimerkkinä teemani slug on " awhitepixel", joten jos luoisin mukautettuja päätepisteitä teemaani, käyttäisin nimiavaruutta " awhitepixel/v1". Tällä nimiavaruudella voisin rekisteröidä päätepisteen ‘ posts‘ eikä se aiheuttaisi ongelmia, vaikka se on identtinen WordPressin päätepisteen nimen kanssa.
Työskentely REST API:n kanssa WordPressissä on laaja aihe, josta on saatavilla paljon hyvää tietoa. Tässä viestissä keskityn käytettävyyteen Gutenberg-editorissa ja niiden hakemiseen Javascriptissä.
Mitä teemme ja mitä tarvitsemme
Mukautettujen tietojen pyytämisen käytettävyydellä on laaja valikoima käyttötapauksia, joten sinun on yleensä mukautettava alla olevia koodiesimerkkejä tarpeidesi mukaan. Tiedot voivat olla mukautettua viestikyselyä, mukautettua SQL-kyselyä tai jotain aivan muuta.
Kun luomme mukautetun päätepisteen, hallitsemme täysin sen palautusta. Voimme suorittaa kaikenlaisia toimintoja ja kyselyitä WordPress/PHP:ssä ja välittää tämän eteenpäin JSON-muodossa. Ja Gutenberg-lohkossamme voimme hakea tämän palautuksen ja tehdä sillä mitä haluamme lohkon edittoiminnon sisällä. Tyypillisesti käytät dataa esitelläksesi loppukäyttäjälle valinnan tai tiedon lohkoeditorissa, mutta voit myös tallentaa niistä tietoja lohkoosi myöhempää käyttöä varten. Voit myös luoda omia mukautettuja varastoja näille tiedoille, mutta en käsittele sitä, miten se tehdään.
Oletan, että olet jo perehtynyt mukautettujen Gutenberg-lohkojen luomiseen, joten en käy tätä tässä yksityiskohtaisesti läpi.
Luodaan REST API -päätepistettä
Mukautetun REST API -päätepisteen rekisteröinti tehdään PHP:ssä. Lisää tämä koodi teemaasi functions.phptai aktiiviseen laajennuskoodiin. Kytke toiminto toimintoon rest_api_initja suorita toiminto [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()jokaiselle rekisteröitävälle päätepisteelle.
Anna nimiavaruutesi ensimmäisenä parametrina, päätepisteen reittisi toiseksi ja joukko asetuksia kolmanneksi parametriksi register_rest_route(). Neljäs parametri määrittää, haluatko ohittaa olemassa olevan reitin vai et; ei ole jotain mitä katsomme täällä. Kolmannen parametrin taulukossa sinun tulee asettaa vähintään ominaisuus " callback" funktiolle, joka vastaa päätepisteen tietojen palauttamisesta. Myös ‘ method‘:n asettaminen on yleistä, esim. päätepisteen asettaminen ‘ GET‘, ‘ POST‘, ‘ PUT‘ jne.
Aloitetaan rekisteröimällä yksinkertainen päätepiste;
Teemani nimiavaruus on " awhitepixel/v1" ja rekisteröin päätepisteen " mydata" tähän nimiavaruuteen. Tämä tarkoittaa, että voin käyttää mukautettua REST-sovellusliittymääni osoitteessa http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
Kun rekisteröit (tai muutat) REST API -reittejä, sinun on huuhdeltava pysyvät linkit, jotta se toimisi. Voit tehdä tämän siirtymällä kohtaan Asetukset > Pysyvät linkit ja napsauttamalla Tallenna.
Yllä oleva koodi ei vielä toimi, koska en ole määritellyt toimintosarjaa takaisinsoittona: awhitepixel_rest_route_mydata. Takaisinsoittotoiminto vastaanottaa yhden parametrin; joukko tietoja, jotka sisältävät pyynnöstä välitettyjä tietoja ja argumentteja. Lopuksi sinun on harkittava huolellisesti takaisinsoittotoiminnon palautusta.
Ensinnäkin sinun on aina palautettava jotain päätepisteestäsi. WordPress muuntaa kaikki palautukset automaattisesti JSON-muotoon. Tämä tarkoittaa, että voit palauttaa funktiossasi käytännössä minkä tahansa muodon dataa; merkkijono, nolla, taulukko tai [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)ilmentymä. Voit myös valita [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)objektin palauttamisen, jotta voit hallita paremmin esim. tilakoodia tai otsikkotietoja. Suosittelen käärimään returnin funktioon [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()varmistaaksesi, että vastauksesi on kelvollinen REST-vastaus.
Määritetään takaisinsoittofunktio ja palautetaan yksinkertainen merkkijono aloitukseksi;
function awhitepixel_rest_route_mydata($data) {
$response = 'Hello there!';
return rest_ensure_response($response);
}Yllä olevalla koodilla (ja tyhjennetyillä pysyvillä linkeillä) voin nyt siirtyä URL-osoitteeseen http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.
Tästä eteenpäin voimme lisätä minkä tahansa koodin takaisinsoittotoimintoomme luodaksemme oikeat tiedot palautettavaksi. Voit tiedustella WordPress-sisältöä esim [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/). -sovelluksella, tehdä kyselyitä tietokantaan tai pyytää ulkopuolisia tietoja. Tämä osa on sinun.
Siirrytään nyt vastakkaiselle puolelle; miten pyynnöt tehdään.
REST API -pyyntöjen tekeminen Javascriptissä
REST-pyynnön suorittaminen tehdään yleensä [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)Javascriptillä. WordPress tarjoaa oman kääreensä fetch, joka yksinkertaistaa WordPress REST API -pyyntöjä; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). Tätä käytän mukautetussa Gutenberg-lohkossani. Muista, että fetchpyynnöt palauttavat "lupauksen" – joten meidän on ketjutettava a .then()voidaksemme käsitellä varsinaisen pyynnön palautuksen. Peruskäyttö on jotain tällaista;
apiFetchantaa meille mahdollisuuden tarjota pathominaisuuden koko URL-osoitteen rakentamisen sijaan. Tarvitsemme vain nimitilan ja päätepisteen, ja lisäämme apiFetchtämän WordPressin REST API -juuri-URL-osoitteeseen. Toiminnon sisällä .then()meillä on pääsy tietoihin, jotka on jo muutettu JSONiksi. Täällä voit tehdä jotain tiedoilla. Yleensä palautetut tiedot tallennetaan esim. komponentin tilaan.
Alla on esimerkki mukautetun Gutenberg-lohkon editkomponentista. Se on luokkapohjainen, jotta sitä voidaan käyttää stateREST API -pyynnöstä palautettujen tietojen tallentamiseen. Tämän ansiosta voimme myös suorittaa pyynnön, componentDidMount()kun se asennetaan ensimmäisen kerran (katso Reactin dokumentaatio elinkaarimenetelmistä ). Kaikki tämä tarjoaa yksinkertaisen esimerkin, jotta voit ymmärtää peruskäsitteen; ei reseptinä tehdä se täsmälleen näin. Voit harkita React-koukkujen ja toiminnallisten komponenttien käyttöä tai rakentaa sen sijaan korkeamman asteen komponentin.
Yllä oleva esimerkki on luokkapohjainen kokoonpano, joka toimitetaan lohkon editfunktiolle registerBlockType(). Se asettaa taulukon tilaobjektin pitämään tiedot (tämä riippuu luonnollisesti palauttamistasi tiedoista) ja tilan looginen arvo tietääkseen, milloin async-pyyntö on palannut. Kun komponentti on asennettu (renderöity ensimmäistä kertaa), se suorittaa toiminnon suorittaakseen apiFetchpyynnön. Asetamme polun päätepisteeseen, jonka rekisteröimme PHP:ssä yllä. Menetelmä on oletuksena GET, joten meidän ei tarvitse määrittää tätä kohdassa apiFetch. Ja .then()toiminnon sisällä kun pyyntö on valmis, päivitämme komponentin tilan palautetuilla tiedoilla.
Ilmeisesti lohkosi renderöintitoiminto tekisi enemmän itse palautetulle tiedolle. Haluat ehkä antaa tiedot käyttäjälle jollakin tavalla esittäen luettelon, josta hän voi valita. Kaikki riippuu siitä, millaista dataa se on ja mihin sitä haluat käyttää.
Argumenttien välittäminen päätepisteeseen
Joissakin tapauksissa meidän on välitettävä joitain argumentteja päätepisteeseen. Yleisiä käyttötarkoituksia ovat tunnuksen välittäminen päätepisteen jälkeen; palauttaisi esimerkiksi http://localhost/wordpress/wp-json/wp/v2/posts/14postitunnuksen 14.
Tämä on melko yksinkertaista ja tehdään lisäämällä regex-hakukuvio päätepisteeseen rekisteröinnin yhteydessä. Monimutkaisten kuvioiden rakentaminen vaatii jonkin verran tietoa regexeistä, mutta alla on esimerkki, joka vastaa numeroa ja antaa sille nimen "id". Osumien nimeäminen antaa meille mahdollisuuden käyttää muuttujaa takaisinsoittotoiminnossamme. Anna minun näyttää, mitä tarkoitan.
Rekisteröidään uusi päätepistereitti. Käytämme samaa päätepistettä kuin aiemmin (‘ awhitepixel/v1/mydata‘), mutta tälle reitille lisäämme säännöllisen lausekkeen numerolle loppuun.
Regex-kuvio (?P<id>[d]+)vaikuttaa salaperäiseltä, mutta se on melko selkeä, kun ymmärrät regexin perustiedot. Osa [d]+vastaa mitä tahansa numeroa (0-9) yhden tai useamman kerran. Osat (?P<id>ja )ovat nimetyn ryhmän yhdistämistä varten. Ryhmän nimi on tässä tapauksessa id, mutta voit nimetä ryhmäsi miten haluat.
Voit ohjata tämän päätepisteen erilliseen takaisinsoittotoimintoon, mutta olen päättänyt käyttää samaa toimintoa sekä /mydatasekä /mydata/<ID>pyyntöjen että pyyntöjen käsittelemiseen. Tämä tarkoittaa, että voin takaisinsoittotoiminnossani tehdä:
function awhitepixel_rest_route_mydata($data) {
if ($data['id']) {
$response = 'Create return for ID: '. $data['id'];
} else {
$response = 'Create general return (no ID provided)';
}
return rest_ensure_response($response);
}Muista, että takaisinkutsufunktion parametri sisältää palautetut argumentit. Koska annoin vastaavalle ryhmälleni nimen " id", vastaava arvo on käytettävissä kielellä $data['id']. Ja lopuksi, koska käytän samaa toimintoa pyyntöjen käsittelyyn tunnuksella ja ilman, voin helposti vaihtaa kahden eri palautuksen välillä.
Tämän (ja päivitettyjen pysyvien linkkien) avulla saan nämä vastaukset mukautetuille päätepisteilleni:
