Creare una query persistente
Una query persistente è una combinazione delle API GraphQL e REST: è una normale query GraphQL, pubblicata sul sito e accessibile tramite il proprio URL, simile a un endpoint REST.
Ad esempio, possiamo esporre dati per un sito web tramite le seguenti queries persistenti:
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contented eseguirla passando l'ID dell'articolo:?post=1/graphql-query/post-content/esper tradurre il contenuto dell'articolo in spagnolo- Altre
Eseguire la query persistente
Una volta pubblicata la query persistente, possiamo eseguirla tramite il suo permalink.
La query persistente può essere eseguita direttamente nel browser, poiché è accessibile via GET, e otterremo i dati richiesti in formato JSON:
Eseguire la query persistente in un'applicazione
Seguire le istruzioni della guida Connettersi al server GraphQL da un client.
Accedere a tutte le queries persistenti
Facendo clic su "Persisted Queries" nel menu del plugin, viene visualizzato l'elenco di tutte le queries persistenti create:
Creare una nuova query persistente
Fare clic sul pulsante "Add New GraphQL persisted query" per aprire l'editor WordPress:
Assegnare un titolo e verificare che il permalink sia quello previsto, inserire la query GraphQL, selezionare la configurazione dello schema e regolare le opzioni. Quando si è pronti, fare clic sul pulsante Pubblica, e il permalink diventa l'endpoint della query persistente.
Il link all'endpoint (e alla sorgente) è mostrato nel pannello laterale "Persisted Query Endpoint Overview":
Per impostazione predefinita, l'endpoint della query persistente ha il percorso /graphql-query/, e questo valore è configurabile tramite le Impostazioni:
Editor di queries
Il client GraphiQL nell'editor è il punto in cui inserire la query GraphQL persistente:
L'editor è dotato del componente aggiuntivo Explorer, che consente di comporre la query facendo clic sui campi nel pannello laterale sinistro. Facendo clic sul pulsante "Run" si esegue la query per visualizzare in anteprima la risposta:
Configurazione dello schema
La definizione di chi può accedere ai campi richiesti nella query persistente è definita nella configurazione dello schema.
Dobbiamo quindi creare una configurazione dello schema, e poi selezionarla dal menu a discesa (oppure non usarne nessuna, o usare quella predefinita):
Queries persistenti private
Impostando lo stato della query persistente come privato, l'endpoint è accessibile solo dall'utente amministratore. Questo evita che i nostri dati vengano condivisi involontariamente con utenti che non dovrebbero avervi accesso.
Ad esempio, possiamo creare queries persistenti private che aiutano a gestire l'applicazione, come il recupero di dati per creare report con le nostre metriche.
Queries persistenti protette da password
Se creiamo una query persistente per un cliente specifico, possiamo assegnarle una password, per fornire un livello aggiuntivo di sicurezza che garantisca l'accesso all'endpoint solo a quel cliente.
Quando si accede per la prima volta a una query persistente protetta da password, si incontra una schermata che richiede la password:
Una volta fornita e validata la password, l'utente accede all'endpoint desiderato.
Rendere la query persistente dinamica tramite parametri URL
Il valore di ogni variabile può essere impostato tramite un parametro URL (con il nome della variabile) durante l'esecuzione della query persistente. Se l'opzione "Do URL params override variables?" è abilitata, il parametro URL avrà la priorità. Altrimenti, il valore definito nel dizionario delle variabili avrà la priorità (se presente).
Ad esempio, in questa query, il numero di risultati è controllato tramite la variabile $limit, con un valore predefinito di 3:
Durante l'esecuzione di questa query persistente, passare ?limit=5 eseguirà la query restituendo 5 risultati invece:
Creare una gerarchia di queries persistenti
Leggere le istruzioni su come creare una gerarchia di API.
Disabilitare la query persistente
Nelle opzioni, impostare "Enabled" su false per disabilitare la query persistente.
Questa funzionalità può essere utile quando la query persistente fa parte di una gerarchia di API, per fornire un comportamento comune alle sue queries persistenti figlie, senza che essa stessa debba essere eseguita.
Descrivere la query persistente
Utilizzare il campo "Estratto", nel pannello delle impostazioni del documento, per assegnare una descrizione alla query persistente.
Trovare ulteriori informazioni nella guida Aggiungere una descrizione all'API.
Testare la query persistente prima della pubblicazione online
Una query persistente con stato bozza o in attesa è disponibile solo per gli utenti editor dello schema.
Possiamo quindi creare una query persistente, assegnarle una configurazione dello schema, pubblicarla come bozza o in attesa, e testarla (ad esempio: verificare che le sue regole di controllo degli accessi siano appropriate).
Una volta approvata, impostiamo il suo stato come pubblicata, rendendo la query persistente disponibile per tutti.
Visualizzare la sorgente
Aggiungendo ?view=source all'endpoint, verrà mostrata la configurazione della query persistente (a condizione che l'utente sia autenticato e che il suo ruolo vi abbia accesso):
Configurazione nell'editor WordPress
Di seguito sono riportati i campi nel corpo dell'editor:
| Campo | Descrizione |
|---|---|
| Titolo | Titolo della query persistente |
| Client GraphiQL | Editor per scrivere ed eseguire la query GraphQL:
GraphiQL Explorer è abilitato) consente di fare clic sui campi, che vengono automaticamente aggiunti alla query |
| Configurazione dello schema | Dal menu a discesa, selezionare la configurazione dello schema applicabile alla query persistente, o una di queste opzioni:
|
| Opzioni | Personalizzare il comportamento della query persistente:
|
Di seguito sono riportati i campi nelle impostazioni del documento:
| Campo | Descrizione |
|---|---|
| Permalink | L'endpoint sotto il quale la query persistente sarà disponibile |
| Categorie | Consente di categorizzare la query persistente. Es.: mobile, app, ecc. |
| Estratto | Fornisce una descrizione per la query persistente. Questo campo è disponibile quando il modulo Excerpt as Description è abilitato |
| Attributi di pagina | Selezionare una query persistente padre. Questo campo è disponibile quando il modulo API Hierarchy è abilitato |