Hola habrozhiteli! Hemos publicado un libro sobre el lenguaje de consulta GraphQL. Decidimos compartir la traducción del capítulo "Anatomía de las consultas GraphQL"
Snowtooth es una estación de esquí ficticia. Por el bien de los ejemplos en este capítulo, pretendemos que esta es una montaña real y trabajamos allí. Veremos cómo el equipo web de Snow Fang usa GraphQL para proporcionar información en tiempo real: información sobre el estado de los remontes y las pistas de esquí. Snow Fang Ski Patrol puede abrir y cerrar remontes y pistas directamente desde su teléfono inteligente. Para seguir los ejemplos de este capítulo, consulte la interfaz Snow Fang en la plataforma GraphQL Playground (snowtooth.moonhighway.com/).
Puede usar la operación de consulta para consultar datos de la API. La consulta describe los datos que desea recibir del servidor GraphQL. Cuando envía una solicitud, solicita unidades de datos por campo. Estos campos se muestran en el mismo campo en la respuesta de datos JSON que recibe del servidor. Por ejemplo, si envía una solicitud de allLifts y solicita los campos de nombre y estado, debería obtener una respuesta JSON que contenga una matriz de allLifts y las cadenas de nombre y estado de cada ascensor, como se muestra aquí:
query { allLifts { name status } }
Manejo de errores
Las solicitudes exitosas devuelven un documento JSON que contiene la clave de datos. Las solicitudes fallidas devuelven un documento JSON que contiene la clave de error. Los detalles de lo que salió mal se transmiten como datos JSON bajo esta clave. Una respuesta JSON puede contener tanto "datos" como "errores".
Puede agregar múltiples consultas a un documento de consulta, pero solo se puede iniciar una operación a la vez. Por ejemplo, puede colocar dos operaciones de consulta en un documento de consulta:
query lifts { allLifts { name status } } query trails { allTrails { name difficulty } }
Cuando hace clic en el botón de reproducción, GraphQL Playground le solicita que seleccione una de estas dos operaciones.
Si desea enviar una solicitud para todos los datos especificados, debe poner todo en la misma solicitud:
query liftsAndTrails { liftCount(status: OPEN) allLifts { name status } allTrails { name difficulty } }
Aquí están los beneficios de GraphQL. Podemos recibir diferentes tipos de datos en una sola solicitud. Solicitamos un liftCount por estado, que nos permite averiguar la cantidad de ascensores que actualmente tienen este estado. También solicitamos el nombre y el estado de cada ascensor. Finalmente, solicitamos el nombre y el estado de cada rastro.
consulta es un tipo de GraphQL. Lo llamamos el tipo raíz porque es el tipo que se asigna a la operación, y las operaciones son las raíces de nuestro documento de consulta. Los campos disponibles para consultar en la API GraphQL se definen en este esquema API. La documentación indica qué campos están disponibles para su selección en el tipo de consulta.
La documentación nos dice que podemos seleccionar los campos liftCount, allLifts y allTrails cuando llamamos a esta API. También define más campos que están disponibles para la selección, pero el objetivo de la consulta es que podemos elegir qué campos necesitamos y cuáles debemos omitir.
Cuando escribimos consultas, seleccionamos los campos que necesitamos, encerrándolos entre llaves. Estos bloques se llaman muestras. Los campos que definimos en la selección están directamente relacionados con los tipos GraphQL. Los campos liftCount, allLifts y allTrails se definen en el tipo de consulta.
Puede incrustar muchas selecciones entre sí. Dado que el campo allLifts devuelve una lista de elevación, necesitamos usar llaves para crear una nueva selección para este tipo. Hay todo tipo de datos que podemos solicitar sobre el ascensor, pero en este ejemplo solo necesitamos el nombre y el estado del ascensor. Del mismo modo, una solicitud allTrails devolverá los tipos de Trail.
La respuesta JSON contiene todos los datos que solicitamos. Estos datos están formateados como JSON y se entregan en la misma forma que nuestra solicitud. Cada campo JSON recibe el mismo nombre que el campo en nuestra muestra. Podemos cambiar los nombres de campo en el objeto de respuesta en la solicitud especificando alias, como se muestra a continuación:
query liftsAndTrails { open: liftCount(status: OPEN) chairlifts: allLifts { liftName: name status } skiSlopes: allTrails { name difficulty } }
La siguiente es la respuesta:
{ "data": { "open": 5, "chairlifts": [ { "liftName": "Astra Express", "status": "open" } ], "skiSlopes": [ { "name": "Ditch of Doom", "difficulty": "intermediate" } ] } }
Ahora devolvemos los datos de la misma forma, pero en nuestra respuesta cambiamos el nombre de varios campos. Una forma de filtrar los resultados de una consulta GraphQL es pasar los argumentos de la consulta. Los argumentos son un par de valores clave (o pares) asociados con un campo de solicitud. Si solo se requieren los nombres de los ascensores cerrados, podemos enviar un argumento que filtrará nuestra respuesta:
query closedLifts { allLifts(status: "CLOSED" sortBy: "name") { name status } }
También puede usar argumentos para seleccionar datos. Por ejemplo, supongamos que necesitamos solicitar el estado de un teleférico individual. Podemos elegir un ascensor por su identificador único:
query jazzCatStatus { Lift(id: "jazz-cat") { name status night elevationGain } }
Aquí vemos que la respuesta contiene nombre, estado, noche y elevación Ganancia para el teleférico Jazz Cat.
»Se puede encontrar más información sobre el libro en
el sitio web del editor»
Contenidos»
ExtractoCupón de 25% de descuento para
vendedores ambulantes -
GraphQLTras el pago de la versión en papel del libro, se envía una versión electrónica del libro por correo electrónico.