Creando una consulta persistida
Una consulta persistida es una combinación de APIs GraphQL y REST: es una consulta GraphQL normal, publicada en el sitio y accedida bajo su propia URL, similar a un endpoint REST.
Por ejemplo, podemos exponer datos para una web mediante las siguientes consultas persistidas:
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contenty ejecutarla pasando el ID de la entrada:?post=1/graphql-query/post-content/espara traducir el contenido de la entrada al español- Otras
Ejecutando la consulta persistida
Una vez publicada la consulta persistida, podemos ejecutarla mediante su permalink.
La consulta persistida puede ejecutarse directamente en el navegador, ya que se accede vía GET, y obtendremos los datos solicitados, en formato JSON:
Ejecutando la consulta persistida en una aplicación
Por favor, sigue las instrucciones en la guía Conectando con el servidor GraphQL desde un cliente.
Accediendo a todas las consultas persistidas
Al hacer clic en "Persisted Queries" en el menú del plugin, se muestra la lista de todas las consultas persistidas creadas:
Creando una nueva consulta persistida
Haz clic en el botón "Add New GraphQL persisted query" para abrir el editor de WordPress:
Asígnale un título y asegúrate de que el permalink es el esperado, introduce la consulta GraphQL, selecciona la configuración del esquema y ajusta las opciones. Cuando esté lista, haz clic en el botón Publicar, y el permalink se convierte en el endpoint de la consulta persistida.
El enlace al endpoint (y al código fuente) se muestra en el panel lateral "Persisted Query Endpoint Overview":
Por defecto, el endpoint de la consulta persistida tiene la ruta /graphql-query/, y este valor es configurable a través de los Ajustes:
Editor de consultas
El cliente GraphiQL en el editor es donde se introduce la consulta GraphQL persistida:
El editor viene con el add-on Explorer, que permite componer la consulta haciendo clic en los campos en el panel del lado izquierdo. Al hacer clic en el botón "Run" se ejecuta la consulta, para previsualizar la respuesta:
Configuración del esquema
Definir quién puede acceder a los campos solicitados en la consulta persistida se define en la configuración del esquema.
Por tanto, debemos crear una configuración del esquema, y luego seleccionarla desde el desplegable (o no usar ninguna, o usar la predeterminada):
Consultas persistidas privadas
Estableciendo el estado de la Consulta Persistida como privada, solo el usuario administrador puede acceder al endpoint. Esto evita que nuestros datos se compartan involuntariamente con usuarios que no deberían tener acceso a ellos.
Por ejemplo, podemos crear Consultas Persistidas privadas que ayuden a gestionar la aplicación, como recuperar datos para crear informes con nuestras métricas.
Consultas persistidas protegidas por contraseña
Si creamos una Consulta Persistida para un cliente específico, podemos asignarle una contraseña, para proporcionar un nivel adicional de seguridad de modo que solo ese cliente acceda al endpoint.
Al acceder por primera vez a una consulta persistida protegida por contraseña, nos encontramos con una pantalla que solicita la contraseña:
Una vez que se proporciona y valida la contraseña, solo entonces el usuario accederá al endpoint deseado.
Haciendo la consulta persistida dinámica vía parámetros de URL
El valor de cada variable puede establecerse mediante un parámetro de URL (con el nombre de la variable) al ejecutar la consulta persistida. Si la opción "Do URL params override variables?" está habilitada, entonces el parámetro de URL tendrá prioridad. De lo contrario, el valor definido en el diccionario de variables tendrá prioridad (si existe).
Por ejemplo, en esta consulta, el número de resultados se controla mediante la variable $limit, con un valor por defecto de 3:
Al ejecutar esta consulta persistida, pasando ?limit=5 se ejecutará la consulta devolviendo 5 resultados en su lugar:
Creando una jerarquía de consultas persistidas
Por favor, lee las instrucciones sobre crear una jerarquía de API.
Deshabilitando la consulta persistida
En las opciones, establece "Enabled" en false para deshabilitar la consulta persistida.
Esta característica puede ser útil cuando se hace que la consulta persistida forme parte de una jerarquía de API, para proporcionar un comportamiento común a sus consultas persistidas hijas, pero sin necesidad de que ella misma se ejecute.
Describiendo la consulta persistida
Usa el campo "Extracto", del panel de ajustes del documento, para dar una descripción a la consulta persistida.
Encuentra más información en la guía Añadiendo una descripción a la API.
Probando la consulta persistida antes de publicarla en línea
Una consulta persistida con estado borrador o pendiente está disponible solo para los usuarios editores del esquema.
Entonces, podemos crear una consulta persistida, asignarle una Configuración del Esquema, publicarla como borrador o pendiente, y probarla (por ejemplo: comprobando que sus reglas de Control de Acceso son apropiadas).
Una vez aprobada, solo entonces establecemos su estado como publicada, haciendo la consulta persistida disponible para todo el mundo.
Viendo el código fuente
Añadiendo ?view=source al endpoint, mostrará la configuración de la consulta persistida (siempre que el usuario esté autenticado y el rol de usuario tenga acceso a ella):
Configuración en el editor de WordPress
Estas son las entradas en el cuerpo del editor:
| Entrada | Descripción |
|---|---|
| Título | Título de la consulta persistida |
| Cliente GraphiQL | Editor para escribir y ejecutar la consulta GraphQL:
GraphiQL Explorer está habilitado) permite hacer clic en los campos, y estos se añaden automáticamente a la consulta |
| Configuración del esquema | Desde el desplegable, selecciona la configuración del esquema que se aplica a la consulta persistida, o una de estas opciones:
|
| Opciones | Personaliza el comportamiento de la consulta persistida:
|
Estas son las entradas en los ajustes del documento:
| Entrada | Descripción |
|---|---|
| Permalink | El endpoint bajo el cual estará disponible la consulta persistida |
| Categorías | Permite categorizar la consulta persistida. Ej.: mobile, app, etc |
| Extracto | Proporciona una descripción para la consulta persistida. Esta entrada está disponible cuando el módulo Excerpt as Description está habilitado |
| Atributos de página | Selecciona una consulta persistida padre. Esta entrada está disponible cuando el módulo API Hierarchy está habilitado |