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.

Diseñar tu esquema de GraphQL

El esquema GraphQL es la base de cualquier implementación de servidor GraphQL. Cada GraphQL API se define mediante un único esquema que contiene tipos y campos que describen cómo se rellenarán los datos de las solicitudes. Los datos que fluyen a través de usted API y las operaciones realizadas deben validarse con respecto al esquema.

En general, el sistema de tipos de GraphQL describe las funcionalidades de un servidor GraphQL y se utiliza para determinar si una consulta es válida. El sistema de tipos de un servidor suele denominarse esquema de ese servidor y puede constar de diferentes tipos de objetos, tipos escalares, tipos de entradas, etc. GraphQL es declarativo y tiene establecimiento inflexible de tipos, lo que significa que los tipos estarán bien definidos en tiempo de ejecución y solo devolverán lo que se haya especificado.

AWS AppSync permite definir y configurar esquemas de GraphQL. En la siguiente sección se describe cómo crear esquemas de GraphQL desde cero utilizando AWS AppSync los servicios.

Estructuración de un esquema de GraphQL

GraphQL es una poderosa herramienta para implementar API servicios. Según el sitio web de GraphQL, GraphQL es lo siguiente:

«GraphQL es un lenguaje de consulta APIs y un entorno de ejecución para completar esas consultas con los datos existentes. GraphQL proporciona una descripción completa y comprensible de los datos que contieneAPI, da a los clientes la posibilidad de pedir exactamente lo que necesitan y nada más, facilita la evolución con el APIs tiempo y habilita potentes herramientas para desarrolladores. »

Esta sección cubre la primera parte de la implementación de GraphQL, el esquema. Utilizando la cita anterior, un esquema cumple la función de «proporcionar una descripción completa y comprensible de los datos que contieneAPI». En otras palabras, un esquema GraphQL es una representación textual de los datos, las operaciones y las relaciones entre ellos de su servicio. El esquema se considera el punto de entrada principal para la implementación del servicio GraphQL. Como era de esperar, suele ser una de las primeras cosas que hace en su proyecto. Recomendamos consultar la sección Esquemas antes de continuar.

Para citar la sección de esquemas, los esquemas de GraphQL se escriben en el lenguaje de definición de esquemas (). SDL SDLse compone de tipos y campos con una estructura establecida:

Los esquemas más simples contendrán tres categorías de datos diferentes:

Para poner esto en perspectiva, imagine que está creando un servicio que almacena autores y los libros que han escrito. Cada autor tiene un nombre y una serie de libros que han escrito. Cada libro tiene un nombre y una lista de autores asociados. También queremos poder añadir o recuperar libros y autores. Una UML representación simple de esta relación puede tener este aspecto:

En GraphQL, las entidades Author y Book representan dos tipos de objetos diferentes en el esquema:

type Author {
}

type Book {
}

Author contiene authorName y Books, mientras que Book contiene bookName y Authors. Estos se pueden representar como los campos incluidos en el ámbito de sus tipos:

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

Como puede ver, las representaciones de tipos se parecen mucho al diagrama. Sin embargo, los métodos son algo más complicados. Se colocarán como campo en uno de algunos tipos de objetos especiales. La categorización de los objetos especiales depende de su comportamiento. GraphQL contiene tres tipos de objetos especiales fundamentales: consultas, mutaciones y suscripciones. Para obtener más información sobre los objetos, consulte Objetos especiales.

Como tanto getAuthor como getBook solicitan datos, se colocarán en un tipo de objeto especial de Query:

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

Las operaciones están vinculadas a la consulta, que a su vez está vinculada al esquema. Cuando se añade una raíz de esquema, se define el tipo de objeto especial (en este caso, Query) como uno de los puntos de entrada. Esto se puede hacer con la palabra clave schema:

schema {
  query: Query
}

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

Si nos fijamos en los dos últimos métodos, addAuthor y addBook añaden datos a la base de datos, por lo que se definirán en un tipo de objeto Mutation especial. Sin embargo, por la página Tipos, también sabemos que no se permiten entradas que hagan referencia directamente a objetos porque son estrictamente tipos de salida. En este caso, no podemos usar Author ni Book, por lo que necesitamos crear un tipo de entrada con los mismos campos. En este ejemplo, añadimos AuthorInput yBookInput, que aceptan los mismos campos de sus tipos correspondientes. A continuación, creamos nuestra mutación usando las entradas como parámetros:

schema {
  query: Query
  mutation: Mutation
}

type Author {
  authorName: String
  Books: [Book]
}

input AuthorInput {
  authorName: String
  Books: [BookInput]
}

type Book {
  bookName: String
  Authors: [Author]
}

input BookInput {
  bookName: String
  Authors: [AuthorInput]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

type Mutation {
  addAuthor(input: [BookInput]): Author
  addBook(input: [AuthorInput]): Book
}

Repasemos lo que acabamos de hacer:

Como puede ver, el proceso de creación de un esquema requiere muchos conceptos del modelado de datos (especialmente del modelado de bases de datos) en general. Puede considerarse que el esquema se ajusta a la forma de los datos de la fuente. También sirve como modelo que el solucionador implementará. En las siguientes secciones, aprenderá a crear un esquema utilizando diversas herramientas y servicios AWS respaldados por ellos.

Creación de esquemas

El esquema estará en un archivo llamadoschema.graphql. AWS AppSync permite a los usuarios crear nuevos esquemas para su APIs GraphQL utilizando varios métodos. En este ejemplo, crearemos un espacio en blanco API junto con un esquema en blanco.

Console

1. Inicie sesión en la AppSyncconsola AWS Management Console y ábrala.

   1. En el panel de control, selecciona Crear API.

   2. En APIlas opciones, selecciona GraphQL APIs, Diseñar desde cero y, a continuación, Siguiente.

      1. En APINombre, cambia el nombre rellenado previamente por el que necesite la aplicación.

      2. Para obtener los detalles de contacto, puede introducir un punto de contacto para identificar al administrador delAPI. Se trata de un campo opcional.

      3. En APIConfiguración privada, puede habilitar API las funciones privadas. Solo se API puede acceder a una cuenta privada desde un VPC punto final configurado (VPCE). Para obtener más información, consulte Privado APIs.

         No le recomendamos habilitar esta característica para este ejemplo. Seleccione Siguiente después de revisar sus entradas.

   3. En Crear un tipo de GraphQL, puede elegir crear una tabla de DynamoDB para utilizarla como origen de datos u omitir este paso y hacerlo más adelante.

      Para este ejemplo, elija Crear recursos de GraphQL más adelante. Crearemos un recurso en una sección aparte.

   4. Revisa las entradas y, a continuación, selecciona Crear API.

2. Estarás en el panel de control de tu perfilAPI. Lo notarás porque el API nombre estará en la parte superior del panel de control. Si este no es el caso, puedes seleccionarlo APIsen la barra lateral y, a continuación, elegir el tuyo API en el APIs panel de control.

   1. En la barra lateral situada debajo de tu nombre, selecciona API Esquema.

3. En el Editor de esquemas, puede configurar su archivo schema.graphql. Puede estar vacío o lleno de tipos generados a partir de un modelo. A la derecha, tiene la sección Solucionadores para asociar solucionadores a los campos del esquema. En esta sección no nos fijaremos en los solucionadores.

CLI

nota

Cuando utilices elCLI, asegúrate de tener los permisos correctos para acceder y crear recursos en el servicio. Es posible que desee establecer políticas de privilegios mínimos para los usuarios que no sean administradores y que necesiten acceder al servicio. Para obtener más información sobre AWS AppSync las políticas, consulte Administración de identidad y acceso para AWS AppSync.

Además, le recomendamos leer primero la versión de consola si aún no lo ha hecho.

1. Si aún no lo ha hecho, instálelo AWS CLI y añada su configuración.

2. Cree un API objeto GraphQL ejecutando el create-graphql-apicomando.

   Deberá escribir dos parámetros para este comando concreto:

   1. El name de tus. API

   2. El authentication-type o el tipo de credenciales utilizadas para acceder a API (IAMOIDC,, etc.).

   nota

   Otros parámetros, como los que se Region deben configurar, suelen tener los valores de CLI configuración predeterminados.

   Un comando de ejemplo puede tener este aspecto:

   aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY

   Se devolverá un resultado en elCLI. A continuación se muestra un ejemplo:

   {
       "graphqlApi": {
           "xrayEnabled": false,
           "name": "testAPI123",
           "authenticationType": "API_KEY",
           "tags": {},
           "apiId": "abcdefghijklmnopqrstuvwxyz",
           "uris": {
               "GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql",
               "REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
           },
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz"
       }
   }

3. nota

   Se trata de un comando opcional que toma un esquema existente y lo carga en el servicio de AWS AppSync mediante un blob de base 64. No utilizaremos este comando para este ejemplo.

   Ejecute el comando start-schema-creation.

   Deberá escribir dos parámetros para este comando concreto:

   1. Su api-id del paso anterior.

   2. La definition del esquema es un blob binario codificado en base 64.

   Un comando de ejemplo puede tener este aspecto:

    aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"

   Se devolverá un resultado:

   {
       "status": "PROCESSING"
   }

   Este comando no devolverá el resultado final después del procesamiento. Para ver el resultado, debe usar un comando diferente, get-schema-creation-status. Tenga en cuenta que estos dos comandos son asíncronos, por lo que puede comprobar el estado de la salida incluso mientras se crea el esquema.

CDK

sugerencia

Antes de utilizar elCDK, le recomendamos que revise CDK la documentación oficial junto con AWS AppSync su CDKreferencia.

Los pasos que se indican a continuación solo mostrarán un ejemplo general del fragmento de código utilizado para añadir un recurso concreto. No se pretende que esta sea una solución funcional en su código de producción. También, se presupone que ya tiene una aplicación en funcionamiento.

1. El punto de partida CDK es un poco diferente. Lo ideal es que el archivo schema.graphql ya esté creado. Solo necesita crear un nuevo archivo con la extensión de archivo .graphql. Puede ser un archivo vacío.

2. En general, puede que tenga que añadir la directiva de importación al servicio que utilice. Por ejemplo, puede seguir estas formas:

   import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
   import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'

   Para añadir un GraphQLAPI, tu archivo de pila debe importar el AWS AppSync servicio:

   import * as appsync from 'aws-cdk-lib/aws-appsync';

   nota

   Esto significa que vamos a importar todo el servicio con la palabra clave appsync. Para usar esto en tu aplicación, tus AWS AppSync construcciones usarán el formato. appsync.construct_name Por ejemplo, si quisiéramos hacer un GraphQLAPI, diríamos. new appsync.GraphqlApi(args_go_here) En el siguiente paso se describe esto.

3. El GraphQL más básico API incluirá un name para la ruta API y la schema ruta.

   const add_api = new appsync.GraphqlApi(this, 'API_ID', {
     name: 'name_of_API_in_console',
     schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema_name.graphql')),
   });

   nota

   Repasemos lo que hace este fragmento de código. Dentro del ámbito deapi, estamos creando un nuevo GraphQL API mediante una llamada. appsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps) El alcance es this, que hace referencia al objeto actual. El identificador es API_ID, que será el nombre API del recurso de GraphQL AWS CloudFormation cuando se cree. GraphqlApiPropsContiene el name de su GraphQL API y el. schema schemaGenerará un esquema (SchemaFile.fromAsset) buscando la ruta absoluta (__dirname) del .graphql archivo (schema_name.graphql). En un escenario real, es probable que el archivo de esquema esté dentro de la CDK aplicación.

   Para usar los cambios realizados en tu GraphQLAPI, tendrás que volver a implementar la aplicación.

Adición de tipos a los esquemas

Ahora que ha añadido su esquema, puede empezar a agregar los tipos tanto de entrada como de salida. Tenga en cuenta que los tipos que aparecen aquí no deben usarse en código real; son solo ejemplos que le ayudarán a entender el proceso.

En primer lugar, crearemos un tipo de objeto. En el código real, no es necesario empezar con estos tipos. Puede crear cualquier tipo que desee en cualquier momento siempre que siga las reglas y la sintaxis de GraphQL.

Console

• Puede crear un tipo de objeto utilizando la palabra clave type junto con el nombre del tipo:

  type Type_Name_Goes_Here {}

  Dentro del ámbito del tipo, puede añadir campos que representen las características del objeto:

  type Type_Name_Goes_Here {
    # Add fields here
  }

  A continuación se muestra un ejemplo:

  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }

  nota

  En este paso, hemos añadido un tipo de objeto genérico con un campo id obligatorio almacenado como ID, un campo title almacenado como String y un campo date almacenado como AWSDateTime. Para ver una lista de tipos y campos, y lo que hacen, consulte Esquemas. Para ver una lista de escalares y lo que hacen, consulte Referencia de tipos.

CLI

nota

Le recomendamos leer primero la versión de consola si aún no lo ha hecho.

• Puede crear un tipo de objeto ejecutando el comando create-type.

  Para este comando en particular, deberá introducir varios parámetros:

  1. El api-id de tus. API

  2. La definition o el contenido de su tipo. En el ejemplo de la consola, esto era:

     type Obj_Type_1 {
       id: ID!
       title: String
       date: AWSDateTime
     }

  3. El format de su entrada. En este ejemplo, usaremos SDL.

  Un comando de ejemplo puede tener este aspecto:

  aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Obj_Type_1{id: ID! title: String date: AWSDateTime}" --format SDL

  Se devolverá una salida en elCLI. A continuación se muestra un ejemplo:

  {
      "type": {
          "definition": "type Obj_Type_1{id: ID! title: String date: AWSDateTime}",
          "name": "Obj_Type_1",
          "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Obj_Type_1",
          "format": "SDL"
      }
  }

  nota

  En este paso, hemos añadido un tipo de objeto genérico con un campo id obligatorio almacenado como ID, un campo title almacenado como String y un campo date almacenado como AWSDateTime. Para ver una lista de tipos y campos, y lo que hacen, consulte Esquemas. Para ver una lista de escalares y lo que hacen, consulte Referencia de tipos.

  Por otra parte, puede que se haya dado cuenta de que introducir la definición directamente funciona para tipos más pequeños pero no es factible para añadir tipos más grandes o múltiples. Puede optar por añadir todo el contenido en un archivo .graphql y, a continuación, pasarlo como entrada.

CDK

sugerencia

Antes de utilizar elCDK, le recomendamos que revise CDK la documentación oficial junto con AWS AppSync su CDKreferencia.

Los pasos que se indican a continuación solo mostrarán un ejemplo general del fragmento de código utilizado para añadir un recurso concreto. No se pretende que esta sea una solución funcional en su código de producción. También, se presupone que ya tiene una aplicación en funcionamiento.

Para añadir un tipo, debe añadirlo a su archivo .graphql. El ejemplo de la consola era:

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

Puede añadir sus tipos directamente al esquema como cualquier otro archivo.

nota

Para usar los cambios realizados en tu GraphQLAPI, tendrás que volver a implementar la aplicación.

El tipo de objeto tiene campos que son de tipo escalar, como cadenas y números enteros. AWS AppSync también te permite usar tipos escalares mejorados, AWSDateTime además de los escalares básicos de GraphQL. Además, todos los campos que terminen con un signo de exclamación son obligatorios.

El tipo escalar ID en concreto es un identificador exclusivo que puede ser String o Int. Puede controlarlos en el código de resolución para la asignación automática.

Existen similitudes entre los tipos de objetos especiales, como Query y los tipos de objetos “normales”, como en el ejemplo anterior, en el sentido de que ambos utilizan la palabra clave type y se consideran objetos. Sin embargo, en el caso de los tipos de objetos especiales (QueryMutation, ySubscription), su comportamiento es muy diferente, ya que se exponen como puntos de entrada al tuyo. API También se centran más en dar forma a las operaciones que a los datos. Para obtener más información, consulte la sección sobre tipos de consultas y mutaciones.

En cuanto a los tipos de objetos especiales, el siguiente paso podría ser añadir uno o más para realizar operaciones con los datos con forma. En un escenario real, cada esquema de GraphQL debe tener al menos un tipo de consulta raíz para solicitar datos. Puede considerar la consulta como uno de los puntos de entrada (o puntos de conexión) de su servidor GraphQL. Añadamos una consulta como ejemplo.

Console

• Para crear una consulta, basta con añadirla al archivo de esquema como cualquier otro tipo. Una consulta requeriría un tipo Query y una entrada en la raíz de la manera siguiente:

  schema {
    query: Name_of_Query
  }
  
  type Name_of_Query {
    # Add field operation here
  }

  Ten en cuenta que Name_of_Query en un entorno de producción simplemente se llamará Query en la mayoría de los casos. Se recomienda mantenerlo en este valor. Dentro del tipo de consulta, puede añadir campos. Cada campo realizará una operación en la solicitud. El resultado es que la mayoría de estos campos, si no todos, se asociarán a un solucionador. Sin embargo, en esta sección o abordaremos eso. En cuanto al formato de la operación de campo, podría ser como este:

  Name_of_Query(params): Return_Type # version with params
  Name_of_Query: Return_Type # version without params

  A continuación se muestra un ejemplo:

  schema {
    query: Query
  }
  
  type Query {
    getObj: [Obj_Type_1]
  }
  
  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }

  nota

  En este paso, agregamos un tipo Query y lo definimos en nuestra raíz de schema. Nuestro tipo Query definió un campo getObj que devuelve una lista de objetos Obj_Type_1. Tenga en cuenta que Obj_Type_1 es el objeto del paso anterior. En el código de producción, sus operaciones de campo normalmente funcionarán con datos moldeados por objetos como Obj_Type_1. Además, campos como getObj suelen tener un solucionador para ejecutar la lógica empresarial. Este tema se tratará en otra sección.

  Como nota adicional, agrega AWS AppSync automáticamente una raíz del esquema durante las exportaciones, por lo que técnicamente no es necesario agregarla directamente al esquema. Nuestro servicio procesará automáticamente los esquemas duplicados. Lo añadimos aquí como práctica recomendada.

CLI

nota

Le recomendamos leer primero la versión de consola si aún no lo ha hecho.

1. Cree una raíz de schema con una definición query ejecutando el comando create-type.

   Para este comando en particular, deberá introducir varios parámetros:

   1. El api-id de tusAPI.

   2. La definition o el contenido de su tipo. En el ejemplo de la consola, esto era:

      schema {
        query: Query
      }

   3. El format de su entrada. En este ejemplo, usaremos SDL.

   Un comando de ejemplo puede tener este aspecto:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL

   Se devolverá una salida en elCLI. A continuación se muestra un ejemplo:

   {
       "type": {
           "definition": "schema {query: Query}",
           "name": "schema",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

   nota

   Tenga en cuenta que si no ha introducido algo correctamente en el comando create-type, puede actualizar la raíz del esquema (o cualquier tipo del esquema) ejecutando el comando update-type. En este ejemplo, cambiaremos temporalmente la raíz del esquema para que contenga una definición de subscription.

   Para este comando en particular, deberá introducir varios parámetros:

   1. El api-id de tusAPI.

   2. El type-name de su tipo. En el ejemplo de la consola, esto era schema.

   3. La definition o el contenido de su tipo. En el ejemplo de la consola, esto era:

      schema {
        query: Query
      }

      El esquema después de añadir una subscription será como el siguiente:

      schema {
        query: Query
        subscription: Subscription
      }

   4. El format de su entrada. En este ejemplo, usaremos SDL.

   Un comando de ejemplo puede tener este aspecto:

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL

   Se devolverá una salida en elCLI. A continuación se muestra un ejemplo:

   {
       "type": {
           "definition": "schema {query: Query subscription: Subscription}",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

   En este ejemplo, seguirá funcionando la adición de archivos preformateados.

2. Cree un tipo de Query ejecutando el comando create-type.

   Para este comando en particular, deberá introducir varios parámetros:

   1. El api-id de tusAPI.

   2. La definition o el contenido de su tipo. En el ejemplo de la consola, esto era:

      type Query {
        getObj: [Obj_Type_1]
      }

   3. El format de su entrada. En este ejemplo, usaremos SDL.

   Un comando de ejemplo puede tener este aspecto:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL

   Se devolverá una salida en elCLI. A continuación se muestra un ejemplo:

   {
       "type": {
           "definition": "Query {getObj: [Obj_Type_1]}",
           "name": "Query",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
           "format": "SDL"
       }
   }

   nota

   En este paso, hemos añadido un tipo Query y lo hemos definido en su raíz de schema. Nuestro tipo Query ha definido un campo getObj que devuelve una lista de objetos Obj_Type_1.

   En el código de raíz de schema query: Query, la parte query: indica que se ha definido una consulta en el esquema, mientras que la parte Query indica el nombre real del objeto especial.

CDK

sugerencia

Antes de utilizar elCDK, le recomendamos que revise CDK la documentación oficial junto con AWS AppSync su CDKreferencia.

Los pasos que se indican a continuación solo mostrarán un ejemplo general del fragmento de código utilizado para añadir un recurso concreto. No se pretende que esta sea una solución funcional en su código de producción. También, se presupone que ya tiene una aplicación en funcionamiento.

Deberá añadir la consulta y la raíz del esquema al archivo .graphql. Nuestro caso era parecido al ejemplo siguiente, pero en este lo sustituirá con su código de esquema actual:

schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

Puede añadir sus tipos directamente al esquema como cualquier otro archivo.

nota

Actualizar la raíz del esquema es opcional. Lo hemos añadido a este ejemplo como práctica recomendada.

Para usar los cambios realizados en tu GraphQLAPI, tendrás que volver a implementar la aplicación.

Ahora ya ha visto un ejemplo de creación tanto de objetos como de objetos especiales (consultas). También ha visto cómo se pueden interconectar para describir datos y operaciones. Puede tener esquemas con solo la descripción de los datos y una o más consultas. Sin embargo, nos gustaría añadir otra operación para añadir datos al origen de datos. Vamos a añadir otro tipo de objeto especial denominado Mutation que modifica los datos.

Console

• Una mutación se llamará Mutation. Como en Query, las operaciones de campo de dentro de Mutation describirán una operación y se asociarán a un solucionador. Tenga en cuenta también que debemos definirla en la raíz schema porque es un tipo de objeto especial. Aquí tiene un ejemplo de mutación:

  schema {
    mutation: Name_of_Mutation
  }
  
  type Name_of_Mutation {
    # Add field operation here
  }

  Una mutación típica aparecerá en la raíz en forma de consulta. La mutación se define mediante la palabra clave type junto con el nombre. Name_of_Mutation normalmente se llamaráMutation, por lo que te recomendamos que la mantengas así. Cada campo realizará también una operación. En cuanto al formato de la operación de campo, podría ser como este:

  Name_of_Mutation(params): Return_Type # version with params
  Name_of_Mutation: Return_Type # version without params

  A continuación se muestra un ejemplo:

  schema {
    query: Query
    mutation: Mutation
  }
  
  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }
  
  type Query {
    getObj: [Obj_Type_1]
  }
  
  type Mutation {
    addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
  }

  nota

  En este paso, hemos añadido un tipo Mutation con un campo addObj. Vamos a resumir lo que hace este campo:

  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1

  addObj está utilizando el objeto Obj_Type_1 para realizar una operación. Esto es evidente debido a los campos, pero la sintaxis lo demuestra en el tipo de retorno : Obj_Type_1. Dentro de addObj, acepta los campos id, title y date del objeto Obj_Type_1 como parámetros. Como puede ver, es muy parecido a la declaración de un método. Sin embargo, aún no hemos descrito el comportamiento de nuestro método. Como se ha afirmado antes, el esquema solo está ahí para definir cuáles serán los datos y las operaciones, no cómo funcionan. La lógica empresarial real se implementará más adelante, cuando creemos nuestros primeros solucionadores.

  Una vez que haya terminado con su esquema, hay una opción para exportarlo como archivo schema.graphql. En el editor de esquemas, puede elegir Exportar esquema para descargar el archivo en un formato compatible.

  Como nota adicional, agrega AWS AppSync automáticamente una raíz del esquema durante las exportaciones, por lo que técnicamente no es necesario agregarla directamente al esquema. Nuestro servicio procesará automáticamente los esquemas duplicados. Lo añadimos aquí como práctica recomendada.

CLI

nota

Le recomendamos leer primero la versión de consola si aún no lo ha hecho.

1. Actualice su esquema de raíz ejecutando el comando update-type.

   Para este comando en particular, deberá introducir varios parámetros:

   1. El api-id de tusAPI.

   2. El type-name de su tipo. En el ejemplo de la consola, esto era schema.

   3. La definition o el contenido de su tipo. En el ejemplo de la consola, esto era:

      schema {
        query: Query
        mutation: Mutation
      }

   4. El format de su entrada. En este ejemplo, usaremos SDL.

   Un comando de ejemplo puede tener este aspecto:

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL

   Se devolverá una salida en elCLI. A continuación se muestra un ejemplo:

   {
       "type": {
           "definition": "schema {query: Query mutation: Mutation}",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

2. Cree un tipo de Mutation ejecutando el comando create-type.

   Para este comando en particular, deberá introducir varios parámetros:

   1. El api-id de tusAPI.

   2. La definition o el contenido de su tipo. En el ejemplo de la consola, esto era:

      type Mutation {
        addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
      }

   3. El format de su entrada. En este ejemplo, usaremos SDL.

   Un comando de ejemplo puede tener este aspecto:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}" --format SDL

   Se devolverá una salida en elCLI. A continuación se muestra un ejemplo:

   {
       "type": {
           "definition": "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}",
           "name": "Mutation",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation",
           "format": "SDL"
       }
   }

CDK

sugerencia

Antes de utilizar elCDK, le recomendamos que revise CDK la documentación oficial junto con AWS AppSync su CDKreferencia.

Los pasos que se indican a continuación solo mostrarán un ejemplo general del fragmento de código utilizado para añadir un recurso concreto. No se pretende que esta sea una solución funcional en su código de producción. También, se presupone que ya tiene una aplicación en funcionamiento.

Deberá añadir la consulta y la raíz del esquema al archivo .graphql. Nuestro caso era parecido al ejemplo siguiente, pero en este lo sustituirá con su código de esquema actual:

schema {
  query: Query
  mutation: Mutation
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

type Query {
  getObj: [Obj_Type_1]
}

type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}

nota

Actualizar la raíz del esquema es opcional. Lo hemos añadido a este ejemplo como práctica recomendada.

Para usar los cambios realizados en tu GraphQLAPI, tendrás que volver a implementar la aplicación.

Consideraciones opcionales: uso de enumeraciones como estados

Llegados a este punto, ya sabe cómo hacer un esquema básico. Sin embargo, hay muchas cosas que se pueden añadir para aumentar la funcionalidad del esquema. Una característica común que se encuentra en las aplicaciones es el uso de enumeraciones como estados. Puede usar una enumeración para forzar la elección de un valor específico de un conjunto de valores cuando se invoque. Esto es adecuado para cosas que sabe que no van a cambiar drásticamente durante largos períodos de tiempo. Hipotéticamente, podríamos añadir una enumeración que devuelva el código de estado o cadena en la respuesta.

Como ejemplo, supongamos que vamos a crear una aplicación de redes sociales que almacene los datos de las publicaciones de un usuario en el backend. Nuestro esquema contiene un tipo Post que representa los datos de una publicación individual:

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

Nuestra Post contendrá un id único, un título de title, una date de publicación y una enumeración denominada PostStatus que representa el estado de la publicación a medida que la aplicación la procesa. Para nuestras operaciones, tendremos una consulta que devolverá todos los datos de la publicación:

type Query {
  getPosts: [Post]
}

También tendremos una mutación que añade publicaciones al origen de datos:

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

Si observamos nuestro esquema, la enumeración PostStatus podría tener varios estados. Tal vez que queramos que los tres estados básicos se llamen success (publicación procesada correctamente), pending (publicación procesada) y error (publicación que no se puede procesar). Para añadir la enumeración, podemos hacer lo siguiente:

enum PostStatus {
  success
  pending
  error
}

El esquema completo podría ser como este:

schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts: [Post]
}

enum PostStatus {  
  success
  pending
  error
}

Si un usuario añade una Post en la aplicación, se llamará a la operación addPost para procesar esos datos. A medida que el solucionador adjunto a addPost procese los datos, actualizará continuamente poststatus con el estado de la operación. Cuando se consulte, Post contendrá el estado final de los datos. Tenga en cuenta que solo estamos describiendo cómo queremos que funcionen los datos en el esquema. Estamos haciendo muchas suposiciones sobre la implementación de nuestros solucionadores, que implementarán la lógica empresarial real para gestionar los datos a fin de cumplir con la solicitud.

Consideraciones opcionales: suscripciones

Las suscripciones en AWS AppSync se invocan como respuesta a una mutación. Se puede configurar con un tipo Subscription y una directiva @aws_subscribe() en el esquema para indicar qué mutaciones invocan una o varias suscripciones. Para obtener más información sobre cómo configurar suscripciones, consulte Datos en tiempo real.

Consideraciones opcionales: relaciones y paginación

Supongamos que tiene un millón de Posts almacenadas en una tabla de DynamoDB y desea devolver algunos de esos datos. Sin embargo, la consulta de ejemplo anterior solo devuelve todas las publicaciones. No le interesa buscarlas todas cada vez que realice una solicitud. Más bien, le interesa paginarlas. Realice los cambios siguientes en su esquema:

schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts(limit: Int, nextToken: String): PostIterator
}

enum PostStatus {
  success
  pending
  error
}

type PostIterator {
  posts: [Post]
  nextToken: String
}

El tipo PostIterator le permite devolver una parte de la lista de objetos de Post y un nextToken para obtener la parte siguiente. Dentro de PostIterator, hay una lista de elementos de Post ([Post]) que se devuelve con un token de paginación (nextToken). En AWS AppSync, se conectaría a Amazon DynamoDB a través de un solucionador y se generaría automáticamente como un token cifrado. Así se convierte el valor del argumento limit en el parámetro maxResults y el argumento nextToken en el parámetro exclusiveStartKey. Para ver ejemplos y los ejemplos de plantillas integradas en la AWS AppSync consola, consulte Resolver reference () JavaScript.