Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Cómo empezar: Crear tu primera API de GraphQL en AWS AppSync Puede usar la AWS AppSync consola para configurar e iniciar una API de GraphQL. GraphQL APIs generalmente requiere tres componentes: 1. **Esquema de GraphQL**: tu esquema de GraphQL es la base para crear la API. Define los tipos y campos que puede solicitar al ejecutar una operación. Para rellenar el esquema con datos, debe conectar los orígenes de datos a la API de GraphQL. En esta guía rápida, crearemos un esquema utilizando un modelo predefinido. 1. **Orígenes de datos**: son los recursos que contienen los datos para rellenar tu API de GraphQL. Puede ser una tabla de DynamoDB, una función Lambda, etc., y admite una multitud de fuentes de datos para crear GraphQL robusto y escalable AWS AppSync . APIs Los orígenes de datos están vinculados a los campos del esquema. Siempre que se realiza una solicitud en un campo, los datos del origen rellenan el campo. Este mecanismo lo controla el solucionador. En esta guía rápida, crearemos un origen de datos utilizando un modelo predefinido junto con el esquema. 1. **Solucionadores**: los solucionadores se ocupan de vincular el campo del esquema al origen de datos. Recuperan los datos de la fuente y, a continuación, devuelven el resultado en función de lo que definió el campo. AWS AppSync admite tanto JavaScript VTL como VTL para escribir resolutores para su GraphQL. APIs En esta guía rápida, los solucionadores se generarán automáticamente en función del esquema y el origen de datos. No vamos a tratar este tema en profundidad en esta sección. AWS AppSync admite la creación y configuración de todos los componentes de GraphQL. Al abrir la consola, puede usar los siguientes métodos para crear su API: 1. Diseñar una API de GraphQL personalizada generándola mediante un modelo predefinido y configurando una nueva tabla de DynamoDB (origen de datos) para respaldarla. 1. Diseñar una API de GraphQL con un esquema en blanco y sin orígenes de datos ni solucionadores. 1. Usar una tabla de DynamoDB para importar datos y generar los tipos y campos de su esquema. 1. Uso AWS AppSync de WebSocket las capacidades y la Pub/Sub arquitectura para desarrollar en tiempo real APIs. 1. Uso de GraphQL APIs (fuente APIs) existente para vincular a una API fusionada. **nota** Es aconsejable consultar la sección [Diseñar un esquema](designing-your-schema.md#aws-appsync-designing-your-schema) antes de trabajar con herramientas más avanzadas. Estas guías explicarán ejemplos más simples que puedes usar conceptualmente para crear aplicaciones más complejas. AWS AppSync AWS AppSync también admite varias opciones que no son de consola para crear APIs GraphQL. Entre ellos se incluyen: 1. AWS Amplify 1. AWS SAM 1. CloudFormation 1. El CDK. En el siguiente ejemplo, se muestra cómo crear los componentes básicos de una API de GraphQL mediante modelos predefinidos y DynamoDB. **Topics** + [Lanzamiento de un esquema](schema-launch-start.md) + [Haciendo un recorrido por la AWS AppSync consola](console-tour.md) + [Uso de mutaciones de GraphQL para añadir datos a una tabla de DynamoDB](add-data-with-graphql-mutation.md) + [Uso de consultas de GraphQL para recuperar datos de una tabla de DynamoDB](retrieve-data-with-graphql-query.md) + [Secciones complementarias](next-steps.md) # Lanzar un esquema en la consola AWS AppSync En este ejemplo, crearás una `Todo` API que permitirá a los usuarios crear `Todo` elementos para recordar las tareas diarias, como *Finish task* o. *Pick up groceries* Esta API muestra cómo utilizar las operaciones de GraphQL cuando el estado persiste en una tabla de DynamoDB. A nivel teórico, hay tres pasos principales para crear su primera API de GraphQL. Debe definir el esquema (tipos y campos), asociar los orígenes de datos a los campos y, a continuación, escribir el solucionador que gestiona la lógica empresarial. Sin embargo, la experiencia con la consola sugiere que es mejor cambiar este orden. Empezaremos por definir cómo queremos que nuestro origen de datos interactúe con nuestro esquema y, más adelante, definiremos el esquema y el solucionador. **Para crear su API de GraphQL** 1. [Inicia sesión en la consola Consola de administración de AWS y ábrelaAppSync .](https://console.aws.amazon.com/appsync/) 1. En el **Panel**, elija **Crear API**. 1. Con **GraphQL APIs** seleccionado, elige **Diseñar desde cero**. A continuación, elija **Siguiente**. 1. En el **Nombre de la API**, cambie el nombre rellenado previamente a **Todo API**. Después, seleccione **Siguiente**. **nota** Hay más opciones presentes aquí, pero no las usaremos en este ejemplo. 1. En la sección **Especificar recursos de GraphQL**, haga lo siguiente: 1. Seleccione **Crear tipo respaldado por una tabla de DynamoDB ahora**. **nota** Esto significa que vamos a crear una nueva tabla de DynamoDB para asociarla como origen de datos. 1. En el campo **Nombre del modelo**, escriba **Todo**. **nota** Nuestro primer requisito es definir nuestro esquema. Este **Nombre del modelo** será el nombre del tipo, de modo que lo que realmente está haciendo es crear un `type` llamado `Todo` que existirá en el esquema: ``` type Todo {} ``` 1. En **Campos**, haga lo siguiente: 1. Cree un campo llamado **id**, con el tipo `ID` y el valor obligatorio establecido en `Yes`. **nota** Estos son los campos que existirán dentro del ámbito de su tipo `Todo`. Aquí, el nombre de su campo se llamará `id` con un tipo de `ID!`: ``` type Todo { id: ID! } ``` AWS AppSync admite varios valores escalares para diferentes casos de uso. 1. Con **Agregar nuevo campo**, cree cuatro campos adicionales con los valores `Name` definidos como **name**, **when**, **where** y **description**. Sus valores `Type` serán `String`, y los valores `Array` y `Required` se establecerán en `No`. Tendrá un aspecto similar al siguiente: ![\[Model information form showing fields for a Todo model with ID, name, when, where, and description.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/model-information-tutorial.png) **nota** El tipo completo y sus campos tendrán un aspecto similar al siguiente: ``` type Todo { id: ID! name: String when: String where: String description: String } ``` Como vamos a crear un esquema con este modelo predefinido, también se rellenará con varias mutaciones reutilizables basadas en el tipo (por ejemplo, `create`, `delete` y `update`) para ayudarle a rellenar el origen de datos fácilmente. 1. En **Configurar la tabla del modelo**, introduzca un nombre de tabla, como **TodoAPITable**. Establezca la **clave principal** en `id`. **nota** Básicamente, estamos creando una nueva tabla de DynamoDB *TodoAPITable* llamada que se adjuntará a la API como fuente de datos principal. Nuestra clave principal se establece en el campo obligatorio `id` que definimos anteriormente. Tenga en cuenta que esta nueva tabla está en blanco y no contiene nada excepto la clave de partición. 1. Elija **Siguiente**. 1. Revise los cambios y seleccione **Crear API**. Espere un momento para que el AWS AppSync servicio termine de crear su API. Ha creado correctamente una API de GraphQL con su esquema y su origen de datos de DynamoDB. Para resumir los pasos anteriores, hemos creado una API de GraphQL completamente nueva. Hemos definido el nombre de la API y, a continuación, hemos agregado nuestra definición de esquema agregando nuestro primer tipo. Hemos definido el tipo y sus campos y, a continuación, hemos optado por asociar un origen de datos a uno de los campos creando una nueva tabla de DynamoDB sin datos. # Haciendo un recorrido por la AWS AppSync consola Antes de añadir datos a nuestra tabla de DynamoDB, debemos revisar las características básicas de la experiencia de AWS AppSync la consola. La pestaña de AWS AppSync consola situada en la parte izquierda de la página permite a los usuarios navegar fácilmente hasta cualquiera de los principales componentes u opciones de configuración, que incluyen: AWS AppSync ![\[AWS AppSync console navigation menu showing APIs, Todo API options, and Documentation link.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/explorer-example-5.jpg) ## Diseñador del esquema Seleccione **Esquema** para ver el esquema que acaba de crear. Si revisa el contenido del esquema, verá que ya incluye un gran número de operaciones auxiliares para agilizar el proceso de desarrollo. En el editor de **esquemas**, si se desplaza por el código, llegará finalmente al modelo que definió en la sección anterior: ``` type Todo { id: ID! name: String when: String where: String description: String } ``` Su modelo ha pasado a ser el tipo en el que se ha basado la creación de todo el esquema. Empezaremos a agregar datos a nuestro origen de datos mediante mutaciones que se han generado automáticamente a partir de este tipo. Estos son algunos consejos y datos adicionales sobre el editor de **esquemas**: 1. El editor de código tiene funcionalidades de análisis y de comprobación de errores que puede utilizar al escribir sus propias aplicaciones. 1. En la parte derecha de la consola se muestran los tipos de GraphQL que se han creado y los solucionadores en diferentes tipos de nivel superior, como, por ejemplo, las consultas. 1. Al añadir nuevos tipos a un esquema (por ejemplo,`type User {...}`), puede hacer que AWS AppSync aprovisione los recursos de DynamoDB por usted. Entre estos se incluyen la clave principal, la clave de clasificación y el diseño del índice adecuados que coincidan mejor con su patrón de acceso a los datos de GraphQL. Si elige **Create Resources (Crear recursos)** en la parte superior y elige uno de estos tipos definidos por el usuario en el menú, puede elegir diferentes opciones de campo en el diseño de esquema. Hablaremos de esto en la sección de [diseño de un esquema](designing-your-schema.md#aws-appsync-designing-your-schema). ### Configuración del solucionador En el diseñador de esquemas, la sección **Solucionadores** contiene todos los tipos y campos del esquema. Si se desplaza por la lista de campos, verá que puede adjuntar solucionadores a determinados campos si selecciona **Asociar**. Esto abrirá un editor de código en el que podrá escribir el código de resolución. AWS AppSync admite tanto VTL como JavaScript tiempos de ejecución, que se pueden cambiar en la parte superior de la página seleccionando **Acciones** y, a continuación, **Actualizar** tiempo de ejecución. En la parte inferior de la página, también puede crear funciones que ejecutarán varias operaciones en secuencia. Sin embargo, los solucionadores son un tema avanzado y no lo trataremos en esta sección. ## Orígenes de datos Seleccione **Orígenes de datos** para ver su tabla de DynamoDB. Al elegir la opción `Resource` (si está disponible), puede ver la configuración de su origen de datos. En nuestro ejemplo, esto lleva a la consola DynamoDB. Desde allí, puede editar sus datos. También puede editar directamente algunos de los datos seleccionando el origen de datos y, a continuación, seleccionando **Editar**. Si alguna vez necesita eliminar el origen de datos, puede elegir el origen de datos y, a continuación, seleccionar **Eliminar**. Por último, puede crear nuevos orígenes de datos. Para ello, seleccione **Crear origen de datos** y, a continuación, configure el nombre y el tipo. Tenga en cuenta que esta opción sirve para vincular el AWS AppSync servicio a un recurso existente. Aún debe crear el recurso en su cuenta mediante el servicio correspondiente antes de AWS AppSync reconocerlo. ## Consultas Seleccione **Consultas** para ver sus consultas y mutaciones. Cuando creamos nuestra API GraphQL con nuestro modelo, generamos AWS AppSync automáticamente algunas mutaciones y consultas auxiliares con fines de prueba. En el editor de consultas, en el lado izquierdo se encuentra el **Explorador**. Esta es una lista que muestra todas sus mutaciones y consultas. Aquí puede activar fácilmente las operaciones y los campos que desea utilizar haciendo clic en los valores de sus nombres. Esto hará que el código aparezca automáticamente en la parte central del editor. Aquí puede editar sus mutaciones y consultas modificando los valores. En la parte inferior del editor, tiene el editor de **Variables de consulta**, que le permite introducir los valores de los campos para las variables de entrada de sus operaciones. Al seleccionar **Ejecutar** en la parte superior del editor, aparecerá una lista desplegable para seleccionar la query/mutation que se va a ejecutar. El resultado de esta ejecución aparecerá en el lado derecho de la página. Al volver a la sección **Explorador** de la parte superior, puede elegir una operación (Consulta, Mutación o Suscripción) y, a continuación, elegir el símbolo **\$1** para agregar una nueva instancia de esa operación en particular. En la parte superior de la página, habrá otra lista desplegable que contiene el modo de autorización para la ejecución de sus consultas. Sin embargo, no abordaremos esa característica en esta sección (para obtener más información, consulte [Seguridad](security-authz.md#aws-appsync-security)). ## Configuración Seleccione **Ajustes** para ver algunas opciones de configuración de su API de GraphQL. Aquí puede habilitar algunas opciones, como el registro, el rastreo y la funcionalidad de firewall de aplicaciones web. También puede agregar nuevos modos de autorización para proteger sus datos de filtraciones no deseadas al público en general. Sin embargo, estas opciones son más avanzadas y no las abordaremos en esta sección. **nota** Nota: El modo de autorización predeterminado, `API_KEY`, utiliza una clave de API para probar la aplicación. Esta es la autorización básica que se otorga a todos los APIs GraphQL recién creados. Es aconsejable utilizar un método de producción diferente. Para ilustrar el ejemplo que nos ocupa, solo usaremos la clave de API. Para obtener más información acerca de los modos de autorización, consulte [Seguridad](security-authz.md#aws-appsync-security). # Uso de mutaciones de GraphQL para añadir datos a una tabla de DynamoDB en la consola AWS AppSync El siguiente paso es agregar datos a su tabla de DynamoDB, que está vacía, mediante una mutación de GraphQL. Las mutaciones son uno de los tipos de operaciones fundamentales en GraphQL. Se definen en el esquema y permiten manipular los datos del origen de datos. En términos de REST APIs, son muy similares a operaciones como o. `PUT` `POST` **Para agregar su origen de datos** 1. Si aún no lo has hecho, inicia sesión en la [AppSync consola Consola de administración de AWS](https://console.aws.amazon.com/appsync/) y ábrela. 1. Seleccione la API de la tabla. 1. En la pestaña de la izquierda, seleccione **Consultas**. 1. En la pestaña del **Explorador** situada a la izquierda de la tabla, debería ver varias mutaciones y consultas ya definidas en el editor de consultas: ![\[Explorer tab showing a dropdown menu with mutation and query options like createTodo and deleteTodo.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/explorer-example-1.png) **nota** De hecho, esta mutación se encuentra en su esquema como el tipo `Mutation`. Tiene el código: ``` type Mutation { createTodo(input: CreateTodoInput!): Todo updateTodo(input: UpdateTodoInput!): Todo deleteTodo(input: DeleteTodoInput!): Todo } ``` Como puede ver, las operaciones aquí son similares al contenido del editor de consultas. AWS AppSync los generó automáticamente a partir del modelo que definimos anteriormente. En este ejemplo, se utilizará la `createTodo` mutación para añadir entradas a nuestra *TodoAPITable* tabla. 1. Seleccione la operación `createTodo` expandiéndola debajo de la mutación `createTodo`: ![\[Expanded createTodo mutation showing input fields like description, id, name, when, and where.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/explorer-example-2.png) Active las casillas de verificación de todos los campos, como se muestra en la imagen anterior. **nota** Los atributos que ve aquí son los diferentes elementos modificables de la mutación. Su `input` se puede interpretar como el parámetro de `createTodo`. Las distintas opciones con casillas de verificación son los campos que se devolverán en la respuesta una vez que se haya realizado una operación. 1. En el editor de código situado en el centro de la pantalla, verá que la operación aparece debajo de la mutación `createTodo`: ``` mutation createTodo($createtodoinput: CreateTodoInput!) { createTodo(input: $createtodoinput) { where when name id description } } ``` **nota** Para explicar este fragmento correctamente, también debemos observar el código del esquema. La declaración `mutation createTodo($createtodoinput: CreateTodoInput!){}` es la mutación con una de sus operaciones, `createTodo`. La mutación completa se encuentra en el esquema: ``` type Mutation { createTodo(input: CreateTodoInput!): Todo updateTodo(input: UpdateTodoInput!): Todo deleteTodo(input: DeleteTodoInput!): Todo } ``` Volviendo a la declaración de mutación del editor, el parámetro es un objeto llamado `$createtodoinput` con un tipo de entrada obligatorio de `CreateTodoInput`. Tenga en cuenta que `CreateTodoInput` (y todas las entradas de la mutación) también están definidas en el esquema. Por ejemplo, este es el código reutilizable de `CreateTodoInput`: ``` input CreateTodoInput { name: String when: String where: String description: String } ``` Contiene los campos que definimos en nuestro modelo: `name`, `when`, `where` y `description`. Volviendo al código del editor, en `createTodo(input: $createtodoinput) {}`, declaramos la entrada como `$createtodoinput`, que también se usó en la declaración de mutación. Hacemos esto porque esto permite a GraphQL validar nuestras entradas con los tipos proporcionados y garantizar que se utilizan con las entradas correctas. La parte final del código del editor muestra los campos que se devolverán en la respuesta después de realizar una operación: ``` { where when name id description } ``` En la pestaña de **Variables de consulta** situada debajo de este editor, habrá un objeto `createtodoinput` genérico que puede contener los siguientes datos: ``` { "createtodoinput": { "name": "Hello, world!", "when": "Hello, world!", "where": "Hello, world!", "description": "Hello, world!" } } ``` **nota** Aquí es donde asignamos los valores de la entrada mencionada anteriormente: ``` input CreateTodoInput { name: String when: String where: String description: String } ``` Cambie `createtodoinput` agregando la información que queremos incluir en nuestra tabla de DynamoDB. En este caso, queríamos crear algunos elementos `Todo` como recordatorios: ``` { "createtodoinput": { "name": "Shopping List", "when": "Friday", "where": "Home", "description": "I need to buy eggs" } } ``` 1. Seleccione **Ejecutar** en la parte superior del editor. En la lista desplegable, seleccione **createTodo**. En la parte derecha del editor, debería ver la respuesta. Puede tener un aspecto similar al siguiente: ``` { "data": { "createTodo": { "where": "Home", "when": "Friday", "name": "Shopping List", "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "description": "I need to buy eggs" } } } ``` Si navega hasta el servicio DynamoDB, ahora verá una entrada en el origen de datos con esta información: ![\[TodoAPITable interface showing a completed scan with 1 item returned in a table format.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/explorer-example-3.png) Para resumir la operación, el motor GraphQL analizó el registro y un solucionador lo insertó en la tabla de Amazon DynamoDB. De nuevo, puede comprobarlo en la consola de DynamoDB. Tenga en cuenta que no ha sido necesario transferir un valor `id`. Se genera un `id` y se devuelve en los resultados. Esto se debe a que en el ejemplo se utilizó una función `autoId()` en un solucionador de GraphQL para el conjunto de claves de partición de los recursos de DynamoDB. Veremos cómo puede crear solucionadores en una sección diferente. Tome nota del valor `id` devuelto; lo usará en la siguiente sección para recuperar datos con una consulta de GraphQL. # Uso de consultas GraphQL para recuperar datos de una tabla de DynamoDB en la consola AWS AppSync Ahora que ya tiene un registro en su base de datos, puede obtener resultados al ejecutar una consulta. Una consulta es otra de las operaciones fundamentales de GraphQL. Se usa para analizar y recuperar información de su origen de datos. En términos de REST APIs, es similar a la operación. `GET` La principal ventaja de las consultas de GraphQL es la capacidad de especificar los requisitos de datos exactos de su aplicación para que pueda obtener los datos relevantes en el momento adecuado. **Para consultar su origen de datos** 1. Si aún no lo ha hecho, inicie sesión en la [AppSync consola Consola de administración de AWS y ábrala](https://console.aws.amazon.com/appsync/). 1. Seleccione la API de la tabla. 1. En la pestaña de la izquierda, seleccione **Consultas**. 1. En la pestaña **Explorador** situada a la izquierda de la tabla, en `query` `listTodos`, expanda la operación `getTodo`: ![\[Expanded getTodo operation showing fields id, description, name, when, and where.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/explorer-example-4.png) 1. En el editor de código, debería ver el código de operación: ``` query listTodos { getTodo(id: "") { description id name when where } ``` En `(id:"")`, introduzca el valor que guardó en el resultado de la operación de mutación. En nuestro ejemplo, sería: ``` query listTodos { getTodo(id: "abcdefgh-1234-1234-1234-abcdefghijkl") { description id name when where } ``` 1. Seleccione **Ejecutar** y, a continuación, **listTodos**. El resultado aparecerá a la derecha del editor. Nuestro ejemplo tenía un aspecto similar al siguiente: ``` { "data": { "getTodo": { "description": "I need to buy eggs", "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "name": "Shopping List", "when": "Friday", "where": "Home" } } } ``` **nota** Las consultas solo devuelven los campos especificados. Puede anular la selección de los campos que no necesite eliminándolos del campo de devolución: ``` { description id name when where } ``` También puede anular la selección de la casilla de la pestaña **Explorador** situada junto al campo que desea eliminar. 1. Asimismo, puede probar la operación `listTodos` repitiendo los pasos para crear una entrada en el origen de datos y, a continuación, repetir los pasos de consulta con la operación `listTodos`. A continuación, se muestra un ejemplo en el que agregamos una segunda tarea: ``` { "createtodoinput": { "name": "Second Task", "when": "Monday", "where": "Home", "description": "I need to mow the lawn" } } ``` Al llamar a la operación `listTodos`, devolvió las entradas antiguas y nuevas: ``` { "data": { "listTodos": { "items": [ { "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "name": "Shopping List", "when": "Friday", "where": "Home", "description": "I need to buy eggs" }, { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "name": "Second Task", "when": "Monday", "where": "Home", "description": "I need to mow the lawn" } ] } } } ``` # Secciones complementarias para la consola AWS AppSync Estas secciones son una referencia para temas más avanzados AWS AppSync . Recomendamos continuar con la sección *Lectura complementaria* antes de nada. ## Integración En la pestaña de la consola, si elige el nombre de su API, aparecerá la página **Integración**: ![\[AWS AppSync sidebar menu with APIs, Todo API highlighted, and other options listed.\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/explorer-example-6.png) En ella, se resumen los pasos para configurar la API y se describen los siguientes pasos para crear una aplicación cliente. La sección **Integrar con tu aplicación** proporciona detalles sobre el uso de la [cadena de herramientas AWS Amplify](https://aws-amplify.github.io/) para automatizar el proceso de conexión de la API con iOS, Android y JavaScript las aplicaciones mediante la configuración y la generación de código. La cadena de herramientas de Amplify es totalmente compatible con la creación de proyectos desde su estación de trabajo local, incluidos el aprovisionamiento de GraphQL y los flujos de trabajo para CI/CD. La sección **Ejemplos de clientes** también incluye ejemplos de aplicaciones cliente (por ejemplo JavaScript, iOS o Android) para probar una end-to-end experiencia. Puede clonar y descargar estos ejemplos y el archivo de configuración que tiene la información necesaria (como su URL de punto de conexión) que precisa para comenzar. Siga las instrucciones de la página [Cadena de herramientas de AWS Amplify](https://aws-amplify.github.io/) para ejecutar su aplicación. ## Lectura complementaria + [Diseñar GraphQL APIs con AWS AppSync](designing-a-graphql-api.md): esta es una guía completa para crear su GraphQL utilizando un esquema en blanco sin orígenes de datos ni solucionadores.