Unlimited WordPress themes, graphics, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress
Code

API REST di WP: Recupero dei dati

by
Difficulty:BeginnerLength:LongLanguages:
This post is part of a series called Introducing the WP REST API.
WP REST API: Setting Up and Using OAuth 1.0a Authentication
WP REST API: Creating, Updating, and Deleting Data

Italian (Italiano) translation by Piergiorgio Sansone (you can also view the original English article)

Nelle parti precedenti della serie, abbiamo potuto vedere che cosa sono le API REST di WP e come ci possono  aiutare a costruire applicazioni migliori utilizzando il back-end di WordPress.

Poi abbiamo visto due modi per impostare l'autenticazione sul server per la generazione le richieste autenticate. Il primo è il metodo di autenticazione base, utile negli ambienti di sviluppo e permette una semplice prototipazione non richidendo molto tempo per l'impostazione. Il secodo metodo di autenticazione è OAuth 1.0a, il quale è raccomandato per gli ambienti di produzione essemdo molto più sicuro del metodo di autenticazione di base.

Adesso che abbiamo imparato come impostare l'autenticazione, siamo pronti a generare richieste di autenticazione per scatenare tutta la potenza delle API REST di WP. Per tutta questa serie, grazie alla sua facilità d'uso, utilizzeremo l'autenticazione di base, ma  per i server di produzione è consigliabile utilizzare l'autenticazione OAuth 1.0 a, come fornito dal plugin OAuth 1.0 a.

Nella parte corrente della serie, ci metteremo la nostra primissima esperienza hands-on con il plugin WP API REST. Ci impegneremo a:

  • analizzare la struttura di una richiesta GET
  • scoprire come la richiesta di OPTIONS auto-documenti l'API
  • inviare le richieste al server per recuperare i dati
  • analizzare la risposta del server che include proprietà, schema e collegamenti

Cominciamo analizzando la struttura di una semplice richiesta GET.

Anatomia di una richiesta GET

Prima di approfondire i dettagli del recupero di tutti i dati con l'API REST di WP, abbiamo bisogno di familiarizzare con la sintassi di una richiesta che viene inviata al server. Questo porrà una solida base per il nostro future interazioni con l'API REST di WP.

Si consideri la seguente richiesta inviata al server:

Il tipo di richiesta che stiamo inviando è GET — uno dei sei verbi HTTP che abbiamo guardato nella parte iniziale di questa serie. Una richiesta GET viene utilizzata per recuperare i dati dal server. Quindi, quando viene eseguita sul server, la richiesta di cui sopra recupera una raccolta di tutti gli oggetti post sotto forma di dati JSON.

Considerando l'URI della richiesta, possiamo scomporla nelle seguenti parti:

  • http://localserver/: l'URL del mio server di sviluppo locale. Potrebbe essere qualsiasi URL a seconda di dove si trova la vostra installazione di WordPress.
  • /wp-json: è il prefisso dell'endpoint dell'API REST di WP.
  • /wp: lo spazio dei nomi del plugin WP API REST.
  • /v2: è la versione del plugin WP API REST.
  • /posts: è la risorsa che si desidera recuperare dal server.

Lo spazio dei nomi impedisce di eseguire l'override che potrebbero verificarsi quando si eseguono più plugin fornendo ad ogniuno un livello di astrazione per l'API RESTful. Quindi, ogni astrazione funziona in un proprio limite senza intaccare i metodi e le proprietà che appartengono a qualche altra astrazione.

Spazio dei nomi e versione non erano presenti nella precedente versione 1.2 del plugin. Così nella versione precedente, la richiesta di cui sopra sarebbe stata come questa:

Ma non parliamo di compatibilità qui. Se volete conoscere tutte le modifiche che si sono verificate tra la versione 1.x e 2.x, potete trovarli sulla pagina ufficiale.

Oltre a recuperare un insieme di risorse (post) utilizzando l'URI di cui sopra, possiamo anche recuperare una risorsa specifica menzionando l'ID:

La richiesta di cui sopra restituirà un oggetto post come indicato di seguito per una risorsa post che ha un ID pari a 100.

Altre volte, abbiamo anche bisogno di cercare tutti i messaggi che soddisfano alcuni criteri specifici. A tale scopo, l'API REST di WP fornisce un modo utilizzando la sintassi filter[]:

Inviando la richiesta di cui sopra, possiamo recuperare tutti i messaggi appartenenti a una categoria di ID 1. La sintassi filtro può essere particolarmente utile durante l'esecuzione di query di inserimento o navigare tra diverse risorse, ad esempio post e categorie, usando le loro relazioni.

Infine, quando si tratta di argomenti che accettano matrici come input nella sintassi filter[], noi possiamo aggiungere un insieme vuoto di parentesi quadre per esprimere le matrici in questo modo:

La sintassi precedente è equivalente alla seguente WP_Query()

Quindi, la richiesta GET sopra recupererà un elenco di tutti i messaggi che appartengono a entrambe le categorie che hanno un ID 1 e 2. La stessa sintassi potrà essere utilizzata anche per argomenti di matrice, avendo più di due elementi. Siete pregati di notare che l'uso del parametro category__and richiede l'autenticazione dell'utente con privilegi di edit_posts.

Esamineremo la sintassi filter[] più dettagliatamente in una sezione successiva.

Ora che abbiamo imparato la formattazione di una richiesta GET fornendo i relativi parametri, è il momento di dare un'occhiata a richiesta OPTIONS. Una richiesta OPTIONS rende facile da navigarzione attraverso l'API e serve in realtà come un modo autodocumentazione per rendere più accessibile l'API documentando tutti i metodi HTTP disponibili su un endpoint, e a sua volta, gli argomenti che la supportano.

Navigazione attraverso l'API utilizzando la richiesta di OPTIONS

Come accennato prima, la richiesta di OPTIONS può essere estremamente utile per esplorare l'API. Esso menziona tutti gli endpoint che appartengono a un determinato percorso e fornisce un elenco di parametri che questi endpoint supportano per le operazioni CRUD.

Mandiamo una richiesta OPTIONS sul percorso /wp/v2/posts per verificare quali endpoint supporta e quali parametri sono richiesti per interrogare i dati e possiamo passare con il GET :

Ho usato un cURL per inviare la richiesta di cui sopra, ma è possibile utilizzare qualsiasi strumento di vostra scelta, tra cui il Postman. Assicurarti di includere il percorso completo all'itinerario sopra, incluso il percorso del server.

La richiesta OPTIONS sopra citata verso il percorso /wp/v2/posts restituisce i dati nel formato JSON che contiene cinque proprietà :

  1. namespace
  2. methods
  3. endpoints
  4. schema
  5. _links

la proprietà namespace identifica il nome del plugin corrente nel nostro caso è wp/v2, che significa la versione 2 del REST API di WP. Nella sezione precedente abbiamo già esaminato il namespace e lo suo scopo.

la proprietà methods contiene la matrice di tutti i metodi supportati dal percorso corrente Esaminando la risposta restituita alla richiesta di cui sopra, è chiaro che il percorso di /wp/v2/posts supporta due metodi, vale a dire GET e POST. Vuol dire che possiamo usare il percorso di /wp/v2/posts per recuperare tutti i messaggi, come pure la creazione di un nuovo post. Ci occuperemo con il metodo POST nella parte successiva di questa serie, così facciamo solo focus il metodo GET per il momento.

La proprietà successiva — endpoints — contiene una matrice di endpoint supportati per il percorso corrente. Questa proprietà è direttamente collegata alla proprietà methods menzionati in precedenza in quanto elenca gli endpoint per i metodi supportati.

La proprietà endpoints contiene valori oggetto che a loro volta contengono due proprietà, vale a dire methods e args. La proprietà methods contiene una matrice di metodi HTTP, e la successiva proprietà args 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 metodo GET, ci imbattiamo in nove argomenti che includono il context, page, per_page, ecc. Questi oggetti di argomento contengono due proprietà, required e default. La proprietà required indica che l'argomento è obbligatorio, e la proprietà default rappresenta il valore predefinito dell'argomento.

La proprietà dello schema nella risposta restituita documenta tutte le proprietà per la risorsa corrente. Lo schema definisce una struttura per i dati in formato JSON. Il formato dello schema utilizzato nell'API REST WP è basato sulla bozza 4 delle specifiche dello schema JSON.

L'ultima proprietà _links contiene una matrice di oggetti contenente i collegamenti di risorse associate. La chiave nell'oggetto specifica il tipo di relazione (es. autore, raccolta, auto, commenti, ecc.), con il relativo valore essendo il link alla risorsa associata. Questo collegamento standard si basa su HAL (Hypertext Application Language). Troverete più su HAL leggendo le specifiche scritte da Mike Kelley.

In modo simile, possiamo inviare una richiesta di OPTIONS ad altri itinerari, compresi quelli degli utenti, commenti, media, pagine, ecc., per controllare i loro metodi supportati e argomenti. Quando si lavora con l'API REST di WP, le richieste OPTIONS sono il tuo migliore amico.

L'API REST di WP fornisce un altro modo per valutare la disponibilità di API inviando una richiesta GET per il percorso di indice /wp-json. Questo elencherà tutti i percorsi e i relativi endpoint assieme ai loro metodi supportati e argomenti.

La richiesta di cui sopra restituirà un oggetto response contenente una proprietà routes come segue:


Questa caratteristica è immensamente potente quanto elenca tutti i percorsi e i loro metodi ed argomenti supportati, eliminando così la necessità di documentarli esternamente. Ci si riferirà a questo oggetto di risposta quando si eseguono operazioni CRUD su risorse diverse.

Dopo aver guardato alle nostre opzioni per esplorare l'API, ora iniziamo  a lavorare con l'API REST di WP per recuperare i dati dal server.

Lavorando con i posts

Ormai, avendo familiarizzato con la richiesta di OPTIONS, che è un modo di autodocumentazione per valutare la disponibilità dell' API. Abbiamo anche visto come si presentano i metodi e gli argomenti supportati per un determinato percorso. Usando questa conoscenza, siamo a recuperare risorse diverse dal server utilizzando l'API REST di WP.

La risorsa con cui inizieremo è la risorsa Post, dal momento che costituisce il blocco  principale di WordPress. Ci occuperemo del recupero dei posts usando diversi filtri. Applicando questa conoscenza, sarete in grado di interrogare i messaggi utilizzando l'API REST di WP, come fareste con la classe WP_Query().

Per tutta questa serie, abbiamo lavorato con la risorsa di post per dimostrare le richieste di esempio e le loro risposte, e sappiamo già come recuperare la lista dei posts e un singolo post dal relativo ID. Così ancora una volta non lo tratteremo. Invece, vedremo alcuni modi più avanzati per recuperare i messaggi utilizzando i parametri di primo livello e la sintassi di filter [].

Lavorare con i parametri di primo livello

L'API REST di WP espone alcune delle variabili di query più comunemente utilizzate per i post direttamente sull'endpoint GET. Questi parametri sono:

  1. context: l'ambito della richiesta. I valori possibili potrebbero essere view, embed o edit.
  2. page: la pagina corrente del post raccolta (collection).
  3. per_page: numero totale di messaggi per pagina.
  4. search: la query di ricerca. Limitare i risultati per la stringa corrispondente.
  5. author: ID dell'autore. Utilizzato per limitare i risultati appartenendo a un autore specifico.
  6. exclude: matrice di post ID per escludereli dai risultati di ricerca.
  7. include: limitare i risultati degli ID dei posts specificati in questa matrice.
  8. offset: risultati della ricerca dal numero specificato di Offset.
  9. order: l'ordine dell'insieme . Può essere asc o desc.
  10. orderby: ordinamento dell'attributo della raccolta. I valori possibili possono essere id, title o slug.
  11. Slug: limitare i risultati a un post avendo uno slug (etichetta) specifica.
  12. status: usato per limitare la raccolta dei post uno statuto particolare.

Il parametro context viene utilizzato per recuperare tutti i messaggi a seconda dell'ambito in cui stiamo lavorando. Se stiamo facendo una lista dei post su una pagina indice, allora è corretto utilizzare il parametro view . Ma se stiamo recuperando i post in ordine per modificarli, dobbiamo utilizzare il parametro edit :

Il parametro di contesto edit introduce un campo aggiuntivo raw nei campi come title, content, excerpt, ecc. Il valore di questo campo raw può essere visualizzato fuori nell'editor per la modifica del contenuto.

Edit context

Per utilizzare il parametro di contesto edit è necessario essere autenticati come utente con privilegi di edit_posts.

Utilizzando embed come il valore del parametro di contesto recuperate la collezione dei post con un sottoinsieme minimo di proprietà.

L'altro parametro che abbiamo citato sopra è abbastanza auto-esplicativo, e può giocherellarci con il tuo client HTTP.

Questi erano i parametri di base che consentono a tutti di interrogare messaggi basati su determinati criteri. Per limitare le nostre capacità di esecuzione della query, l'API REST di WP fornisce la sintassi filter [] che supporta un sottoinsieme degli argomenti del WP_Query().

Utilizzando la sintassi filter[]

Oltre a recuperare una raccolta di post utilizzando alcuni parametri di base di primo livello, l'API REST di WP espone alcune delle variabili WP_Query() utilizzando la sintassi filter[]. Utilizzando questa sintassi, noi possiamo interrogare il post allo stesso modo come facciamo quando si lavora con la classe WP_Query().

I parametri di paginazione sono più importanti di tutti i filtri, dato che sono ampiamente utilizzati sulle pagine post listing. I parametri di impaginazione consentono di mostrare un numero specifico di post per pagina e passare a un numero specifico di pagine che contengono tutti i messaggi.

l'impostazione predefinita di una richiesta GET recupera una raccolta di 10 post per pagina. Vediamo come possiamo presentare una richiesta GET per recuperare solo cinque messaggi per pagina:

La richiesta di cui sopra, utilizza la variabile di posts_per_page  per la quale avreste familiarità, se avete lavorato con WP_Query().

Il parametro paged viene utilizzato in combinazione con il parametro di posts_per_page, e utilizzarlo per passare a un numero specifico di pagine. Dopo aver recuperato cinque post per pagina, faremmo la seguente richiesta per passare alla seconda pagina:

I filtri posts_per_page e paged possono essere estremamente utili quando si lavora per costruire l'impaginazione in inserzione pagine utilizzando l'API REST di WP. Questi due parametri sono equivalenti ai parametri per_page e page di primo livello. Quindi, la seguente richiesta fa lo stesso lavoro come quella di sopra:

Oltre alla raccolta di post restituisce la richiesta di cui sopra, il server restituisce anche un numero di intestazioni con una risposta che contiene informazioni utili, tra cui il numero totale di posti e il numero di pagine. Questi valori sono contenuti nelle intestazioni di risposta  X-WP-TotalPages,X-WP-total.

Response headers

 Le intestazioni di risposta X-WP-TotalPages, X-WP-totalsono estremamente utili quando si crea l'impaginazione utilizzando l'API REST di WP quando elencano rispettivamente il numero totale di pagine e il numero totale di posti .

Oltre a filtri di paginazione, altri usi più importanti della sintassi filter[] deve essere in grado di interrogare i messaggi per data. A questo scopo, la sitassi fileter[] prevede otto parametri come per la clesse WP_Query():

  1. year:I quettro caratteri dell'anno (e.s 2015 o 2016)
  2. monthnum: Il numero dei mesi 1 o 12
  3. m: Sei caratteri anno-mese (es. 201601)
  4. w: Le settimane dell'anno da 0 a 52 (53 per 2015)
  5. day: Il giorno del mese dal 1 al 31
  6. hour : Le ore del giorno dalle 0 alle 23
  7. minute: Il minuto dell'ora da 0 a 60
  8. second:Il secondo del minuto da 0 a 60

Così se stiamo cercando il post pubblicato alla data 2015-10-15 (aaaa/mm/gg), questo può essere archiviato dalla seguente query:

Una query simile può essere preparata con l'aiuto dei suddetti parametri, se abbiamo bisogno di limitare la nostra ricerca per l'esatta ora e i minuti.

Abbiamo già visto in una sezione precedente di questo tutorial come abbiamo potuto recuperare i post appartenenti a una categoria specifica o più categorie utilizzando i parametri di filter [category__and] e filter [cat]. Ora usiamo il parametro filter [category__in] per mostrare tutti i messaggi appartenenti a categorie avere un id di 5 e 6:

La richiesta di cui sopra consente di recuperare un elenco di tutti i post appartenenti alle categorie avere un id di 5 e 6.

L'effetto opposto potrebbe essere ottenuta utilizzando il parametro filter [category__not_in] nel modo seguente:

Questo consente di recuperare un elenco di post escludendo tutti quei posti appartenenti alle categorie avere un ID di 5 o 6.

Più potrebbe essere scritto utilizzando la sintassi filter[], ma non che copre tutto ciò che qui. Si può trovare un elenco di tutte le variabili di query supportati dalla sintassi filter[] 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 è ancora carente in alcune zone. Al momento della stesura di questo tutorial, la documentazione ufficiale della versione 2 non dichiara nulla circa la sintassi filter[] e le variabili della query supporte, ma possiamo sperare di vedere miglioramenti nella documentazione ufficiale nel prossimo futuro, dato che ci sono un certo numero di persone (me compreso) che contribuiscono allo sviluppo di plugin e documentazione.

Ora che abbiamo esaminato le diverse opzioni quando si eseguono query post con l'aiuto dell'API REST WP, siamo  pronti a fare un ulteriore passo in avanti nel  nostro cammino e guardare alcune altre risorse supportati dall'API REST di WP.

Lavorare con le revisioni, categorie, tag e Meta

Le revisioni forniscono un modo per visualizzare e ripristinare le modifiche apportate a un post. L'API REST di WP fornisce un modo per visualizzare tutte le revisioni di un post eseguendo l'endpoint  posts/<id>/revisions. Quindi per un determinato post avere un ID di 10, tutte le revisioni possono essere recuperate inviando la seguente richiesta:

La richiesta di cui sopra restituirà una matrice contenente oggetti di revisione. L'oggetto delle revisioni contiene un sottoinsieme di oggetti trovati nell'oggetto del post. Di seguito è riportato un esempio di oggetto di revisione nel Postman:

Post revision

Una revisione specifica può essere recuperata dato che sappiamo che il relativo id. Così una revisione avente un ID di 2 con post un ID di 10 può essere recuperata utilizzando il seguente oggetto:

La richiesta di cui sopra restituirà un oggetto di revisione singola.

Diverso da revisioni post, le categorie per un post specifico possono essere recuperate utilizzando la seguente richiesta:

E per i tag, usiamo la seguente richiesta:

Con <post_id> è l'ID del post.

Se abbiamo bisogno di recuperare post meta per un post che ha ID 10, ci invia la seguente richiesta come utente autenticato:

Questo restituirà una matrice di oggetti di meta.

Siete pregati di notare che per lavorare con post e pagina meta in WP API REST, è necessario avere installato il plugin  messo a disposizione su GitHub dal team API REST di WP.

Lavorare con altre risorse

Ormai, abbiamo acquisito una solida esperienza per lavorare con l'API REST di WP per recuperare i dati. Abbiamo già guardato la richiesta di opzioni e come ci aiuta a esplorare l'API senza la necessità di un documentazione esterna.

Puoi sempre inviare una richiesta di OPTIONS per una particolare risorsa e controllare quali parametri ed endpoint supporta. Se hai bisogno di elencare tutte le rotte che fornisce l'API REST di WP, è possibile inviare una richiesta GET per l'endpoint di indice alle /wp-json come abbiamo imparato a fare all'inizio di questo tutorial.

Considerando questo vantaggio di auto-documentazione, non credo che abbiamo bisogno di esplorare ulteriormente ogni singola risorsa in questo tutorial, come siete ora in grado di farlo da soli.

Qual è il prossimo?

In questa lunga esercitazione, abbiamo imparato ad esplorare l'API utilizzando la richiesta di OPTIONS, nonché di recuperare i dati dal server utilizzando l'API REST di WP. Abbiamo appena guardato una manciata di risorse tra cui post, post revisione e post meta, come non potevamo copriamo tutte le risorse supportate in un tutorial. Ma dovrebbe essere in grado di esplorare l'API sul proprio 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 consentono di costruire il tuo sito e il progetto. La natura open source della piattaforma, inoltre, lo rende una grande opzione da cui si può meglio le vostre abilità di programmazione. In ogni caso, si può vedere ciò che tutti abbiamo a disposizione sul marketplace di Envato.

Nella prossima puntata di questa serie, impareremo a effettuare le altre tre operazioni di CRUD, ovvero creare, aggiornare ed eliminare risorse. Quindi rimanete sintonizzati...

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.