Põhjalik juhend kohandatud WP REST API lõpp-punktide loomise ja toomise kohta

See postitus näitab, kuidas luua kohandatud WordPressi REST-i lõpp-punkte ja erinevaid meetodeid neile päringute tegemiseks. Näiteid on nii PHP-s, jQuerys kui ka vanilje Javascriptis.

Oletan, et olete juba tuttav WP REST API-ga, kuid siin on lühike kokkuvõte. WordPress REST API on JSON-liides teie WordPressi saidi andmete saatmiseks ja vastuvõtmiseks. Lõpp-punktidele (konkreetsed teed/URL-id) pääsete juurde nii väliselt kui ka sisemiselt. WordPressil on juba saadaval hunnik lõpp-punkte, nt postituste, kategooriate toomiseks, saidilt otsimiseks ja muuks. Vaadake WordPressi vaikeotspunktide ülevaadet siit. Kuid arendajatel on täielik vabadus luua selle API abil oma kohandatud lõpp-punkte kas toimingute tegemiseks või andmete toomiseks.

Alustame esimesest sammust; mis loob kohandatud lõpp-punkte. Kui teid huvitab ainult taotluste esitamine, minge edasi teise osa juurde.

Loo kohandatud lõpp-punktid

Kohandatud lõpp-punktide registreerimine toimub PHP-s. Saate lisada koodi oma teema functions.phpvõi aktiivse pistikprogrammi koodifaili. Looge funktsioon rest_api_initja kasutage seda [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()iga lõpp-punkti jaoks, mille soovite lisada.

Esimese parameetrina register_rest_route()peate esitama unikaalse nimeruumi, et teie lõpp-punktid ei oleks vastuolus ühegi teisega. Kasutage oma teema või pistikprogrammi näpunäidet. Tavaliselt lisatakse /seejärel oma koodile versiooninumber. Näitena kasutan nimeruumi awhitepixel/v1. Teine parameeter on tee (mis järgneb nimeruumile). Lõpuks saate valikuliselt pakkuda massiivi kolmanda parameetrina koos suvanditega. Selles massiivis saate näiteks määratleda päringumeetodi (GET, POST või mis tahes muu), defineerida parameetrid ja mis kõige tähtsam – määrata funktsiooni, mida selle lõpp-punkti taotlemisel käivitada.

Kolmanda parameetrina peaksite esitama vähemalt argumendid "meetod" ja "tagasihelistamine" (mis on lõpp-punkti andmete käsitlemise funktsioon). „Meetodi” jaoks saate määrata need kui „ GET', 'POST', 'PUT', või mis tahes muu kehtiva päringu meetodi (või mitme erineva massiivi), kuid ma soovitan selleks kasutada WordPressi vaikeseadeid. Need on järgmised:

• WP_REST_Server::READABLE meetod " GET"
• WP_REST_Server::EDITABLE meetodid ‘ POST‘, ‘ PUT‘ ja ‘ PATCH‘
• WP_REST_Server::DELETABLE meetod " DELETE"
• WP_REST_Server::ALLMETHODS kõik ülaltoodud meetodid

Loome põhilise kohandatud lõpp-punkti, milleni on võimalik jõuda GET-päringute abil:

Real #2oleme oma kohandatud lõpp-punkti määratlenud kui " awhitepixel/v1/getsomedata". Täielik URL oleks WordPressi REST API juur-URL eesliitega, mis on <yourdomain>/wp-json. Seega oleks ülaltoodud lõpp-punkti täielik URL " <yourdomain>/wp-json/awhitepixel/v1/getsomedata". Reas #4oleme andnud tagasihelistamiseks funktsiooni nime, mille lisame peagi.

Kui registreerite (või muudate) REST API marsruute kasutades register_rest_route(), peate selle  toimimiseks loputama oma püsilingid. Seda saate teha, avades administraatori jaotises Seaded> Püsilingid ja klõpsake lihtsalt nuppu Salvesta.

Me ei ole veel defineerinud tagasihelistamisfunktsiooni – see on funktsioon koodi jaoks, mis käsitleb selle lõpp-punkti kasutamise reaktsiooni. See peab tagastama kehtiva REST vastuse (JSON-is), nii et peate midagi tagastama, kuigi lõpp-punkt ei peaks andmeid tagastama. Saate kasutada funktsiooni [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()funktsiooni või luua objekti eksemplari WP_REST_Responsekui tagasihelistamist. Tagasihelistamisfunktsiooni parameetrina saame WP_REST_Requestobjekti, mis sisaldab kogu teavet päringu kohta, sealhulgas kõiki parameetreid. Loome lihtsa tagasihelistamisfunktsiooni, mis saadab vastuseks lihtsalt teksti:

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

See on kõige lihtsam viis tagasihelistamise kirjutamiseks. Funktsioon rest_ensure_response()tagab, et kõik meie esitatud andmed (string) teisendatakse kehtivaks REST vastuseks. Ilmselt soovite siia lisada rohkem koodi, et WordPressis midagi teha või andmeid tuua ja tagasi saata.

Ülaltoodud koodiga (lõpp-punkti ja tagasihelistamisfunktsiooni registreerimine) võite proovida minna oma brauseris URL-ile ja vaadata, mida saate. (Ärge unustage oma püsilinke loputada). Brauseris lehele minnes <domain>/wp-json/awhitepixel/v1/getsomedatakuvatakse string „Tere!".

Parameetrite aktsepteerimine

See on väga levinud ja kasulik lubada lõpp-punktidel parameetreid aktsepteerida. Näiteks kui teie saidil on nt tooteandmed, soovite lõpp-punkti, kus saate selle toote andmete hankimiseks esitada toote ID. Selleks on kaks võimalust. Kõige tavalisem on GET-päringustringi kasutamine (mis lisatakse URL-i järele pärast ?, eraldatuna &vormingus võti=väärtus. Näiteks ‘ <endpoint>/product/?product_id=14‘). Teise võimalusena saate määratleda "ilusama" URL-i mustri, kus parameetrid on osa teest. Näiteks ‘ <endpoint>/product/14/‘. See viimane meetod nõuab regexide tegemiseks siiski teatud teadmisi. See, millist meetodit valida, on teie otsustada, ma demonstreerin mõlemat allpool.

GET parameetrid

Võimalike lõpp-punkti GET-parameetrite määratlemiseks kasutatakse kolmandas parameetris argsklahvi " ". register_rest_route()Määrake iga lubatava parameetri jaoks võtmeväärtus (ülaltoodud näites ‘ product_id‘) ja selle parameetri valikute massiiv. Valikutena saate määrata parameetri vormingu (kui see eeldab näiteks numbrit või stringi) ja samuti otsustada, kas see parameeter on nõutav või mitte.

Näiteks tahame lubada oma lõpp-punktil aktsepteerida product_idmittevajaliku numbrina.

Kui määrate parameetri väärtuseks Tõene required, edastab WordPress 400 veavastuse. Samamoodi, kui edastate vale vormingu, näiteks „tere”, väärtusena parameetrile, mis eeldab numbrit.

Tagasihelistamise funktsiooni real #15näete, kuidas päringu parameetri väärtust hankida; kasutades meetodit get_param()läbitud WP_REST_Requestobjektis. Näitena näitan erinevaid vastuseid olenevalt sellest, kas neid product_idesitati või mitte (pidage meeles, et oleme määratlenud selle valikulisena). Koodi muutmise loogika vastavalt esitatud parameetritele on täielikult teie ja teie projekti otsustada. Teil võib olla vähem lõpp-punkte, mis aktsepteerivad palju parameetreid, või palju rohkem eraldi lõpp-punkte iga konkreetse juhtumi jaoks.

Ülaltoodud koodiga saan "Tere!" kui ma külastan <yourdomain>/awhitepixel/v1/getsomedataja "Tagasta tooteandmed ID 14 jaoks", kui lähen aadressile <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Parameetrid tee osana

Kui soovite lubada, et parameetrid oleksid pigem tee osa kui GET-päringustring, saate seda teha. Seejärel esitate teele regex-mustri – teise parameetri register_rest_route().

Regulaarsete mustrite loomine võib tunduda üsna salapärane, kuid kuna see on terve teema, leiate hõlpsalt näiteid konkreetsete juhtumite jaoks, kui seda googeldada. Näitan näidet regexi määratlemisest, mis aktsepteerib mis tahes pikkusega arvu;

Nagu näete real #2, olen lisanud regex-mustri (?P<product_id>[d]+)lõppu. See muster tähendab, et me peame koguma mis dtahes pikkusega arvu (+) ja määrama kogutud väärtuse parameetri võtmesse product_id. Ja oma tagasihelistamisfunktsioonis kasutame täpselt sama meetodit, mida kasutasime GET-i parameetrite seadistamisel; get_param()funktsioonile ettenähtud WP_REST_Requestobjektis.

<yourdomain>/wp-json/awhitepixel/v1/getsomedata/14Ülaltoodud koodiga (pärast püsilinkide loputamist) saame vastuse saamiseks külastada URL -i. Selle meetodi tulemuseks on kindlasti "ilusamad" URL-id, kuid kood võib kergesti muutuda raskemini loetavaks ja veaparanduseks. Ükskõik millise meetodi valite, on teie otsustada.

Õige vastuse tagastamine

Varem mainisin lühidalt, kuidas tagasihelistamise funktsioon peab tagastama õige REST vastuse. Siiani oleme kasutanud lihtsamat rest_ensure_response(). Kuid mõnikord võite soovida oma lõpp-punkti tagastamist rohkem kontrollida. Näiteks võite soovida juhtida HTTP vastuse olekukoodi. Oletame, et loote lõpp-punkti, kus saate esitada toote ID ja hankida selle toote kohta andmeid. Kuid kui seda toote ID-d ei eksisteerinud või segadust tekitavad mõni muu parameeter, võiksite tagastada olekukoodi, näiteks 400 (halb taotlus) või 404 (ei leitud). Või ehk 500 (serveri viga). Alati 200 (Õnnestunud) läbimine, kuigi päring oli halb, võib saatjal probleeme tekitada.

Seejärel soovitaksin teie tagasihelistamisfunktsioonil WP_REST_Responseobjekti tagastada. Selle objektiga saate juhtida mitmeid asju, sealhulgas olekukoodi. See on lihtsam kui arvate! Lihtsamal kujul loote uue eksemplari WP_REST_Response, esitate esimese parameetrina tagastatavate andmete massiivi ja teise parameetrina olekukoodi. Näiteks:

Ülaltoodud näites salvestame awhitepixel_get_product()funktsiooni tagastamise muutujas. Seda funktsiooni pole olemas ja peaksite selle asendama funktsiooniga, mis peaks hankima (või tegema) teie projektis soovitud toimingud. Kuid oletame, et funktsioon tagastab tühja massiivi ja see tähendab, et midagi läks valesti (näiteks toodet ei eksisteerinud). Seejärel saame tagastada WP_REST_Responseobjekti olekukoodiga 400 ja valikuliselt sõnumi, mis selgitab, miks see ebaõnnestus (rida #5-9). Vastasel juhul tagastame andmed olekukoodiga 200 Edu (rida #10).

Päringute saatmine (kohandatud) lõpp-punktidesse

Liigume edasi teise poole, saatmisosa juurde: Kuidas saata päringuid meie kohandatud lõpp-punktidesse. Tavaliselt saadate WP REST API päringuid Javascripti abil ja siit leiate näiteid jQuery, WordPressi teegi ja vanilje Javascripti kasutamisest. REST-i päringu sooritamine PHP-ga on haruldane, kuid võimalik – seega olen lisanud ka selle näite.

Esimene asi, mida peaksite teadma, on see, et ilmselt peate päringu saatmiseks teadma täielikku URL-i. Ma ei soovita domeeni kõvasti kodeerida (enne lõpp-punkti), kuna selle saamiseks on mitu võimalust, kui teie Javascript töötab WordPressis. WordPressi vanemates versioonides peaksite kasutama [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()PHP-s ja edastama põhilise REST URL-i globaalse Javascripti muutujana. Kuid allolevad näited näitavad uuemat ja paremat viisi WordPressi saidi REST juur-URL-i hankimiseks.

Veel üks asi, mida tuleks tähele panna, on see, et tõenäoliselt pakendaksite oma projekti taotlused mõne tegevuse tulemusena. Asjade lihtsuse huvides valmistan kõik päringud DOM-is valmis, nii et peaksite kindlasti mähkima päringu koodi nt külastaja nupu klõpsamise tulemusel.

jQuery kasutamine

Kui teil on jQuery teek ja soovite seda kasutada, saate kasutada selle [$.ajax](https://api.jquery.com/jquery.ajax/)()funktsiooni.

Kuid kõigepealt märkus teie Javascripti faili sõltuvuste kohta. Ilmselt vajaks teie skript 'jquery'selle järjekorda seadmisel sõltuvust. Kuid selleks, et pääseda hõlpsalt juurde oma WordPressi REST juur-URL-ile, lisage veel üks sõltuvus; ‘wp-api-taotlus’. See tagab, et Javascripti muutuja wpApiSettings.rooton saadaval ja sisaldab REST API juur-URL-i. Siin on näide selle kohta, kuidas saate oma skripti selle sõltuvuse illustreerimiseks järjekorda panna;

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

Liin #5on huvitav; kus me määratleme nii jQuery kui wp-api-requestka sõltuvuse. Seejärel saame oma Javascripti failis täita WP REST API päringu järgmiselt:

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

See on nii elementaarne kui võimalik. Kasutame $.ajax()GET-päringu saatmiseks määratud URL-ile. URL-ina kasutame wpApiSettings.rootREST API juur-URL-i hankimiseks ja seejärel lisame selle järele soovitud lõpp-punkti; meie puhul varem loodud kohandatud lõpp-punkt. Valikuliselt saame parameetreid edastada andmetes. Ülaltoodud näide läheb product_idväärtusega 14 lõpp-punkti. Lõpuks successsaame funktsioonis parameetrina (edukas) päringu ja saame sellega teha, mida tahame. Ülaltoodud näites prindime selle lihtsalt konsooli.

WordPressi teegi kasutamine (mitte jQuery)

Kui teie WordPressi saidil pole jQuery teeki või saate seda kasutada, saate REST API päringu hõlpsaks täitmiseks kasutada WordPressi Javascripti teeki. Funktsioon on apiFetchsee, mis on saadaval WordPressi globaalses wpnimeruumis. wp.apiFetch()on brauseri standardfunktsiooni fetch()ümbrismeetod (mida näidatakse järgmisena).

Meie Javascript vajab wp.apiFetch() kasutamiseks sõltuvust ‘wp-api’. Näiteks võime skripti järjekorda panna järgmiselt:

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

Kriitilise sõltuvuse leiate realt #5. Sellega oleme taganud, et meie Javascripti fail on wp.apiFetch()saadaval. Siin on selle kasutamise põhinäide:

Pidage meeles, et rida #9-13on lihtsalt loogiline, et käivitada funktsioon pärast DOM-i valmimist.

Üks kasutamise eelis wp.apiFetch()võrreldes tavapärasega fetch()on see, et saame kasutada URL-i, mis nõuab täielikku URL-i, asemel „teed”, mis nõuab ainult lõpp-punkti. Teine eelis on see, et esimene "ahel" .then()tagastab juba JSON-vormingus andmed. Kui kasutate originaali .fetch(), vajate rohkem ".then() ahelaid". Vaadake järgmist näidet ("Vanilje Javascripti kasutamine"), et näha, mida ma mõtlen.

Pidage meeles, et fetch()(ja sellest tulenevalt wp.apiFetch()) ei paku parameetrite edastamiseks "puhast" viisi. Peame käsitsi konstrueerima GET-päringu stringi teekonnas, nagu ma eespool tegin: '../getsomedata?product_id=14'.

Kui olete huvitatud sellest, kuidas wp.apiFetchGutenbergi plokki lisada ja kohandada lõpp-punkte, olen selle kohta kirjutanud eraldi õpetuse:

Vanilje Javascripti kasutamine

Viimase näitena Javascripti meetoditest WP REST API-le päringu saatmiseks on puhas vanilje, mitte-WordPress viis, kasutades fetch(). Pange tähele, et ma kasutan REST juur-URL-i saamiseks WordPressi globaalset muutujat. Kui lisate selle skripti väljaspool WordPressi, peate tõenäoliselt kogu URL-i kõvasti kodeerima.

Kuna ma tahan endiselt juurdepääsu WP REST juur-URL-i globaalsele muutujale, lisan 'wp-api-request'oma Javascripti järjekorrafunktsioonile sõltuvuse, näiteks:

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 siis meie Javascripti failis oleks kõige lihtsam näide:

Nagu eespool mainitud ("WordPressi teegi kasutamine") .fetch()ei toeta kena ja puhas parameetrite esitamise viis. Seega peate URL-i käsitsi ehitama päringustringi (?product_id=14).

Pidage meeles, et toomistaotlus ei naase otse koos andmetega – see tagastab lubaduse. Seetõttu peame .then()enne andmete käsitlemist aheldama " ". Kui see tundub teile võõras, soovitan uurida, kuidas töötada fetch()– Google’is on palju selgitusi ja näiteid, mis suudavad seda minust paremini selgitada.

Kui soovite kontrollida oma päringu vastuse olekukoodi REST, saate seda teha nii;

Ülaltoodud näites kohandatud lõpp-punktide registreerimisel mainisin, kuidas saate tagastada erinevad HTTP olekukoodid. Ülaltoodud kood näitab näidet vastuse olekukoodi kontrollimiseks, mis on saadaval tagastatava objekti .statusatribuudis. Ülaltoodud näites kontrollin, kas olekukood on real 200 (edu) erinev #5. Ainult siis, kui olekukood oli 200, teisendan lubaduse andmetagastuse JSON-iks (rida #9).

PHP kasutamine

Vähem levinud, kuid siiski võimalik, on WordPressis PHP-ga sisemiselt sooritada REST-päring. Siin on, kuidas.

PHP-s WP REST API päringu saatmiseks loome WP_REST_Requestobjekti (täpselt nagu see, mis meie tagasihelistamisfunktsioonile selles postituses varem edastati). Selles objektieksemplaris määratleme meetodi (nt GET) ja lõpp-punkti tee. Soovi korral saame lisada ka parameetreid. Seejärel kasutame [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()selle päringu eksemplari puhul WordPressi funktsiooni. Lõpuks saame vastuse s-klassis [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()saadaval oleva funktsiooniga .WP_REST_Server'

Funktsioonikutse set_query_params()(rida #3-5) on valikuline ja vajalik ainult siis, kui soovite edastada parameetreid. Selle postituse punase lõime järel lisan näite funktsiooni parameetri edastamisest parameetriklahvile REST product_id.

Rida #6, kuhu me päringu saadame. Ja real #7tagastame vastuse andmed. Nii et kui kutsuksime seda PHP funktsiooni näiteks, awp_do_php_rest_request( 14 )saaksime vastuse, mille me selles lõpp-punktis määratlesime (stringiga massiiv, kui kasutate endiselt sama näidet, mis selle postituse alguses).