{"meta":{"title":"Formar llamados con GraphQl","intro":"Aprende cómo autenticarte en la API de GraphQL, y luego cómo crear y ejecutar consultas y mutaciones.","product":"GraphQL API","breadcrumbs":[{"href":"/es/graphql","title":"GraphQL API"},{"href":"/es/graphql/guides","title":"Guías"},{"href":"/es/graphql/guides/forming-calls-with-graphql","title":"Formación de llamadas con GraphQL"}],"documentType":"article"},"body":"# Formar llamados con GraphQl\n\nAprende cómo autenticarte en la API de GraphQL, y luego cómo crear y ejecutar consultas y mutaciones.\n\n## Autenticarse con GraphQL\n\nPuede autenticarse en la API de GraphQL mediante personal access token, GitHub App o OAuth app.\n\n### Autenticación con personal access token\n\nPara autenticarse con personal access token, siga los pasos indicados en [Administración de tokens de acceso personal](/es/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Los datos que solicitas determinarán qué ámbitos o permisos necesitarás.\n\nPor ejemplo, seleccione el permiso \"issues:read\" para leer todos los problemas de los repositorios a los que el token tiene acceso.\n\nTodos los fine-grained personal access token incluyen acceso de lectura a repositorios públicos. Para acceder a repositorios públicos con personal access token (classic), seleccione el alcance \"public\\_repo\".\n\nSi el token no tiene los ámbitos o permisos necesarios para access un recurso, la API devolverá un mensaje de error que indica los ámbitos o permisos que necesita el token.\n\n### Autenticación con GitHub App\n\nSi desea usar la API en nombre de una organización u otro usuario, GitHub recomienda usar .GitHub App\nPara atribuir la actividad a la aplicación, puedes hacer que la aplicación se autentique como una instalación de aplicación. Para atribuir la actividad de la aplicación a un usuario, puedes hacer que la aplicación se autentique en nombre de un usuario. En ambos casos, generarás un token que puedes usar para autenticarte en la GraphQL API. Para obtener más información, vea [Registro de una aplicación de GitHub](/es/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) y [Acerca de la autenticación con una aplicación de GitHub](/es/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app).\n\n### Autenticación con OAuth app\n\nPara autenticarte con un token OAuth de un OAuth app, primero debes autorizar tu OAuth app mediante un flujo de aplicación web o un flujo de dispositivo. A continuación, puede usar el token de acceso que recibió para acceder a la API. Para obtener más información, vea [Creación de una aplicación de OAuth](/es/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) y [Autorización de aplicaciones de OAuth](/es/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).\n\n## Punto de acceso de GraphQL\n\nLa API REST tiene numerosos puntos de conexión. Con GraphQL API, el punto de conexión permanece constante sin importar la operación que realices. Para GitHub.com, ese punto de conexión es:\n\n
https://api.github.com/graphql
\n\n## Comunicarse con GraphQL\n\nDado que las operaciones de GraphQL constan de JSON de varias líneas, GitHub recomienda usar los clientes de [GraphQL](/es/graphql/guides/using-graphql-clients) para realizar llamadas a GraphQL. También puedes utilizar `curl` o cualquier otra biblioteca que entienda HTTP.\n\nEn REST, los [verbos HTTP](/es/rest#http-verbs) determinan la operación realizada. En GraphQL, tendrá que proporcionar un cuerpo codificado con JSON cuando realice una consulta o una mutación, por lo que el verbo HTTP es `POST`. La excepción es una [consulta de introspección](/es/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), que es una `GET` sencilla al punto de conexión. Para obtener más información sobre GraphQL frente a REST, consulte [Migrar desde Rest hacia GraphQL](/es/graphql/guides/migrating-from-rest-to-graphql).\n\nPara consultar GraphQL mediante un comando `curl`, realiza una solicitud `POST` con una carga JSON. La carga debe contener una cadena denominada `query`:\n\n```shell\ncurl -H \"Authorization: bearer TOKEN\" -X POST -d \" \\\n { \\\n \\\"query\\\": \\\"query { viewer { login }}\\\" \\\n } \\\n\" https://api.github.com/graphql\n```\n\n> \\[!NOTE]\n> El valor de cadena de `\"query\"` debe aplicar escape a los caracteres de nueva línea o el esquema no lo analizará correctamente. Para el cuerpo `POST`, use comillas dobles externas y comillas dobles interiores con escape.\n\n### Acerca de las operaciones de consulta y mutación\n\nLos dos tipos de operaciones permitidas en graphQL API de GitHub son *consultas* y *mutaciones*. Si se compara GraphQL con REST, las consultas funcionan como solicitudes `GET`, mientras que las mutaciones funcionan como`POST`/`PATCH`/`DELETE`. El nombre de la mutación determina qué modificación se ejecuta.\n\nPara obtener información sobre la limitación de tasas, consulta [Límites de frecuencia y consulta para GraphQL API](/es/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api).\n\nLas consultas y mutaciones comparten formatos similares con algunas diferencias importantes.\n\n### Acerca de las consultas\n\nLas consultas de GraphQL devuelven solo los datos que especifique. Para formular una consulta, debes especificar [campos dentro de campos](/es/graphql/guides/introduction-to-graphql#field) (también conocidos como *subcampos anidados*) hasta que solo se devuelvan valores escalares.\n\nLas consultas se estructuran de esta manera:\n\n
query {\n  JSON-OBJECT-TO-RETURN\n}
\n\nPara obtener un ejemplo real, lee [Consulta de ejemplo](#example-query).\n\n### Acerca de las mutaciones\n\nPara formar una mutación, debes especificar tres cosas:\n\n1. *Nombre de la mutación*. El Tipo de modificación que quieres realizar.\n2. *Objeto de entrada*. Los datos que quiere enviar al servidor, formados por *campos de entrada*. Pásalo como un argumento al nombre de la mutación.\n3. *Objeto de carga útil*. Los datos que se quieren devolver desde el servidor, compuestos por *campos de retorno*. Pásalos como el cuerpo del nombre de la mutación.\n\nLas mutaciones se estructuran de la siguiente forma:\n\n
mutation {\n  MUTATION-NAME(input: {MUTATION-NAME-INPUT!}) {\n    MUTATION-NAME-PAYLOAD\n  }\n}
\n\nEl objeto de entrada de este ejemplo es `MutationNameInput`y el objeto de carga es `MutationNamePayload`.\n\nEn la referencia de mutaciones, los *campos de entrada* enumerados son los que se pasan como objeto de entrada. Los *campos devueltos* enumerados son lo que se pasa como objeto de carga.\n\nPara obtener un ejemplo real, consulta [Mutación de ejemplo](#example-mutation).\n\n## Trabajo con variables\n\nLas [variables](https://graphql.org/learn/queries/#variables) pueden hacer que las consultas sean más dinámicas y eficaces, y pueden reducir la complejidad al pasar objetos de entrada de mutación.\n\nAquí hay una consulta de ejemplo con una sola variable:\n\n```graphql\nquery($number_of_repos:Int!) {\n viewer {\n name\n repositories(last: $number_of_repos) {\n nodes {\n name\n }\n }\n }\n}\nvariables {\n \"number_of_repos\": 3\n}\n```\n\nHay tres pasos para utilizar las variables:\n\n1. Defina la variable fuera de la operación en un objeto `variables`:\n\n ```graphql\n variables {\n \"number_of_repos\": 3\n }\n ```\n\n El objeto debe ser un JSON válido. En este ejemplo se muestra un tipo de variable `Int` sencillo, pero se pueden definir tipos de variable más complejos, como los objetos de entrada. También puedes definir variables múltiples aquí.\n\n2. Pasa la variable a la operación como un argumento:\n\n ```graphql\n query($number_of_repos:Int!){\n ```\n\n El argumento es un par clave-valor, donde la clave es el *nombre* que empieza por `$` (por ejemplo, `$number_of_repos`) y el valor es el *tipo* (por ejemplo, `Int`). Agregue `!` para indicar si el tipo es obligatorio. Si has identificado variables múltiples, inclúyelas aquí como argumentos múltiples.\n\n3. Utiliza la variable dentro de la operación:\n\n ```graphql\n repositories(last: $number_of_repos) {\n ```\n\n En este ejemplo, sustituimos la variable por la cantidad de repositorios a devolver. Especificamos un tipo en el paso 2, ya que GraphQL requiere tipado fuerte.\n\nEste proceso vuelve dinámico el argumento de la consulta. Ahora se puede cambiar el valor en el objeto `variables` y mantener el resto de la consulta igual.\n\nEl uso de variables como argumentos permite actualizar los valores del objeto `variables` de forma dinámica sin cambiar la consulta.\n\n## Ejemplo de consulta\n\nAnalicemos una consulta más compleja y pongamos esta información en contexto.\n\nLa consulta siguiente examina el repositorio `octocat/Hello-World`, busca las 20 incidencias cerradas más recientes y devuelve el título, la dirección URL y las 5 primeras etiquetas de cada incidencia:\n\n```graphql\nquery {\n repository(owner:\"octocat\", name:\"Hello-World\") {\n issues(last:20, states:CLOSED) {\n edges {\n node {\n title\n url\n labels(first:5) {\n edges {\n node {\n name\n }\n }\n }\n }\n }\n }\n }\n}\n```\n\nAnalizando la composición línea por línea:\n\n* `query {`\n\n Como el objetivo es leer datos del servidor, no modificarlos, la operación raíz es `query`. (Si no especifica una operación, `query` también es el valor predeterminado).\n\n* `repository(owner:\"octocat\", name:\"Hello-World\") {`\n\n Para comenzar la consulta, se busca un objeto [`repository`](/es/graphql/reference/repos#object-repository). La validación del esquema indica que este objeto necesita un `owner` y un argumento `name`.\n\n* `issues(last:20, states:CLOSED) {`\n\n Para tener en cuenta todas las incidencias del repositorio, se llama al objeto `issues`. (Se *podría* consultar un único `issue` en `repository`, pero para eso sería necesario conocer el número de la incidencia que se quiere devolver y proporcionarlo como argumento).\n\n Algunos detalles sobre el objeto `issues`:\n\n * En la [documentación](/es/graphql/reference/repos#object-repository) se indica que este objeto tiene el tipo `IssueConnection`.\n * La validación del esquema indica que este objeto necesita un número de resultados `last` o `first` como argumento, por lo que se proporciona `20`.\n * En la [documentación](/es/graphql/reference/repos#object-repository) también se indica que este objeto acepta un argumento `states`, que es una enumeración [`IssueState`](/es/graphql/reference/issues#enum-issuestate) que acepta valores `OPEN` o `CLOSED`. Para busca solo incidencias cerradas, se asigna un valor de `states` a la clave `CLOSED`.\n\n* `edges {`\n\n Se sabe que `issues` es una conexión porque tiene el tipo `IssueConnection`. Para recuperar datos sobre incidencias individuales, tenemos que acceder al nodo a través de `edges`.\n\n* `node {`\n\n Aquí obtenemos el nodo al final de la arista. En la documentación de [`IssueConnection`](/es/graphql/reference/issues#object-issueconnection) se indica que el nodo al final del tipo `IssueConnection` es un objeto `Issue`.\n\n* Ahora que se sabe que se va a recuperar un objeto `Issue`, se puede examinar la [documentación](/es/graphql/reference/issues#object-issue) y especificar los campos que se quieren devolver:\n\n ```graphql\n title\n url\n labels(first:5) {\n edges {\n node {\n name\n }\n }\n }\n ```\n\n Aquí se especifican los campos `title`, `url` y `labels` del objeto `Issue`.\n\n El campo `labels` tiene el tipo [`LabelConnection`](/es/graphql/reference/issues#object-labelconnection). Como sucede con el objeto `issues`, como `labels` es una conexión, es necesario desplazar sus bordes a un nodo conectado: el objeto `label`. En el nodo, se pueden especificar los campos del objeto `label` que se quieren devolver, en este caso, `name`.\n\nEs posible que observe que la ejecución de esta consulta en el repositorio `Hello-World` de Octocat no devuelve muchas etiquetas. Intenta ejecutarlo en uno de tus propios repositorios que utilice etiquetas, y seguramente verás la diferencia.\n\n## Mutación de ejemplo\n\nLas mutaciones a menudo requieren información que solo puedes encontrar si realizas una consulta primero. Este ejemplo muestra dos operaciones:\n\n1. Una consulta para obtener el ID de una incidencia.\n2. Una mutación para agregar una reacción de emoji a un problema.\n\n```graphql\nquery FindIssueID {\n repository(owner:\"octocat\", name:\"Hello-World\") {\n issue(number:349) {\n id\n }\n }\n}\n\nmutation AddReactionToIssue {\n addReaction(input:{subjectId:\"MDU6SXNzdWUyMzEzOTE1NTE=\",content:HOORAY}) {\n reaction {\n content\n }\n subject {\n id\n }\n }\n}\n```\n\nAnalicemos el ejemplo. La tarea parece sencilla: agregar una reacción de emoji a una incidencia.\n\nAsí que, ¿cómo sabemos que debemos comenzar con una consulta? Aún no sabemos nada.\n\nYa que queremos modificar los datos en el servidor (agregar un emoji a un informe de problemas), empezamos buscando en el esquema una mutación útil. En la documentación de referencia se muestra la mutación [`addReaction`](/es/graphql/reference/reactions#mutation-addreaction), con esta descripción: `Adds a reaction to a subject.` Perfecto.\n\nLos documentos para la mutación listan tres campos de entrada:\n\n* `clientMutationId` (`String`)\n* `subjectId` (`ID!`)\n* `content` (`ReactionContent!`)\n\nLos valores `!` indican que `subjectId` y `content` son campos obligatorios. Un campo `content` obligatorio tiene sentido: el objetivo es agregar una reacción, por lo que será necesario especificar el emoji que se va a usar.\n\n¿Pero por qué `subjectId` es obligatorio? Se debe a que `subjectId` es la única manera de identificar a *qué* incidencia de *qué* repositorio se debe reaccionar.\n\nEste es el motivo de comenzar el ejemplo con una consulta: para obtener `ID`.\n\nExaminemos la consulta línea por línea:\n\n* `query FindIssueID {`\n\n Aquí se realiza una consulta y se le asigna el nombre `FindIssueID`. Tenga en cuenta que asignar un nombre a una consulta es opcional; aquí le damos un nombre para poder incluirla en la misma ventana del cliente de la interfaz gráfica que la mutación.\n\n* `repository(owner:\"octocat\", name:\"Hello-World\") {`\n\n Para especificar el repositorio se consulta el objeto `repository` y se pasan los argumentos `owner` y `name`.\n\n* `issue(number:349) {`\n\n Para especificar la incidencia a la que reaccionar se consulta el objeto `issue` y se pasa un argumento `number`.\n\n* `id`\n\n Aquí es donde recuperamos el `id` de `https://github.com/octocat/Hello-World/issues/349` para pasar como `subjectId`.\n\nCuando se ejecuta la consulta, se obtiene `id`: `MDU6SXNzdWUyMzEzOTE1NTE=`.\n\n> \\[!NOTE]\n> El valor `id` devuelto en la consulta es el que se pasará como `subjectID` en la mutación. Ni la documentación ni la introspección del esquema indicarán esta relación; necesitarás comprender los conceptos que subyacen a los nombres para descubrirla.\n\nUna vez conociendo la ID, podemos proceder con la mutación:\n\n* `mutation AddReactionToIssue {`\n\n Aquí se ejecuta una mutación y se le asigna el nombre `AddReactionToIssue`. Al igual que con las consultas, la nomenclatura de una mutación es opcional; Aquí se le asigna un nombre para que podamos incluirlo en la misma ventana de cliente de GUI que la consulta.\n\n* `addReaction(input:{subjectId:\"MDU6SXNzdWUyMzEzOTE1NTE=\",content:HOORAY}) {`\n\n Examinemos esta línea:\n\n * `addReaction` es el nombre de la mutación.\n * `input` es la clave de argumento obligatoria. Esto siempre será `input` para una mutación.\n * `{subjectId:\"MDU6SXNzdWUyMzEzOTE1NTE=\",content:HOORAY}` es el valor de argumento obligatorio. Este será siempre un objeto de entrada (de ahí las llaves) compuesto por campos de entrada (`subjectId` y `content` en este caso) para una mutación.\n\n ¿Cómo sabemos qué valor utilizar para el contenido? La [`addReaction` documentación](/es/graphql/reference/reactions#mutation-addreaction) nos indica que el campo `content` tiene el tipo [`ReactionContent`](/es/graphql/reference/reactions#enum-reactioncontent), que es un tipo enumerado porque en las incidencias de GitHub solo se admiten ciertas reacciones con emoji. Estos son los valores permitidos para las reacciones (nota que algunos valores son diferentes de sus nombres de emoji correspondientes):\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ContenidoEmoji
+1👍
-1👎
laugh😄
confused😕
heart❤️
hooray🎉
rocket🚀
eyes👀
\n\n* El resto del llamado se compone del objeto de carga útil. Aquí es donde especificamos los datos que queremos recuperar del servidor después de que realicemos la mutación. Estas líneas proceden de la documentación de [`addReaction`](/es/graphql/reference/reactions#mutation-addreaction), con tres campos devueltos posibles:\n\n * `clientMutationId` (`String`)\n * `reaction` (`Reaction!`)\n * `subject` (`Reactable!`)\n\n En este ejemplo, se devuelven los dos campos obligatorios (`reaction` y `subject`), que tienen subcampos obligatorios (`content` y `id`, respectivamente).\n\nCuando ejecutamos la mutación, esta es la respuesta:\n\n```json\n{\n \"data\": {\n \"addReaction\": {\n \"reaction\": {\n \"content\": \"HOORAY\"\n },\n \"subject\": {\n \"id\": \"MDU6SXNzdWUyMTc5NTQ0OTc=\"\n }\n }\n }\n}\n```\n\nEso es todo. Revisa tu [reacción ante el problema](https://github.com/octocat/Hello-World/issues/349) pasando el ratón sobre el :tada: para encontrar tu nombre de usuario.\n\nUna última nota: cuando pasas varios campos en un objeto de entrada, la sintaxis puede ser difícil de manejar. Puede resultar útil mover los campos a una [variable](#working-with-variables). Así es como podrías reescribir la mutación original utilizando una variable:\n\n```graphql\nmutation($myVar:AddReactionInput!) {\n addReaction(input:$myVar) {\n reaction {\n content\n }\n subject {\n id\n }\n }\n}\nvariables {\n \"myVar\": {\n \"subjectId\":\"MDU6SXNzdWUyMTc5NTQ0OTc=\",\n \"content\":\"HOORAY\"\n }\n}\n```\n\n> \\[!NOTE]\n> Es posible que observe que el valor del campo `content` en el ejemplo anterior (donde se usa directamente en la mutación) no tiene comillas alrededor de `HOORAY`, pero sí cuando se usa en la variable. Esto es por una razón:\n>\n> * Cuando se usa `content` directamente en la mutación, el esquema espera que el valor sea de tipo [`ReactionContent`](/es/graphql/reference/reactions#enum-reactioncontent), que es una *enumeración*, no una cadena. La validación del modelo arrojará un error si agregas comillas antes y después del valor de enumerador, ya que estas están reservadas para las cadenas.\n> * Cuando se usa `content` en una variable, la sección de variables debe ser código JSON válido, por lo que las comillas son obligatorias. La validación del esquema interpreta correctamente el tipo `ReactionContent` cuando la variable se pasa a la mutación durante la ejecución.\n>\n> Para más información sobre la diferencia entre enumeraciones y cadenas, vea la [especificación oficial de GraphQL](https://spec.graphql.org/June2018/#sec-Enums).\n\n## Información adicional\n\nHay *mucho* más que puedes hacer cuando realizas llamadas de GraphQL. Aquí hay algunos lugares que te pueden interesar posteriormente:\n\n* [Uso de la paginación en la API GraphQL](/es/graphql/guides/using-pagination-in-the-graphql-api)\n* [Fragmentos](https://graphql.org/learn/queries/#fragments)\n* [Fragmentos alineados](https://graphql.org/learn/queries/#inline-fragments)\n* [Directivas](https://graphql.org/learn/queries/#directives)"}