GraphQL

Una solicitud GraphQL contiene una consulta, sus variables y el esquema con el que está escrita. Echolot usa el esquema para completar campos mientras escribes, para señalar errores antes de enviar y para mostrar los tipos junto a la respuesta.

Crea una solicitud GraphQLCopy Anchor Link

Elige Archivo › Nueva solicitud GraphQL, o Nueva solicitud GraphQL en el menú + junto a Solicitudes en la barra lateral. Escribe el endpoint en el campo de dirección: para la tienda de demostración, {{baseURL}}/graphql. El espacio de trabajo Alpenglow trae una preparada: Catalog › Search products.

El editor tiene estas pestañas: Docs, Consulta, Variables, Cabeceras, Parámetros, Autenticación, Variables (las variables propias de la solicitud), Pruebas, Scripts y Ajustes. Las cabeceras, la autenticación, las pruebas y los scripts funcionan como en las solicitudes HTTP.

Consulta y variablesCopy Anchor Link

Escribe la consulta en la pestaña Consulta:

query SearchProducts($text: String!, $first: Int = 10) {
  search(text: $text, first: $first) {
    totalCount
    nodes { sku name price { amount currency } rating stock { warehouse available } }
  }
}

y sus variables como JSON en la pestaña Variables. Las {{variables}} funcionan dentro del JSON:

{
  "text": "{{searchTerm}}"
}

Cuando el documento contiene varias operaciones, escribe la que quieres enviar en Operación, encima de la consulta. Déjalo vacío si el documento tiene una sola operación.

Envía con Enviar o con ⌘R.

Cómo se envía la solicitudCopy Anchor Link

La insignia GQL antes de la dirección es un menú. Bajo Enviar como:

Dos interruptores debajo:

• Consultas persistentes (APQ) envía primero el hash SHA-256 de la consulta, sin la consulta. Cuando el servidor responde que no conoce el hash, Echolot vuelve a enviar con la consulta, para que el servidor pueda guardarla.
• Agrupar todas las operaciones envía juntas todas las operaciones con nombre del documento, como un solo array JSON.

El esquemaCopy Anchor Link

El menú del esquema está a la derecha de la pestaña Consulta. Muestra el archivo de esquema y su número de tipos, como shop.graphql · … types, o Sin esquema.

• Obtener del servidor ejecuta la consulta de introspección contra la dirección de la solicitud y guarda el resultado como un archivo en la carpeta specs/ del espacio de trabajo. Elígelo de nuevo para actualizar el esquema.
• Usar esquema lista los archivos de esquema que ya están en el espacio de trabajo (.graphql, .graphqls y .json), para elegir uno.
• Añadir un archivo de esquema… toma un archivo SDL (.graphql) o un resultado de introspección (.json) de tu Mac.
• Mostrar el explorador del esquema abre el esquema junto a la respuesta.
• Dejar de usar este esquema quita el esquema de la solicitud.

Un archivo de esquema en specs/ puede compartirse entre todas las solicitudes GraphQL contra ese servidor, y subirse al repositorio con el espacio de trabajo. Cuando una descarga sustituye un archivo de esquema y el esquema ha cambiado, El esquema ha cambiado lista los cambios como Incompatibles, Peligrosos y Seguros, como un campo eliminado o un argumento obligatorio nuevo. Los cambios incompatibles son los que hacen fallar a las consultas que usan lo que se eliminó o se cambió. En la línea de comandos, echolot graphql diff compara dos esquemas de la misma manera: consulta echolot graphql.

Cuando el esquema no se puede leer, el menú muestra Problema del esquema, y la barra bajo la consulta dice el motivo.

Autocompletado, problemas e información al pasar el punteroCopy Anchor Link

Con un esquema, el editor de consultas te ayuda mientras escribes:

• El autocompletado ofrece campos, argumentos, campos de entrada, tipos, valores de enumeración, variables, directivas y fragmentos que encajan donde está el cursor, con su documentación. Los obsoletos se marcan.
• Problemas: se subrayan mientras escribes: campos desconocidos, tipos de argumento incorrectos, argumentos obligatorios que faltan y más. La barra bajo la consulta muestra el primero y cuenta los errores y las advertencias; pasa el puntero por ella para leerlos todos.
• Pasa el puntero por un campo o un tipo para ver su firma y su documentación, y si está obsoleto.
• Haz clic en un campo o un tipo con ⌘ pulsada para abrir su tipo en el explorador del esquema.

El explorador del esquema y el constructorCopy Anchor Link

La pestaña Esquema del panel de respuesta muestra el esquema de la solicitud, incluso antes del primer envío. Si la solicitud aún no tiene esquema, elige ahí Obtener del servidor.

Explorar empieza en los Puntos de entrada (Query, Mutation y Subscription). Haz clic en un tipo para ver sus campos, campos de entrada, valores de enumeración, o los tipos que lo implementan o que pertenecen a él, con las obsolescencias marcadas. Atrás vuelve al tipo anterior. Buscar tipos y campos encuentra cualquier cosa del esquema por nombre.

Construir escribe la consulta por ti. Elige consulta, mutation o subscription en Operación y marca campos en el árbol: cada marca añade el campo al texto de la consulta, y desmarcarlo lo quita de nuevo. Lo que escribiste alrededor se queda. El constructor trabaja sobre la operación indicada en Operación, o sobre la primera operación de ese tipo en el documento; si no hay ninguna, añade una.

RespuestasCopy Anchor Link

La respuesta aparece en la pestaña Cuerpo como JSON, como cualquier respuesta. Echolot también lee lo que GraphQL dice junto a los datos:

• N errores de GraphQL en el resumen de la respuesta: el servidor envió un array errors, incluso con HTTP 200. Haz clic para leer cada mensaje y la ruta a la que pertenece.
• Datos parciales: llegaron datos junto con errores, así que algunos campos son null porque fallaron.
• Extensiones: las extensions de la respuesta, como la información de trazas o de coste.

Añade una comprobación Errores de GraphQL igual a 0 en la pestaña Pruebas para que una ejecución falle por ellos. Consulta scripts y pruebas.

Suscripciones y entrega incrementalCopy Anchor Link

Una suscripción sigue enviando resultados hasta que termina:

• Por HTTP (POST o GET), Echolot pide eventos enviados por el servidor cuando la operación es una suscripción.
• Por WebSocket (graphql-transport-ws), Echolot abre el WebSocket, envía la suscripción con las cabeceras y la autenticación de la solicitud, y responde a los pings del servidor.

Una consulta con @defer o @stream llega en partes (multipart/mixed).

En ambos casos, el panel de respuesta incluye una pestaña Eventos: cada evento o parte en orden, numerado, con su tipo (como next o part), su id y sus errores. Para @defer y @stream, Resultado combinado en la parte superior muestra el primer resultado con todas las partes posteriores aplicadas. La pestaña sigue los eventos nuevos mientras el stream está activo, con Escuchando… Detener lo termina. Elige Cancelar (⌘.) para terminarlo. Un stream que ya ha empezado no se corta por el tiempo de espera total de la solicitud.

Subida de archivosCopy Anchor Link

Para una mutation con una variable Upload, añade el archivo en Archivos para variables en la pestaña Variables:

1. Elige +.
2. Escribe la variable, como file, o files.0 para el primer elemento de una lista.
3. Escribe la ruta del archivo, relativa al espacio de trabajo.

El POST sigue entonces la especificación GraphQL multipart request: la variable es null en operations, y el archivo va en una parte propia.