WP REST API Preluarea datelor

În părțile anterioare ale seriei, ne-am uitat la ceea ce este WP REST API și cum ne poate ajuta să construim aplicații mai bune folosind WordPress back end.

Apoi am analizat două moduri de a configura autentificarea pe server pentru generarea de cereri autentificate. Prima este metoda de autentificare de bază, care este utilă în medii de dezvoltare și permite prototiparea rapidă, deoarece nu necesită mult timp pentru a configura. A doua metodă de autentificare este OAuth 1.0a, care este recomandat pentru medii de producție deoarece este mult mai sigur decât metoda de autentificare de bază.

Acum, că am învățat cum să configuram autentificarea, suntem gata să generăm cereri autentificate pentru a dezlănțui toată puterea API-ului WP REST. Vom utiliza autentificarea de bază în cadrul acestei serii datorită ușurinței de utilizare, dar este recomandat să utilizați autentificarea OAuth 1.0a, așa cum este prevăzută de pluginul OAuth 1.0a, pentru serverele dvs. de producție.

În partea curentă a seriei, vom beneficia de prima noastră experiență hands-on cu pluginul WP REST API. Noi vom:

analiza structurii unui a OBȚINE cerere
verificați cum OPȚIUNI solicitați auto-documente API-ul
trimiteți cereri către server pentru recuperarea datelor
analizați răspunsul serverului care include proprietăți, scheme și linkuri

Deci, haideți să începem prin analizarea structurii unui simplu OBȚINE cerere.

Anatomia a `OBȚINE` Cerere

Înainte de a ne detalia detaliile de recuperare a oricăror date cu WP REST API, trebuie să ne familiarizăm cu sintaxa unei solicitări care este trimisă către server. Acest lucru va oferi o bază solidă pentru viitoarele noastre interacțiuni cu WP REST API.

Luați în considerare următoarea solicitare trimisă pe server:

$ GET http: // localserver / wp-json / wp / v2 / postări

Tipul de cerere pe care îl trimitem este OBȚINE-unul dintre cele șase verbe HTTP pe care le-am analizat în partea inițială a acestei serii. A OBȚINE cererea este utilizată pentru a prelua date de pe server. Prin urmare, atunci când este executat la server, cererea de mai sus preia o colecție de toate obiectele postate sub formă de date JSON.

Având în vedere URI-ul de solicitare, îl putem rupe în următoarele părți:

http: // LocalServer /: Adresa URL a serverului meu local de dezvoltare. Ar putea fi orice URL în funcție de locul în care este localizată instalarea WordPress.
/ Wp-json: Este prefixul punctului final al WP REST API.
/ wp: Spațiul de nume al pluginului WP REST API.
/ v2: Este versiunea pluginului WP REST API.
/ posturi: Este resursa pe care dorim să o preluăm de pe server.

Spațiul de nume împiedică suprascrierea care ar putea apărea atunci când rulează mai multe plugin-uri, fiecare furnizând propriul strat de abstractizare pentru API-ul RESTful. Prin urmare, fiecare abstracție funcționează la limita proprie fără a afecta metodele și proprietățile care aparțin unei alte abstracțiuni.

Spațiul de nume și versiunea nu erau prezente în vechea versiune 1.2 a pluginului. Deci, în versiunea moștenită, cererea de mai sus ar fi așa:

$ GET http: // localserver / wp-json / postări

Dar nu vom vorbi despre compatibilitate înapoi aici. Dacă doriți să aflați despre toate modificările care au avut loc între versiunea 1.x și 2.x, le puteți găsi pe pagina oficială.

Pe lângă recuperarea unei colecții de resurse (postări) utilizând URI de mai sus, putem să preluăm și o resursă specifică menționând codul său de identificare:

$ GET / wp / v2 / posturi / 100

Cererea de mai sus va returna un obiect post care arată în jos pentru o resursă post care are un ID de 100.

De altă dată, trebuie să căutăm și postări care îndeplinesc anumite criterii specifice. În acest scop, WP REST API oferă o modalitate de a utiliza filtru[] sintaxă:

$ GET / wp / v2 / posts? Filtru [cat] = 1

Prin trimiterea solicitării de mai sus, putem prelua toate postările aparținând unei categorii de ID 1. Sintaxa de filtrare poate fi utilă în special atunci când interogați postări sau navigați între diferite resurse, de ex. posturi și categorii, folosind relațiile lor.

În cele din urmă, atunci când se ocupă de argumente care iau matricele ca intrări filtru[] sintaxa, putem adăuga un set gol de paranteze pătrate pentru a exprima astfel de elemente:

$ GET / wp / v2 / posts? Filtrează [categoria] și [] = 1 și filtrează [category__and] [] = 2

Sintaxa de mai sus este echivalentă cu următoarea WP_Query ():

 matrice (1, 2)));

Prin urmare, cele de mai sus OBȚINE cererea va prelua o listă de posturi care aparțin ambelor categorii având un ID de 1 și 2. Aceeași sintaxă poate fi de asemenea utilizată pentru argumentele de array care au mai mult de două elemente. Rețineți că utilizarea funcției category__and parametrul necesită autentificarea utilizatorului cu edit_posts privilegii.

Vom examina filtru[] sintaxa în detaliu într-o secțiune ulterioară.

Acum, că am învățat despre formatarea a OBȚINE cererea și furnizarea parametrilor săi, este timpul să aruncăm o privire la OPȚIUNI cerere. Un OPȚIUNI cererea facilitează navigarea prin API și de fapt servește ca o modalitate de auto-documentare pentru a face API mai accesibil prin documentarea tuturor metodelor HTTP disponibile pe un punct final și, la rândul său, argumentele pe care le suportă.

Navigarea prin API folosind `OPȚIUNI` Cerere

Așa cum am menționat anterior, OPȚIUNI cererea poate fi extrem de utilă în explorarea API-ului. Menționează toate punctele finale care aparțin unui anumit traseu și oferă o listă de parametri care susțin aceste puncte finale pentru operațiile CRUD.

Să trimitem un mesaj OPȚIUNI cererea către / Wp / v2 / mesaje pentru a verifica ce puncte finale suportă și parametrii pe care le putem trece de-a lungul OBȚINE solicitați date de interogare:

$ curl -X OPȚIUNI wp / v2 / postări

Am folosit cURL pentru a trimite cererea de mai sus, dar puteți folosi orice instrument ales de dvs., inclusiv Postman. Asigurați-vă că includeți calea completă la ruta de mai sus, inclusiv calea serverului dvs..

"namespace": "wp / v2", "metode": [...], "puncte finale": [...], "schema": ..., _links: ...

De mai sus OPȚIUNI cererea către / Wp / v2 / mesaje rută returnează date în format JSON care conține cinci proprietăți:

Spațiu de nume
metode
puncte finale
schemă
_links

"spațiu de nume": "wp / v2", ...

Spațiu de nume proprietatea identifică spațiul de nume al pluginului curent. În cazul nostru wp / v2, care semnifică versiunea 2 a WP REST API. Am analizat deja spațiul de nume și scopul pe care îl servește în secțiunea anterioară.

... "metode": ["GET", "POST"], ...

metode proprietatea conține o serie de metode acceptate de ruta curentă. Privind răspunsul la cererea de mai sus, este clar că / Wp / v2 / mesaje traseu sprijină două metode, și anume OBȚINE și POST. Înseamnă că putem folosi / Wp / v2 / mesaje traseu pentru a prelua posturile, precum și pentru a crea un post nou. Ne vom ocupa de POST în următoarea parte a acestei serii, așa că trebuie doar să ne concentrăm asupra OBȚINE pentru moment.

Următoarea proprietate-puncte finale-conține o serie de puncte finale acceptate pentru ruta curentă. Această proprietate este legată direct de cele menționate anterior metode proprietate, deoarece enumeră obiectivele pentru metodele acceptate.

... "" puncte finale ": " metode ": " GET "]," args "

puncte finale proprietatea conține valori obiect care la rândul lor conțin două proprietăți, și anume metode și args. metode proprietatea conține o serie de metode HTTP și următoarea args proprietatea conține toate argumentele acceptate pentru aceste metode. Acestea sunt argumentele pe care le trimitem de-a lungul cererii sub forma parametrilor URI.

Privind argumentele susținute de OBȚINE metodă, întâlnim nouă argumente care includ context, pagină, per pagină, etc. Aceste obiecte argument conțin două proprietăți, necesar și Mod implicit. necesar proprietatea indică dacă argumentul este necesar și Mod implicit proprietatea reprezintă valoarea implicită a argumentului.

"metode": ["GET"], "args": "context": "obligatoriu": false, "default": "view"; 1, "per_page": "necesar": false, "implicit": 10, "filtru": "necesar": false

schemă proprietatea în documentele de răspuns returnate toate proprietățile pentru resursele curente. Schema definește o structură pentru date în format JSON. Formatul de schemă folosit în WP REST API se bazează pe schița 4 a specificațiilor schemei JSON.

Ultimul _links proprietatea deține o serie de obiecte care conțin legăturile de resurse asociate. Cheia în obiect specifică tipul relației (de ex. autor, Colectie, de sine, comentarii, etc), valoarea sa fiind legătura cu acea resursă asociată. Acest standard de conectare se bazează pe HAL (Hypertext Application Language). Puteți afla mai multe despre HAL citirea specificațiilor create de Mike Kelley.

În mod similar, putem trimite un mesaj OPȚIUNI cereți altor rute, inclusiv celor ale utilizatorilor, comentariilor, media, pagini etc., pentru a verifica metodele și argumentele acceptate. OPȚIUNI solicitările sunt cel mai bun prieten când lucrați cu WP REST API.

API-ul WP REST oferă încă o altă modalitate de a evalua disponibilitatea API prin trimiterea unui mesaj OBȚINE cererea către / Wp-json traseu index. Aceasta va lista toate rutele și obiectivele lor împreună cu metodele și argumentele lor acceptate.

$ curl -X GET http: // wordpress-server / wp-json

Cererea de mai sus va returna un obiect de răspuns care conține o proprietate de trasee după cum urmează:

Această caracteristică este extrem de puternică, deoarece enumeră toate rutele și metodele și argumentele acceptate, eliminând astfel necesitatea ca toate acestea să fie documentate extern. Vom face referire la acest obiect de răspuns când efectuăm operațiuni CRUD pe diferite resurse.

După ce ne-am uitat la opțiunile noastre de a explora API, să începem acum să lucrăm cu API-ul WP REST pentru a prelua datele de pe server.

Lucrul cu mesajele

Până acum, ne-am familiarizat cu OPȚIUNI cerere, care este o modalitate autocumentantă de a evalua disponibilitatea API. De asemenea, am analizat cum arată metode și argumente acceptate pentru un anumit traseu. Folosind aceste cunoștințe, suntem acum gata să recuperăm diferite resurse de la server utilizând API-ul WP REST.

Resursa pe care o vom începe este Mesaje de resurse, deoarece este blocul principal de WordPress. Ne vom ocupa de preluarea postărilor utilizând filtre diferite. Aplicând aceste cunoștințe, veți putea să căutați postări folosind API-ul WP REST la fel ca și în cazul clasei WP_Query ().

De-a lungul acestei serii, am lucrat cu Mesaje de resurse pentru a demonstra exemple de cereri și răspunsurile acestora și deja știm cum să preluăm colectarea postului și o postare individuală prin ID-ul său. Deci nu vom mai acoperi asta. În schimb, vom examina câteva modalități mai avansate de recuperare a postărilor utilizând parametrii de nivel superior și filtru[] sintaxă.

Lucrul cu parametrii de nivel superior

API-ul WP REST expune câteva dintre cele mai frecvent utilizate variabile de interogare pentru postări direct pe OBȚINE punct final. Acești parametri sunt:

context: Domeniul de aplicare al cererii. Posibile valori ar putea fi vedere, încorporare sau Editați | ×.
pagină: Pagina curentă a colecției postale.
per pagină: Numărul total de postări pe pagină.
căutare: Interogarea de căutare. Limitați rezultatele la șirul de potrivire.
autor: ID-ul autorului. Folosit pentru a limita rezultatele aparținând unui anumit autor.
exclude: O serie de ID-uri de post pentru a exclude din rezultatele căutării.
include: Limitați rezultatele pentru a posta ID-urile specificate în acest câmp.
ofset: Deplasați rezultatele căutării după numărul specificat.
Ordin: Ordinea colecției. Poate fi asc sau desc.
orderby: Atributul de sortare al colecției. Valorile posibile pot fi id, titlu sau melc.
melc: Limitați rezultatele la un post care are un anumit slug.
stare: Utilizat pentru a limita colectarea posturilor care au un anumit statut.

context parametru este folosit pentru a prelua posturi în funcție de domeniul în care lucrăm. Dacă doar listarea postărilor pe o anumită pagină index, atunci suntem bine să mergem cu vedere context. Dar dacă preluăm posturi pentru a le edita, atunci trebuie să folosim Editați | × context:

$ GET / wp / v2 / posts? Context = editare

Editați | × contextul de context introduce o suplimentare brut câmp în domenii cum ar fi titlu, conţinut, extras, etc. Valoarea acestui lucru brut câmpul poate fi reluat în editor pentru editarea conținutului.

Utilizarea Editați | × contextul necesită autentificarea utilizatorului ca utilizator edit_posts privilegii.

Utilizarea încorporare ca valoare a context parametrul preia colecția posturilor cu un subset minim de proprietăți.

Alți parametri menționați mai sus sunt destul de explicați și puteți juca cu ei în clientul dvs. HTTP.

Acestea au fost parametrii de bază care vă permit să căutați posturi pe baza anumitor criterii. Pentru a restrânge capacitățile noastre de interogare, WP REST API oferă filtru[] sintaxă care acceptă un subset al funcției WP_Query () args.

Utilizarea `filtru[]` Sintaxă

Pe lângă recuperarea unei colecții de postări care utilizează câțiva parametri de bază de nivel superior, WP REST API expune o parte din WP_Query () variabilele utilizând filtru[] sintaxă. Folosind această sintaxă, putem interoga posturile în același mod ca și noi când lucrăm cu WP_Query () clasă.

Parametrii de paginare sunt cei mai importanți dintre toate filtrele, deoarece sunt utilizate pe scară largă în paginile cu postare. Parametrii de paginare ne permit să afișăm un anumit număr de postări pe pagină și să navigăm la un anumit număr de pagini care conțin postări.

Implicit, a OBȚINE cererea returnează o colecție de 10 postări pe pagină. Să vedem cum putem să prezentăm a OBȚINE solicitați să preluați numai cinci postări pe pagină:

$ GET / wp / v2 / posts? Filtru [posts_per_page] = 5

Cererea de mai sus utilizează posts_per_page variabilă cu care ați putea fi familiarizat dacă ați lucrat WP_Query ().

Paged parametru este utilizat împreună cu posts_per_page parametru și este folosit pentru a naviga la un anumit număr de pagini. După ce am recuperat cinci postări pe pagină, vom face următoarea solicitare de a naviga la a doua pagină:

$ GET / wp / v2 / posts? Filtru [posts_per_page] = 5 & filtra [paged] = 2

posts_per_page și Paged filtrele pot fi extrem de la îndemână atunci când lucrează pentru a construi paginarea în listarea paginilor utilizând API-ul WP REST. Acești doi parametri sunt echivalenți cu per pagină și pagină parametrii de nivel superior. Prin urmare, următoarea solicitare face aceeași lucrare ca cea de mai sus:

$ GET / wp / v2 / posturi? Per_page = 5 & pagina = 2

În plus față de colecția de postări, cererea de mai sus revine, serverul returnează, de asemenea, un număr de anteturi cu un răspuns care conține informații utile, inclusiv numărul total de postări și numărul de pagini. Aceste valori sunt cuprinse în X-WP-TotalPages și X-WP-Total rapoarte de răspuns.

X-WP-TotalPages și X-WP-Total rapoartele de răspuns sunt extrem de utile atunci când creați paginarea folosind API-ul WP REST, deoarece acestea conțin numărul total de pagini și numărul total de postări.

În afară de filtrele de paginare, cea mai importantă utilizare a filtru[] sintaxa trebuie să poată interoga postările după datele lor. În acest scop, filtru[] sintaxa suporta opt parametri, la fel ca si cei ai WP_Query () clasă:

an: Anul cu patru cifre (de exemplu, 2015 sau 2016)
monthnum: Numărul lunii de la 1 la 12
m: Șase cifre pe an (de exemplu, 201601)
w: Săptămâna anului de la 0 la 53
zi: Ziua lunii de la 1 la 31
ora: Ora oră de la 0 la 23
minut: Momentul de la ora 0 la 60
al doilea: Al doilea minut de la 0 la 60

Deci, dacă căutăm posturile publicate la data 2015-10-15 (aaaa / mm / zi), acest lucru se poate realiza prin următoarea interogare:

$ GET / wp / v2 / posts? Filtru [anul] = 2015 & filtru [monthnum] = 10 & filter [day] = 15

O interogare similară poate fi pregătită cu ajutorul parametrilor de mai sus dacă trebuie să restrângem căutarea la ora și minutul exact.

Am văzut deja într-o secțiune anterioară a acestui tutorial cum am putea prelua posturile aparținând unei anumite categorii sau mai multor categorii utilizând filtru de [cat] și filtru de [category__and] parametrii. Acum vom folosi filtru de [category__in] parametru pentru a afișa postări aparținând categoriilor cu un id de 5 și 6:

$ GET / wp / v2 / posts? Filtru [category__in] [] = 5 & filtru [category__in] [] = 6

Cererea de mai sus va prelua o listă cu toate posturile aparținând categoriilor cu un id de 5 și 6.

Efectul opus ar putea fi obținut prin utilizarea filtru de [category__not_in] parametru în modul următor:

$ GET / wp / v2 / posts? Filtru [category__not_in] [] = 5 & filtru [category__not_in] [] = 6

Aceasta va prelua o listă de posturi, excluzând toate postările aparținând categoriilor care au un ID de 5 sau 6.

Mai multe ar putea fi scrise cu privire la utilizarea filtru[] sintaxă, dar nu voi acoperi toate cele de aici. Puteți găsi o listă cu toate variabilele de interogare acceptate de filtru[] sintaxă în documentația oficială a versiunii 1 a pluginului. O mare parte din aceste informații sunt încă valabile cu versiunea 2 a WP REST API, dar în unele zone le lipsește. La momentul elaborării acestui tutorial, documentația oficială a versiunii 2 nu menționează nimic despre filtru[] sintaxa și interogarea pe care o susține, dar sperăm să vedem îmbunătățiri în documentația oficială în viitorul apropiat, deoarece există un număr de oameni (inclusiv mine) care contribuie la dezvoltarea plugin-ului și a documentației.

Acum că am analizat diferite opțiuni atunci când interogăm posturi cu ajutorul API-ului WP REST, suntem gata să avansăm în continuare în călătoria noastră și să examinăm alte resurse susținute de WP REST API.

Lucrul cu revizuiri Post, Categorii, Etichete și Meta

Revizuirile post oferă o modalitate de a vizualiza și de a restabili editările efectuate într-o postare. API-ul WP REST oferă o modalitate de a vizualiza toate revizuirile unei postări prin interogarea / posturi // revizii punct final. Prin urmare, pentru un post dat cu un ID de 10, toate revizuirile pot fi preluate prin trimiterea următoarei solicitări:

$ GET / wp / v2 / posts / 10 / revizuiri

Cererea de mai sus va returna o matrice care conține obiecte de revizuire. Obiectul revizii conține un subset de proprietăți găsite în obiectul post. Mai jos este un exemplu de revizuire obiect în Postman:

O revizie specifică poate fi recuperată având în vedere că știm id-ul său. Deci, o revizuire care are un ID de 2 cu post având un ID de 10 poate fi preluat de următorul obiect:

$ GET / wp / v2 / posturi / 10 / revizii / 2

Cererea de mai sus va returna un singur obiect de revizuire.

În afară de revizuirile post, categoriile pentru o anumită postare pot fi preluate de următoarea solicitare:

$ GET / wp / v2 / categorii? Post =

Și pentru etichete, utilizăm următoarea solicitare:

$ GET / wp / v2 / tags? Post =

Cu fiind identitatea postului.

Dacă trebuie să preluăm post meta pentru post care are un ID de 10, trimitem următoarea solicitare ca utilizator autentificat:

$ GET / wp / v2 / posturi / 10 / meta

Aceasta va returna o serie de obiecte meta.

Rețineți că pentru a lucra cu meta de pagină și de pagină în WP REST API, trebuie să aveți pluginul companion instalat disponibil pe GitHub de către echipa WP REST API.

Lucrul cu alte resurse

Până acum, am câștigat o bază destul de solidă pentru a lucra cu WP REST API pentru a prelua date. Am analizat deja cererea de opțiuni și cum ne ajută să explorăm API fără a avea nevoie de documentație externă.

Puteți trimite oricând un mesaj OPȚIUNI solicitați o anumită resursă și verificați ce obiective și parametri suportă. Dacă trebuie să listați toate rutele pe care WP REST API le oferă, puteți să o trimiteți OBȚINE solicitați la punctul final al indexului la / Wp-json așa cum am învățat să facem la începutul acestui tutorial.

Având în vedere acest avantaj al auto-documentării, nu cred că mai trebuie să explorăm fiecare resursă individuală din acest tutorial, deoarece acum sunteți în stare să faceți acest lucru pe cont propriu.

Ce este în continuare?

În acest tutorial de lungă durată, am învățat să explorăm API utilizând solicitarea OPTIONS, precum și să preluăm date de la server utilizând API-ul WP REST. Ne-am uitat la o mână de resurse, inclusiv postări, post-revizuire și post-meta, deoarece nu am putut acoperi toate resursele susținute într-un singur tutorial. Dar acum ar trebui să explorați API pe cont propriu folosind tehnicile pe care le-am învățat în acest tutorial.

WordPress are o economie incredibil de activă. Există teme, pluginuri, biblioteci și multe alte produse care vă ajută să vă construiți site-ul și proiectul. Natura open source a platformei o face de asemenea o opțiune excelentă din care vă puteți îmbunătăți abilitățile de programare. Indiferent de situație, puteți vedea ce avem la dispoziție în piața Envato Marketplace.

În următoarea tranșă a acestei serii, vom învăța să realizăm celelalte trei operații ale CRUD, adică crearea, actualizarea și ștergerea resurselor. Deci stați liniștit ...

Cod