Share
Nelle parti precedenti della serie, abbiamo esaminato che cos'è l'API WP REST e come può aiutarci a creare applicazioni migliori utilizzando il back-end di WordPress.
Quindi abbiamo esaminato due modi per configurare l'autenticazione sul server per la generazione di richieste autenticate. Il primo è il metodo di autenticazione di base, che è utile negli ambienti di sviluppo e consente la prototipazione rapida in quanto non richiede molto tempo per la configurazione. Il secondo metodo di autenticazione è OAuth 1.0a, che è consigliato per gli ambienti di produzione in quanto è molto più sicuro del metodo di autenticazione di base.
Ora che abbiamo imparato come impostare l'autenticazione, siamo pronti a generare richieste autenticate per liberare tutta la potenza dell'API REST di WP. Utilizzeremo l'autenticazione di base in questa serie grazie alla sua facilità d'uso, ma si consiglia di utilizzare l'autenticazione OAuth 1.0a, come fornita dal plugin OAuth 1.0a, per i server di produzione.
Nella parte attuale della serie, avremo la nostra prima esperienza pratica con il plug-in API WEST REST. Noi:
Accentsconagua
OTTENERE richiestaOPZIONI richiedere l'auto-documentazione dell'APIQuindi iniziamo analizzando la struttura di un semplice OTTENERE richiesta.
OTTENERE RichiestaPrima di approfondire i dettagli del recupero di tutti i dati con l'API WP REST, è necessario familiarizzare con la sintassi di una richiesta inviata al server. Ciò getterà una solida base per le nostre future interazioni con l'API REST di WP.
Considera la seguente richiesta inviata al server:
$ OTTIENI http: // localserver / wp-json / wp / v2 / posts
Il tipo di richiesta che stiamo inviando è OTTENERE-uno dei sei verbi HTTP che abbiamo visto nella parte iniziale di questa serie. UN OTTENERE richiesta viene utilizzata per recuperare i dati dal server. Quindi, quando eseguito sul server, la richiesta sopra riportata recupera una raccolta di tutti gli oggetti del post sotto forma di dati JSON.
Considerando l'URI della richiesta, possiamo suddividerlo nelle seguenti parti:
http: // LocalServer /: L'URL del mio server di sviluppo locale. Potrebbe essere qualsiasi URL a seconda di dove si trova l'installazione di WordPress./ Wp-JSON: È il prefisso endpoint dell'API REST di WP./ wp: Lo spazio dei nomi del plug-in API REST WP./ v2: È la versione del plug-in API REST WP./ messaggi: È la risorsa che vogliamo recuperare dal server.Lo spazio dei nomi impedisce l'override che potrebbe verificarsi quando si eseguono più plug-in con ciascuno che fornisce il proprio livello di astrazione per l'API RESTful. Quindi, ogni astrazione lavora nel proprio limite senza influenzare i metodi e le proprietà che appartengono ad un'altra astrazione.
Lo spazio dei nomi e la versione non erano presenti nella versione legacy 1.2 del plug-in. Quindi nella versione legacy, la richiesta sopra sarebbe così:
$ OTTIENI http: // localserver / wp-json / posts
Ma non parleremo di compatibilità con le versioni precedenti qui. Se vuoi conoscere tutte le modifiche avvenute tra la versione 1.x e 2.x, puoi trovarle nella pagina ufficiale.
Oltre a recuperare una raccolta di risorse (post) utilizzando l'URI sopra, possiamo anche recuperare una risorsa specifica menzionando il suo ID:
$ GET / wp / v2 / posts / 100
La richiesta sopra riportata restituirà un oggetto post come cerca una risorsa post che abbia un ID di 100.
Altre volte, dobbiamo anche cercare i post che soddisfano determinati criteri. A tale scopo, l'API WP REST fornisce un modo per utilizzare il filtro[] sintassi:
$ GET / wp / v2 / posts? Filter [cat] = 1
Inviando la richiesta di cui sopra, possiamo recuperare tutti i post appartenenti a una categoria di ID 1. La sintassi del filtro può essere particolarmente utile quando si interrogano post o si naviga tra diverse risorse, ad es. post e categorie, usando le loro relazioni.
Infine, quando si tratta di argomenti che utilizzano array come input in filtro[] sintassi, possiamo aggiungere un insieme vuoto di parentesi quadre per esprimere array in questo modo:
$ GET / wp / v2 / posts? Filter [category__and] [] = 1 & filter [category__and] [] = 2
La sintassi precedente è equivalente al seguente WP_Query ():
array (1, 2)));
Quindi, quanto sopra OTTENERE la richiesta recupererà un elenco di post che appartengono a entrambe le categorie con ID 1 e 2. La stessa sintassi può essere utilizzata anche per argomenti array con più di due elementi. Si prega di notare che l'uso del category__and il parametro richiede l'autenticazione dell'utente con edit_posts privilegi.
Guarderemo nel filtro[] sintassi più in dettaglio in una sezione successiva.
Ora che abbiamo imparato a formattare a OTTENERE richiesta e fornendo i suoi parametri, è il momento di dare un'occhiata al OPZIONI richiesta. Un OPZIONI la richiesta semplifica la navigazione attraverso l'API e funge effettivamente da modalità di auto-documentazione per rendere l'API più accessibile documentando tutti i metodi HTTP disponibili su un endpoint e, a sua volta, gli argomenti supportati.
OPZIONI RichiestaCome accennato prima, il OPZIONI la richiesta può essere estremamente utile nell'esplorazione dell'API. Indica tutti gli endpoint che appartengono a una determinata rotta e fornisce un elenco di parametri supportati da questi endpoint per le operazioni CRUD.
Mandiamo un OPZIONI richiesta al / WP / V2 / messaggi percorso per verificare quali endpoint supporta e quali parametri possiamo passare lungo il OTTENERE richiesta di interrogare i dati:
$ curl -X OPZIONI wp / v2 / posts
Ho usato cURL per inviare la richiesta di cui sopra, ma puoi usare qualsiasi strumento di tua scelta, incluso Postman. Assicurati di includere il percorso completo per il percorso sopra, compreso il percorso del tuo server.
"namespace": "wp / v2", "metodi": [...], "endpoint": [...], "schema": ..., "_links": ...
Quanto sopra OPZIONI richiesta al / WP / V2 / messaggi route restituisce i dati nel formato JSON che contiene cinque proprietà:
namespacemetodiendpointschema_links"namespace": "wp / v2", ...
Il namespace proprietà identifica lo spazio dei nomi del plugin corrente. Nel nostro caso lo è wp / v2, che indica la versione 2 dell'API REST di WP. Abbiamo già esaminato lo spazio dei nomi e lo scopo che serve nella sezione precedente.
... "metodi": ["GET", "POST"], ...
Il metodi la proprietà contiene una matrice di tutti i metodi supportati dal percorso corrente. Guardando la risposta restituita la richiesta di cui sopra, è chiaro che il / WP / V2 / messaggi percorso supporta due metodi, vale a dire OTTENERE e INVIARE. Significa che possiamo usare il / WP / V2 / messaggi percorso per recuperare i post, oltre a creare un nuovo post. Ci occuperemo del INVIARE metodo nella parte successiva di questa serie, quindi concentriamoci solo su OTTENERE metodo per il momento.
La prossima proprietà-endpoint-contiene una matrice degli endpoint supportati per la rotta corrente. Questa proprietà è direttamente collegata al precedente metodi proprietà in quanto elenca gli endpoint per i metodi supportati.
... "endpoint": ["metodi": ["GET"], "args": ..., "metodi": ["POST"], "args": ...], ...
Il endpoint la proprietà contiene valori oggetto che a loro volta contengono due proprietà, vale a dire metodi e args. Il metodi la proprietà contiene una matrice di metodi HTTP e la successiva args proprietà contiene tutti gli argomenti supportati per questi metodi. Questi sono gli argomenti che inviamo lungo la richiesta sotto forma di parametri URI.
Guardando gli argomenti supportati dal OTTENERE metodo, ci imbattiamo in nove argomenti che includono contesto, pagina, per pagina, ecc. Questi oggetti argomento contengono due proprietà, necessario e predefinito. Il necessario proprietà indica se l'argomento è richiesto e il predefinito proprietà rappresenta il valore predefinito dell'argomento.
"metodi": ["GET"], "args": "context": "required": false, "default": "view", "page": "required": false, "default": 1, "per_page": "required": false, "default": 10, "filter": "required": false
Il schema la proprietà nella risposta restituita documenta tutte le proprietà per la risorsa corrente. Lo schema definisce una struttura per i dati nel formato JSON. Il formato dello schema utilizzato nell'API REST di WP si basa sulla bozza 4 delle specifiche dello schema JSON.
L'ultimo _links proprietà contiene una serie di oggetti contenenti i collegamenti delle risorse associate. La chiave nell'oggetto specifica il tipo di relazione (ad es. autore, collezione, se stesso, Commenti, ecc.), con il suo valore come collegamento a quella risorsa associata. Questo standard di collegamento è basato su HAL (Hypertext Application Language). Puoi trovare ulteriori informazioni su HAL leggendo le specifiche create da Mike Kelley.
In modo simile, possiamo inviare un OPZIONI richiedere ad altri percorsi, inclusi quelli di utenti, commenti, media, pagine, ecc., per verificare i loro metodi e argomenti supportati. OPZIONI le richieste sono il tuo migliore amico quando si lavora con l'API REST di WP.
L'API WP REST fornisce un altro modo per valutare la disponibilità dell'API inviando un OTTENERE richiesta al / Wp-JSON percorso dell'indice. Questo elencherà tutti i percorsi e i relativi endpoint insieme ai loro metodi e argomenti supportati.
$ curl -X OTTIENI http: // wordpress-server / wp-json
La richiesta sopra riportata restituirà un oggetto risposta contenente una proprietà route come segue:
Questa funzione è immensamente potente in quanto elenca tutti i percorsi e i loro metodi e argomenti supportati, eliminando così la necessità che tutti questi siano documentati esternamente. Faremo riferimento a questo oggetto risposta quando si eseguono operazioni CRUD su risorse diverse.
Dopo aver esaminato le nostre opzioni per esplorare l'API, iniziamo ora a lavorare con l'API REST di WP per recuperare i dati dal server.
Ormai, ci siamo familiarizzati con il OPZIONI richiesta, che è un modo auto-documentante per valutare la disponibilità dell'API. Abbiamo anche esaminato come mostra metodi e argomenti supportati per un determinato percorso. Utilizzando questa conoscenza, siamo ora pronti a recuperare risorse diverse dal server usando l'API REST di WP.
La risorsa con cui inizieremo è la Messaggi risorsa, poiché è il componente principale di WordPress. Ci occuperemo del recupero dei messaggi utilizzando diversi filtri. Applicando questa conoscenza, sarai in grado di interrogare i post usando l'API WP REST proprio come fai con la classe WP_Query ().
In questa serie, abbiamo lavorato con Messaggi risorsa per dimostrare le richieste di esempio e le loro risposte, e sappiamo già come recuperare la raccolta post e un singolo post dal suo ID. Quindi non lo ricopriremo di nuovo. Invece, vedremo alcuni modi più avanzati per recuperare i messaggi utilizzando i parametri di primo livello e il filtro[] sintassi.
L'API WP REST espone alcune delle variabili di query più utilizzate per i post direttamente su OTTENERE endpoint. Questi parametri sono:
contesto: L'ambito della richiesta. I valori possibili potrebbero essere vista, incorporare o modificare.pagina: La pagina corrente della raccolta post.per pagina: Numero totale di post per pagina.ricerca: La query di ricerca. Limita i risultati alla stringa corrispondente.autore: L'ID dell'autore. Utilizzato per limitare i risultati appartenenti a un autore specifico.escludere: Una serie di ID post da escludere dai risultati di ricerca.includere: Limita i risultati agli ID post specificati in questo array.compensare: Offset i risultati della ricerca per numero specificato.ordine: L'ordine della raccolta. Può essere o asc o disc.ordinato da: Ordinamento attributo della raccolta. I valori possibili possono essere id, titolo o lumaca.lumaca: Limita i risultati a un post che ha uno slug specifico.stato: Utilizzato per limitare la raccolta dei post con uno stato particolare.Il contesto parametro viene utilizzato per recuperare i messaggi a seconda dell'ambito in cui stiamo lavorando. Se stiamo solo elencando i post in qualche pagina indice, allora siamo a posto vista contesto. Ma se stiamo recuperando i post per poterli modificare, allora dobbiamo usare il modificare contesto:
$ GET / wp / v2 / posts? Context = edit
Il modificare il parametro context introduce un ulteriore crudo campo in campi come titolo, soddisfare, estratto, ecc. Il valore di questo crudo campo può essere echeggiato nell'editor per la modifica del contenuto.
Usando il modificare contesto richiede di essere autenticato come utente con edit_posts privilegi.
utilizzando incorporare come il valore del contesto parametro recupera la raccolta dei post con un sottoinsieme minimo delle loro proprietà.
Gli altri parametri sopra menzionati sono abbastanza intuitivi e puoi giocarci con loro nel tuo client HTTP.
Questi erano i parametri di base che ti consentono di interrogare i post in base a determinati criteri. Per limitare le nostre capacità di interrogazione, l'API WP REST fornisce il filtro[] sintassi che supporta un sottoinsieme di WP_Query () args.
filtro[] SintassiOltre a recuperare una raccolta di post utilizzando alcuni parametri basilari di primo livello, l'API WP REST espone alcuni dei WP_Query () variabili usando il filtro[] sintassi. Usando questa sintassi, possiamo interrogare i post nello stesso modo in cui lo facciamo quando lavoriamo con WP_Query () classe.
I parametri di impaginazione sono il più importante di tutti i filtri, in quanto sono ampiamente utilizzati nelle pagine di post-elenco. I parametri di impaginazione ci consentono di mostrare un numero specifico di post per pagina e di navigare verso un numero specifico di pagine contenenti post.
Per impostazione predefinita, a OTTENERE richiesta recupera una raccolta di 10 post per pagina. Vediamo come possiamo inviare un OTTENERE richiesta di recuperare solo cinque messaggi per pagina:
$ GET / wp / v2 / posts? Filter [posts_per_page] = 5
La richiesta di cui sopra utilizza il posts_per_page variabile con cui potresti avere familiarità se hai lavorato con WP_Query ().
Il paging parametro è usato insieme al posts_per_page parametro, ed è usato per navigare verso un numero specifico di pagine. Dopo aver recuperato cinque post per pagina, faremo la seguente richiesta per navigare verso la seconda pagina:
$ GET / wp / v2 / posts? Filter [posts_per_page] = 5 e filter [paged] = 2
Il posts_per_page e paging i filtri possono essere estremamente utili quando si lavora per creare l'impaginazione nelle pagine dell'elenco utilizzando l'API WP REST. Questi due parametri sono equivalenti al per pagina e pagina parametri di primo livello. Quindi, la seguente richiesta esegue lo stesso lavoro di quello precedente:
$ GET / wp / v2 / posts? Per_page = 5 & page = 2
Oltre alla raccolta di post restituiti dalla richiesta precedente, il server restituisce anche un numero di intestazioni con una risposta che contiene informazioni utili, tra cui il numero totale di post e il numero di pagine. Questi valori sono contenuti nel X-WP-TotalPages e X-WP-Total intestazioni di risposta.
Il X-WP-TotalPages e X-WP-Total le intestazioni di risposta sono estremamente utili quando si crea l'impaginazione usando l'API WP REST mentre elencano rispettivamente il numero totale di pagine e il numero totale di post.
Oltre ai filtri di impaginazione, l'altro uso più importante del filtro[] la sintassi deve essere in grado di interrogare i post in base alle loro date. A questo scopo, il filtro[] la sintassi supporta otto parametri, uguali a quelli di WP_Query () classe:
anno: L'anno a quattro cifre (ad esempio 2015 o 2016)monthnum: Il numero del mese da 1 a 12m: Sei cifre anno-mese (ad esempio, 201601)w: La settimana dell'anno da 0 a 53giorno: Il giorno del mese dall'1 al 31ora: L'ora del giorno da 0 a 23minuto: Il minuto dell'ora da 0 a 60secondo: Il secondo del minuto da 0 a 60Quindi, se stiamo cercando i post pubblicati nella data 2015-10-15 (aaaa / mm / gg), questo può essere ottenuto con la seguente query:
$ GET / wp / v2 / posts? Filter [anno] = 2015 e filtro [monthnum] = 10 e filtro [giorno] = 15
Una query simile può essere preparata con l'aiuto dei parametri di cui sopra se abbiamo bisogno di restringere la nostra ricerca all'esatta ora e minuto.
Abbiamo già visto in una precedente sezione di questo tutorial come possiamo recuperare i post appartenenti a una specifica categoria o più categorie usando il filtrare [gatto] e filtrata [category__and] parametri. Ora useremo il filtrata [category__in] parametro per mostrare i post appartenenti alle categorie che hanno un id di 5 e 6:
$ GET / wp / v2 / posts? Filter [category__in] [] = 5 e filter [category__in] [] = 6
La richiesta di cui sopra recupererà un elenco di tutti i post appartenenti a categorie aventi un id di 5 e 6.
L'effetto opposto potrebbe essere ottenuto usando il filtrata [category__not_in] parametro nel modo seguente:
$ GET / wp / v2 / posts? Filter [category__not_in] [] = 5 e filtro [category__not_in] [] = 6
Ciò recupererà un elenco di post escludendo tutti i post appartenenti a categorie con ID 5 o 6.
Più potrebbe essere scritto sull'uso del filtro[] sintassi, ma non coprirò tutto questo qui. È possibile trovare un elenco di tutte le variabili di query supportate da filtro[] sintassi nella documentazione ufficiale della versione 1 del plugin. Gran parte di queste informazioni è ancora valida con la versione 2 dell'API REST di WP, ma in alcune aree manca ancora. Al momento della stesura di questo tutorial, la documentazione ufficiale della versione 2 non riporta nulla a riguardo filtro[] la sintassi e la query vars che supporta, ma possiamo sperare di vedere miglioramenti nella documentazione ufficiale nel prossimo futuro poiché ci sono un certo numero di persone (incluso me stesso) che contribuiscono allo sviluppo e alla documentazione dei plugin.
Ora che abbiamo esaminato diverse opzioni durante l'interrogazione dei post con l'aiuto dell'API REST di WP, siamo pronti ad avanzare ulteriormente nel nostro viaggio e a guardare alcune altre risorse supportate dall'API REST di WP.
Le revisioni delle pubblicazioni forniscono un modo per visualizzare e ripristinare le modifiche apportate a un post. L'API REST di WP offre un modo per visualizzare tutte le revisioni di un post eseguendo una query su / post / endpoint. Quindi per un dato post avente un ID di 10, tutte le revisioni possono essere recuperate inviando la seguente richiesta:
$ GET / wp / v2 / posts / 10 / revisioni
La richiesta sopra riportata restituirà un array contenente oggetti di revisione. L'oggetto revisioni contiene un sottoinsieme di proprietà trovato nell'oggetto post. Di seguito è riportato un esempio di oggetto di revisione in Postman:
Una revisione specifica può essere recuperata dato che conosciamo il suo id. Quindi una revisione avente un ID di 2 con post con un ID di 10 può essere recuperata dal seguente oggetto:
$ GET / wp / v2 / posts / 10 / revisioni / 2
La richiesta di cui sopra restituirà un singolo oggetto di revisione.
Oltre alle revisioni post, le categorie per un post specifico possono essere recuperate dalla seguente richiesta:
$ GET / wp / v2 / categories? Post =
E per i tag, usiamo la seguente richiesta:
$ GET / wp / v2 / tags? Post =
Con
Se abbiamo bisogno di recuperare post meta per post con un ID di 10, inviamo la seguente richiesta come utente autenticato:
$ GET / wp / v2 / posts / 10 / meta
Ciò restituirà una serie di meta oggetti.
Si noti che per lavorare con meta post e pagina nell'API REST di WP, è necessario che il plug-in associato sia disponibile su GitHub dal team dell'API REST di WP..
A questo punto, abbiamo acquisito una solida base per lavorare con l'API REST di WP per recuperare i dati. Abbiamo già esaminato la richiesta di opzioni e il modo in cui ci aiuta a esplorare l'API senza la necessità di documentazione esterna.
Puoi sempre inviare un OPZIONI richiedere una risorsa specifica e verificare quali endpoint e parametri supportano. Se è necessario elencare tutti i percorsi forniti dall'API WP REST, è possibile inviare un messaggio OTTENERE richiesta al punto finale dell'indice a / Wp-JSON come abbiamo imparato a fare all'inizio di questo tutorial.
Considerando questo vantaggio dell'autodocumentazione, non penso che abbiamo bisogno di esplorare ogni singola risorsa in questo tutorial, dato che ora sei in grado di farlo da solo.
In questo lungo tutorial, abbiamo imparato ad esplorare l'API utilizzando la richiesta OPTIONS oltre a recuperare i dati dal server utilizzando l'API WP REST. Abbiamo appena esaminato una manciata di risorse tra cui post, post revisione e post meta, poiché non siamo riusciti a coprire tutte le risorse supportate in un solo tutorial. Ma ora dovresti essere in grado di esplorare l'API da solo utilizzando le tecniche che abbiamo imparato in questo tutorial.
WordPress ha un'economia incredibilmente attiva. Ci sono temi, plugin, librerie e molti altri prodotti che ti aiutano a costruire il tuo sito e progetto. La natura open source della piattaforma lo rende anche un'ottima opzione da cui puoi migliorare le tue capacità di programmazione. In ogni caso, puoi vedere tutto ciò che abbiamo a disposizione nel Marketplace Envato.
Nella prossima puntata di questa serie, impareremo a eseguire le altre tre operazioni di CRUD, ovvero creare, aggiornare ed eliminare risorse. Quindi rimani sintonizzato ...
