Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Conception de GraphQL APIs avec AWS AppSync
AWS AppSync vous permet de créer GraphQL à APIs l'aide de l'expérience de la console. Vous en avez eu un aperçu dans la section [Lancement d'un exemple de schéma](https://docs.aws.amazon.com/appsync/latest/devguide/quickstart.html). Cependant, ce guide ne présentait pas le catalogue complet des options et des configurations que vous pouviez exploiter AWS AppSync.
Lorsque vous choisissez de créer une API GraphQL dans la console, plusieurs options s'offrent à vous. Si vous avez suivi notre guide de [lancement d'un exemple de schéma](https://docs.aws.amazon.com/appsync/latest/devguide/quickstart.html), nous vous avons montré comment créer une API à partir d'un modèle prédéfini. Dans les sections suivantes, nous vous expliquerons les autres options et configurations permettant de créer GraphQL APIs dans. AWS AppSync
Dans cette section, vous allez passer en revue les concepts suivants :
1. [Blank APIs or imports](blank-import-api.md#aws-appsync-blank-import-api): Ce guide décrit l'intégralité du processus de création d'une API GraphQL. Vous apprendrez à créer un GraphQL à partir d'un modèle vierge sans modèle, à configurer des sources de données pour votre schéma et à ajouter votre premier résolveur à un champ.
1. [Real-time data](aws-appsync-real-time-data.md#aws-appsync-real-time-data-anchor): Ce guide vous montrera les options potentielles pour créer une API à l'aide AWS AppSync du WebSocket moteur.
1. [Merged APIs](merged-api.md#aws-appsync-merged-api): Ce guide explique comment créer un nouveau GraphQL en associant et APIs en fusionnant des données provenant de plusieurs GraphQL existants. APIs
1. [Création de GraphQL APIs avec l'introspection RDS](rds-introspection.md): Ce guide explique comment intégrer vos tables Amazon RDS à l'aide d'une API de données.
# Structuration d'une API GraphQL (vide ou importée) APIs
Avant de créer votre API GraphQL à partir d'un modèle vierge, il serait utile de passer en revue les concepts qui entourent GraphQL. Une API GraphQL comporte trois composants fondamentaux :
1. Le **schéma** est le fichier contenant la forme et la définition de vos données. Lorsqu'un client envoie une demande à votre service GraphQL, les données renvoyées suivent les spécifications du schéma. Pour de plus amples informations, veuillez consulter [Schémas GraphQL](schema-components.md#aws-appsync-schema-components).
1. La **source de données** est attachée à votre schéma. Lorsqu'une demande est faite, c'est ici que les données sont récupérées et modifiées. Pour de plus amples informations, veuillez consulter [Sources de données](data-source-components.md#aws-appsync-data-source-components).
1. Le **résolveur** se trouve entre le schéma et la source de données. Lorsqu'une demande est faite, le résolveur effectue l'opération sur les données de la source, puis renvoie le résultat sous forme de réponse. Pour de plus amples informations, veuillez consulter [Résolveurs](resolver-components.md#aws-appsync-resolver-components).
![\[GraphQL API architecture showing schema, resolvers, and data sources connected via AppSync.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/appsync-architecture-graphql-api.png)
AWS AppSync gère le vôtre APIs en vous permettant de créer, de modifier et de stocker le code de vos schémas et résolveurs. Vos sources de données proviendront de référentiels externes tels que des bases de données, des tables DynamoDB et des fonctions Lambda. Si vous utilisez un AWS service pour stocker vos données ou si vous envisagez de le faire, AWS AppSync offre une expérience quasiment fluide lorsque vous associez les données de vos AWS comptes à votre GraphQL APIs.
Dans la section suivante, vous allez apprendre à créer chacun de ces composants à l'aide du AWS AppSync service.
**Topics**
+ [Conception de votre schéma GraphQL](designing-your-schema.md)
+ [Joindre une source de données](attaching-a-data-source.md)
+ [Configuration des AWS AppSync résolveurs](resolver-config-overview.md)
+ [Utilisation APIs avec le CDK](using-your-api.md)
# Conception de votre schéma GraphQL
Le schéma GraphQL est la base de toute implémentation de serveur GraphQL. Chaque API GraphQL est définie par un schéma **unique** qui contient des types et des champs décrivant la manière dont les données des demandes seront renseignées. Les données qui transitent par votre API et les opérations effectuées doivent être validées par rapport au schéma.
En général, le [système de type GraphQL](https://graphql.org/learn/schema/#type-system) décrit les fonctionnalités d'un serveur GraphQL et est utilisé pour déterminer si une requête est valide. Le système de types d'un serveur est souvent appelé schéma de ce serveur et peut être composé de différents types d'objets, de types scalaires, de types d'entrée, etc. GraphQL est à la fois déclaratif et fortement typé, ce qui signifie que les types seront bien définis lors de l'exécution et ne renverront que ce qui a été spécifié.
AWS AppSync vous permet de définir et de configurer des schémas GraphQL. La section suivante décrit comment créer des schémas GraphQL à partir de zéro à l'aide AWS AppSync des services.
## Structuration d'un schéma GraphQL
**Astuce**
Nous vous recommandons de consulter la section [Schémas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html) avant de continuer.
GraphQL est un outil puissant pour implémenter des services d'API. Selon le [site Web de GraphQL,](https://graphql.org/) GraphQL est le suivant :
« *GraphQL est un langage de requête APIs et un environnement d'exécution permettant de répondre à ces requêtes avec vos données existantes. GraphQL fournit une description complète et compréhensible des données de votre API, donne aux clients le pouvoir de demander exactement ce dont ils ont besoin et rien de plus, facilite l'évolution au APIs fil du temps et permet de puissants outils de développement.* «
Cette section couvre la toute première partie de votre implémentation GraphQL, le schéma. En utilisant la citation ci-dessus, un schéma joue le rôle de « fournir une description complète et compréhensible des données de votre API ». En d'autres termes, un schéma GraphQL est une représentation textuelle des données, des opérations et des relations entre les données de votre service. Le schéma est considéré comme le point d'entrée principal pour l'implémentation de votre service GraphQL. Comme on pouvait s'y attendre, c'est souvent l'une des premières choses que vous réalisez dans votre projet. Nous vous recommandons de consulter la section [Schémas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html) avant de continuer.
Pour citer la section [Schémas, les schémas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html) GraphQL sont écrits dans le langage SDL (*Schema Definition* Language). SDL est composé de types et de champs dotés d'une structure établie :
+ **Types** : Les types sont la façon dont GraphQL définit la forme et le comportement des données. GraphQL prend en charge une multitude de types qui seront expliqués plus loin dans cette section. Chaque type défini dans votre schéma contiendra sa propre portée. Le champ d'application comportera un ou plusieurs champs pouvant contenir une valeur ou une logique qui sera utilisée dans votre service GraphQL. Les types remplissent de nombreux rôles différents, les plus courants étant les objets ou les scalaires (types de valeurs primitives).
+ **Champs** : les champs existent dans le cadre d'un type et contiennent la valeur demandée au service GraphQL. Elles sont très similaires aux variables d'autres langages de programmation. La forme des données que vous définissez dans vos champs déterminera la manière dont les données sont structurées lors d'une request/response opération. Cela permet aux développeurs de prévoir ce qui sera renvoyé sans savoir comment le backend du service est implémenté.
Les schémas les plus simples contiendront trois catégories de données différentes :
1. **Racines du schéma** : les racines définissent les points d'entrée de votre schéma. Il indique les champs qui effectueront certaines opérations sur les données, telles que l'ajout, la suppression ou la modification de quelque chose.
1. **Types** : il s'agit de types de base utilisés pour représenter la forme des données. Vous pouvez presque les considérer comme des objets ou des représentations abstraites de quelque chose avec des caractéristiques définies. Par exemple, vous pouvez créer un `Person` objet représentant une personne dans une base de données. Les caractéristiques de chaque personne seront définies dans les champs `Person` as. Ils peuvent être n'importe quoi comme le nom, l'âge, le travail, l'adresse de la personne, etc.
1. **Types d'objets spéciaux** : ce sont les types qui définissent le comportement des opérations dans votre schéma. Chaque type d'objet spécial est défini une fois par schéma. Ils sont d'abord placés dans la racine du schéma, puis définis dans le corps du schéma. Chaque champ d'un type d'objet spécial définit une opération unique à implémenter par votre résolveur.
Pour mettre les choses en perspective, imaginez que vous créez un service qui stocke les auteurs et les livres qu'ils ont écrits. Chaque auteur a un nom et une liste de livres qu'il a écrits. Chaque livre a un nom et une liste d'auteurs associés. Nous voulons également pouvoir ajouter ou récupérer des livres et des auteurs. Une représentation UML simple de cette relation peut ressembler à ceci :
![\[UML diagram showing Author and Book classes with attributes and methods, linked by association.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/GraphQL-UML-1.png)
Dans GraphQL, les entités `Author` et B `Book` représentent deux types d'objets différents dans votre schéma :
```
type Author {
}
type Book {
}
```
`Author`contient `authorName` et`Books`, tandis que `Book` contient `bookName` et`Authors`. Ceux-ci peuvent être représentés sous la forme de champs correspondant à vos types :
```
type Author {
authorName: String
Books: [Book]
}
type Book {
bookName: String
Authors: [Author]
}
```
Comme vous pouvez le constater, les représentations de type sont très proches du diagramme. Cependant, c'est dans les méthodes que cela devient un peu plus délicat. Ils seront placés dans l'un des rares types d'objets spéciaux sous forme de champ. La catégorisation des objets spéciaux dépend de leur comportement. GraphQL contient trois types d'objets spéciaux fondamentaux : les requêtes, les mutations et les abonnements. Pour plus d'informations, consultez la section [Objets spéciaux](https://docs.aws.amazon.com//appsync/latest/devguide/graphql-types.html#special-object-components).
Parce que `getAuthor` `getBook` les deux demandent des données, elles seront placées dans un type d'objet `Query` spécial :
```
type Author {
authorName: String
Books: [Book]
}
type Book {
bookName: String
Authors: [Author]
}
type Query {
getAuthor(authorName: String): Author
getBook(bookName: String): Book
}
```
Les opérations sont liées à la requête, elle-même liée au schéma. L'ajout d'une racine de schéma définira le type d'objet spécial (`Query`dans ce cas) comme l'un de vos points d'entrée. Cela peut être fait en utilisant le `schema` mot clé :
```
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
}
```
Examinez les deux dernières méthodes `addAuthor` et ajoutez `addBook` des données à votre base de données, afin qu'elles soient définies dans un type d'objet `Mutation` spécial. Cependant, depuis la page [Types](https://docs.aws.amazon.com/appsync/latest/devguide/graphql-types.html#input-components), nous savons également que les entrées faisant directement référence à des objets ne sont pas autorisées car il s'agit uniquement de types de sortie. Dans ce cas, nous ne pouvons pas utiliser `Author` ou`Book`, nous devons donc créer un type de saisie avec les mêmes champs. Dans cet exemple, nous avons ajouté `AuthorInput` et`BookInput`, qui acceptent tous deux les mêmes champs de leurs types respectifs. Ensuite, nous créons notre mutation en utilisant les entrées comme paramètres :
```
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
}
```
Passons en revue ce que nous venons de faire :
1. Nous avons créé un schéma avec les `Author` types `Book` et pour représenter nos entités.
1. Nous avons ajouté les champs contenant les caractéristiques de nos entités.
1. Nous avons ajouté une requête pour récupérer ces informations dans la base de données.
1. Nous avons ajouté une mutation pour manipuler les données de la base de données.
1. Nous avons ajouté des types d'entrée pour remplacer les paramètres de nos objets dans la mutation afin de respecter les règles de GraphQL.
1. Nous avons ajouté la requête et la mutation à notre schéma racine afin que l'implémentation GraphQL comprenne l'emplacement du type de racine.
Comme vous pouvez le constater, le processus de création d'un schéma repose sur de nombreux concepts issus de la modélisation des données (en particulier de la modélisation de base de données) en général. Vous pouvez considérer le schéma comme s'adaptant à la forme des données provenant de la source. Il sert également de modèle que le résolveur implémentera. Dans les sections suivantes, vous allez apprendre à créer un schéma à l'aide de divers outils et services AWS basés sur des outils.
**Note**
Les exemples présentés dans les sections suivantes ne sont pas destinés à être exécutés dans une application réelle. Ils ne sont là que pour présenter les commandes afin que vous puissiez créer vos propres applications.
## Création de schémas
Votre schéma figurera dans un fichier appelé`schema.graphql`. AWS AppSync permet aux utilisateurs de créer de nouveaux schémas pour leur APIs GraphQL en utilisant différentes méthodes. Dans cet exemple, nous allons créer une API vide avec un schéma vide.
------
#### [ Console ]
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **Tableau de bord**, choisissez **Créer une API**.
1. **Dans **les options de l'API**, choisissez **GraphQL APIs**, **Design from scratch**, puis Next.**
1. Pour le **nom de l'API**, modifiez le nom prérempli en fonction des besoins de votre application.
1. Pour les **coordonnées**, vous pouvez saisir un point de contact afin d'identifier un responsable de l'API. Il s'agit d'un champ facultatif.
1. Dans **Configuration de l'API privée**, vous pouvez activer les fonctionnalités de l'API privée. Une API privée n'est accessible qu'à partir d'un point de terminaison VPC configuré (VPCE). Pour plus d'informations, voir [Privé APIs](https://docs.aws.amazon.com/appsync/latest/devguide/using-private-apis.html).
Nous ne recommandons pas d'activer cette fonctionnalité pour cet exemple. Choisissez **Next** après avoir examiné vos entrées.
1. Sous **Créer un type GraphQL**, vous pouvez choisir de créer une table DynamoDB à utiliser comme source de données ou de l'ignorer pour le faire ultérieurement.
Pour cet exemple, choisissez **Create GraphQL resources later**. Nous allons créer une ressource dans une section séparée.
1. Passez en revue vos entrées, puis choisissez **Create API**.
1. Vous serez dans le tableau de bord de votre API spécifique. Vous pouvez le savoir, car le nom de l'API figurera en haut du tableau de bord. Si ce n'est pas le cas, vous pouvez sélectionner **APIs**dans la **barre latérale**, puis choisir votre API dans le **APIs tableau de bord**.
1. Dans la **barre latérale** située sous le nom de votre API, choisissez **Schema**.
1. Dans l'**éditeur de schéma**, vous pouvez configurer votre `schema.graphql` fichier. Il peut être vide ou rempli de types générés à partir d'un modèle. Sur la droite, vous avez la section **Résolveurs** pour associer des résolveurs aux champs de votre schéma. Nous n'examinerons pas les résolveurs dans cette section.
------
#### [ CLI ]
**Note**
Lorsque vous utilisez la CLI, assurez-vous de disposer des autorisations appropriées pour accéder au service et en créer des ressources. Vous souhaiterez peut-être définir des politiques [de moindre privilège](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) pour les utilisateurs non administrateurs qui ont besoin d'accéder au service. Pour plus d'informations sur AWS AppSync les politiques, consultez la section [Gestion des identités et des accès pour AWS AppSync](https://docs.aws.amazon.com//appsync/latest/devguide/security-iam.html).
En outre, nous vous recommandons de lire d'abord la version console si ce n'est pas déjà fait.
1. Si ce n'est pas déjà fait, [installez](https://docs.aws.amazon.com//cli/latest/userguide/cli-chap-getting-started.html) la AWS CLI, puis ajoutez votre [configuration](https://docs.aws.amazon.com//cli/latest/userguide/cli-configure-quickstart.html).
1. Créez un objet d'API GraphQL en exécutant la [https://docs.aws.amazon.com/cli/latest/reference/appsync/create-graphql-api.html](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-graphql-api.html)commande.
Vous devez saisir deux paramètres pour cette commande en particulier :
1. Celui `name` de votre API.
1. Le ou `authentication-type` le type d'informations d'identification utilisées pour accéder à l'API (IAM, OIDC, etc.).
**Note**
D'autres paramètres, tels que ceux qui `Region` doivent être configurés, sont généralement définis par défaut sur les valeurs de configuration de votre CLI.
Voici un exemple de commande :
```
aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"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"
}
}
```
1.
**Note**
Il s'agit d'une commande facultative qui prend un schéma existant et le télécharge vers le AWS AppSync service à l'aide d'un blob en base 64. Nous n'utiliserons pas cette commande pour les besoins de cet exemple.
Exécutez la commande [https://docs.aws.amazon.com/cli/latest/reference/appsync/start-schema-creation.html](https://docs.aws.amazon.com/cli/latest/reference/appsync/start-schema-creation.html).
Vous devez saisir deux paramètres pour cette commande en particulier :
1. C'est ce que vous `api-id` avez fait à l'étape précédente.
1. Le schéma `definition` est un blob binaire codé en base 64.
Voici un exemple de commande :
```
aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"
```
Une sortie sera renvoyée :
```
{
"status": "PROCESSING"
}
```
Cette commande ne renverra pas le résultat final après le traitement. Vous devez utiliser une commande séparée pour voir le résultat. [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/get-schema-creation-status.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/get-schema-creation-status.html) Notez que ces deux commandes sont asynchrones. Vous pouvez donc vérifier l'état de sortie même pendant la création du schéma.
------
#### [ CDK ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
1. Le point de départ du CDK est un peu différent. Idéalement, votre `schema.graphql` fichier devrait déjà être créé. Il vous suffit de créer un nouveau fichier avec l'extension de `.graphql` fichier. Il peut s'agir d'un fichier vide.
1. En général, vous devrez peut-être ajouter la directive d'importation au service que vous utilisez. Par exemple, il peut suivre les formes suivantes :
```
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'
```
Pour ajouter une API GraphQL, votre fichier de pile doit importer le AWS AppSync service :
```
import * as appsync from 'aws-cdk-lib/aws-appsync';
```
**Note**
Cela signifie que nous importons l'intégralité du service sous le `appsync` mot clé. Pour l'utiliser dans votre application, vos AWS AppSync constructions utiliseront le format`appsync.construct_name`. Par exemple, si nous voulions créer une API GraphQL, nous dirions. `new appsync.GraphqlApi(args_go_here)` L'étape suivante illustre cela.
1. L'API GraphQL la plus basique inclura un `name` pour l'API et le `schema` chemin.
```
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')),
});
```
**Note**
Voyons ce que fait cet extrait. Dans le cadre de`api`, nous créons une nouvelle API GraphQL en appelant. `appsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps)` La portée est`this`, qui fait référence à l'objet actuel. L'identifiant est*API\$1ID*, qui sera le nom de la ressource de votre API GraphQL CloudFormation lors de sa création. Le `GraphqlApiProps` `name` contient votre API GraphQL et le. `schema` Le `schema` va générer un schéma (`SchemaFile.fromAsset`) en recherchant le chemin absolu (`__dirname`) du `.graphql` fichier (*schema\$1name.graphql*). Dans un scénario réel, votre fichier de schéma se trouvera probablement dans l'application CDK.
Pour utiliser les modifications apportées à votre API GraphQL, vous devez redéployer l'application.
------
## Ajouter des types aux schémas
Maintenant que vous avez ajouté votre schéma, vous pouvez commencer à ajouter vos types d'entrée et de sortie. Notez que les types présentés ici ne doivent pas être utilisés dans le code réel ; ce ne sont que des exemples destinés à vous aider à comprendre le processus.
Nous allons d'abord créer un type d'objet. Dans le code réel, il n'est pas nécessaire de commencer par ces types. Vous pouvez créer le type que vous voulez à tout moment, à condition de respecter les règles et la syntaxe de GraphQL.
**Note**
Les prochaines sections utiliseront l'**éditeur de schéma**, alors gardez-le ouvert.
------
#### [ Console ]
+ Vous pouvez créer un type d'objet en utilisant le `type` mot-clé associé au nom du type :
```
type Type_Name_Goes_Here {}
```
Dans le champ d'application du type, vous pouvez ajouter des champs qui représentent les caractéristiques de l'objet :
```
type Type_Name_Goes_Here {
# Add fields here
}
```
Voici un exemple :
```
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
**Note**
Dans cette étape, nous avons ajouté un type d'objet générique avec un `id` champ obligatoire stocké sous forme`ID`, un `title` champ stocké sous forme de et un `date` champ stocké sous forme de`AWSDateTime`. `String` Pour consulter la liste des types et des champs et leur fonction, reportez-vous à la section [Schémas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html). Pour voir la liste des scalaires et leur fonction, consultez la [référence Type](https://docs.aws.amazon.com/appsync/latest/devguide/type-reference.html).
------
#### [ CLI ]
**Note**
Nous vous recommandons de lire d'abord la version console si ce n'est pas déjà fait.
+ Vous pouvez créer un type d'objet en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html)commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le`definition`, ou le contenu de votre type. Dans l'exemple de console, c'était :
```
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
1. Celui `format` de votre contribution. Dans cet exemple, nous utilisons`SDL`.
Voici un exemple de commande :
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Obj_Type_1{id: ID! title: String date: AWSDateTime}" --format SDL
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"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"
}
}
```
**Note**
Dans cette étape, nous avons ajouté un type d'objet générique avec un `id` champ obligatoire stocké sous forme`ID`, un `title` champ stocké sous forme de et un `date` champ stocké sous forme de`AWSDateTime`. `String` Pour consulter la liste des types et des champs et leur fonction, reportez-vous à la section [Schémas](https://docs.aws.amazon.com//appsync/latest/devguide/schema-components.html). Pour consulter la liste des scalaires et leur fonction, reportez-vous à la section [Référence des types](https://docs.aws.amazon.com/appsync/latest/devguide/type-reference.html).
Par ailleurs, vous vous êtes peut-être rendu compte que la saisie de la définition fonctionne directement pour les types plus petits, mais qu'elle est impossible pour l'ajout de types plus grands ou multiples. Vous pouvez choisir de tout ajouter dans un `.graphql` fichier, puis de [le transmettre en entrée](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html).
------
#### [ CDK ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
Pour ajouter un type, vous devez l'ajouter à votre `.graphql` fichier. Par exemple, l'exemple de console était le suivant :
```
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
Vous pouvez ajouter vos types directement au schéma comme dans n'importe quel autre fichier.
**Note**
Pour utiliser les modifications apportées à votre API GraphQL, vous devez redéployer l'application.
------
Le [type d'objet](https://graphql.org/learn/schema/#object-types-and-fields) contient des champs de [type scalaire](https://graphql.org/learn/schema/#scalar-types) tels que des chaînes et des entiers. AWS AppSync vous permet également d'utiliser des types scalaires améliorés, `AWSDateTime` en plus des scalaires GraphQL de base. En outre, tout champ se terminant par un point d'exclamation est obligatoire.
Le type `ID` scalaire en particulier est un identifiant unique qui peut être `String` soit`Int`. Vous pouvez les contrôler dans le code de votre résolveur pour une attribution automatique.
Il existe des similitudes entre les types d'objets spéciaux `Query` et les types d'objets « ordinaires », comme dans l'exemple ci-dessus, en ce sens qu'ils utilisent tous deux le `type` mot-clé et sont considérés comme des objets. Cependant, pour les types d'objets spéciaux (`Query`,`Mutation`, et`Subscription`), leur comportement est très différent car ils sont exposés en tant que points d'entrée de votre API. Ils visent également à façonner les opérations plutôt que les données. Pour plus d'informations, consultez [la section Les types de requête et de mutation](https://graphql.org/learn/schema/#the-query-and-mutation-types).
En ce qui concerne les types d'objets spéciaux, l'étape suivante pourrait consister à en ajouter un ou plusieurs pour effectuer des opérations sur les données mises en forme. Dans un scénario réel, chaque schéma GraphQL doit au moins avoir un type de requête racine pour demander des données. Vous pouvez considérer la requête comme l'un des points d'entrée (ou points de terminaison) de votre serveur GraphQL. Ajoutons une requête à titre d'exemple.
------
#### [ Console ]
+ Pour créer une requête, vous pouvez simplement l'ajouter au fichier de schéma comme n'importe quel autre type. Une requête nécessiterait un `Query` type et une entrée à la racine comme ceci :
```
schema {
query: Name_of_Query
}
type Name_of_Query {
# Add field operation here
}
```
Notez que *Name\$1of\$1Query* dans un environnement de production, il sera simplement appelé `Query` dans la plupart des cas. Nous vous recommandons de le maintenir à cette valeur. Dans le type de requête, vous pouvez ajouter des champs. Chaque champ effectuera une opération dans la demande. Par conséquent, la plupart de ces champs, sinon tous, seront attachés à un résolveur. Cependant, cela ne nous intéresse pas dans cette section. En ce qui concerne le format de l'opération sur le terrain, cela pourrait ressembler à ceci :
```
Name_of_Query(params): Return_Type # version with params
Name_of_Query: Return_Type # version without params
```
Voici un exemple :
```
schema {
query: Query
}
type Query {
getObj: [Obj_Type_1]
}
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
**Note**
Dans cette étape, nous avons ajouté un `Query` type et l'avons défini dans notre `schema` racine. Notre `Query` type a défini un `getObj` champ qui renvoie une liste d'`Obj_Type_1`objets. Notez que `Obj_Type_1` c'est l'objet de l'étape précédente. Dans le code de production, vos opérations sur le terrain travailleront normalement avec des données façonnées par des objets tels que`Obj_Type_1`. De plus, les champs de `getObj` ce type auront normalement un résolveur pour exécuter la logique métier. Cela sera traité dans une autre section.
En outre, ajoute AWS AppSync automatiquement une racine de schéma lors des exportations. Techniquement, vous n'avez donc pas besoin de l'ajouter directement au schéma. Notre service traitera automatiquement les schémas dupliqués. Nous l'ajoutons ici en tant que meilleure pratique.
------
#### [ CLI ]
**Note**
Nous vous recommandons de lire d'abord la version console si ce n'est pas déjà fait.
1. Créez une `schema` racine avec une `query` définition en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html)commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le`definition`, ou le contenu de votre type. Dans l'exemple de console, c'était :
```
schema {
query: Query
}
```
1. Celui `format` de votre contribution. Dans cet exemple, nous utilisons`SDL`.
Voici un exemple de commande :
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"type": {
"definition": "schema {query: Query}",
"name": "schema",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
"format": "SDL"
}
}
```
**Note**
Notez que si vous n'avez pas saisi quelque chose correctement dans la `create-type` commande, vous pouvez mettre à jour la racine de votre schéma (ou n'importe quel type du schéma) en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html)commande. Dans cet exemple, nous allons modifier temporairement la racine du schéma pour qu'elle contienne une `subscription` définition.
Vous devez entrer quelques paramètres pour cette commande en particulier :
Celui `api-id` de votre API.
Celui `type-name` de ton genre. Dans l'exemple de console, c'était le cas`schema`.
Le`definition`, ou le contenu de votre type. Dans l'exemple de console, c'était :
```
schema {
query: Query
}
```
Le schéma après avoir ajouté un `subscription` ressemblera à ceci :
```
schema {
query: Query
subscription: Subscription
}
```
Celui `format` de votre contribution. Dans cet exemple, nous utilisons`SDL`.
Voici un exemple de commande :
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"type": {
"definition": "schema {query: Query subscription: Subscription}",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
"format": "SDL"
}
}
```
L'ajout de fichiers préformatés fonctionnera toujours dans cet exemple.
1. Créez un `Query` type en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html)commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le`definition`, ou le contenu de votre type. Dans l'exemple de console, c'était :
```
type Query {
getObj: [Obj_Type_1]
}
```
1. Celui `format` de votre contribution. Dans cet exemple, nous utilisons`SDL`.
Voici un exemple de commande :
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"type": {
"definition": "Query {getObj: [Obj_Type_1]}",
"name": "Query",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
"format": "SDL"
}
}
```
**Note**
Dans cette étape, nous avons ajouté un `Query` type et l'avons défini dans votre `schema` racine. Notre `Query` type définissait un `getObj` champ qui renvoyait une liste d'`Obj_Type_1`objets.
Dans le code `schema` racine`query: Query`, la `query:` partie indique qu'une requête a été définie dans votre schéma, tandis que la `Query` partie indique le nom réel de l'objet spécial.
------
#### [ CDK ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
Vous devez ajouter votre requête et la racine du schéma au `.graphql` fichier. Notre exemple ressemble à celui ci-dessous, mais vous devez le remplacer par votre code de schéma actuel :
```
schema {
query: Query
}
type Query {
getObj: [Obj_Type_1]
}
type Obj_Type_1 {
id: ID!
title: String
date: AWSDateTime
}
```
Vous pouvez ajouter vos types directement au schéma comme dans n'importe quel autre fichier.
**Note**
La mise à jour de la racine du schéma est facultative. Nous l'avons ajoutée à cet exemple en tant que meilleure pratique.
Pour utiliser les modifications apportées à votre API GraphQL, vous devez redéployer l'application.
------
Vous avez maintenant vu un exemple de création d'objets et d'objets spéciaux (requêtes). Vous avez également vu comment ils peuvent être interconnectés pour décrire les données et les opérations. Vous pouvez avoir des schémas contenant uniquement la description des données et une ou plusieurs requêtes. Cependant, nous aimerions ajouter une autre opération pour ajouter des données à la source de données. Nous allons ajouter un autre type d'objet spécial appelé `Mutation` qui modifie les données.
------
#### [ Console ]
+ Une mutation sera appelée`Mutation`. Par exemple`Query`, les opérations de terrain qu'`Mutation`il contient décriront une opération et seront associées à un résolveur. Notez également que nous devons le définir à la `schema` racine car il s'agit d'un type d'objet spécial. Voici un exemple de mutation :
```
schema {
mutation: Name_of_Mutation
}
type Name_of_Mutation {
# Add field operation here
}
```
Une mutation typique sera répertoriée à la racine comme une requête. La mutation est définie à l'aide du `type` mot clé associé au nom. *Name\$1of\$1Mutation*sera généralement appelé`Mutation`, nous vous recommandons donc de continuer ainsi. Chaque champ effectuera également une opération. En ce qui concerne le format de l'opération sur le terrain, cela pourrait ressembler à ceci :
```
Name_of_Mutation(params): Return_Type # version with params
Name_of_Mutation: Return_Type # version without params
```
Voici un exemple :
```
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
}
```
**Note**
Dans cette étape, nous avons ajouté un `Mutation` type avec un `addObj` champ. Résumons le rôle de ce champ :
```
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
```
`addObj`utilise l'`Obj_Type_1`objet pour effectuer une opération. Cela est évident en raison des champs, mais la syntaxe le prouve dans le type de `: Obj_Type_1` retour. À l'intérieur`addObj`, il accepte les `date` champs`id`,`title`, et de l'`Obj_Type_1`objet en tant que paramètres. Comme vous pouvez le constater, cela ressemble beaucoup à une déclaration de méthode. Cependant, nous n'avons pas encore décrit le comportement de notre méthode. Comme indiqué précédemment, le schéma est uniquement là pour définir quelles seront les données et les opérations, et non leur mode de fonctionnement. La mise en œuvre de la véritable logique métier interviendra plus tard lorsque nous créerons nos premiers résolveurs.
Une fois que vous avez terminé avec votre schéma, il est possible de l'exporter sous forme de `schema.graphql` fichier. Dans l'**éditeur de schéma**, vous pouvez choisir **Exporter le schéma** pour télécharger le fichier dans un format pris en charge.
En outre, ajoute AWS AppSync automatiquement une racine de schéma lors des exportations. Techniquement, vous n'avez donc pas besoin de l'ajouter directement au schéma. Notre service traitera automatiquement les schémas dupliqués. Nous l'ajoutons ici en tant que meilleure pratique.
------
#### [ CLI ]
**Note**
Nous vous recommandons de lire d'abord la version console si ce n'est pas déjà fait.
1. Mettez à jour votre schéma racine en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-type.html)commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Celui `type-name` de ton genre. Dans l'exemple de console, c'était le cas`schema`.
1. Le`definition`, ou le contenu de votre type. Dans l'exemple de console, c'était :
```
schema {
query: Query
mutation: Mutation
}
```
1. Celui `format` de votre contribution. Dans cet exemple, nous utilisons`SDL`.
Voici un exemple de commande :
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"type": {
"definition": "schema {query: Query mutation: Mutation}",
"arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
"format": "SDL"
}
}
```
1. Créez un `Mutation` type en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-type.html)commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le`definition`, ou le contenu de votre type. Dans l'exemple de console, c'était
```
type Mutation {
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}
```
1. Celui `format` de votre contribution. Dans cet exemple, nous utilisons`SDL`.
Voici un exemple de commande :
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}" --format SDL
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"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 ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
Vous devez ajouter votre requête et la racine du schéma au `.graphql` fichier. Notre exemple ressemble à celui ci-dessous, mais vous devez le remplacer par votre code de schéma actuel :
```
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
}
```
**Note**
La mise à jour de la racine du schéma est facultative. Nous l'avons ajoutée à cet exemple en tant que meilleure pratique.
Pour utiliser les modifications apportées à votre API GraphQL, vous devez redéployer l'application.
------
## Considérations facultatives - Utilisation des énumérations comme statuts
À ce stade, vous savez comment créer un schéma de base. Cependant, vous pouvez ajouter de nombreux éléments pour améliorer les fonctionnalités du schéma. Une chose courante dans les applications est l'utilisation d'énumérations comme statuts. Vous pouvez utiliser une énumération pour forcer le choix d'une valeur spécifique d'un ensemble de valeurs lors de l'appel. C'est bon pour des choses dont vous savez qu'elles ne changeront pas radicalement sur de longues périodes. Hypothétiquement parlant, nous pourrions ajouter une énumération qui renvoie le code d'état ou une chaîne dans la réponse.
Par exemple, supposons que nous créons une application de réseau social qui stocke les données de publication d'un utilisateur dans le backend. Notre schéma contient un `Post` type qui représente les données d'une publication individuelle :
```
type Post {
id: ID!
title: String
date: AWSDateTime
poststatus: PostStatus
}
```
Notre message `Post` `title` contiendra une publication unique `id` et une énumération appelée `PostStatus` qui représente l'état de la publication telle qu'elle est traitée par l'application. `date` Pour nos opérations, nous aurons une requête qui renverra toutes les données de publication :
```
type Query {
getPosts: [Post]
}
```
Nous aurons également une mutation qui ajoutera des publications à la source de données :
```
type Mutation {
addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}
```
En regardant notre schéma, l'`PostStatus`énumération peut avoir plusieurs statuts. Nous souhaiterons peut-être que les trois états de base soient appelés `success` (post traité avec succès), `pending` (post en cours de traitement) et `error` (post incapable d'être traité). Pour ajouter l'énumération, nous pourrions faire ceci :
```
enum PostStatus {
success
pending
error
}
```
Le schéma complet pourrait ressembler à ceci :
```
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 utilisateur ajoute un `Post` dans l'application, l'`addPost`opération sera appelée pour traiter ces données. Au fur et à mesure que le résolveur attaché `addPost` traite les données, il les met continuellement à jour en `poststatus` fonction de l'état de l'opération. Lorsqu'il est demandé, le `Post` testament contiendra le statut final des données. N'oubliez pas que nous ne décrivons que la manière dont nous voulons que les données fonctionnent dans le schéma. Nous avons beaucoup d'hypothèses quant à la mise en œuvre de nos résolveurs, qui mettront en œuvre la logique métier réelle pour traiter les données afin de répondre à la demande.
## Considérations facultatives - Abonnements
Les abonnements AWS AppSync sont invoqués en réponse à une mutation. Vous configurez cela avec un type `Subscription` et une directive `@aws_subscribe()` du schéma pour signifier quelles mutations appellent un ou plusieurs abonnements. Pour plus d'informations sur la configuration des abonnements, consultez la section [Données en temps réel](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html).
## Considérations facultatives - Relations et pagination
Supposons qu'un million soit `Posts` stocké dans une table DynamoDB et que vous souhaitiez renvoyer certaines de ces données. Cependant, l'exemple de requête donné ci-dessus ne renvoie que tous les messages. Vous ne voudriez pas les récupérer tous à chaque fois que vous faites une demande. Au lieu de cela, vous devriez les [paginer](https://graphql.org/learn/pagination/). Apportez les modifications suivantes à votre schéma :
+ Dans le `getPosts` champ, ajoutez deux arguments d'entrée : `nextToken` (itérateur) et `limit` (limite d'itération).
+ Ajoutez un nouveau `PostIterator` type contenant `Posts` (récupère la liste des `Post` objets) et des champs `nextToken` (itérateur).
+ `getPosts`Modifiez-le pour qu'il renvoie `PostIterator` et non une liste d'`Post`objets.
```
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
}
```
Le `PostIterator` type vous permet de renvoyer une partie de la liste des `Post` objets et un `nextToken` pour obtenir la partie suivante. À l'intérieur`PostIterator`, il y a une liste d'`Post`items (`[Post]`) qui est renvoyée avec un jeton de pagination (`nextToken`). En AWS AppSync, il serait connecté à Amazon DynamoDB via un résolveur et généré automatiquement sous forme de jeton chiffré. Cela convertir la valeur de l'argument `limit` en paramètre `maxResults` et l'argument `nextToken` en paramètre `exclusiveStartKey`. Pour des exemples et des exemples de modèles intégrés dans la AWS AppSync console, voir [Resolver reference (JavaScript).](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)
# Joindre une source de données dans AWS AppSync
Les sources de données sont des ressources de votre AWS compte avec lesquelles GraphQL APIs peut interagir. AWS AppSync prend en charge une multitude de sources de données telles qu'Amazon DynamoDB AWS Lambda, les bases de données relationnelles (Amazon Aurora Serverless), OpenSearch Amazon Service et les points de terminaison HTTP. Une AWS AppSync API peut être configurée pour interagir avec plusieurs sources de données, ce qui vous permet d'agréger les données en un seul endroit. AWS AppSync peut utiliser les AWS ressources existantes de votre compte ou approvisionner des tables DynamoDB en votre nom à partir d'une définition de schéma.
La section suivante explique comment associer une source de données à votre API GraphQL.
## Types de sources de données
Maintenant que vous avez créé un schéma dans la AWS AppSync console, vous pouvez y associer une source de données. Lorsque vous créez une API pour la première fois, il est possible de configurer une table Amazon DynamoDB lors de la création du schéma prédéfini. Cependant, nous n'aborderons pas cette option dans cette section. Vous pouvez en voir un exemple dans la section [Lancement d'un schéma](https://docs.aws.amazon.com//appsync/latest/devguide/schema-launch-start.html).
Nous examinerons plutôt toutes les sources de données prises AWS AppSync en charge. De nombreux facteurs entrent en ligne de compte pour choisir la bonne solution pour votre application. Les sections ci-dessous fournissent un contexte supplémentaire pour chaque source de données. Pour des informations générales sur les sources de données, consultez la section [Sources de données](https://docs.aws.amazon.com/appsync/latest/devguide/data-source-components.html).
### Amazon DynamoDB
Amazon DynamoDB est l'une des principales solutions AWS de stockage pour les applications évolutives. Le composant principal de DynamoDB est **la** table, qui est simplement un ensemble de données. Vous créerez généralement des tables basées sur des entités telles que `Book` ou`Author`. Les informations d'entrée de table sont stockées sous forme d'**éléments**, qui sont des groupes de champs uniques à chaque entrée. Un élément complet représente un élément de row/record la base de données. Par exemple, un élément d'une `Book` entrée peut inclure `title` et `author` avec leurs valeurs. Les champs individuels tels que `title` et `author` sont appelés **attributs**, qui sont similaires aux valeurs de colonne dans les bases de données relationnelles.
Comme vous pouvez le deviner, les tables seront utilisées pour stocker les données de votre application. AWS AppSync vous permet de connecter vos tables DynamoDB à votre API GraphQL pour manipuler des données. Prenez ce [cas d'utilisation](https://aws.amazon.com/blogs/mobile/new-real-time-multi-group-app-with-aws-amplify-graphql-build-a-twitter-community-clone/) tiré du *blog Web et mobile de Frontend*. Cette application permet aux utilisateurs de s'inscrire à une application de réseau social. Les utilisateurs peuvent rejoindre des groupes et télécharger des publications qui sont diffusées aux autres utilisateurs abonnés au groupe. Leur application stocke les informations relatives aux utilisateurs, aux publications et aux groupes d'utilisateurs dans DynamoDB. L'API GraphQL (gérée par AWS AppSync) s'interface avec la table DynamoDB. Lorsqu'un utilisateur apporte une modification au système qui sera répercutée sur le front-end, l'API GraphQL récupère ces modifications et les diffuse aux autres utilisateurs en temps réel.
### AWS Lambda
Lambda est un service piloté par les événements qui crée automatiquement les ressources nécessaires pour exécuter le code en réponse à un événement. Lambda utilise des **fonctions**, qui sont des instructions de groupe contenant le code, les dépendances et les configurations nécessaires à l'exécution d'une ressource. Les fonctions s'exécutent automatiquement lorsqu'elles détectent un **déclencheur**, un groupe d'activités qui invoque votre fonction. Un déclencheur peut être quelque chose comme une application effectuant un appel d'API, un AWS service de votre compte faisant tourner une ressource, etc. Lorsqu'elles sont déclenchées, les fonctions traitent les **événements**, qui sont des documents JSON contenant les données à modifier.
Lambda est idéal pour exécuter du code sans avoir à fournir les ressources nécessaires à son exécution. Prenez ce [cas d'utilisation](https://aws.amazon.com/blogs/mobile/building-a-graphql-api-with-java-and-aws-lambda/) tiré du *blog Web et mobile de Frontend*. Ce cas d'utilisation est un peu similaire à celui présenté dans la section DynamoDB. Dans cette application, l'API GraphQL est chargée de définir les opérations pour des choses telles que l'ajout de publications (mutations) et la récupération de ces données (requêtes). Pour implémenter les fonctionnalités de leurs opérations (par exemple,,`getPostsByAuthor ( author: String ! ) : [ Post ]`)`getPost ( id: String ! ) : Post`, ils utilisent les fonctions Lambda pour traiter les demandes entrantes. Dans le cadre de l'*option 2 : AWS AppSync avec le résolveur Lambda*, ils utilisent le AWS AppSync service pour gérer leur schéma et lier une source de données Lambda à l'une des opérations. Lorsque l'opération est appelée, Lambda s'interface avec le proxy Amazon RDS pour exécuter la logique métier sur la base de données.
### Amazon RDS
Amazon RDS vous permet de créer et de configurer rapidement des bases de données relationnelles. Dans Amazon RDS, vous allez créer une **instance de base de données** générique qui servira d'environnement de base de données isolé dans le cloud. Dans ce cas, vous utiliserez un **moteur de base** de données, qui est le véritable logiciel RDBMS (PostgreSQL, MySQL, etc.). Le service décharge une grande partie du travail de backend en fournissant une évolutivité grâce à l'infrastructure, aux services AWS de sécurité tels que les correctifs et le chiffrement, et en réduisant les coûts administratifs liés aux déploiements.
Prenez le même [cas d'utilisation](https://aws.amazon.com/blogs/mobile/building-a-graphql-api-with-java-and-aws-lambda/) que celui de la section Lambda. Dans le cadre de l'*option 3 : AWS AppSync avec le résolveur Amazon RDS*, une autre option présentée consiste à lier directement l'API GraphQL à AWS AppSync Amazon RDS. À l'aide d'une [API de données](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html), ils associent la base de données à l'API GraphQL. Un résolveur est attaché à un champ (généralement une requête, une mutation ou un abonnement) et implémente les instructions SQL nécessaires pour accéder à la base de données. Lorsqu'une demande appelant le champ est faite par le client, le résolveur exécute les instructions et renvoie la réponse.
### Amazon EventBridge
Dans EventBridge, vous allez créer des **bus d'événements**, qui sont des pipelines qui reçoivent des événements provenant de services ou d'applications que vous associez (la **source des événements**) et qui les traitent selon un ensemble de règles. Un **événement** est un changement d'état dans un environnement d'exécution, tandis qu'une **règle** est un ensemble de filtres pour les événements. Une règle suit un **modèle d'événement** ou les métadonnées du changement d'état d'un événement (identifiant, région, numéro de compte, ARN, etc.). Lorsqu'un événement correspond au modèle d'événement, EventBridge il est envoyé à travers le pipeline vers le service de destination (**cible**) et déclenche l'action spécifiée dans la règle.
EventBridge est utile pour acheminer les opérations de changement d'état vers un autre service. Prenez ce [cas d'utilisation](https://aws.amazon.com/blogs/mobile/appsync-eventbridge/) tiré du *blog Web et mobile de Frontend*. L'exemple illustre une solution de commerce électronique dans laquelle plusieurs équipes gèrent différents services. L'un de ces services fournit des mises à jour des commandes au client à chaque étape de la livraison (commande passée, en cours, expédiée, livrée, etc.) sur le front-end. Cependant, l'équipe frontale qui gère ce service n'a pas un accès direct aux données du système de commande, car celles-ci sont gérées par une équipe principale distincte. Le système de commande de l'équipe principale est également décrit comme une boîte noire. Il est donc difficile de glaner des informations sur la manière dont l'équipe structure ses données. Cependant, l'équipe principale a mis en place un système qui publiait les données des commandes via un bus d'événements géré par EventBridge. Pour accéder aux données provenant du bus d'événements et les acheminer vers le front-end, l'équipe du front-end a créé une nouvelle cible pointant vers son API GraphQL installée. AWS AppSync Ils ont également créé une règle pour envoyer uniquement les données relatives à la mise à jour de la commande. Lorsqu'une mise à jour est effectuée, les données du bus d'événements sont envoyées à l'API GraphQL. Le schéma de l'API traite les données, puis les transmet au front-end.
### Aucune source de données
Si vous n'avez pas l'intention d'utiliser une source de données, vous pouvez la définir sur`none`. Une source de `none` données, bien qu'elle soit toujours explicitement classée comme source de données, n'est pas un support de stockage. Généralement, un résolveur invoque une ou plusieurs sources de données à un moment donné pour traiter la demande. Il existe toutefois des situations dans lesquelles il n'est pas nécessaire de manipuler une source de données. La définition de la source de données sur `none` exécutera la demande, ignorera l'étape d'appel des données, puis exécutera la réponse.
Prenez le même [cas d'utilisation](https://aws.amazon.com/blogs/mobile/appsync-eventbridge/) que celui de la EventBridge section. Dans le schéma, la mutation traite la mise à jour du statut, puis l'envoie aux abonnés. Pour rappeler le fonctionnement des résolveurs, il y a généralement au moins un appel de source de données. Cependant, les données de ce scénario ont déjà été envoyées automatiquement par le bus d'événements. Cela signifie que la mutation n'est pas nécessaire pour effectuer un appel de source de données ; le statut de la commande peut simplement être géré localement. La mutation est définie sur`none`, qui agit comme une valeur directe sans appel de source de données. Le schéma est ensuite renseigné avec les données, qui sont envoyées aux abonnés.
### OpenSearch
Amazon OpenSearch Service est une suite d'outils permettant de mettre en œuvre la recherche en texte intégral, la visualisation des données et la journalisation. Vous pouvez utiliser ce service pour interroger les données structurées que vous avez téléchargées.
Dans ce service, vous allez créer des instances de OpenSearch. C'est ce qu'on appelle **des nœuds**. Dans un nœud, vous allez ajouter au moins un **index**. D'un point de vue conceptuel, les indices sont un peu comme des tables dans des bases de données relationnelles. (Cependant, il OpenSearch n'est pas conforme à l'ACID, il ne doit donc pas être utilisé de cette façon). Vous allez remplir votre index avec les données que vous téléchargez sur le OpenSearch service. Lorsque vos données sont téléchargées, elles sont indexées dans une ou plusieurs partitions présentes dans l'index. Une **partition** est similaire à une partition de votre index qui contient certaines de vos données et peut être interrogée séparément des autres partitions. Une fois chargées, vos données seront structurées sous forme de fichiers JSON appelés **documents**. Vous pouvez ensuite interroger le nœud pour obtenir des données dans le document.
### Points de terminaison HTTP
Vous pouvez utiliser des points de terminaison HTTP comme sources de données. AWS AppSync peut envoyer des demandes aux points de terminaison avec les informations pertinentes telles que les paramètres et la charge utile. La réponse HTTP sera exposée au résolveur, qui renverra la réponse finale une fois ses opérations terminées.
## Ajouter une source de données
Si vous avez créé une source de données, vous pouvez la lier au AWS AppSync service et, plus précisément, à l'API.
------
#### [ Console ]
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Choisissez votre API dans le **tableau de bord**.
1. Dans la **barre latérale**, sélectionnez **Sources de données.**
1. Choisissez **Create data source**.
1. Donnez un nom à votre source de données. Vous pouvez également lui donner une description, mais c'est facultatif.
1. Choisissez votre **type de source de données**.
1. Pour DynamoDB, vous devez choisir votre région, puis le tableau dans la région. Vous pouvez dicter des règles d'interaction avec votre table en choisissant de créer un nouveau rôle de table générique ou en important un rôle existant pour la table. Vous pouvez activer le [versionnement](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html), qui permet de créer automatiquement des versions des données pour chaque demande lorsque plusieurs clients tentent de mettre à jour les données en même temps. Le versionnement est utilisé pour conserver et gérer plusieurs variantes de données à des fins de détection et de résolution de conflits. Vous pouvez également activer la génération automatique de schéma, qui prend votre source de données et génère une partie du CRUD`List`, ainsi que les `Query` opérations nécessaires pour y accéder dans votre schéma.
En OpenSearch effet, vous devrez choisir votre région, puis le domaine (cluster) de la région. Vous pouvez dicter des règles d'interaction avec votre domaine en choisissant de créer un nouveau rôle de table générique ou en important un rôle existant pour la table.
Pour Lambda, vous devrez choisir votre région, puis l'ARN de la fonction Lambda dans la région. Vous pouvez dicter des règles d'interaction avec votre fonction Lambda en choisissant de créer un nouveau rôle de table générique ou en important un rôle existant pour la table.
Pour le protocole HTTP, vous devez saisir votre point de terminaison HTTP.
En EventBridge effet, vous devrez choisir votre région, puis le bus événementiel de la région. Vous pouvez dicter des règles d'interaction avec votre bus d'événements en choisissant de créer un nouveau rôle de table générique ou en important un rôle existant pour la table.
Pour RDS, vous devrez choisir votre région, puis le magasin secret (nom d'utilisateur et mot de passe), le nom de la base de données et le schéma.
Dans aucun cas, vous ajouterez une source de données sans source de données réelle. Cela permet de gérer les résolveurs localement plutôt que par le biais d'une source de données réelle.
**Note**
Si vous importez des rôles existants, ils ont besoin d'une politique de confiance. Pour plus d'informations, consultez la [politique de confiance IAM](#iam-trust-policy.title).
1. Choisissez **Créer**.
**Note**
Si vous créez une source de données DynamoDB, vous pouvez également accéder à **la page Schéma de la** console, **choisir Créer** des ressources en haut de la page, puis remplir un modèle prédéfini à convertir en table. Dans cette option, vous allez remplir ou importer le type de base, configurer les données de base de la table, y compris la clé de partition, et passer en revue les modifications du schéma.
------
#### [ CLI ]
+ Créez votre source de données en exécutant la [https://docs.aws.amazon.com/cli/latest/reference/appsync/create-data-source.html](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-data-source.html)commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Celui `name` de ta table.
1. La source `type` de données. Selon le type de source de données que vous choisissez, vous devrez peut-être saisir une balise `service-role-arn` et une `-config` balise.
Voici un exemple de commande :
```
aws appsync create-data-source --api-id abcdefghijklmnopqrstuvwxyz --name data_source_name --type data_source_type --service-role-arn arn:aws:iam::107289374856:role/role_name --[data_source_type]-config {params}
```
------
#### [ CDK ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait de code utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
Pour ajouter votre source de données spécifique, vous devez ajouter la construction à votre fichier de pile. Vous trouverez une liste des types de sources de données ici :
+ [ DynamoDbDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.DynamoDbDataSource.html)
+ [ EventBridgeDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.EventBridgeDataSource.html)
+ [ HttpDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.HttpDataSource.html)
+ [ LambdaDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.LambdaDataSource.html)
+ [ NoneDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.NoneDataSource.html)
+ [ OpenSearchDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.OpenSearchDataSource.html)
+ [ RdsDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.RdsDataSource.html)
1. En général, vous devrez peut-être ajouter la directive d'importation au service que vous utilisez. Par exemple, il peut suivre les formes suivantes :
```
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'
```
Par exemple, voici comment vous pouvez importer les services AWS AppSync et DynamoDB :
```
import * as appsync from 'aws-cdk-lib/aws-appsync';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
```
1. Certains services tels que RDS nécessitent une configuration supplémentaire dans le fichier de pile avant de créer la source de données (par exemple, création de VPC, rôles et informations d'accès). Consultez les exemples dans les pages CDK correspondantes pour plus d'informations.
1. Pour la plupart des sources de données, en particulier les AWS services, vous allez créer une nouvelle instance de la source de données dans votre fichier de pile. En général, cela ressemblera à ce qui suit :
```
const add_data_source_func = new service_scope.resource_name(scope: Construct, id: string, props: data_source_props);
```
Par exemple, voici un exemple de table Amazon DynamoDB :
```
const add_ddb_table = new dynamodb.Table(this, 'Table_ID', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
sortKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
tableClass: dynamodb.TableClass.STANDARD,
});
```
**Note**
La plupart des sources de données auront au moins un accessoire obligatoire (indiqué **sans** `?` symbole). Consultez la documentation du CDK pour savoir quels accessoires sont nécessaires.
1. Ensuite, vous devez lier la source de données à l'API GraphQL. La méthode recommandée consiste à l'ajouter lorsque vous créez une fonction pour votre résolveur de pipeline. Par exemple, l'extrait ci-dessous est une fonction qui analyse tous les éléments d'une table DynamoDB :
```
const add_func = new appsync.AppsyncFunction(this, 'func_ID', {
name: 'func_name_in_console',
add_api,
dataSource: add_api.addDynamoDbDataSource('data_source_name_in_console', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return { operation: 'Scan' };
}
export function response(ctx) {
return ctx.result.items;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
```
Dans les `dataSource` accessoires, vous pouvez appeler l'API GraphQL `add_api` () et utiliser l'une de ses méthodes intégrées `addDynamoDbDataSource` () pour établir l'association entre la table et l'API GraphQL. Les arguments sont le nom de ce lien qui existera dans la AWS AppSync console (`data_source_name_in_console`dans cet exemple) et la méthode de table (`add_ddb_table`). Plus d'informations sur ce sujet seront révélées dans la section suivante lorsque vous commencerez à créer des résolveurs.
Il existe d'autres méthodes pour lier une source de données. Techniquement, vous pouvez les ajouter `api` à la liste des accessoires dans la fonction de table. Par exemple, voici l'extrait de l'étape 3, mais avec un `api` accessoire contenant une API GraphQL :
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
...
});
const add_ddb_table = new dynamodb.Table(this, 'Table_ID', {
...
api: add_api
});
```
Vous pouvez également appeler la `GraphqlApi` construction séparément :
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
...
});
const add_ddb_table = new dynamodb.Table(this, 'Table_ID', {
...
});
const link_data_source = add_api.addDynamoDbDataSource('data_source_name_in_console', add_ddb_table);
```
Nous recommandons de créer l'association uniquement dans les accessoires de la fonction. Sinon, vous devrez soit lier votre fonction de résolution à la source de données manuellement dans la AWS AppSync console (si vous souhaitez continuer à utiliser la valeur de la console`data_source_name_in_console`), soit créer une association distincte dans la fonction sous un autre nom, par exemple`data_source_name_in_console_2`. Cela est dû aux limites de la manière dont les accessoires traitent les informations.
**Note**
Vous devrez redéployer l'application pour voir vos modifications.
------
### Politique de confiance IAM
Si vous utilisez un rôle IAM existant pour votre source de données, vous devez accorder à ce rôle les autorisations appropriées pour effectuer des opérations sur votre AWS ressource, par exemple `PutItem` sur une table Amazon DynamoDB. Vous devez également modifier la politique de confiance associée à ce rôle afin de permettre son utilisation AWS AppSync pour l'accès aux ressources, comme indiqué dans l'exemple de politique suivant :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Vous pouvez également ajouter des conditions à votre politique de confiance afin de limiter l'accès à la source de données comme vous le souhaitez. Actuellement, `SourceArn` et `SourceAccount` les clés peuvent être utilisées dans ces conditions. Par exemple, la politique suivante limite l'accès à votre source de données au compte `123456789012` :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}
```
------
Vous pouvez également limiter l'accès à une source de données à une API spécifique, par exemple en `abcdefghijklmnopq` appliquant la politique suivante :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:appsync:us-west-2:123456789012:apis/abcdefghijklmnopq"
}
}
}
]
}
```
------
Vous pouvez limiter l'accès à tous AWS AppSync APIs ceux d'une région spécifique, par exemple en `us-east-1` appliquant la politique suivante :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appsync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:appsync:us-east-1:123456789012:apis/*"
}
}
}
]
}
```
------
Dans la section suivante ([Configuration des résolveurs](https://docs.aws.amazon.com//appsync/latest/devguide/resolver-config-overview.html)), nous allons ajouter notre logique métier de résolveur et l'associer aux champs de notre schéma pour traiter les données de notre source de données.
Pour plus d'informations sur la configuration de la politique de rôle, consultez la section [Modification d'un rôle](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_manage_modify.html) dans le *Guide de l'utilisateur IAM*.
Pour plus d'informations sur l'accès multicompte aux AWS Lambda résolveurs pour AWS AppSync, voir [Création de résolveurs multicomptes AWS Lambda](https://aws.amazon.com/blogs/mobile/appsync-lambda-cross-account/) pour. AWS AppSync
# Configuration des résolveurs dans AWS AppSync
Dans les sections précédentes, vous avez appris à créer votre schéma GraphQL et votre source de données, puis à les lier ensemble dans le AWS AppSync service. Dans votre schéma, vous avez peut-être défini un ou plusieurs champs (opérations) dans votre requête et votre mutation. Bien que le schéma décrive les types de données que les opérations demanderaient à la source de données, il n'a jamais mis en œuvre le comportement de ces opérations en fonction des données.
Le comportement d'une opération est toujours implémenté dans le résolveur, qui sera lié au champ effectuant l'opération. Pour plus d'informations sur le fonctionnement général des résolveurs, consultez la page [Résolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html).
Dans AWS AppSync, votre résolveur est lié à un environnement d'exécution, qui est l'environnement dans lequel votre résolveur s'exécute. Les environnements d'exécution dictent la langue dans laquelle votre résolveur sera écrit. Deux environnements d'exécution sont actuellement pris en charge : APPSYNC\$1JS (JavaScript) et Apache Velocity Template Language (VTL).
Lors de la mise en œuvre de résolveurs, ils suivent une structure générale :
+ **Avant l'étape** : lorsqu'une demande est faite par le client, les données de la demande sont transmises aux résolveurs des champs de schéma utilisés (généralement vos requêtes, mutations, abonnements). Le résolveur commencera à traiter les données de la demande à l'aide d'un gestionnaire avant étape, qui permet d'effectuer certaines opérations de prétraitement avant que les données ne passent par le résolveur.
+ **Fonction (s)** : Une fois l'étape précédente exécutée, la demande est transmise à la liste des fonctions. La première fonction de la liste s'exécutera sur la source de données. Une fonction est un sous-ensemble du code de votre résolveur contenant son propre gestionnaire de requêtes et de réponses. Un gestionnaire de demandes prendra les données de la demande et effectuera des opérations sur la source de données. Le gestionnaire de réponses traitera la réponse de la source de données avant de la renvoyer à la liste. S'il existe plusieurs fonctions, les données de la demande seront envoyées à la fonction suivante de la liste à exécuter. Les fonctions de la liste seront exécutées en série dans l'ordre défini par le développeur. Une fois que toutes les fonctions ont été exécutées, le résultat final est transmis à l'étape suivante.
+ **Étape suivante** : L'étape suivante est une fonction de gestion qui vous permet d'effectuer certaines opérations finales sur la réponse de la fonction finale avant de la transmettre à la réponse GraphQL.
Ce flux est un exemple de résolveur de pipeline. Les résolveurs de pipeline sont pris en charge dans les deux environnements d'exécution. Cependant, il s'agit d'une explication simplifiée de ce que les résolveurs de pipeline peuvent faire. De plus, nous ne décrivons qu'une seule configuration de résolveur possible. Pour plus d'informations sur les configurations de résolveurs prises en charge, consultez l'aperçu des [JavaScript résolveurs pour APPSYNC\$1JS ou l'aperçu](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html) du modèle de mappage des [résolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-overview.html) pour VTL.
Comme vous pouvez le constater, les résolveurs sont modulaires. Pour que les composants du résolveur fonctionnent correctement, ils doivent être capables de vérifier l'état de l'exécution à partir d'autres composants. Dans la section [Résolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html), vous savez que chaque composant du résolveur peut recevoir des informations vitales sur l'état de l'exécution sous forme d'un ensemble d'arguments (`args`,`context`, etc.). En AWS AppSync, cela est géré strictement par le`context`. Il s'agit d'un conteneur contenant les informations relatives au champ en cours de résolution. Cela peut inclure tout, des arguments transmis aux résultats, aux données d'autorisation, aux données d'en-tête, etc. Pour plus d'informations sur le contexte, consultez la référence de l'[objet de contexte Resolver pour APPSYNC\$1JS ou la référence](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) de contexte du modèle de [mappage Resolver](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference.html) pour VTL.
Le contexte n'est pas le seul outil que vous pouvez utiliser pour implémenter votre résolveur. AWS AppSync prend en charge un large éventail d'utilitaires pour la génération de valeur, la gestion des erreurs, l'analyse syntaxique, la conversion, etc. [Vous pouvez voir une liste d'utilitaires [ici](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html) pour APPSYNC\$1JS ou ici pour VTL.](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference.html)
Dans les sections suivantes, vous allez apprendre à configurer les résolveurs dans votre API GraphQL.
**Topics**
+ [Création de requêtes de base (JavaScript)](configuring-resolvers-js.md)
+ [Création de requêtes de base (VTL)](configuring-resolvers.md)
# Création de requêtes de base (JavaScript)
Les résolveurs GraphQL connectent les champs d'un schéma de type à une source de données. Les résolveurs sont le mécanisme par lequel les demandes sont satisfaites.
Résolveurs AWS AppSync utilisés JavaScript pour convertir une expression GraphQL dans un format utilisable par la source de données. Les modèles de mappage peuvent également être écrits dans le [langage VTL (Apache Velocity Template Language)](https://velocity.apache.org/engine/2.0/vtl-reference.html) pour convertir une expression GraphQL dans un format utilisable par la source de données.
Cette section décrit comment configurer les résolveurs à l'aide JavaScript de. La section [Tutoriels sur les résolveurs (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/tutorials-js.html) propose des didacticiels approfondis sur la façon d'implémenter des résolveurs à l'aide de. JavaScript La section [Resolver reference (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) fournit une explication des opérations utilitaires qui peuvent être utilisées avec les JavaScript résolveurs.
Nous vous recommandons de suivre ce guide avant d'essayer d'utiliser l'un des didacticiels mentionnés ci-dessus.
Dans cette section, nous expliquerons comment créer et configurer des résolveurs pour les requêtes et les mutations.
**Note**
Ce guide part du principe que vous avez créé votre schéma et que vous avez au moins une requête ou une mutation. Si vous recherchez des abonnements (données en temps réel), consultez [ce](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html) guide.
Dans cette section, nous allons fournir quelques étapes générales pour configurer les résolveurs, ainsi qu'un exemple utilisant le schéma ci-dessous :
```
// schema.graphql file
input CreatePostInput {
title: String
date: AWSDateTime
}
type Post {
id: ID!
title: String
date: AWSDateTime
}
type Mutation {
createPost(input: CreatePostInput!): Post
}
type Query {
getPost: [Post]
}
```
## Création de résolveurs de requêtes de base
Cette section explique comment créer un résolveur de requêtes de base.
------
#### [ Console ]
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Entrez les détails de votre schéma et de votre source de données. Consultez les sections [Conception de votre schéma](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) et [Attachement d'une source de données](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html) pour plus d'informations.
1. À côté de l'éditeur de **schéma**, il y a une fenêtre appelée **Resolvers.** Cette zone contient une liste des types et des champs tels que définis dans votre fenêtre de **schéma**. Vous pouvez associer des résolveurs aux champs. Vous allez probablement associer des résolveurs à vos opérations sur le terrain. Dans cette section, nous allons examiner les configurations de requêtes simples. Sous le type de **requête**, choisissez **Joindre** à côté du champ de votre requête.
1. Sur la page **Attacher un résolveur**, sous **Type de résolveur**, vous pouvez choisir entre des résolveurs de type pipeline ou unitaire. Pour plus d'informations sur ces types, consultez la section [Résolveurs.](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html) Ce guide utilisera`pipeline resolvers`.
**Astuce**
Lorsque vous créez des résolveurs de pipeline, vos sources de données seront associées aux fonctions de pipeline. Les fonctions sont créées une fois que vous avez créé le résolveur de pipeline lui-même, c'est pourquoi il n'est pas possible de le définir dans cette page. Si vous utilisez un résolveur d'unités, la source de données est directement liée au résolveur. Vous devez donc la définir dans cette page.
Pour **Resolver Runtime**, choisissez `APPSYNC_JS` d'activer le JavaScript runtime.
1. Vous pouvez activer la [mise en cache](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html) pour cette API. Nous vous recommandons de désactiver cette fonctionnalité pour le moment. Choisissez **Créer**.
1. Sur la page **Modifier le résolveur**, il existe un éditeur de code appelé **Resolver code** qui vous permet d'implémenter la logique du gestionnaire de résolution et de la réponse (avant et après les étapes). Pour plus d'informations, consultez la [présentation des JavaScript résolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html).
**Note**
Dans notre exemple, nous allons simplement laisser la demande vide et la réponse définie pour renvoyer le dernier résultat de la source de données à partir du [contexte](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) :
```
import {util} from '@aws-appsync/utils';
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
```
Sous cette section, il y a un tableau appelé **Fonctions**. Les fonctions vous permettent d'implémenter du code qui peut être réutilisé dans plusieurs résolveurs. Au lieu de constamment réécrire ou copier le code, vous pouvez stocker le code source sous forme de fonction à ajouter à un résolveur chaque fois que vous en avez besoin.
Les fonctions constituent l'essentiel de la liste des opérations d'un pipeline. Lorsque vous utilisez plusieurs fonctions dans un résolveur, vous définissez l'ordre des fonctions, et elles seront exécutées dans cet ordre de manière séquentielle. Ils sont exécutés après l'exécution de la fonction de demande et avant le début de la fonction de réponse.
Pour ajouter une nouvelle fonction, sous **Fonctions**, choisissez **Ajouter une fonction**, puis **Créer une nouvelle fonction**. Vous pouvez également voir un bouton **Créer une fonction** pour choisir à la place.
1. Choisissez une source de données. Il s'agira de la source de données sur laquelle le résolveur agira.
**Note**
Dans notre exemple, nous attachons un résolveur pour`getPost`, qui récupère un `Post` objet par. `id` Supposons que nous ayons déjà configuré une table DynamoDB pour ce schéma. Sa clé de partition est définie sur `id` et est vide.
1. Entrez un`Function name`.
1. Sous **Code de fonction**, vous devez implémenter le comportement de la fonction. Cela peut prêter à confusion, mais chaque fonction aura son propre gestionnaire de requêtes et de réponses local. La demande est exécutée, puis la source de données est invoquée pour traiter la demande, puis la réponse de la source de données est traitée par le gestionnaire de réponses. Le résultat est stocké dans l'objet de [contexte](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html). Ensuite, la fonction suivante de la liste s'exécutera ou sera transmise au gestionnaire de réponses après étape s'il s'agit de la dernière.
**Note**
Dans notre exemple, nous attachons un résolveur à`getPost`, qui obtient une liste d'`Post`objets à partir de la source de données. Notre fonction de requête demandera les données de notre table, la table transmettra sa réponse au contexte (ctx), puis la réponse renverra le résultat dans le contexte. AWS AppSync Sa force réside dans son interconnexion avec les autres AWS services. Comme nous utilisons DynamoDB, nous disposons d'[une suite d'opérations pour simplifier ce type de](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html) choses. Nous avons également quelques exemples standard pour d'autres types de sources de données.
Notre code ressemblera à ceci :
```
import { util } from '@aws-appsync/utils';
/**
* Performs a scan on the dynamodb data source
*/
export function request(ctx) {
return { operation: 'Scan' };
}
/**
* return a list of scanned post items
*/
export function response(ctx) {
return ctx.result.items;
}
```
Au cours de cette étape, nous avons ajouté deux fonctions :
`request`: Le gestionnaire de demandes effectue l'opération de récupération par rapport à la source de données. L'argument contient l'objet contextuel (`ctx`) ou certaines données accessibles à tous les résolveurs effectuant une opération particulière. Par exemple, il peut contenir des données d'autorisation, les noms de champs en cours de résolution, etc. L'instruction return exécute une [https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan](https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-scan)opération (voir [ici](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html) pour des exemples). Comme nous travaillons avec DynamoDB, nous sommes autorisés à utiliser certaines des opérations de ce service. L'analyse effectue une extraction de base de tous les éléments de notre tableau. Le résultat de cette opération est stocké dans l'objet de contexte sous forme de `result` conteneur avant d'être transmis au gestionnaire de réponses. Le `request` est exécuté avant la réponse dans le pipeline.
`response`: le gestionnaire de réponses qui renvoie le résultat du`request`. L'argument est l'objet de contexte mis à jour et l'instruction de retour est`ctx.prev.result`. À ce stade du guide, cette valeur ne vous est peut-être pas familière. `ctx`fait référence à l'objet de contexte. `prev`fait référence à l'opération précédente dans le pipeline, qui était la nôtre`request`. `result`Il contient le ou les résultats du résolveur lorsqu'il se déplace dans le pipeline. Si vous mettez le tout ensemble, `ctx.prev.result` il renvoie le résultat de la dernière opération effectuée, à savoir le gestionnaire de demandes.
1. Choisissez **Créer une** fois que vous avez terminé.
1. De retour sur l'écran du résolveur, sous **Fonctions**, choisissez le menu déroulant **Ajouter une fonction** et ajoutez votre fonction à votre liste de fonctions.
1. Choisissez **Enregistrer** pour mettre à jour le résolveur.
------
#### [ CLI ]
**Pour ajouter votre fonction**
+ Créez une fonction pour votre résolveur de pipeline à l'aide de la `[create-function](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-function.html)` commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le `name` de la fonction dans la AWS AppSync console.
1. Le `data-source-name` ou le nom de la source de données que la fonction utilisera. Il doit déjà être créé et lié à votre API GraphQL dans le AWS AppSync service.
1. L'`runtime`environnement ou le langage de la fonction. Car JavaScript le nom doit être`APPSYNC_JS`, et le runtime,`1.0.0`.
1. Les `code` gestionnaires de requêtes et de réponses de votre fonction. Bien que vous puissiez le saisir manuellement, il est beaucoup plus facile de l'ajouter à un fichier .txt (ou dans un format similaire), puis de le transmettre en tant qu'argument.
**Note**
Notre code de requête se trouvera dans un fichier transmis en argument :
```
import { util } from '@aws-appsync/utils';
/**
* Performs a scan on the dynamodb data source
*/
export function request(ctx) {
return { operation: 'Scan' };
}
/**
* return a list of scanned post items
*/
export function response(ctx) {
return ctx.result.items;
}
```
Voici un exemple de commande :
```
aws appsync create-function \
--api-id abcdefghijklmnopqrstuvwxyz \
--name get_posts_func_1 \
--data-source-name table-for-posts \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file://~/path/to/file/{filename}.{fileType}
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"functionConfiguration": {
"functionId": "ejglgvmcabdn7lx75ref4qeig4",
"functionArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/functions/ejglgvmcabdn7lx75ref4qeig4",
"name": "get_posts_func_1",
"dataSourceName": "table-for-posts",
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output goes here"
}
}
```
**Note**
Assurez-vous de l'enregistrer `functionId` quelque part car cela sera utilisé pour associer la fonction au résolveur.
**Pour créer votre résolveur**
+ Créez une fonction de pipeline pour `Query` en exécutant la `[create-resolver](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)` commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le `type-name` ou le type d'objet spécial dans votre schéma (requête, mutation, abonnement).
1. L'`field-name`opération ou l'opération sur le terrain à l'intérieur du type d'objet spécial auquel vous souhaitez associer le résolveur.
1. Le`kind`, qui spécifie un résolveur d'unité ou de pipeline. Définissez ce paramètre sur `PIPELINE` pour activer les fonctions de pipeline.
1. La `pipeline-config` ou les fonctions à associer au résolveur. Assurez-vous de connaître les `functionId` valeurs de vos fonctions. L'ordre d'inscription est important.
1. Le`runtime`, qui était `APPSYNC_JS` (JavaScript). L'est `runtimeVersion` actuellement`1.0.0`.
1. Le`code`, qui contient les gestionnaires d'étapes avant et après.
**Note**
Notre code de requête se trouvera dans un fichier transmis en argument :
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
const { id, ...values } = ctx.args;
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id }),
attributeValues: util.dynamodb.toMapValues(values),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Voici un exemple de commande :
```
aws appsync create-resolver \
--api-id abcdefghijklmnopqrstuvwxyz \
--type-name Query \
--field-name getPost \
--kind PIPELINE \
--pipeline-config functions=ejglgvmcabdn7lx75ref4qeig4 \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file:///path/to/file/{filename}.{fileType}
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"resolver": {
"typeName": "Mutation",
"fieldName": "getPost",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation/resolvers/getPost",
"kind": "PIPELINE",
"pipelineConfig": {
"functions": [
"ejglgvmcabdn7lx75ref4qeig4"
]
},
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output goes here"
}
}
```
------
#### [ CDK ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait de code utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
Une application de base nécessite les éléments suivants :
1. Directives d'importation de services
1. Code de schéma
1. Générateur de sources de données
1. Code de fonction
1. Code du résolveur
Dans les sections [Conception de votre schéma](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) et [Attachement d'une source de données](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html), nous savons que le fichier de pile inclura les directives d'importation du formulaire :
```
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'
```
**Note**
Dans les sections précédentes, nous avons uniquement indiqué comment importer des AWS AppSync constructions. Dans le code réel, vous devrez importer davantage de services juste pour exécuter l'application. Dans notre exemple, si nous devions créer une application CDK très simple, nous importerions au moins le AWS AppSync service avec notre source de données, qui était une table DynamoDB. Nous aurions également besoin d'importer des constructions supplémentaires pour déployer l'application :
```
import * as cdk from 'aws-cdk-lib';
import * as appsync from 'aws-cdk-lib/aws-appsync';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';
```
Pour résumer chacune d'entre elles :
`import * as cdk from 'aws-cdk-lib';`: Cela vous permet de définir votre application CDK et des constructions telles que la pile. Il contient également des fonctions utilitaires utiles pour notre application, telles que la manipulation des métadonnées. Si vous connaissez cette directive d'importation, mais que vous vous demandez pourquoi la bibliothèque principale cdk n'est pas utilisée ici, consultez la page de [migration](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html).
`import * as appsync from 'aws-cdk-lib/aws-appsync';`: Cela permet d'importer le [AWS AppSync service](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
`import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';`: Ceci importe le service [DynamoDB](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb-readme.html).
`import { Construct } from 'constructs';`: Nous en avons besoin pour définir la [construction](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html) racine.
Le type d'importation dépend des services que vous appelez. Nous vous recommandons de consulter la documentation du CDK pour obtenir des exemples. Le schéma en haut de la page sera un fichier distinct dans votre application CDK sous forme de `.graphql` fichier. Dans le fichier de pile, nous pouvons l'associer à un nouveau GraphQL sous la forme :
```
const add_api = new appsync.GraphqlApi(this, 'graphQL-example', {
name: 'my-first-api',
schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema.graphql')),
});
```
**Note**
Dans le cadre de `add_api` ce projet, nous ajoutons une nouvelle API GraphQL en utilisant le `new` mot clé suivi de. `appsync.GraphqlApi(scope: Construct, id: string , props: GraphqlApiProps)` Notre champ d'application est `this` le suivant : l'identifiant CFN est`graphQL-example`, et nos accessoires sont `my-first-api` (nom de l'API dans la console) et `schema.graphql` (le chemin absolu vers le fichier de schéma).
Pour ajouter une source de données, vous devez d'abord ajouter votre source de données à la pile. Ensuite, vous devez l'associer à l'API GraphQL en utilisant la méthode spécifique à la source. L'association se produira lorsque vous ferez fonctionner votre résolveur. En attendant, prenons un exemple en créant la table DynamoDB en utilisant : `dynamodb.Table`
```
const add_ddb_table = new dynamodb.Table(this, 'posts-table', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
```
**Note**
Si nous devions l'utiliser dans notre exemple, nous ajouterions une nouvelle table DynamoDB avec l'identifiant CFN de et une clé `posts-table` de partition de. `id (S)`
Ensuite, nous devons implémenter notre résolveur dans le fichier de pile. Voici un exemple de requête simple qui recherche tous les éléments d'une table DynamoDB :
```
const add_func = new appsync.AppsyncFunction(this, 'func-get-posts', {
name: 'get_posts_func_1',
add_api,
dataSource: add_api.addDynamoDbDataSource('table-for-posts', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return { operation: 'Scan' };
}
export function response(ctx) {
return ctx.result.items;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
new appsync.Resolver(this, 'pipeline-resolver-get-posts', {
add_api,
typeName: 'Query',
fieldName: 'getPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func],
});
```
**Note**
Tout d'abord, nous avons créé une fonction appelée`add_func`. Cet ordre de création peut sembler un peu paradoxal, mais vous devez créer les fonctions dans votre résolveur de pipeline avant de créer le résolveur lui-même. Une fonction se présente sous la forme suivante :
```
AppsyncFunction(scope: Construct, id: string, props: AppsyncFunctionProps)
```
Notre champ d'application était`this`, notre identifiant CFN l'était`func-get-posts`, et nos accessoires contenaient les détails de la fonction réelle. À l'intérieur des accessoires, nous avons inclus :
La `name` fonction qui sera présente dans la AWS AppSync console (`get_posts_func_1`).
L'API GraphQL que nous avons créée précédemment ()`add_api`.
La source de données ; c'est le point où nous lions la source de données à la valeur de l'API GraphQL, puis nous l'associons à la fonction. Nous prenons la table que nous avons créée (`add_ddb_table`) et l'attachons à l'API GraphQL (`add_api`) en utilisant l'une des `GraphqlApi` méthodes ([https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.GraphqlApi.html#addwbrdynamowbrdbwbrdatawbrsourceid-table-options](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.GraphqlApi.html#addwbrdynamowbrdbwbrdatawbrsourceid-table-options)). La valeur id (`table-for-posts`) est le nom de la source de données dans la AWS AppSync console. Pour obtenir la liste des méthodes spécifiques à la source, consultez les pages suivantes :
[ DynamoDbDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.DynamoDbDataSource.html)
[ EventBridgeDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.EventBridgeDataSource.html)
[ HttpDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.HttpDataSource.html)
[ LambdaDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.LambdaDataSource.html)
[ NoneDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.NoneDataSource.html)
[ OpenSearchDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.OpenSearchDataSource.html)
[ RdsDataSource ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync.RdsDataSource.html)
Le code contient les gestionnaires de demandes et de réponses de notre fonction, à savoir un simple scan et un retour.
Le runtime indique que nous voulons utiliser le runtime APPSYNC\$1JS version 1.0.0. Notez qu'il s'agit actuellement de la seule version disponible pour APPSYNC\$1JS.
Ensuite, nous devons associer la fonction au résolveur de pipeline. Nous avons créé notre résolveur en utilisant le formulaire :
```
Resolver(scope: Construct, id: string, props: ResolverProps)
```
Notre champ d'application était`this`, notre identifiant CFN l'était`pipeline-resolver-get-posts`, et nos accessoires contenaient les détails de la fonction réelle. À l'intérieur des accessoires, nous avons inclus :
L'API GraphQL que nous avons créée précédemment ()`add_api`.
Le nom du type d'objet spécial ; il s'agit d'une opération de requête, nous avons donc simplement ajouté la valeur`Query`.
Le nom du champ (`getPost`) est le nom du champ dans le schéma sous le `Query` type.
Le code contient vos gestionnaires avant et après. Notre exemple renvoie simplement les résultats qui se trouvaient dans le contexte une fois que la fonction a effectué son opération.
Le runtime indique que nous voulons utiliser le runtime APPSYNC\$1JS version 1.0.0. Notez qu'il s'agit actuellement de la seule version disponible pour APPSYNC\$1JS.
La configuration du pipeline contient la référence à la fonction que nous avons créée (`add_func`).
------
Pour résumer ce qui s'est passé dans cet exemple, vous avez vu une AWS AppSync fonction implémentant un gestionnaire de requêtes et de réponses. La fonction était chargée d'interagir avec votre source de données. Le gestionnaire de demandes a envoyé une `Scan` opération à AWS AppSync, lui indiquant quelle opération effectuer sur votre source de données DynamoDB. Le gestionnaire de réponses a renvoyé la liste des éléments (`ctx.result.items`). La liste des éléments a ensuite été automatiquement mappée au type `Post` GraphQL.
## Création de résolveurs de mutations de base
Cette section vous montrera comment créer un résolveur de mutations de base.
------
#### [ Console ]
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Dans la section **Résolveurs** et dans le type de **mutation**, choisissez **Attacher** à côté de votre champ.
**Note**
Dans notre exemple, nous attachons un résolveur pour`createPost`, qui ajoute un `Post` objet à notre tableau. Supposons que nous utilisions la même table DynamoDB que celle de la section précédente. Sa clé de partition est définie sur `id` et est vide.
1. Sur la page **Joindre un résolveur**, sous **Type de résolveur, sélectionnez**. `pipeline resolvers` Pour rappel, vous trouverez plus d'informations sur les résolveurs [ici](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-components.html). Pour **Resolver Runtime**, choisissez `APPSYNC_JS` d'activer le JavaScript runtime.
1. Vous pouvez activer la [mise en cache](https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html) pour cette API. Nous vous recommandons de désactiver cette fonctionnalité pour le moment. Choisissez **Créer**.
1. Choisissez **Ajouter une fonction**, puis **Créer une nouvelle fonction**. Vous pouvez également voir un bouton **Créer une fonction** pour choisir à la place.
1. Choisissez votre source de données . Il doit s'agir de la source dont vous allez manipuler les données avec la mutation.
1. Entrez un`Function name`.
1. Sous **Code de fonction**, vous devez implémenter le comportement de la fonction. Comme il s'agit d'une mutation, la demande effectuera idéalement une opération de changement d'état sur la source de données invoquée. Le résultat sera traité par la fonction de réponse.
**Note**
`createPost`c'est ajouter, ou « mettre », un nouveau `Post` dans le tableau avec nos paramètres comme données. Nous pourrions ajouter quelque chose comme ceci :
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Au cours de cette étape, nous avons également ajouté `request` des `response` fonctionnalités :
`request`: Le gestionnaire de requêtes accepte le contexte comme argument. L'instruction return du gestionnaire de requêtes exécute une [https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem](https://docs.aws.amazon.com//appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-putitem)commande, qui est une opération DynamoDB intégrée ([voir](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html) ici [ou](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.WritingData) ici pour des exemples). La `PutItem` commande ajoute un `Post` objet à notre table DynamoDB en prenant la valeur de la `key` partition (générée automatiquement `util.autoid()` par) `attributes` et à partir de l'argument de contexte saisi (ce sont les valeurs que nous transmettrons dans notre demande). Les arguments du `title` champ `key` est `id` `date` et `attributes` sont le et. Ils sont tous deux préformatés via l'[https://docs.aws.amazon.com//appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb-js.html#utility-helpers-in-toMap-js](https://docs.aws.amazon.com//appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb-js.html#utility-helpers-in-toMap-js)assistant pour fonctionner avec la table DynamoDB.
`response`: La réponse accepte le contexte mis à jour et renvoie le résultat du gestionnaire de demandes.
1. Choisissez **Créer une** fois que vous avez terminé.
1. De retour sur l'écran du résolveur, sous **Fonctions**, choisissez le menu déroulant **Ajouter une fonction** et ajoutez votre fonction à votre liste de fonctions.
1. Choisissez **Enregistrer** pour mettre à jour le résolveur.
------
#### [ CLI ]
**Pour ajouter votre fonction**
+ Créez une fonction pour votre résolveur de pipeline à l'aide de la `[create-function](https://docs.aws.amazon.com/cli/latest/reference/appsync/create-function.html)` commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le `name` de la fonction dans la AWS AppSync console.
1. Le `data-source-name` ou le nom de la source de données que la fonction utilisera. Il doit déjà être créé et lié à votre API GraphQL dans le AWS AppSync service.
1. L'`runtime`environnement ou le langage de la fonction. Car JavaScript le nom doit être`APPSYNC_JS`, et le runtime,`1.0.0`.
1. Les `code` gestionnaires de requêtes et de réponses de votre fonction. Bien que vous puissiez le saisir manuellement, il est beaucoup plus facile de l'ajouter à un fichier .txt (ou dans un format similaire) puis de le transmettre comme argument.
**Note**
Notre code de requête se trouvera dans un fichier transmis en argument :
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Voici un exemple de commande :
```
aws appsync create-function \
--api-id abcdefghijklmnopqrstuvwxyz \
--name add_posts_func_1 \
--data-source-name table-for-posts \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file:///path/to/file/{filename}.{fileType}
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"functionConfiguration": {
"functionId": "vulcmbfcxffiram63psb4dduoa",
"functionArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/functions/vulcmbfcxffiram63psb4dduoa",
"name": "add_posts_func_1",
"dataSourceName": "table-for-posts",
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output foes here"
}
}
```
**Note**
Assurez-vous de l'enregistrer `functionId` quelque part car cela sera utilisé pour associer la fonction au résolveur.
**Pour créer votre résolveur**
+ Créez une fonction de pipeline pour `Mutation` en exécutant la `[create-resolver](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)` commande.
Vous devez entrer quelques paramètres pour cette commande en particulier :
1. Celui `api-id` de votre API.
1. Le `type-name` ou le type d'objet spécial dans votre schéma (requête, mutation, abonnement).
1. L'`field-name`opération ou l'opération sur le terrain à l'intérieur du type d'objet spécial auquel vous souhaitez associer le résolveur.
1. Le`kind`, qui spécifie un résolveur d'unité ou de pipeline. Définissez ce paramètre sur `PIPELINE` pour activer les fonctions de pipeline.
1. La `pipeline-config` ou les fonctions à associer au résolveur. Assurez-vous de connaître les `functionId` valeurs de vos fonctions. L'ordre d'inscription est important.
1. Le`runtime`, qui était `APPSYNC_JS` (JavaScript). L'est `runtimeVersion` actuellement`1.0.0`.
1. Le`code`, qui contient les étapes avant et après.
**Note**
Notre code de requête se trouvera dans un fichier transmis en argument :
```
import { util } from '@aws-appsync/utils';
/**
* Sends a request to `put` an item in the DynamoDB data source
*/
export function request(ctx) {
const { id, ...values } = ctx.args;
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id }),
attributeValues: util.dynamodb.toMapValues(values),
};
}
/**
* returns the result of the `put` operation
*/
export function response(ctx) {
return ctx.result;
}
```
Voici un exemple de commande :
```
aws appsync create-resolver \
--api-id abcdefghijklmnopqrstuvwxyz \
--type-name Mutation \
--field-name createPost \
--kind PIPELINE \
--pipeline-config functions=vulcmbfcxffiram63psb4dduoa \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0 \
--code file:///path/to/file/{filename}.{fileType}
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"resolver": {
"typeName": "Mutation",
"fieldName": "createPost",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation/resolvers/createPost",
"kind": "PIPELINE",
"pipelineConfig": {
"functions": [
"vulcmbfcxffiram63psb4dduoa"
]
},
"maxBatchSize": 0,
"runtime": {
"name": "APPSYNC_JS",
"runtimeVersion": "1.0.0"
},
"code": "Code output goes here"
}
}
```
------
#### [ CDK ]
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/home.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Les étapes répertoriées ci-dessous ne montreront qu'un exemple général de l'extrait de code utilisé pour ajouter une ressource particulière. Cela **n'est pas** censé être une solution fonctionnelle dans votre code de production. Nous partons également du principe que vous disposez déjà d'une application fonctionnelle.
+ Pour effectuer une mutation, en supposant que vous participez au même projet, vous pouvez l'ajouter au fichier de pile comme dans la requête. Voici une fonction modifiée et un résolveur pour une mutation qui ajoute un nouveau élément `Post` à la table :
```
const add_func_2 = new appsync.AppsyncFunction(this, 'func-add-post', {
name: 'add_posts_func_1',
add_api,
dataSource: add_api.addDynamoDbDataSource('table-for-posts-2', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
export function response(ctx) {
return ctx.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
new appsync.Resolver(this, 'pipeline-resolver-create-posts', {
add_api,
typeName: 'Mutation',
fieldName: 'createPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func_2],
});
```
**Note**
Comme cette mutation et la requête sont structurées de la même manière, nous allons simplement expliquer les modifications que nous avons apportées pour effectuer la mutation.
Dans la fonction, nous avons changé l'identifiant CFN `func-add-post` et le nom `add_posts_func_1` pour refléter le fait que nous ajoutons `Posts` à la table. Dans la source de données, nous avons créé une nouvelle association avec notre table (`add_ddb_table`) dans la AWS AppSync console, `table-for-posts-2` car la `addDynamoDbDataSource` méthode l'exige. N'oubliez pas que cette nouvelle association utilise toujours la même table que celle que nous avons créée précédemment, mais que nous disposons désormais de deux connexions dans la AWS AppSync console : une pour la requête as `table-for-posts` et une pour la mutation as`table-for-posts-2`. Le code a été modifié pour ajouter un `Post` en générant sa `id` valeur automatiquement et en acceptant les entrées d'un client pour le reste des champs.
Dans le résolveur, nous avons modifié la valeur de l'identifiant `pipeline-resolver-create-posts` pour refléter le fait que nous ajoutons `Posts` à la table. Pour refléter la mutation dans le schéma, le nom du type a été changé en`Mutation`, et le nom,`createPost`. La configuration du pipeline a été définie sur notre nouvelle fonction de mutation`add_func_2`.
------
Pour résumer ce qui se passe dans cet exemple, convertit AWS AppSync automatiquement les arguments définis dans le `createPost` champ à partir de votre schéma GraphQL en opérations DynamoDB. L'exemple stocke les enregistrements dans DynamoDB à l'aide d'une clé `id` de, qui est automatiquement créée à l'aide de notre assistant. `util.autoId()` Tous les autres champs que vous transmettez aux arguments de contexte (`ctx.args.input`) à partir de requêtes effectuées dans la AWS AppSync console ou autrement seront stockés en tant qu'attributs de la table. La clé et les attributs sont automatiquement mappés dans un format DynamoDB compatible à l'aide de l'assistant. `util.dynamodb.toMapValues(values)`
AWS AppSync prend également en charge les flux de travail de test et de débogage pour l'édition de résolveurs. Vous pouvez utiliser un `context` objet fictif pour voir la valeur transformée du modèle avant de l'invoquer. Vous pouvez éventuellement consulter la demande complète adressée à une source de données de manière interactive lorsque vous exécutez une requête. Pour plus d'informations, voir [Tester et déboguer les résolveurs (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/test-debug-resolvers-js.html) et [Surveillance et journalisation](https://docs.aws.amazon.com/appsync/latest/devguide/monitoring.html#aws-appsync-monitoring).
## Résolveurs avancés
Si vous suivez la section facultative de pagination de la section [Conception de votre schéma](designing-your-schema.md#aws-appsync-designing-your-schema), vous devez tout de même ajouter votre résolveur à votre demande pour utiliser la pagination. Notre exemple a utilisé une pagination de requête appelée `getPosts` pour renvoyer uniquement une partie des éléments demandés à la fois. Le code de notre résolveur sur ce champ peut ressembler à ceci :
```
/**
* Performs a scan on the dynamodb data source
*/
export function request(ctx) {
const { limit = 20, nextToken } = ctx.args;
return { operation: 'Scan', limit, nextToken };
}
/**
* @returns the result of the `put` operation
*/
export function response(ctx) {
const { items: posts = [], nextToken } = ctx.result;
return { posts, nextToken };
}
```
Dans la demande, nous transmettons le contexte de la demande. Notre `limit` est*20*, ce qui signifie que nous renvoyons jusqu'à 20 `Posts` dans la première requête. Notre `nextToken` curseur est fixé sur la première `Post` entrée de la source de données. Ils sont transmis aux arguments. La demande effectue ensuite un scan depuis le premier `Post` jusqu'au nombre limite de scan. La source de données stocke le résultat dans le contexte, qui est transmis à la réponse. La réponse renvoie `Posts` le résultat récupéré, puis définit le `nextToken` is set sur l'`Post`entrée juste après la limite. La demande suivante est envoyée pour faire exactement la même chose, mais en commençant par le décalage juste après la première requête. N'oubliez pas que ces types de demandes sont effectués de manière séquentielle et non en parallèle.
# Tester et déboguer les résolveurs dans AWS AppSync () JavaScript
AWS AppSync exécute des résolveurs sur un champ GraphQL par rapport à une source de données. Lorsque vous travaillez avec des résolveurs de pipeline, les fonctions interagissent avec vos sources de données. Comme décrit dans la [présentation des JavaScript résolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html), les fonctions communiquent avec les sources de données à l'aide de gestionnaires de requêtes et de réponses écrits JavaScript et exécutés sur le `APPSYNC_JS` moteur d'exécution. Cela vous permet de fournir une logique et des conditions personnalisées avant et après la communication avec la source de données.
Pour aider les développeurs à écrire, tester et déboguer ces résolveurs, la AWS AppSync console fournit également des outils permettant de créer une requête et une réponse GraphQL avec des données fictives jusqu'au résolveur de champs individuel. En outre, vous pouvez effectuer des requêtes, des mutations et des abonnements dans la AWS AppSync console et consulter un journal détaillé de l'intégralité de la demande d'Amazon CloudWatch. Cela inclut les résultats de la source de données.
## Tester avec des données fictives
Lorsqu'un résolveur GraphQL est invoqué, il contient un `context` objet contenant des informations pertinentes sur la requête. Ces informations incluent les arguments d'un client, les informations d'identité et les données du champ GraphQL parent. Il stocke également les résultats de la source de données, qui peuvent être utilisés dans le gestionnaire de réponses. Pour plus d'informations sur cette structure et les utilitaires d'assistance disponibles à utiliser lors de la programmation, consultez la référence de l'[objet contextuel Resolver](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html).
Lorsque vous écrivez ou modifiez une fonction de résolution, vous pouvez transmettre un objet de *contexte *fictif* ou de test* à l'éditeur de console. Cela vous permet de voir comment les gestionnaires de demandes et de réponses s'évaluent sans réellement se heurter à une source de données. Par exemple, vous pouvez transmettre un argument de test `firstname: Shaggy` et voir comment il est analysé lors de l'utilisation de `ctx.args.firstname` dans votre modèle de code. Vous pouvez également tester l'évaluation de n'importe quelle annotation d'utilitaire telle que `util.autoId()` ou `util.time.nowISO8601()`.
### Tester les résolveurs
Cet exemple utilisera la AWS AppSync console pour tester les résolveurs.
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, sélectionnez **Fonctions.**
1. Choisissez une fonction existante.
1. En haut de la page de la **fonction de mise à jour**, choisissez **Sélectionner le contexte de test**, puis sélectionnez **Créer un nouveau contexte**.
1. Sélectionnez un exemple d'objet de contexte ou renseignez le JSON manuellement dans la fenêtre **Configurer le contexte de test** ci-dessous.
1. Entrez un **nom de contexte de texte**.
1. Choisissez le bouton **Enregistrer**.
1. Pour évaluer votre résolveur à l'aide de cet objet de contexte simulé, choisissez **Exécuter test**
Pour un exemple plus pratique, supposons que vous disposiez d'une application stockant un type GraphQL `Dog` qui utilise la génération automatique d'identifiants pour les objets et les stocke dans Amazon DynamoDB. Vous souhaitez également écrire des valeurs à partir des arguments d'une mutation GraphQL et n'autoriser que certains utilisateurs à voir une réponse. L'extrait suivant montre à quoi pourrait ressembler le schéma :
```
type Dog {
breed: String
color: String
}
type Mutation {
addDog(firstname: String, age: Int): Dog
}
```
Vous pouvez écrire une AWS AppSync fonction et l'ajouter à votre `addDog` résolveur pour gérer la mutation. Pour tester votre AWS AppSync fonction, vous pouvez renseigner un objet de contexte comme dans l'exemple suivant. Le suivant possède les arguments `name` et `age` du client, ainsi qu'un `username` renseigné dans l'objet `identity` :
```
{
"arguments" : {
"firstname": "Shaggy",
"age": 4
},
"source" : {},
"result" : {
"breed" : "Miniature Schnauzer",
"color" : "black_grey"
},
"identity": {
"sub" : "uuid",
"issuer" : " https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
"username" : "Nadia",
"claims" : { },
"sourceIp" :[ "x.x.x.x" ],
"defaultAuthStrategy" : "ALLOW"
}
}
```
Vous pouvez tester votre AWS AppSync fonction à l'aide du code suivant :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id: util.autoId() }),
attributeValues: util.dynamodb.toMapValues(ctx.args),
};
}
export function response(ctx) {
if (ctx.identity.username === 'Nadia') {
console.log("This request is allowed")
return ctx.result;
}
util.unauthorized();
}
```
Le gestionnaire de demandes et de réponses évalué contient les données de votre objet de contexte de test et la valeur générée à partir de`util.autoId()`. De plus, si vous deviez modifier `username` avec une valeur autre que `Nadia`, les résultats ne seront pas renvoyés, car le contrôle d'autorisation échouerait. Pour plus d'informations sur le contrôle d'accès détaillé, consultez la section Cas [d'utilisation des autorisations](security-authorization-use-cases.md#aws-appsync-security-authorization-use-cases).
### Tester les gestionnaires de demandes et de réponses avec AWS AppSync APIs
Vous pouvez utiliser la commande `EvaluateCode` API pour tester votre code à distance avec des données simulées. Pour commencer à utiliser la commande, assurez-vous d'avoir ajouté l'`appsync:evaluateMappingCode`autorisation à votre politique. Par exemple :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateCode",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
Vous pouvez utiliser la commande en utilisant le [AWS CLI](https://aws.amazon.com/cli/)ou [AWS SDKs](https://aws.amazon.com/tools/). Prenons l'exemple du `Dog` schéma et de ses gestionnaires de demandes et de réponses de AWS AppSync fonctions présentés dans la section précédente. À l'aide de la CLI de votre station locale, enregistrez le code dans un fichier nommé`code.js`, puis enregistrez l'`context`objet dans un fichier nommé`context.json`. Depuis votre shell, exécutez la commande suivante :
```
$ aws appsync evaluate-code \
--code file://code.js \
--function response \
--context file://context.json \
--runtime name=APPSYNC_JS,runtimeVersion=1.0.0
```
La réponse contient un `evaluationResult` contenant la charge utile renvoyée par votre gestionnaire. Il contient également un `logs` objet contenant la liste des journaux générés par votre gestionnaire lors de l'évaluation. Cela permet de déboguer facilement l'exécution de votre code et de consulter les informations relatives à votre évaluation pour vous aider à résoudre le problème. Par exemple :
```
{
"evaluationResult": "{\"breed\":\"Miniature Schnauzer\",\"color\":\"black_grey\"}",
"logs": [
"INFO - code.js:13:5: \"This request is allowed\""
]
}
```
Ils `evaluationResult` peuvent être analysés au format JSON, ce qui donne :
```
{
"breed": "Miniature Schnauzer",
"color": "black_grey"
}
```
À l'aide du SDK, vous pouvez facilement intégrer des tests issus de votre suite de tests préférée pour valider le comportement de vos gestionnaires. Nous vous recommandons de créer des tests à l'aide du [Jest Testing Framework](https://jestjs.io/), mais toutes les suites de tests fonctionnent. L'extrait suivant montre une exécution de validation hypothétique. Notez que nous nous attendons à ce que la réponse d'évaluation soit un JSON valide. Nous utilisons donc `JSON.parse` pour récupérer le JSON à partir de la réponse sous forme de chaîne :
```
const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })
const runtime = {name:'APPSYNC_JS',runtimeVersion:'1.0.0')
test('request correctly calls DynamoDB', async () => {
const code = fs.readFileSync('./code.js', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
const contextJSON = JSON.parse(context)
const response = await client.evaluateCode({ code, context, runtime, function: 'request' }).promise()
const result = JSON.parse(response.evaluationResult)
expect(result.key.id.S).toBeDefined()
expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})
```
Cela donne le résultat suivant :
```
Ran all test suites.
> jest
PASS ./index.test.js
✓ request correctly calls DynamoDB (543 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 totalTime: 1.511 s, estimated 2 s
```
## Débogage d'une requête en direct
Rien ne remplace un end-to-end test et une journalisation pour déboguer une application de production. AWS AppSync vous permet de consigner les erreurs et de fournir les détails complets des demandes via Amazon CloudWatch. En outre, vous pouvez utiliser la AWS AppSync console pour tester les requêtes GraphQL, les mutations et les abonnements, ainsi que pour diffuser en direct les données du journal de chaque requête dans l'éditeur de requêtes afin de les déboguer en temps réel. Pour les abonnements, les journaux affichent les informations de temps de connexion.
Pour ce faire, vous devez activer Amazon CloudWatch Logs à l'avance, comme décrit dans [Surveillance et journalisation](monitoring.md#aws-appsync-monitoring). Ensuite, dans la AWS AppSync console, choisissez l'onglet **Requêtes**, puis entrez une requête GraphQL valide. Dans la section inférieure droite, cliquez et faites glisser la fenêtre **Logs** pour ouvrir la vue des logs. À l'aide de la flèche « Play » en haut de la page, exécutez votre requête GraphQL. Dans quelques instants, l'intégralité de vos journaux de demandes et de réponses relatifs à l'opération est diffusée dans cette section et vous pouvez les consulter dans la console.
# Configuration et utilisation des résolveurs de pipeline dans AWS AppSync () JavaScript
AWS AppSync exécute des résolveurs sur un champ GraphQL. Dans certains cas, les applications nécessitent l'exécution de plusieurs opérations pour résoudre un seul champ GraphQL. Avec les résolveurs de pipeline, les développeurs peuvent désormais composer des opérations appelées fonctions et les exécuter en séquence. Les résolveurs de pipeline sont utiles pour les applications qui, par exemple, doivent effectuer un contrôle d'autorisation avant d'extraire des données pour un champ.
Pour plus d'informations sur l'architecture d'un résolveur de JavaScript pipeline, consultez la présentation des [JavaScriptrésolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html#anatomy-of-a-pipeline-resolver-js).
## Étape 1 : Création d'un résolveur de pipeline
Dans la AWS AppSync console, accédez à la page **Schéma**.
Enregistrez le schéma suivant :
```
schema {
query: Query
mutation: Mutation
}
type Mutation {
signUp(input: Signup): User
}
type Query {
getUser(id: ID!): User
}
input Signup {
username: String!
email: String!
}
type User {
id: ID!
username: String
email: AWSEmail
}
```
Nous allons raccorder un résolveur de pipeline au champ **signUp** sur le type **Mutation**. Dans le champ Type de **mutation** sur le côté droit, choisissez **Attacher** à côté du champ de `signUp` mutation. Réglez le résolveur sur `pipeline resolver` et le `APPSYNC_JS` runtime, puis créez le résolveur.
Notre résolveur de pipeline inscrit un utilisateur en validant tout d'abord l'adresse e-mail saisie, puis en enregistrant l'utilisateur dans le système. **Nous allons encapsuler la validation de l'e-mail dans une fonction **ValidateEmail** et la sauvegarde de l'utilisateur dans une fonction SaveUser.** La fonction **validateEmail** s'exécute d'abord, puis si l'e-mail est valide, alors la fonction **saveUser** s'exécute.
Le flux d'exécution sera le suivant :
1. Gestionnaire de requêtes du résolveur Mutation.signup
1. Fonction validateEmail
1. Fonction saveUser
1. Gestionnaire de réponses du résolveur Mutation.signup
Comme nous réutiliserons probablement la fonction **ValidateEmail** dans d'autres résolveurs de notre API, nous voulons éviter d'`ctx.args`y accéder car ceux-ci changeront d'un champ GraphQL à l'autre. Au lieu de cela, nous pouvons utiliser le `ctx.stash` pour stocker l'attribut e-mail depuis l'argument de champ de saisie `signUp(input: Signup)`.
Mettez à jour le code de votre résolveur en remplaçant vos fonctions de demande et de réponse :
```
export function request(ctx) {
ctx.stash.email = ctx.args.input.email
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
```
Choisissez **Créer** ou **Enregistrer** pour mettre à jour le résolveur.
## Étape 2 : Création d'une fonction
Sur la page du résolveur de pipeline, dans la section **Fonctions**, cliquez sur **Ajouter une fonction**, puis sur **Créer une nouvelle fonction**. Il est également possible de créer des fonctions sans passer par la page du résolveur ; pour cela, dans la AWS AppSync console, rendez-vous sur la page **Fonctions**. Choisissez le bouton **Créer une fonction**. Créons une fonction permettant de vérifier si un e-mail est valide et provient d'un domaine spécifique. Si l'e-mail n'est pas valide, la fonction renvoie une erreur. Dans le cas contraire, elle transmet les données saisies.
Assurez-vous d'avoir créé une source de données de type **NONE**. Choisissez cette source de données dans la liste des **noms des sources de données**. Entrez le **nom de la fonction**`validateEmail`. Dans la zone du **code de fonction**, remplacez tout par cet extrait de code :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
const { email } = ctx.stash;
const valid = util.matches(
'^[a-zA-Z0-9_.+-]+@(?:(?:[a-zA-Z0-9-]+\.)?[a-zA-Z]+\.)?(myvaliddomain)\.com',
email
);
if (!valid) {
util.error(`"${email}" is not a valid email.`);
}
return { payload: { email } };
}
export function response(ctx) {
return ctx.result;
}
```
Passez en revue vos entrées, puis choisissez **Create**. Nous venons de créer notre fonction **validateEmail**. Répétez ces étapes pour créer la fonction **SaveUser** avec le code suivant (Pour des raisons de simplicité, nous utilisons **une** source de données NONE et prétendons que l'utilisateur a été enregistré dans le système après l'exécution de la fonction. ) :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return ctx.prev.result;
}
export function response(ctx) {
ctx.result.id = util.autoId();
return ctx.result;
}
```
Nous venons de créer notre fonction **SaveUser**.
## Étape 3 : Ajouter une fonction à un résolveur de pipeline
Nos fonctions auraient dû être ajoutées automatiquement au résolveur de pipeline que nous venons de créer. Si ce n'était pas le cas, ou si vous avez créé les fonctions via la page **Fonctions**, vous pouvez cliquer sur **Ajouter une fonction** sur la page du `signUp` résolveur pour les joindre. Ajoutez les fonctions **ValidateEmail** **et** SaveUser au résolveur. La fonction **validateEmail** doit être placée avant la fonction **saveUser**. Au fur et à mesure que vous ajoutez des fonctions, vous pouvez utiliser les options de **déplacement vers le haut** **et de déplacement vers le bas** pour réorganiser l'ordre d'exécution de vos fonctions. Passez en revue vos modifications, puis choisissez **Enregistrer**.
## Étape 4 : Exécution d'une requête
Dans la AWS AppSync console, accédez à la page **Requêtes**. Dans l'explorateur, assurez-vous d'utiliser votre mutation. Si ce n'est pas le cas, choisissez `Mutation` dans la liste déroulante, puis choisissez`+`. Entrez la requête suivante :
```
mutation {
signUp(input: {email: "nadia@myvaliddomain.com", username: "nadia"}) {
id
username
}
}
```
Cela devrait renvoyer quelque chose comme :
```
{
"data": {
"signUp": {
"id": "256b6cc2-4694-46f4-a55e-8cb14cc5d7fc",
"username": "nadia"
}
}
}
```
Nous avons inscrit notre utilisateur et validé l'e-mail saisi à l'aide d'un résolveur de pipeline.
# Création de requêtes de base (VTL)
**Note**
Nous prenons désormais principalement en charge le runtime APPSYNC\$1JS et sa documentation. [Pensez à utiliser le runtime APPSYNC\$1JS et ses guides ici.](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)
Les résolveurs GraphQL connectent les champs d'un schéma de type à une source de données. Les résolveurs sont le mécanisme par lequel les demandes sont satisfaites. AWS AppSync peut créer et connecter automatiquement des résolveurs à partir d'un schéma ou créer un schéma et connecter des résolveurs à partir d'une table existante sans que vous ayez à écrire de code.
Résolveurs AWS AppSync utilisés JavaScript pour convertir une expression GraphQL dans un format utilisable par la source de données. Les modèles de mappage peuvent également être écrits dans le [langage VTL (Apache Velocity Template Language)](https://velocity.apache.org/engine/2.0/vtl-reference.html) pour convertir une expression GraphQL dans un format utilisable par la source de données.
Cette section explique comment configurer les résolveurs à l'aide de VTL. Un guide de programmation de type didacticiel d'introduction pour l'écriture de résolveurs se trouve dans le [guide de programmation du modèle de mappage Resolver](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide), et les utilitaires d'assistance disponibles pour la programmation se trouvent dans la référence contextuelle du modèle de mappage [Resolver](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference). AWS AppSync possède également des flux de test et de débogage intégrés que vous pouvez utiliser lorsque vous modifiez ou créez à partir de zéro. Pour plus d'informations, consultez la section [Tester et déboguer les résolveurs](test-debug-resolvers.md#aws-appsync-test-debug-resolvers).
Nous vous recommandons de suivre ce guide avant d'essayer d'utiliser l'un des didacticiels mentionnés ci-dessus.
Dans cette section, nous expliquerons comment créer un résolveur, ajouter un résolveur pour les mutations et utiliser des configurations avancées.
## Créez votre premier résolveur
En suivant les exemples des sections précédentes, la première étape consiste à créer un résolveur adapté à votre `Query` type.
------
#### [ Console ]
1. Connectez-vous à la [AppSync console AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Sur le côté droit de la page, il y a une fenêtre appelée **Resolvers**. Cette zone contient une liste des types et des champs tels que définis dans votre fenêtre de **schéma** sur le côté gauche de la page. Vous pouvez associer des résolveurs aux champs. Par exemple, sous le type de **requête**, choisissez **Joindre** à côté du `getTodos` champ.
1. Sur la page **Create Resolver**, choisissez la source de données que vous avez créée dans le guide [Joindre une source de données](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html). Dans la fenêtre **Configurer les modèles de mappage**, vous pouvez choisir à la fois les modèles de mappage de demande et de réponse génériques à l'aide de la liste déroulante de droite ou écrire le vôtre.
**Note**
L'appariement d'un modèle de mappage de demande à un modèle de mappage de réponse est appelé résolveur d'unités. Les résolveurs d'unités sont généralement conçus pour effectuer des opérations par cœur ; nous recommandons de les utiliser uniquement pour des opérations uniques avec un petit nombre de sources de données. Pour les opérations plus complexes, nous recommandons d'utiliser des résolveurs de pipeline, qui peuvent exécuter plusieurs opérations avec plusieurs sources de données de manière séquentielle.
Pour plus d'informations sur la différence entre les modèles de mappage de demandes et de réponses, consultez [Unit Resolvers](https://docs.aws.amazon.com//appsync/latest/devguide/resolver-mapping-template-reference-overview.html#unit-resolvers).
Pour plus d'informations sur l'utilisation des résolveurs de pipeline, consultez la section [Résolveurs de pipeline](pipeline-resolvers.md#aws-appsync-pipeline-resolvers).
1. Pour les cas d'utilisation courants, la AWS AppSync console possède des modèles intégrés que vous pouvez utiliser pour obtenir des éléments à partir de sources de données (par exemple, toutes les requêtes relatives aux articles, les recherches individuelles, etc.). Par exemple, dans la version simple du schéma de [Designing your schema](designing-your-schema.md#aws-appsync-designing-your-schema) where `getTodos` didn't have pagination, le modèle de mappage des demandes pour la liste des éléments est le suivant :
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. Vous avez toujours besoin d'un modèle de mappage des réponses pour accompagner la demande. La console fournit un modèle par défaut avec la valeur de transmission suivante pour les listes :
```
$util.toJson($ctx.result.items)
```
Dans cet exemple, l'objet `context` (dont l'alias est `$ctx`) pour les listes d'éléments se présente sous la forme `$context.result.items`. Si votre opération GraphQL renvoie un seul élément, ce serait `$context.result`. AWS AppSync fournit des fonctions d'assistant pour les opérations courantes, notamment la fonction `$util.toJson` répertoriée précédemment, pour mettre correctement en forme les réponses. Pour obtenir la liste complète des fonctions, consultez la [référence de l'utilitaire de modèle de mappage Resolver](resolver-util-reference.md#aws-appsync-resolver-mapping-template-util-reference).
1. Choisissez **Save Resolver.**
------
#### [ API ]
1. Créez un objet résolveur en appelant l'[https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html)API.
1. Vous pouvez modifier les champs de votre résolveur en appelant l'[https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html)API.
------
#### [ CLI ]
1. Créez un résolveur en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)commande.
Vous devez saisir 6 paramètres pour cette commande particulière :
1. Celui `api-id` de votre API.
1. Le `type-name` type que vous souhaitez modifier dans votre schéma. Dans l'exemple de console, c'était le cas`Query`.
1. Le `field-name` champ que vous souhaitez modifier dans votre type. Dans l'exemple de console, c'était le cas`getTodos`.
1. La source `data-source-name` de données que vous avez créée dans le guide [Joindre une source de données](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html).
1. Le`request-mapping-template`, qui est le corps de la demande. Dans l'exemple de console, c'était :
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. Le`response-mapping-template`, qui est le corps de la réponse. Dans l'exemple de console, c'était :
```
$util.toJson($ctx.result.items)
```
Voici un exemple de commande :
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Query --field-name getTodos --data-source-name TodoTable --request-mapping-template "{ "version" : "2017-02-28", "operation" : "Scan", }" --response-mapping-template ""$"util.toJson("$"ctx.result.items)"
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"resolver": {
"kind": "UNIT",
"dataSourceName": "TodoTable",
"requestMappingTemplate": "{ version : 2017-02-28, operation : Scan, }",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query/resolvers/getTodos",
"typeName": "Query",
"fieldName": "getTodos",
"responseMappingTemplate": "$util.toJson($ctx.result.items)"
}
}
```
1. Pour modifier les modèles de and/or mappage de champs d'un résolveur, exécutez la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html)commande.
À l'exception du `api-id` paramètre, les paramètres utilisés dans la `create-resolver` commande seront remplacés par les nouvelles valeurs de la `update-resolver` commande.
------
## Ajouter un résolveur pour les mutations
L'étape suivante consiste à créer un résolveur adapté à votre `Mutation` type.
------
#### [ Console ]
1. Connectez-vous à la [AppSync console AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Sous le type de **mutation**, choisissez **Attacher** à côté du `addTodo` champ.
1. Sur la page **Create Resolver**, choisissez la source de données que vous avez créée dans le guide [Joindre une source de données](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html).
1. Dans la fenêtre **Configurer les modèles de mappage**, vous devez modifier le modèle de demande car il s'agit d'une mutation dans laquelle vous ajoutez un nouvel élément à DynamoDB. Utilisez le modèle de mappage de demande suivant :
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
1. AWS AppSync convertit automatiquement les arguments définis dans le `addTodo` champ à partir de votre schéma GraphQL en opérations DynamoDB. L'exemple précédent stocke les enregistrements dans DynamoDB à l'aide d'une clé `id` de, qui est transmise par l'argument de mutation sous la forme. `$ctx.args.id` Tous les autres champs que vous traversez sont automatiquement mappés aux attributs DynamoDB avec. `$util.dynamodb.toMapValuesJson($ctx.args)`
Pour ce résolveur, utilisez ensuite le modèle de mappage de réponse suivant :
```
$util.toJson($ctx.result)
```
AWS AppSync prend également en charge les flux de travail de test et de débogage pour l'édition de résolveurs. Vous pouvez utiliser un objet `context` simulé pour afficher la valeur transformée du modèle avant l'appel. Le cas échéant, vous pouvez afficher l'intégralité de l'exécution de la requête sur une source de données de façon interactive lorsque vous exécutez une requête. Pour plus d'informations, consultez les sections [Tester et déboguer les résolveurs](test-debug-resolvers.md#aws-appsync-test-debug-resolvers) et [Surveillance et journalisation](monitoring.md#aws-appsync-monitoring).
1. Choisissez **Save Resolver.**
------
#### [ API ]
Vous pouvez également le faire APIs en utilisant les commandes de la section [Créez votre premier résolveur](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) et les détails des paramètres de cette section.
------
#### [ CLI ]
Vous pouvez également le faire dans la CLI en utilisant les commandes de la section [Créez votre premier résolveur](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) et les détails des paramètres de cette section.
------
À ce stade, si vous n'utilisez pas les résolveurs avancés, vous pouvez commencer à utiliser votre API GraphQL comme indiqué [dans Utilisation](using-your-api.md#aws-appsync-using-your-api) de votre API.
## Résolveurs avancés
Si vous suivez la section Avancé et que vous créez un exemple de schéma dans [Conception de votre schéma](designing-your-schema.md#aws-appsync-designing-your-schema) pour effectuer un scan paginé, utilisez plutôt le modèle de demande suivant pour le `getTodos` champ :
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"limit": $util.defaultIfNull(${ctx.args.limit}, 20),
"nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}
```
Pour ce scénario de pagination, le mappage de réponse est plus qu'une simple transmission, car il doit contenir à la fois le *curseur* (afin que le client sache quelle est la prochaine page à démarrer) et le jeu de résultats. Le modèle de mappage est ainsi :
```
{
"todos": $util.toJson($context.result.items),
"nextToken": $util.toJson($context.result.nextToken)
}
```
Les champs du précédent modèle de mappage de réponse doivent correspondre aux champs définis dans votre type `TodoConnection`.
Dans le cas de relations où vous avez une `Comments` table et que vous résolvez le champ de commentaires sur le `Todo` type (qui renvoie un type de`[Comment]`), vous pouvez utiliser un modèle de mappage qui exécute une requête sur la deuxième table. Pour ce faire, vous devez déjà avoir créé une source de données pour la `Comments` table, comme indiqué dans la section [Joindre une source de données](attaching-a-data-source.md#aws-appsync-getting-started-build-a-schema-from-scratch).
**Note**
Nous utilisons une opération de requête sur une deuxième table à des fins d'illustration uniquement. Vous pouvez utiliser une autre opération sur DynamoDB à la place. En outre, vous pouvez extraire les données d'une autre source de données, telle qu' AWS Lambda Amazon OpenSearch Service, car la relation est contrôlée par votre schéma GraphQL.
------
#### [ Console ]
1. Connectez-vous à la [AppSync console AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Sous le type **Todo**, choisissez **Joindre** à côté du `comments` champ.
1. Sur la page **Créer un résolveur**, choisissez la source de données de votre table de **commentaires**. Le nom par défaut du tableau des **commentaires** dans les guides de démarrage rapide est`AppSyncCommentTable`, mais il peut varier en fonction du nom que vous lui avez donné.
1. Ajoutez l'extrait suivant à votre modèle de mappage de demandes :
```
{
"version": "2017-02-28",
"operation": "Query",
"index": "todoid-index",
"query": {
"expression": "todoid = :todoid",
"expressionValues": {
":todoid": {
"S": $util.toJson($context.source.id)
}
}
}
}
```
1. Le `context.source` fait référence à l'objet parent du champ actif en cours de résolution. Dans cet exemple, `source.id` fait référence à l'objet `Todo` individuel, qui est ensuite utilisé pour l'expression de la requête.
Vous pouvez utiliser le modèle de mappage de réponse de transmission, comme suit :
```
$util.toJson($ctx.result.items)
```
1. Choisissez **Save Resolver.**
1. Enfin, revenez sur la page **Schéma** de la console, attachez un résolveur au `addComment` champ et spécifiez la source de données de la `Comments` table. Dans ce cas, le modèle de mappage de requête est un simple `PutItem` avec le `todoid` spécifique qui est commenté en tant qu'argument, mais vous utilisez l'utilitaire `$utils.autoId()` pour créer une clé de tri unique pour le commentaire de la façon suivante :
```
{
"version": "2017-02-28",
"operation": "PutItem",
"key": {
"todoid": { "S": $util.toJson($context.arguments.todoid) },
"commentid": { "S": "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
Utilisez un modèle de réponse de transmission comme suit :
```
$util.toJson($ctx.result)
```
------
#### [ API ]
Vous pouvez également le faire APIs en utilisant les commandes de la section [Créez votre premier résolveur](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) et les détails des paramètres de cette section.
------
#### [ CLI ]
Vous pouvez également le faire dans la CLI en utilisant les commandes de la section [Créez votre premier résolveur](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver) et les détails des paramètres de cette section.
------
# Désactivation des modèles de mappage VTL avec des résolveurs Lambda directs (VTL)
**Note**
Nous prenons désormais principalement en charge le runtime APPSYNC\$1JS et sa documentation. [Pensez à utiliser le runtime APPSYNC\$1JS et ses guides ici.](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)
Avec les résolveurs Lambda directs, vous pouvez contourner l'utilisation de modèles de mappage VTL lorsque vous utilisez des sources de données. AWS Lambda AWS AppSync peut fournir une charge utile par défaut à votre fonction Lambda ainsi qu'une traduction par défaut de la réponse d'une fonction Lambda en un type GraphQL. Vous pouvez choisir de fournir un modèle de demande, un modèle de réponse ou aucun des deux et AWS AppSync vous les traiterez en conséquence.
Pour en savoir plus sur la charge utile des demandes par défaut et la traduction des réponses AWS AppSync fournies, consultez la référence du [résolveur Direct Lambda](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers). Pour plus d'informations sur la configuration d'une source de AWS Lambda données et la configuration d'une politique de confiance IAM, voir [Joindre une source de données](attaching-a-data-source.md).
## Configurer des résolveurs Lambda directs
Les sections suivantes vous montrent comment associer des sources de données Lambda et ajouter des résolveurs Lambda à vos champs.
### Ajouter une source de données Lambda
Avant de pouvoir activer les résolveurs Lambda directs, vous devez ajouter une source de données Lambda.
------
#### [ Console ]
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, sélectionnez **Sources de données.**
1. Choisissez **Create data source**.
1. Dans **Nom de la source de données**, entrez un nom pour votre source de données, tel que**myFunction**.
1. Pour **Type de source de données**, sélectionnez **AWS Lambda fonction**.
1. Pour **Région**, choisissez la région appropriée.
1. Pour **Function ARN**, choisissez la fonction Lambda dans la liste déroulante. Vous pouvez rechercher le nom de la fonction ou saisir manuellement l'ARN de la fonction que vous souhaitez utiliser.
1. Créez un nouveau rôle IAM (recommandé) ou choisissez un rôle existant disposant de l'autorisation `lambda:invokeFunction` IAM. Les rôles existants nécessitent une politique de confiance, comme expliqué dans la section [Joindre une source de données](attaching-a-data-source.md).
Voici un exemple de politique IAM disposant des autorisations requises pour effectuer des opérations sur la ressource :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "lambda:invokeFunction" ],
"Resource": [
"arn:aws:lambda:us-west-2:123456789012:function:myFunction",
"arn:aws:lambda:us-west-2:123456789012:function:myFunction:*"
]
}
]
}
```
------
1. Choisissez le bouton **Créer**.
------
#### [ CLI ]
1. Créez un objet de source de données en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html)commande.
Vous devez saisir 4 paramètres pour cette commande particulière :
1. Celui `api-id` de votre API.
1. Le `name` de votre source de données. Dans l'exemple de console, il s'agit du **nom de la source de données**.
1. La source `type` de données. Dans l'exemple de console, il s'agit d'**AWS Lambda une fonction**.
1. Le`lambda-config`, qui est l'**ARN de la fonction** dans l'exemple de console.
**Note**
Il existe d'autres paramètres tels `Region` que ceux qui doivent être configurés, mais ils seront généralement définis par défaut sur les valeurs de configuration de votre CLI.
Voici un exemple de commande :
```
aws appsync create-data-source --api-id abcdefghijklmnopqrstuvwxyz --name myFunction --type AWS_LAMBDA --lambda-config lambdaFunctionArn=arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"dataSource": {
"dataSourceArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/datasources/myFunction",
"type": "AWS_LAMBDA",
"name": "myFunction",
"lambdaConfig": {
"lambdaFunctionArn": "arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example"
}
}
}
```
1. Pour modifier les attributs d'une source de données, exécutez la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html)commande.
À l'exception du `api-id` paramètre, les paramètres utilisés dans la `create-data-source` commande seront remplacés par les nouvelles valeurs de la `update-data-source` commande.
------
### Activer les résolveurs Lambda directs
Après avoir créé une source de données Lambda et configuré le rôle IAM approprié pour permettre d'invoquer la fonction, vous pouvez la lier AWS AppSync à un résolveur ou à une fonction de pipeline.
------
#### [ Console ]
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Dans la fenêtre **Resolvers**, choisissez un champ ou une opération, puis cliquez sur le bouton **Joindre**.
1. Sur la page **Créer un nouveau résolveur**, choisissez la fonction Lambda dans la liste déroulante.
1. Afin de tirer parti des résolveurs Lambda directs, vérifiez que les modèles de mappage de demandes et de réponses sont désactivés dans la section **Configurer les modèles de mappage**.
1. Cliquez sur le bouton **Enregistrer le résolveur**.
------
#### [ CLI ]
+ Créez un résolveur en exécutant la [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)commande.
Vous devez saisir 6 paramètres pour cette commande particulière :
1. Celui `api-id` de votre API.
1. Le `type-name` type de votre schéma.
1. Le champ `field-name` de votre schéma.
1. Le ou `data-source-name` le nom de votre fonction Lambda.
1. Le`request-mapping-template`, qui est le corps de la demande. Dans l'exemple de console, cela a été désactivé :
```
" "
```
1. Le`response-mapping-template`, qui est le corps de la réponse. Dans l'exemple de console, cela a également été désactivé :
```
" "
```
Voici un exemple de commande :
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Subscription --field-name onCreateTodo --data-source-name LambdaTest --request-mapping-template " " --response-mapping-template " "
```
Une sortie sera renvoyée dans la CLI. Voici un exemple :
```
{
"resolver": {
"resolverArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/types/Subscription/resolvers/onCreateTodo",
"typeName": "Subscription",
"kind": "UNIT",
"fieldName": "onCreateTodo",
"dataSourceName": "LambdaTest"
}
}
```
------
Lorsque vous désactivez vos modèles de mappage, plusieurs comportements supplémentaires se produisent dans AWS AppSync :
+ En désactivant un modèle de mappage, vous indiquez AWS AppSync que vous acceptez les traductions de données par défaut spécifiées dans la référence du résolveur Direct [Lambda](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers).
+ [En désactivant le modèle de mappage des demandes, votre source de données Lambda recevra une charge utile composée de l'ensemble de l'objet Context.](resolver-context-reference.md)
+ En désactivant le modèle de mappage de réponse, le résultat de votre appel Lambda sera traduit en fonction de la version du modèle de mappage de demandes ou si le modèle de mappage de demandes est également désactivé.
# Tester et déboguer des résolveurs dans AWS AppSync (VTL)
**Note**
Nous prenons désormais principalement en charge le runtime APPSYNC\$1JS et sa documentation. [Pensez à utiliser le runtime APPSYNC\$1JS et ses guides ici.](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)
AWS AppSync exécute des résolveurs sur un champ GraphQL par rapport à une source de données. Comme décrit dans la section [Présentation du modèle de mappage Resolver](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview), les résolveurs communiquent avec les sources de données à l'aide d'un langage de modélisation. Cela vous permet de personnaliser le comportement et d'appliquer une logique et des conditions avant et après la communication avec la source de données. Pour un guide de programmation de type didacticiel d'introduction à l'écriture de résolveurs, consultez le guide de programmation du modèle de [mappage Resolver](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide).
Pour aider les développeurs à écrire, tester et déboguer ces résolveurs, la AWS AppSync console fournit également des outils permettant de créer une requête et une réponse GraphQL avec des données fictives jusqu'au résolveur de champs individuel. En outre, vous pouvez effectuer des requêtes, des mutations et des abonnements dans la AWS AppSync console et consulter un journal détaillé de l'intégralité CloudWatch de la demande provenant d'Amazon. Cela inclut les résultats d'une source de données.
## Tester avec des données fictives
Lorsqu'un résolveur GraphQL est invoqué, il contient un `context` objet contenant des informations sur la demande. Ces informations incluent les arguments d'un client, les informations d'identité et les données du champ GraphQL parent. Il contient également les résultats de la source de données, qui peuvent être utilisés dans le modèle de réponse. Vous trouverez plus de détails sur cette structure et les utilitaires d'annotations disponibles à utiliser lors de la programmation dans le document [Référence du contexte du modèle de mappage des résolveurs](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference).
Lorsque vous écrivez ou modifiez un résolveur, vous pouvez transmettre un objet de *contexte *fictif* ou de test* dans l'éditeur de console. Cela vous permet de voir comment les deux modèles de la demande et de la réponse évaluent, sans réellement s'exécuter par rapport à une source de données. Par exemple, vous pouvez transmettre un argument de test `firstname: Shaggy` et voir comment il est analysé lors de l'utilisation de `$ctx.args.firstname` dans votre modèle de code. Vous pouvez également tester l'évaluation de n'importe quelle annotation d'utilitaire telle que `$util.autoId()` ou `util.time.nowISO8601()`.
### Tester les résolveurs
Cet exemple utilisera la AWS AppSync console pour tester les résolveurs.
1. Connectez-vous à la [AppSyncconsole AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **APIs tableau de bord**, choisissez votre API GraphQL.
1. Dans la **barre latérale**, choisissez **Schema.**
1. Si ce n'est pas déjà fait, sous le type et à côté du champ, choisissez **Joindre** pour ajouter votre résolveur.
Pour plus d'informations sur la création d'un résolveur complet, voir [Configuration des](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html) résolveurs.
Sinon, sélectionnez le résolveur qui se trouve déjà dans le champ.
1. En haut de la page **Modifier le résolveur**, choisissez **Sélectionner le contexte de test**, puis **Créer un nouveau contexte**.
1. Sélectionnez un exemple d'objet de contexte ou renseignez le JSON manuellement dans la fenêtre de **contexte d'exécution** ci-dessous.
1. Entrez un **nom de contexte de texte**.
1. Choisissez le bouton **Enregistrer**.
1. En haut de la page **Modifier le résolveur**, sélectionnez **Exécuter le test**.
Pour un exemple plus pratique, supposons que vous disposiez d'une application stockant un type GraphQL `Dog` qui utilise la génération automatique d'identifiants pour les objets et les stocke dans Amazon DynamoDB. Il se peut aussi que vous souhaitiez écrire certaines valeurs des arguments d'une mutation GraphQL et permettre uniquement à des utilisateurs spécifiques de voir une réponse. Le schéma pourrait s'apparenter à ce qui suit :
```
type Dog {
breed: String
color: String
}
type Mutation {
addDog(firstname: String, age: Int): Dog
}
```
Lorsque vous ajoutez un résolveur pour la `addDog` mutation, vous pouvez renseigner un objet de contexte comme dans l'exemple suivant. Le suivant possède les arguments `name` et `age` du client, ainsi qu'un `username` renseigné dans l'objet `identity` :
```
{
"arguments" : {
"firstname": "Shaggy",
"age": 4
},
"source" : {},
"result" : {
"breed" : "Miniature Schnauzer",
"color" : "black_grey"
},
"identity": {
"sub" : "uuid",
"issuer" : " https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
"username" : "Nadia",
"claims" : { },
"sourceIp" :[ "x.x.x.x" ],
"defaultAuthStrategy" : "ALLOW"
}
}
```
Vous pouvez effectuer le test en utilisant les modèles de mappage de demande et de réponse suivants :
**Modèle de demande**
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
**Modèle de réponse**
```
#if ($context.identity.username == "Nadia")
$util.toJson($ctx.result)
#else
$util.unauthorized()
#end
```
Le modèle évalué possède les données de votre objet de contexte du test et la valeur générée à partir de `$util.autoId()`. De plus, si vous deviez modifier `username` avec une valeur autre que `Nadia`, les résultats ne seront pas renvoyés, car le contrôle d'autorisation échouerait. Pour plus d'informations sur le contrôle d'accès détaillé, consultez la section [Cas d'utilisation des autorisations](security-authorization-use-cases.md#aws-appsync-security-authorization-use-cases).
### Tester des modèles de mappage avec AWS AppSync APIs
Vous pouvez utiliser la commande `EvaluateMappingTemplate` API pour tester à distance vos modèles de mappage avec des données simulées. Pour commencer à utiliser la commande, assurez-vous d'avoir ajouté l'`appsync:evaluateMappingTemplate`autorisation à votre politique. Par exemple :
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateMappingTemplate",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
Vous pouvez utiliser la commande en utilisant le [AWS CLI](https://aws.amazon.com/cli/)ou [AWS SDKs](https://aws.amazon.com/tools/). Prenons par exemple le `Dog` schéma et ses modèles de request/response mappage de la section précédente. À l'aide de la CLI de votre station locale, enregistrez le modèle de demande dans un fichier nommé`request.vtl`, puis enregistrez l'`context`objet dans un fichier nommé`context.json`. Depuis votre shell, exécutez la commande suivante :
```
aws appsync evaluate-mapping-template --template file://request.vtl --context file://context.json
```
Cette commande renvoie la réponse suivante :
```
{
"evaluationResult": "{\n \"version\" : \"2017-02-28\",\n \"operation\" : \"PutItem\",\n \"key\" : {\n \"id\" : { \"S\" : \"afcb4c85-49f8-40de-8f2b-248949176456\" }\n },\n \"attributeValues\" : {\"firstname\":{\"S\":\"Shaggy\"},\"age\":{\"N\":4}}\n}\n"
}
```
`evaluationResult`Il contient les résultats du test de votre modèle fourni avec le modèle fourni`context`. Vous pouvez également tester vos modèles à l'aide du AWS SDKs. Voici un exemple d'utilisation du AWS SDK pour la JavaScript version 2 :
```
const AWS = require('aws-sdk')
const client = new AWS.AppSync({ region: 'us-east-2' })
const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
client
.evaluateMappingTemplate({ template, context })
.promise()
.then((data) => console.log(data))
```
À l'aide du SDK, vous pouvez facilement intégrer les tests de votre suite de tests préférée pour valider le comportement de votre modèle. Nous vous recommandons de créer des tests à l'aide du [Jest Testing Framework](https://jestjs.io/), mais toutes les suites de tests fonctionnent. L'extrait suivant montre une exécution de validation hypothétique. Notez que nous nous attendons à ce que la réponse d'évaluation soit un JSON valide. Nous utilisons donc `JSON.parse` pour récupérer le JSON à partir de la réponse sous forme de chaîne :
```
const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })
test('request correctly calls DynamoDB', async () => {
const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
const contextJSON = JSON.parse(context)
const response = await client.evaluateMappingTemplate({ template, context }).promise()
const result = JSON.parse(response.evaluationResult)
expect(result.key.id.S).toBeDefined()
expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})
```
Cela donne le résultat suivant :
```
Ran all test suites.
> jest
PASS ./index.test.js
✓ request correctly calls DynamoDB (543 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.511 s, estimated 2 s
```
## Débogage d'une requête en direct
Rien ne remplace un end-to-end test et une journalisation pour déboguer une application de production. AWS AppSync vous permet de consigner les erreurs et de fournir les détails complets des demandes à l'aide d'Amazon CloudWatch. En outre, vous pouvez utiliser la AWS AppSync console pour tester les requêtes GraphQL, les mutations et les abonnements, ainsi que pour diffuser en direct les données du journal de chaque requête dans l'éditeur de requêtes afin de les déboguer en temps réel. Pour les abonnements, les journaux affichent les informations de temps de connexion.
Pour ce faire, vous devez activer Amazon CloudWatch Logs à l'avance, comme décrit dans [Surveillance et journalisation](monitoring.md#aws-appsync-monitoring). Ensuite, dans la AWS AppSync console, choisissez l'onglet **Requêtes**, puis entrez une requête GraphQL valide. Dans la section inférieure droite, cliquez et faites glisser la fenêtre **Logs** pour ouvrir la vue des logs. À l'aide de la flèche « Play » en haut de la page, exécutez votre requête GraphQL. Dans quelques instants, vos journaux complets de demande et de réponse pour l'opération sont diffusés vers cette section et vous pouvez les voir dans la console.
# Configuration et utilisation de résolveurs de pipeline dans AWS AppSync (VTL)
**Note**
Nous prenons désormais principalement en charge le runtime APPSYNC\$1JS et sa documentation. [Pensez à utiliser le runtime APPSYNC\$1JS et ses guides ici.](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)
AWS AppSync exécute des résolveurs sur un champ GraphQL. Dans certains cas, les applications nécessitent l'exécution de plusieurs opérations pour résoudre un seul champ GraphQL. Avec les résolveurs de pipeline, les développeurs peuvent désormais composer des opérations appelées fonctions et les exécuter en séquence. Les résolveurs de pipeline sont utiles pour les applications qui, par exemple, doivent effectuer un contrôle d'autorisation avant d'extraire des données pour un champ.
Un résolveur de pipeline est composé d'un modèle de mappage **Avant**, d'un modèle de mappage **Après** et d'une liste de Fonctions. Chaque fonction possède un modèle de mappage de **requêtes** et de **réponses** qu'elle exécute par rapport à une source de données. Comme un résolveur de pipeline délègue l'exécution à une liste de fonctions, il n'est lié à aucune source de données. Les résolveurs d'unités et les fonctions sont des primitives qui exécutent des opérations sur des sources de données. Consultez la [présentation du modèle de mappage Resolver](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview) pour plus d'informations.
## Étape 1 : Création d'un résolveur de pipeline
Dans la AWS AppSync console, accédez à la page **Schéma**.
Enregistrez le schéma suivant :
```
schema {
query: Query
mutation: Mutation
}
type Mutation {
signUp(input: Signup): User
}
type Query {
getUser(id: ID!): User
}
input Signup {
username: String!
email: String!
}
type User {
id: ID!
username: String
email: AWSEmail
}
```
Nous allons raccorder un résolveur de pipeline au champ **signUp** sur le type **Mutation**. Dans le champ Type de **mutation** sur le côté droit, choisissez **Attacher** à côté du champ de `signUp` mutation. Sur la page de création d'un résolveur, cliquez sur **Actions**, puis sur **Mettre à jour le moteur d'exécution**. Choisissez`Pipeline Resolver`, puis choisissez`VTL`, puis choisissez **Mettre à jour**. La page doit désormais afficher trois sections : une zone de texte **avant le mappage du modèle**, une section **Fonctions** et une zone de texte **après le mappage du modèle**.
Notre résolveur de pipeline inscrit un utilisateur en validant tout d'abord l'adresse e-mail saisie, puis en enregistrant l'utilisateur dans le système. Nous allons encapsuler la validation d'e-mail dans une fonction **validateEmail** et l'enregistrement de l'utilisateur dans une fonction **saveUser**. La fonction **validateEmail** s'exécute d'abord, puis si l'e-mail est valide, alors la fonction **saveUser** s'exécute.
Le flux d'exécution sera comme suit :
1. Modèle de mappage de demande de résolveur Mutation.signUp
1. Fonction validateEmail
1. Fonction saveUser
1. Modèle de mappage de réponse de résolveur Mutation.signUp
Comme nous réutiliserons probablement la fonction **ValidateEmail** dans d'autres résolveurs de notre API, nous voulons éviter d'`$ctx.args`y accéder car ceux-ci changeront d'un champ GraphQL à l'autre. Au lieu de cela, nous pouvons utiliser le `$ctx.stash` pour stocker l'attribut e-mail depuis l'argument de champ de saisie `signUp(input: Signup)`.
Modèle **de** mappage BEFORE :
```
## store email input field into a generic email key
$util.qr($ctx.stash.put("email", $ctx.args.input.email))
{}
```
La console fournit un modèle de mappage **AFTER** passthrough par défaut que nous utiliserons :
```
$util.toJson($ctx.result)
```
Choisissez **Créer** ou **Enregistrer** pour mettre à jour le résolveur.
## Étape 2 : Création d'une fonction
Sur la page du résolveur de pipeline, dans la section **Fonctions**, cliquez sur **Ajouter une fonction**, puis sur **Créer une nouvelle fonction**. Il est également possible de créer des fonctions sans passer par la page du résolveur ; pour cela, dans la AWS AppSync console, rendez-vous sur la page **Fonctions**. Choisissez le bouton **Créer une fonction**. Créons une fonction permettant de vérifier si un e-mail est valide et provient d'un domaine spécifique. Si l'e-mail n'est pas valide, la fonction renvoie une erreur. Dans le cas contraire, elle transmet les données saisies.
Sur la page des nouvelles fonctions, choisissez **Actions**, puis **Mettre à jour le moteur d'exécution**. Choisissez`VTL`, puis **Mettre à jour**. Assurez-vous d'avoir créé une source de données de type **NONE**. Choisissez cette source de données dans la liste des **noms des sources de données**. Pour le **nom de la fonction**, entrez`validateEmail`. Dans la zone du **code de fonction**, remplacez tout par cet extrait de code :
```
#set($valid = $util.matches("^[a-zA-Z0-9_.+-]+@(?:(?:[a-zA-Z0-9-]+\.)?[a-zA-Z]+\.)?(myvaliddomain)\.com", $ctx.stash.email))
#if (!$valid)
$util.error("$ctx.stash.email is not a valid email.")
#end
{
"payload": { "email": $util.toJson(${ctx.stash.email}) }
}
```
Collez ceci dans le modèle de mappage des réponses :
```
$util.toJson($ctx.result)
```
Passez en revue vos modifications, puis choisissez **Créer**. Nous venons de créer notre fonction **validateEmail**. Répétez ces étapes pour créer la fonction **SaveUser** avec les modèles de mappage de demandes et de réponses suivants (par souci de simplicité, nous utilisons **une** source de données NONE et prétendons que l'utilisateur a été enregistré dans le système après l'exécution de la fonction. ) :
Modèle de mappage de demande :
```
## $ctx.prev.result contains the signup input values. We could have also
## used $ctx.args.input.
{
"payload": $util.toJson($ctx.prev.result)
}
```
Modèle de mappage de réponse :
```
## an id is required so let's add a unique random identifier to the output
$util.qr($ctx.result.put("id", $util.autoId()))
$util.toJson($ctx.result)
```
Nous venons de créer notre fonction **SaveUser**.
## Étape 3 : Ajouter une fonction à un résolveur de pipeline
Nos fonctions auraient dû être ajoutées automatiquement au résolveur de pipeline que nous venons de créer. Si ce n'était pas le cas, ou si vous avez créé les fonctions via la page **Fonctions**, vous pouvez cliquer sur **Ajouter une fonction** sur la page du résolveur pour les joindre. Ajoutez les fonctions **ValidateEmail** **et** SaveUser au résolveur. La fonction **validateEmail** doit être placée avant la fonction **saveUser**. Au fur et à mesure que vous ajoutez des fonctions, vous pouvez utiliser les options de **déplacement vers le haut** **et de déplacement vers le bas** pour réorganiser l'ordre d'exécution de vos fonctions. Passez en revue vos modifications, puis choisissez **Enregistrer**.
## Étape 4 : Exécution d'une requête
Dans la AWS AppSync console, accédez à la page **Requêtes**. Dans l'explorateur, assurez-vous d'utiliser votre mutation. Si ce n'est pas le cas, choisissez `Mutation` dans la liste déroulante, puis choisissez`+`. Entrez la requête suivante :
```
mutation {
signUp(input: {
email: "nadia@myvaliddomain.com"
username: "nadia"
}) {
id
email
}
}
```
Cela devrait renvoyer quelque chose comme :
```
{
"data": {
"signUp": {
"id": "256b6cc2-4694-46f4-a55e-8cb14cc5d7fc",
"email": "nadia@myvaliddomain.com"
}
}
}
```
Nous avons inscrit notre utilisateur et validé l'e-mail saisi à l'aide d'un résolveur de pipeline. Pour suivre un didacticiel plus complet sur les résolveurs de pipeline, vous pouvez consulter le [Didacticiel : Résolveurs de Pipeline](tutorial-pipeline-resolvers.md#aws-appsync-tutorial-pipeline-resolvers)
# Utilisation d'une AWS AppSync API avec le AWS CDK
**Astuce**
Avant d'utiliser le CDK, nous vous recommandons de consulter la [documentation officielle du CDK ainsi que la](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) référence AWS AppSync du [CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_appsync-readme.html).
Nous vous recommandons également de vous assurer que vos installations [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) et [NPM](https://docs.npmjs.com/) fonctionnent sur votre système.
Dans cette section, nous allons créer une application CDK simple capable d'ajouter et de récupérer des éléments à partir d'une table DynamoDB. Il s'agit d'un exemple de démarrage rapide utilisant une partie du code des sections [Conception de votre schéma](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html), [Attachement d'une source de données](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html) et [Configuration des résolveurs (JavaScript)](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html).
## Configuration d'un projet CDK
**Avertissement**
Ces étapes peuvent ne pas être totalement précises en fonction de votre environnement. Nous partons du principe que les utilitaires nécessaires sont installés sur votre système, qu'il existe un moyen d'interfacer avec les AWS services et que les configurations appropriées sont en place.
La première étape consiste à installer le AWS CDK. Dans votre CLI, vous pouvez entrer la commande suivante :
```
npm install -g aws-cdk
```
Ensuite, vous devez créer un répertoire de projet, puis y accéder. Voici un exemple d'ensemble de commandes permettant de créer un répertoire et d'y accéder :
```
mkdir example-cdk-app
cd example-cdk-app
```
Ensuite, vous devez créer une application. Notre service utilise principalement TypeScript. Dans le répertoire de votre projet, entrez la commande suivante :
```
cdk init app --language typescript
```
Dans ce cas, une application CDK ainsi que ses fichiers d'initialisation seront installés :
![\[Terminal output showing Git repository initialization and npm install completion.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-init-app-example.png)
La structure de votre projet peut ressembler à ceci :
![\[Project directory structure showing folders and files for an example CDK app.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-init-directories.png)
Vous remarquerez que nous avons plusieurs annuaires importants :
+ `bin`: Le fichier bin initial créera l'application. Nous n'aborderons pas cela dans ce guide.
+ `lib`: Le répertoire lib contient vos fichiers de pile. Vous pouvez considérer les fichiers de pile comme des unités d'exécution individuelles. Les constructions se trouveront dans nos fichiers de pile. Il s'agit essentiellement de ressources pour un service qui sera intégré CloudFormation lors du déploiement de l'application. C'est là que se déroulera la majeure partie de notre codage.
+ `node_modules`: Ce répertoire est créé par NPM et contient toutes les dépendances du package que vous avez installées à l'aide de la `npm` commande.
Notre fichier de pile initial peut contenir quelque chose comme ceci :
```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// import * as sqs from 'aws-cdk-lib/aws-sqs';
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// The code that defines your stack goes here
// example resource
// const queue = new sqs.Queue(this, 'ExampleCdkAppQueue', {
// visibilityTimeout: cdk.Duration.seconds(300)
// });
}
}
```
Il s'agit du code standard pour créer une pile dans notre application. Dans cet exemple, la majeure partie de notre code entrera dans le champ d'application de cette classe.
Pour vérifier que votre fichier de pile se trouve dans l'application, dans le répertoire de votre application, exécutez la commande suivante dans le terminal :
```
cdk ls
```
Une liste de vos piles devrait apparaître. Si ce n'est pas le cas, vous devrez peut-être recommencer les étapes ou consulter la documentation officielle pour obtenir de l'aide.
Si vous souhaitez créer vos modifications de code avant le déploiement, vous pouvez toujours exécuter la commande suivante dans le terminal :
```
npm run build
```
Et pour voir les modifications avant le déploiement :
```
cdk diff
```
Avant d'ajouter notre code au fichier de pile, nous allons effectuer un bootstrap. Le bootstrapping nous permet de fournir des ressources pour le CDK avant le déploiement de l'application. Vous trouverez plus d'informations sur ce processus [ici](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html). Pour créer un bootstrap, la commande est la suivante :
```
cdk bootstrap aws://ACCOUNT-NUMBER/REGION
```
**Astuce**
Cette étape nécessite plusieurs autorisations IAM sur votre compte. Votre bootstrap sera refusé si vous ne les avez pas. Dans ce cas, vous devrez peut-être supprimer les ressources incomplètes causées par le bootstrap, telles que le compartiment S3 qu'il génère.
Bootstrap lancera plusieurs ressources. Le message final ressemblera à ceci :
![\[Terminal output showing successful bootstrapping of an AWS environment.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-init-bootstrap-final.png)
Cela se fait une fois par compte et par région, vous n'aurez donc pas à le faire souvent. Les principales ressources du bootstrap sont la CloudFormation pile et le compartiment Amazon S3.
Le compartiment Amazon S3 est utilisé pour stocker les fichiers et les rôles IAM qui accordent les autorisations nécessaires pour effectuer des déploiements. Les ressources requises sont définies dans une CloudFormation pile, appelée pile bootstrap, qui est généralement nommée`CDKToolkit`. Comme toute CloudFormation pile, elle apparaît dans la CloudFormation console une fois déployée :
![\[CDKToolkit stack with CREATE_COMPLETE status in CloudFormation console.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-init-bootstrap-cfn-console.png)
Il en va de même pour le bucket :
![\[S3 bucket details showing name, region, access settings, and creation date.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-init-bootstrap-bucket-console.png)
Pour importer les services dont nous avons besoin dans notre fichier de pile, nous pouvons utiliser la commande suivante :
```
npm install aws-cdk-lib # V2 command
```
**Astuce**
Si vous rencontrez des problèmes avec la V2, vous pouvez installer les bibliothèques individuelles à l'aide des commandes V1 :
```
npm install @aws-cdk/aws-appsync @aws-cdk/aws-dynamodb
```
Nous ne le recommandons pas car la V1 est obsolète.
## Implémentation d'un projet CDK - Schéma
Nous pouvons maintenant commencer à implémenter notre code. Nous devons d'abord créer notre schéma. Vous pouvez simplement créer un `.graphql` fichier dans votre application :
```
mkdir schema
touch schema.graphql
```
Dans notre exemple, nous avons inclus un répertoire de premier niveau appelé `schema` contenant : `schema.graphql`
![\[File structure showing a schema folder containing schema.graphql file.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-schema-directory.png)
Dans notre schéma, incluons un exemple simple :
```
input CreatePostInput {
title: String
content: String
}
type Post {
id: ID!
title: String
content: String
}
type Mutation {
createPost(input: CreatePostInput!): Post
}
type Query {
getPost: [Post]
}
```
De retour dans notre fichier de pile, nous devons nous assurer que les directives d'importation suivantes sont définies :
```
import * as cdk from 'aws-cdk-lib';
import * as appsync from 'aws-cdk-lib/aws-appsync';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';
```
Dans la classe, nous allons ajouter du code pour créer notre API GraphQL et le connecter à notre `schema.graphql` fichier :
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// makes a GraphQL API
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
}
}
```
Nous ajouterons également du code pour imprimer l'URL, la clé d'API et la région de GraphQL :
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Makes a GraphQL API construct
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
// Prints out URL
new cdk.CfnOutput(this, "GraphQLAPIURL", {
value: api.graphqlUrl
});
// Prints out the AppSync GraphQL API key to the terminal
new cdk.CfnOutput(this, "GraphQLAPIKey", {
value: api.apiKey || ''
});
// Prints out the stack region to the terminal
new cdk.CfnOutput(this, "Stack Region", {
value: this.region
});
}
}
```
À ce stade, nous allons à nouveau utiliser Deploy notre application :
```
cdk deploy
```
Voici le résultat :
![\[Deployment output showing ExampleCdkAppStack details, including GraphQL API URL and stack region.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-schema.png)
Il semble que notre exemple soit réussi, mais vérifions la AWS AppSync console juste pour confirmer :
![\[GraphQL interface showing successful API request with response data displayed.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-schema-result-1.png)
Il semblerait que notre API ait été créée. Nous allons maintenant vérifier le schéma attaché à l'API :
![\[GraphQL schema defining CreatePostInput, Post type, Mutation, and Query operations.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-schema-result-2.png)
Cela semble correspondre à notre code de schéma, c'est donc un succès. Une autre façon de le confirmer du point de vue des métadonnées consiste à examiner la CloudFormation pile :
![\[CloudFormation stack showing ExampleCdkAppStack update complete and CDKToolkit creation complete.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-schema-result-3.png)
Lorsque nous déployons notre application CDK, elle génère CloudFormation des ressources telles que le bootstrap. Chaque pile de notre application correspond à une CloudFormation pile à l'échelle 1:1. Si vous revenez au code de pile, le nom de la pile a été extrait du nom de la classe`ExampleCdkAppStack`. Vous pouvez voir les ressources qu'il a créées, qui correspondent également à nos conventions de dénomination, dans notre structure d'API GraphQL :
![\[Expanded view of post-apis resource showing Schema, DefaultApiKey, and CDKMetadata.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-schema-result-4.png)
## Implémentation d'un projet CDK - Source de données
Ensuite, nous devons ajouter notre source de données. Notre exemple utilisera une table DynamoDB. Dans la classe stack, nous allons ajouter du code pour créer une nouvelle table :
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Makes a GraphQL API construct
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
//creates a DDB table
const add_ddb_table = new dynamodb.Table(this, 'posts-table', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
// Prints out URL
new cdk.CfnOutput(this, "GraphQLAPIURL", {
value: api.graphqlUrl
});
// Prints out the AppSync GraphQL API key to the terminal
new cdk.CfnOutput(this, "GraphQLAPIKey", {
value: api.apiKey || ''
});
// Prints out the stack region to the terminal
new cdk.CfnOutput(this, "Stack Region", {
value: this.region
});
}
}
```
À ce stade, déployons à nouveau :
```
cdk deploy
```
Nous devrions vérifier la console DynamoDB pour trouver notre nouvelle table :
![\[DynamoDB console showing ExampleCdkAppStack-poststable as Active with Provisioned capacity.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-ddb-result-1.png)
Le nom de notre pile est correct et le nom de la table correspond à notre code. Si nous vérifions à nouveau notre CloudFormation pile, nous verrons maintenant le nouveau tableau :
![\[Expanded view of a logical ID in CloudFormation showing post-apis, posts-table, and CDKMetadata.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-ddb-result-2.png)
## Implémentation d'un projet CDK - Resolver
Cet exemple utilisera deux résolveurs : l'un pour interroger la table et l'autre pour y ajouter des éléments. Puisque nous utilisons des résolveurs de pipeline, nous devrons déclarer deux résolveurs de pipeline avec une fonction dans chacun. Dans la requête, nous allons ajouter le code suivant :
```
export class ExampleCdkAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Makes a GraphQL API construct
const api = new appsync.GraphqlApi(this, 'post-apis', {
name: 'api-to-process-posts',
schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'),
});
//creates a DDB table
const add_ddb_table = new dynamodb.Table(this, 'posts-table', {
partitionKey: {
name: 'id',
type: dynamodb.AttributeType.STRING,
},
});
// Creates a function for query
const add_func = new appsync.AppsyncFunction(this, 'func-get-post', {
name: 'get_posts_func_1',
api,
dataSource: api.addDynamoDbDataSource('table-for-posts', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return { operation: 'Scan' };
}
export function response(ctx) {
return ctx.result.items;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
// Creates a function for mutation
const add_func_2 = new appsync.AppsyncFunction(this, 'func-add-post', {
name: 'add_posts_func_1',
api,
dataSource: api.addDynamoDbDataSource('table-for-posts-2', add_ddb_table),
code: appsync.Code.fromInline(`
export function request(ctx) {
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({id: util.autoId()}),
attributeValues: util.dynamodb.toMapValues(ctx.args.input),
};
}
export function response(ctx) {
return ctx.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
});
// Adds a pipeline resolver with the get function
new appsync.Resolver(this, 'pipeline-resolver-get-posts', {
api,
typeName: 'Query',
fieldName: 'getPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func],
});
// Adds a pipeline resolver with the create function
new appsync.Resolver(this, 'pipeline-resolver-create-posts', {
api,
typeName: 'Mutation',
fieldName: 'createPost',
code: appsync.Code.fromInline(`
export function request(ctx) {
return {};
}
export function response(ctx) {
return ctx.prev.result;
}
`),
runtime: appsync.FunctionRuntime.JS_1_0_0,
pipelineConfig: [add_func_2],
});
// Prints out URL
new cdk.CfnOutput(this, "GraphQLAPIURL", {
value: api.graphqlUrl
});
// Prints out the AppSync GraphQL API key to the terminal
new cdk.CfnOutput(this, "GraphQLAPIKey", {
value: api.apiKey || ''
});
// Prints out the stack region to the terminal
new cdk.CfnOutput(this, "Stack Region", {
value: this.region
});
}
}
```
Dans cet extrait, nous avons ajouté un résolveur de pipeline appelé auquel est `func-add-post` attachée `pipeline-resolver-create-posts` une fonction appelée. Il s'agit du code qui sera ajouté `Posts` au tableau. L'autre résolveur de pipeline a été appelé `pipeline-resolver-get-posts` avec une fonction appelée `func-get-post` qui récupère les éléments `Posts` ajoutés à la table.
Nous allons le déployer pour l'ajouter au AWS AppSync service :
```
cdk deploy
```
Examinons la AWS AppSync console pour voir s'ils étaient attachés à notre API GraphQL :
![\[GraphQL API schema showing mutation and query fields with Pipeline resolvers.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-1.png)
Cela semble correct. Dans le code, ces deux résolveurs étaient attachés à l'API GraphQL que nous avons créée (indiquée par la valeur props présente à `api` la fois dans les résolveurs et dans les fonctions). Dans l'API GraphQL, les champs auxquels nous avons attaché nos résolveurs étaient également spécifiés dans les accessoires (définis par les `fieldname` accessoires `typename` et de chaque résolveur).
Voyons si le contenu des résolveurs est correct en commençant par : `pipeline-resolver-get-posts`
![\[Code snippet showing request and response functions in a resolver, with an arrow pointing to them.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-2.png)
Les gestionnaires avant et après correspondent à la valeur de nos `code` accessoires. Nous pouvons également voir qu'une fonction est appelée`add_posts_func_1`, ce qui correspond au nom de la fonction que nous avons attachée dans le résolveur.
Regardons le contenu du code de cette fonction :
![\[Function code showing request and response methods for a PutItem operation.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-3.png)
Cela correspond aux `code` accessoires de la `add_posts_func_1` fonction. Notre requête a été chargée avec succès, alors vérifions-la :
![\[Resolver code with request and response functions, and a get_posts_func_1 function listed below.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-4.png)
Ils correspondent également au code. Si nous examinons `get_posts_func_1` :
![\[Code snippet showing two exported functions: request returning 'Scan' operation and response returning items.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-5.png)
Tout semble être en place. Pour confirmer cela du point de vue des métadonnées, nous pouvons CloudFormation réexaminer notre pile :
![\[List of logical IDs for AWS resources including API, table, functions, and pipelines.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-deploy-resolver-result-6.png)
Maintenant, nous devons tester ce code en effectuant quelques requêtes.
## Mise en œuvre d'un projet CDK - Demandes
Pour tester notre application dans la AWS AppSync console, nous avons effectué une requête et une mutation :
![\[GraphQL code snippet showing a query to get post details and a mutation to create a post.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-request-1.png)
`MyMutation`contient une `createPost` opération avec les arguments `1970-01-01T12:30:00.000Z` et`first post`. Il renvoie le `date` et `title` que nous avons transmis ainsi que la `id` valeur générée automatiquement. L'exécution de la mutation donne le résultat suivant :
```
{
"data": {
"createPost": {
"date": "1970-01-01T12:30:00.000Z",
"id": "4dc1c2dd-0aa3-4055-9eca-7c140062ada2",
"title": "first post"
}
}
}
```
Si nous vérifions rapidement la table DynamoDB, nous pouvons voir notre entrée dans la table lorsque nous la scannons :
![\[DynamoDB table entry showing id, date, and title fields for a single item.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cdk-code-request-2.png)
De retour dans la AWS AppSync console, si nous exécutons la requête pour le récupérer`Post`, nous obtenons le résultat suivant :
```
{
"data": {
"getPost": [
{
"id": "9f62c4dd-49d5-48d5-b835-143284c72fe0",
"date": "1970-01-01T12:30:00.000Z",
"title": "first post"
}
]
}
}
```
# Utilisation d'abonnements pour des applications de données en temps réel dans AWS AppSync
**Important**
À WebSockets partir du 13 mars 2025, vous pouvez créer une PubSub API en temps réel alimentée par AWS AppSync Events. Pour plus d'informations, consultez la section [Publier des événements via WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) le *Guide du développeur d'AWS AppSync événements*.
AWS AppSyncvous permet d'utiliser des abonnements pour mettre en œuvre des mises à jour d'applications en direct, des notifications push, etc. Lorsque les clients invoquent les opérations d'abonnement GraphQL, une WebSocket connexion sécurisée est automatiquement établie et maintenue par. AWS AppSync Les applications peuvent ensuite distribuer des données en temps réel à partir d'une source de données aux abonnés tout en gérant en AWS AppSync permanence les exigences de connexion et de dimensionnement de l'application. Les sections suivantes vous montreront comment AWS AppSync fonctionnent les abonnements.
## Directives d'abonnement au schéma GraphQL
Les abonnements AWS AppSync sont invoqués en réponse à une mutation. Cela signifie que vous pouvez créer n'importe quelle source de données en temps AWS AppSync réel en spécifiant une directive de schéma GraphQL sur une mutation.
Les bibliothèques AWS Amplify clientes gèrent automatiquement la gestion des connexions par abonnement. Les bibliothèques utilisent Pure WebSockets comme protocole réseau entre le client et le service.
**Note**
Pour contrôler l'autorisation au moment de la connexion à un abonnement, vous pouvez utiliser Gestion des identités et des accès AWS (IAM) AWS Lambda, les groupes d'identités Amazon Cognito ou les groupes d'utilisateurs Amazon Cognito pour l'autorisation au niveau du champ. Pour des contrôles d'accès précis sur les abonnements, vous pouvez associer des résolveurs à vos champs d'abonnement et exécuter une logique en utilisant l'identité de l'appelant et les sources de données. AWS AppSync Pour de plus amples informations, veuillez consulter [Configuration de l'autorisation et de l'authentification pour sécuriser votre GraphQL APIs](security-authz.md).
Les abonnements sont déclenchés à partir des mutations et le jeu de sélection de mutations est envoyé aux abonnés.
L'exemple suivant montre comment utiliser les abonnements GraphQL. Il ne spécifie pas de source de données, car celle-ci peut être Lambda, Amazon DynamoDB ou Amazon Service. OpenSearch
Pour commencer à utiliser les abonnements, vous devez ajouter un point d'entrée d'abonnement à votre schéma comme suit :
```
schema {
query: Query
mutation: Mutation
subscription: Subscription
}
```
Supposons que vous disposez d'un site de blog et que vous souhaitez vous abonner à de nouveaux blogs et à des modifications de blogs existants. Pour ce faire, vous devez ajouter la définition `Subscription` suivante à votre schéma :
```
type Subscription {
addedPost: Post
updatedPost: Post
deletedPost: Post
}
```
Supposons encore que vous disposez des mutations suivantes :
```
type Mutation {
addPost(id: ID! author: String! title: String content: String url: String): Post!
updatePost(id: ID! author: String! title: String content: String url: String ups: Int! downs: Int! expectedVersion: Int!): Post!
deletePost(id: ID!): Post!
}
```
Vous pouvez transformer ces champs en temps réel en ajoutant une directive `@aws_subscribe(mutations: ["mutation_field_1", "mutation_field_2"])` pour chacun des abonnements pour lesquels vous souhaitez recevoir des notifications, comme suit :
```
type Subscription {
addedPost: Post
@aws_subscribe(mutations: ["addPost"])
updatedPost: Post
@aws_subscribe(mutations: ["updatePost"])
deletedPost: Post
@aws_subscribe(mutations: ["deletePost"])
}
```
Comme il `@aws_subscribe(mutations: ["",..,""])` prend un ensemble d'entrées de mutation, vous pouvez spécifier plusieurs mutations, ce qui déclenche un abonnement. Si vous vous abonnez à partir d'un client, votre requête GraphQL peut ressembler à ce qui suit :
```
subscription NewPostSub {
addedPost {
__typename
version
title
content
author
url
}
}
```
Cette requête d'abonnement est nécessaire pour les connexions client et l'outillage.
Avec le WebSockets client pur, le filtrage des ensembles de sélection est effectué par client, car chaque client peut définir son propre ensemble de sélection. Dans ce cas, le jeu de sélection d'abonnement doit être un sous-ensemble du jeu de sélection de mutation. Par exemple, un abonnement `addedPost{author title}` lié à la mutation ne `addPost(...){id author title url version}` reçoit que l'auteur et le titre de l'article. Il ne reçoit pas les autres champs. Cependant, si la mutation n'avait pas l'auteur dans son ensemble de sélection, l'abonné obtiendrait une valeur `null` pour le champ auteur (ou une erreur dans le cas où le champ auteur est défini comme « required/not-null » dans le schéma).
L'ensemble de sélection des abonnements est essentiel lors de l'utilisation de Pure WebSockets. Si un champ n'est pas explicitement défini dans l'abonnement, il AWS AppSync ne renvoie pas le champ.
Dans l'exemple précédent, les abonnements n'avaient pas d'arguments. Supposons que votre schéma ressemble à ce qui suit :
```
type Subscription {
updatedPost(id:ID! author:String): Post
@aws_subscribe(mutations: ["updatePost"])
}
```
Dans ce cas, votre client définit un abonnement ainsi :
```
subscription UpdatedPostSub {
updatedPost(id:"XYZ", author:"ABC") {
title
content
}
}
```
Le type de retour d'un champ `subscription` dans votre schéma doit correspondre au type de retour du champ de mutation correspondant. L'exemple précédent illustrait cela avec `addPost` et `addedPost` qui ont été renvoyés en tant que type de `Post`.
Pour configurer les abonnements sur le client, voir[Création d'une application cliente à l'aide du client Amplify](building-a-client-app.md).
## Utilisation d'arguments d'abonnement
Pour utiliser les abonnements GraphQL, il est important de comprendre quand et comment utiliser les arguments. Vous pouvez apporter des modifications subtiles pour modifier comment et quand informer les clients des mutations survenues. Pour ce faire, consultez l'exemple de schéma du chapitre de démarrage rapide, qui crée « Todos ». Pour cet exemple de schéma, les mutations suivantes sont définies :
```
type Mutation {
createTodo(input: CreateTodoInput!): Todo
updateTodo(input: UpdateTodoInput!): Todo
deleteTodo(input: DeleteTodoInput!): Todo
}
```
Dans l'exemple par défaut, les clients peuvent s'abonner aux mises à jour de n'importe quel produit en `Todo` utilisant le `onUpdateTodo` `subscription` paramètre sans argument :
```
subscription OnUpdateTodo {
onUpdateTodo {
description
id
name
when
}
}
```
Vous pouvez filtrer votre `subscription` en utilisant ses arguments. Par exemple, pour déclencher un uniquement `subscription` lorsqu'un fichier `todo` contenant un élément spécifique `ID` est mis à jour, spécifiez la `ID` valeur :
```
subscription OnUpdateTodo {
onUpdateTodo(id: "a-todo-id") {
description
id
name
when
}
}
```
Vous pouvez également transmettre plusieurs arguments. Par exemple, ce qui suit `subscription` montre comment être informé de toute `Todo` mise à jour à un endroit et à une heure spécifiques :
```
subscription todosAtHome {
onUpdateTodo(when: "tomorrow", where: "at home") {
description
id
name
when
where
}
}
```
Notez que tous les arguments sont facultatifs. Si vous ne spécifiez aucun argument dans votre application`subscription`, vous serez abonné à toutes les `Todo` mises à jour effectuées dans votre application. Cependant, vous pouvez mettre à jour votre définition `subscription` de champ pour exiger l'`ID`argument. Cela forcerait la réponse d'un `todo` s spécifique `todo` au lieu de tous :
```
onUpdateTodo(
id: ID!,
name: String,
when: String,
where: String,
description: String
): Todo
```
### La valeur null de l'argument a une signification
Lorsque vous effectuez une requête d'abonnement dans AWS AppSync, la valeur d'un `null` argument filtrera les résultats différemment de l'omission complète de l'argument.
Revenons à l'exemple d'API todos où nous pourrions créer des todos. Consultez l'exemple de schéma du chapitre de démarrage rapide.
Modifions notre schéma pour inclure un nouveau `owner` champ, sur le `Todo` type, qui décrit le propriétaire. Le `owner` champ n'est pas obligatoire et peut uniquement être activé`UpdateTodoInput`. Consultez la version simplifiée suivante du schéma :
```
type Todo {
id: ID!
name: String!
when: String!
where: String!
description: String!
owner: String
}
input CreateTodoInput {
name: String!
when: String!
where: String!
description: String!
}
input UpdateTodoInput {
id: ID!
name: String
when: String
where: String
description: String
owner: String
}
type Subscription {
onUpdateTodo(
id: ID,
name: String,
when: String,
where: String,
description: String
): Todo @aws_subscribe(mutations: ["updateTodo"])
}
```
L'abonnement suivant renvoie toutes les `Todo` mises à jour :
```
subscription MySubscription {
onUpdateTodo {
description
id
name
when
where
}
}
```
Si vous modifiez l'abonnement précédent pour ajouter l'argument de champ`owner: null`, vous posez maintenant une autre question. Cet abonnement enregistre désormais le client pour qu'il soit informé de toutes les `Todo` mises à jour pour lesquelles aucun propriétaire n'a été fourni.
```
subscription MySubscription {
onUpdateTodo(owner: null) {
description
id
name
when
where
}
}
```
**Note**
**Depuis le 1er janvier 2022, MQTT over n' WebSockets est plus disponible en tant que protocole pour les abonnements GraphQL dans. AWS AppSync APIs Pure WebSockets est le seul protocole pris en charge dans AWS AppSync.**
Les clients basés sur le AWS AppSync SDK ou les bibliothèques Amplify, publiés après novembre 2019, utilisent automatiquement WebSockets pure par défaut. La mise à niveau des clients vers la dernière version leur permet AWS AppSync d'utiliser le WebSockets moteur pur.
Pure WebSockets propose une charge utile plus importante (240 Ko), une plus grande variété d'options client et des CloudWatch indicateurs améliorés. Pour plus d'informations sur l'utilisation de WebSocket clients purs, consultez[Création d'un WebSocket client en temps réel dans AWS AppSync](real-time-websocket-client.md).
# Création d'un générique pub/sub APIs alimenté par serverless WebSockets dans AWS AppSync
**Important**
À WebSockets partir du 13 mars 2025, vous pouvez créer une PubSub API en temps réel alimentée par AWS AppSync Events. Pour plus d'informations, consultez la section [Publier des événements via WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) le *Guide du développeur d'AWS AppSync événements*.
Certaines applications ne nécessitent que des applications simples WebSocket APIs lorsque les clients écoutent une chaîne ou un sujet spécifique. Les données JSON génériques ne présentant aucune forme spécifique ni aucune exigence typographique stricte peuvent être transmises aux clients écoutant l'un de ces canaux selon un schéma purement et simple de publication/abonnement (pub/sub).
AWS AppSync À utiliser pour implémenter pub/sub WebSocket APIs des applications simples avec peu ou pas de connaissances GraphQL en quelques minutes en générant automatiquement du code GraphQL à la fois sur le backend de l'API et côté client.
## Création et configuration de pub-sub APIs
Pour commencer, procédez comme suit :
1. Connectez-vous à la [AppSync console AWS Management Console et ouvrez-la](https://console.aws.amazon.com/appsync/).
1. Dans le **Tableau de bord**, choisissez **Créer une API**.
1. Sur l'écran suivant, choisissez **Créer une API en temps réel**, puis cliquez sur **Suivant**.
1. Entrez un nom convivial pour votre pub/sub API.
1. Vous pouvez activer les fonctionnalités d'[API privées](https://docs.aws.amazon.com/appsync/latest/devguide/using-private-apis.html), mais nous vous recommandons de les désactiver pour le moment. Choisissez **Suivant**.
1. Vous pouvez choisir de générer automatiquement une pub/sub API fonctionnelle à l'aide de WebSockets. Nous vous recommandons également de désactiver cette fonctionnalité pour le moment. Choisissez **Suivant**.
1. Choisissez **Create API**, puis attendez quelques minutes. Une nouvelle API AWS AppSync pub/sub préconfigurée sera créée dans votre compte. AWS
L'API utilise des AWS AppSync résolveurs locaux intégrés (pour plus d'informations sur l'utilisation des résolveurs locaux, voir [Tutoriel : résolveurs locaux](https://docs.aws.amazon.com/appsync/latest/devguide/tutorial-local-resolvers-js.html) dans le *guide du AWS AppSync développeur*) pour gérer plusieurs pub/sub canaux et WebSocket connexions temporaires, qui fournissent et filtrent automatiquement les données aux clients abonnés en fonction uniquement du nom du canal. Les appels d'API sont autorisés à l'aide d'une clé d'API.
Une fois l'API déployée, quelques étapes supplémentaires vous sont proposées pour générer du code client et l'intégrer à votre application client. À titre d'exemple sur la façon d'intégrer rapidement un client, ce guide utilisera une simple application Web React.
1. Commencez par créer une application React standard à l'aide de [NPM](https://www.npmjs.com/get-npm) sur votre machine locale :
```
$ npx create-react-app mypubsub-app
$ cd mypubsub-app
```
**Note**
Cet exemple utilise les [bibliothèques Amplify](https://docs.amplify.aws/lib/) pour connecter les clients à l'API principale. Cependant, il n'est pas nécessaire de créer un projet Amplify CLI localement. Bien que React soit le client de choix dans cet exemple, les bibliothèques Amplify prennent également en charge les clients iOS, Android et Flutter, offrant les mêmes fonctionnalités dans ces différents environnements d'exécution. [Les clients Amplify pris en charge fournissent des abstractions simples pour interagir avec les backends d'API AWS AppSync GraphQL avec quelques lignes de code, y compris des WebSocket fonctionnalités intégrées entièrement compatibles avec le protocole en temps réel :AWS AppSync WebSocket ](https://docs.aws.amazon.com/appsync/latest/devguide/real-time-websocket-client.html)
```
$ npm install @aws-amplify/api
```
1. Dans la AWS AppSync console **JavaScript**, sélectionnez puis **Télécharger pour télécharger** un seul fichier contenant les détails de configuration de l'API et le code d'opérations GraphQL généré.
1. Copiez le fichier téléchargé dans le `/src` dossier de votre projet React.
1. Remplacez ensuite le contenu du `src/App.js` fichier standard existant par l'exemple de code client disponible dans la console.
1. Utilisez la commande suivante pour démarrer l'application localement :
```
$ npm start
```
1. Pour tester l'envoi et la réception de données en temps réel, ouvrez deux fenêtres de navigateur et accédez-y*localhost:3000*. L'exemple d'application est configuré pour envoyer des données JSON génériques à un canal codé en dur nommé*robots*.
1. Dans l'une des fenêtres du navigateur, entrez le blob JSON suivant dans la zone de texte, puis cliquez sur **Soumettre** :
```
{
"robot":"r2d2",
"planet": "tatooine"
}
```
Les deux instances de navigateur sont abonnées au *robots* canal et reçoivent les données publiées en temps réel, affichées en bas de l'application Web :
![\[Exemple d'application React pour pub/sub API\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/pub-sub-react.png)
Tout le code d'API GraphQL nécessaire, y compris le schéma, les résolveurs et les opérations, est généré automatiquement pour permettre un cas d'utilisation générique pub/sub . Sur le backend, les données sont publiées sur le point AWS AppSync de terminaison en temps réel avec une mutation GraphQL telle que la suivante :
```
mutation PublishData {
publish(data: "{\"msg\": \"hello world!\"}", name: "channel") {
data
name
}
}
```
Les abonnés accèdent aux données publiées envoyées au canal temporaire spécifique avec un abonnement GraphQL associé :
```
subscription SubscribeToData {
subscribe(name:"channel") {
name
data
}
}
```
## Implémentation de pub-sub APIs dans les applications existantes
Si vous devez simplement implémenter une fonctionnalité en temps réel dans une application existante, cette configuration d' pub/sub API générique peut être facilement intégrée à n'importe quelle application ou technologie d'API. Bien qu'il y ait des avantages à utiliser un point de terminaison d'API unique pour accéder, manipuler et combiner en toute sécurité des données provenant d'une ou de plusieurs sources de données en un seul appel réseau avec GraphQL, il n'est pas nécessaire de convertir ou de reconstruire une application REST existante à partir de zéro afin de tirer parti des fonctionnalités en temps réel AWS AppSync de celle-ci. Par exemple, vous pouvez avoir une charge de travail CRUD existante dans un point de terminaison d'API distinct, les clients envoyant et recevant des messages ou des événements de l'application existante à l' pub/sub API générique en temps réel et à pub/sub des fins uniquement.
# Définition de filtres d'abonnement améliorés dans AWS AppSync
**Important**
À WebSockets partir du 13 mars 2025, vous pouvez créer une PubSub API en temps réel alimentée par AWS AppSync Events. Pour plus d'informations, consultez la section [Publier des événements via WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) le *Guide du développeur d'AWS AppSync événements*.
Dans AWS AppSync, vous pouvez définir et activer la logique métier pour le filtrage des données sur le backend directement dans les résolveurs d'abonnement à l'API GraphQL en utilisant des filtres prenant en charge des opérateurs logiques supplémentaires. Vous pouvez configurer ces filtres, contrairement aux arguments d'abonnement définis dans la requête d'abonnement du client. Pour plus d'informations sur l'utilisation des arguments d'abonnement, consultez[Utilisation d'arguments d'abonnement](aws-appsync-real-time-data.md#using-subscription-arguments). Pour obtenir la liste des opérateurs, voir[AWS AppSync référence de l'utilitaire du modèle de mappage du résolveur](resolver-util-reference.md).
Aux fins du présent document, nous répartissons le filtrage des données en temps réel dans les catégories suivantes :
+ **Filtrage de base** : filtrage basé sur les arguments définis par le client dans la requête d'abonnement.
+ **Filtrage amélioré** : filtrage basé sur une logique définie de manière centralisée dans le backend du AWS AppSync service.
Les sections suivantes expliquent comment configurer des filtres d'abonnement améliorés et présentent leur utilisation pratique.
## Définition des abonnements dans votre schéma GraphQL
Pour utiliser des filtres d'abonnement améliorés, vous définissez l'abonnement dans le schéma GraphQL, puis vous définissez le filtre amélioré à l'aide d'une extension de filtrage. Pour illustrer le fonctionnement du filtrage amélioré des abonnements AWS AppSync, utilisez le schéma GraphQL suivant, qui définit une API de système de gestion des tickets, à titre d'exemple :
```
type Ticket {
id: ID
createdAt: AWSDateTime
content: String
severity: Int
priority: Priority
category: String
group: String
status: String
}
type Mutation {
createTicket(input: TicketInput): Ticket
}
type Query {
getTicket(id: ID!): Ticket
}
type Subscription {
onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"])
onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"])
}
enum Priority {
none
lowest
low
medium
high
highest
}
input TicketInput {
content: String
severity: Int
priority: Priority
category: String
group: String
```
Supposons que vous créiez une source de `NONE` données pour votre API, puis que vous associiez un résolveur à la `createTicket` mutation à l'aide de cette source de données. Vos gestionnaires peuvent ressembler à ceci :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
payload: {
id: util.autoId(),
createdAt: util.time.nowISO8601(),
status: 'pending',
...ctx.args.input,
},
};
}
export function response(ctx) {
return ctx.result;
}
```
**Note**
Les filtres améliorés sont activés dans le gestionnaire du résolveur GraphQL dans le cadre d'un abonnement donné. Pour plus d'informations, consultez la section [Référence du résolveur](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html).
Pour implémenter le comportement du filtre amélioré, vous devez utiliser la `extensions.setSubscriptionFilter()` fonction pour définir une expression de filtre évaluée par rapport aux données publiées à partir d'une mutation GraphQL susceptible d'intéresser les clients abonnés. Pour plus d'informations sur les extensions de filtrage, consultez la section [Extensions](https://docs.aws.amazon.com//appsync/latest/devguide/extensions-js.html).
La section suivante explique comment utiliser les extensions de filtrage pour implémenter des filtres améliorés.
## Création de filtres d'abonnement améliorés à l'aide d'extensions de filtrage
Les filtres améliorés sont écrits en JSON dans le gestionnaire de réponses des résolveurs de l'abonnement. Les filtres peuvent être regroupés dans une liste appelée `filterGroup` a. Les filtres sont définis à l'aide d'au moins une règle, chacune comportant des champs, des opérateurs et des valeurs. Définissons un nouveau résolveur pour `onSpecialTicketCreated` configurer un filtre amélioré. Vous pouvez configurer plusieurs règles dans un filtre qui sont évaluées à l'aide de la logique ET, tandis que plusieurs filtres d'un groupe de filtres sont évalués à l'aide de la logique OR :
```
import { util, extensions } from '@aws-appsync/utils';
export function request(ctx) {
// simplfy return null for the payload
return { payload: null };
}
export function response(ctx) {
const filter = {
or: [
{ severity: { ge: 7 }, priority: { in: ['high', 'medium'] } },
{ category: { eq: 'security' }, group: { in: ['admin', 'operators'] } },
],
};
extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
// important: return null in the response
return null;
}
```
Sur la base des filtres définis dans l'exemple précédent, les tickets importants sont automatiquement envoyés aux clients API abonnés si un ticket est créé avec :
+ `priority`niveau `high` ou `medium`
AND
+ `severity`niveau supérieur ou égal à `7` (`ge`)
OU
+ `classification`billet réglé à `Security`
AND
+ `group`assignation définie sur `admin` ou `operators`
![\[Exemple illustrant une requête de filtrage de tickets\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/aws-priority-example.png)
Les filtres définis dans le résolveur d'abonnement (filtrage amélioré) ont priorité sur le filtrage basé uniquement sur les arguments d'abonnement (filtrage de base). Pour plus d'informations sur l'utilisation des arguments d'abonnement, consultez la section [Utilisation des arguments d'abonnement](https://docs.aws.amazon.com//appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments)).
Si un argument est défini et requis dans le schéma GraphQL de l'abonnement, le filtrage basé sur l'argument donné n'a lieu que si l'argument est défini en tant que règle dans la méthode du résolveur. `extensions.setSubscriptionFilter()` Toutefois, s'il n'existe aucune méthode de `extensions` filtrage dans le résolveur d'abonnement, les arguments définis dans le client ne sont utilisés que pour le filtrage de base. Vous ne pouvez pas utiliser simultanément le filtrage de base et le filtrage amélioré.
Vous pouvez utiliser la [`context`variable](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) dans la logique d'extension de filtre de l'abonnement pour accéder aux informations contextuelles relatives à la demande. Par exemple, lorsque vous utilisez des groupes d'utilisateurs Amazon Cognito, des autorisateurs personnalisés OIDC ou Lambda pour l'autorisation, vous pouvez récupérer des informations sur vos utilisateurs au `context.identity` moment de l'établissement de l'abonnement. Vous pouvez utiliser ces informations pour établir des filtres en fonction de l'identité de vos utilisateurs.
Supposons maintenant que vous souhaitez implémenter le comportement de filtre amélioré pour`onGroupTicketCreated`. L'`onGroupTicketCreated`abonnement nécessite un `group` nom obligatoire comme argument. Une fois créés, un `pending` statut est automatiquement attribué aux tickets. Vous pouvez configurer un filtre d'abonnement pour ne recevoir que les tickets nouvellement créés appartenant au groupe fourni :
```
import { util, extensions } from '@aws-appsync/utils';
export function request(ctx) {
// simplfy return null for the payload
return { payload: null };
}
export function response(ctx) {
const filter = { group: { eq: ctx.args.group }, status: { eq: 'pending' } };
extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
return null;
}
```
Lorsque les données sont publiées à l'aide d'une mutation, comme dans l'exemple suivant :
```
mutation CreateTicket {
createTicket(input: {priority: medium, severity: 2, group: "aws"}) {
id
priority
severity
status
group
createdAt
}
}
```
Les clients abonnés écoutent les données à transmettre automatiquement WebSockets dès qu'un ticket est créé avec la `createTicket` mutation :
```
subscription OnGroup {
onGroupTicketCreated(group: "aws") {
category
status
severity
priority
id
group
createdAt
content
}
}
```
Les clients peuvent être abonnés sans arguments car la logique de filtrage est implémentée dans le AWS AppSync service avec un filtrage amélioré, ce qui simplifie le code client. Les clients reçoivent des données uniquement si les critères de filtre définis sont remplis.
## Définition de filtres améliorés pour les champs de schéma imbriqués
Vous pouvez utiliser le filtrage des abonnements amélioré pour filtrer les champs de schéma imbriqués. Supposons que nous ayons modifié le schéma de la section précédente pour inclure les types de localisation et d'adresse :
```
type Ticket {
id: ID
createdAt: AWSDateTime
content: String
severity: Int
priority: Priority
category: String
group: String
status: String
location: ProblemLocation
}
type Mutation {
createTicket(input: TicketInput): Ticket
}
type Query {
getTicket(id: ID!): Ticket
}
type Subscription {
onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"])
onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"])
}
type ProblemLocation {
address: Address
}
type Address {
country: String
}
enum Priority {
none
lowest
low
medium
high
highest
}
input TicketInput {
content: String
severity: Int
priority: Priority
category: String
group: String
location: AWSJSON
```
Avec ce schéma, vous pouvez utiliser un `.` séparateur pour représenter l'imbrication. L'exemple suivant ajoute une règle de filtre pour un champ de schéma imbriqué sous`location.address.country`. L'abonnement sera déclenché si l'adresse du ticket est définie comme suit `USA` :
```
import { util, extensions } from '@aws-appsync/utils';
export const request = (ctx) => ({ payload: null });
export function response(ctx) {
const filter = {
or: [
{ severity: { ge: 7 }, priority: { in: ['high', 'medium'] } },
{ category: { eq: 'security' }, group: { in: ['admin', 'operators'] } },
{ 'location.address.country': { eq: 'USA' } },
],
};
extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
return null;
}
```
Dans l'exemple ci-dessus, `location` représente le niveau d'imbrication un, `address` représente le niveau d'imbrication deux et `country` représente le niveau d'imbrication trois, tous ces éléments étant séparés par le séparateur. `.`
Vous pouvez tester cet abonnement en utilisant la `createTicket` mutation :
```
mutation CreateTicketInUSA {
createTicket(input: {location: "{\"address\":{\"country\":\"USA\"}}"}) {
category
content
createdAt
group
id
location {
address {
country
}
}
priority
severity
status
}
}
```
## Définition de filtres améliorés à partir du client
Vous pouvez utiliser le filtrage de base dans GraphQL avec des arguments d'[abonnement](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments). Le client qui effectue l'appel dans la requête d'abonnement définit les valeurs des arguments. Lorsque des filtres améliorés sont activés dans un résolveur AWS AppSync d'abonnement avec le `extensions` filtrage, les filtres principaux définis dans le résolveur ont la priorité et la priorité.
Configurez des filtres améliorés dynamiques définis par le client à l'aide d'un `filter` argument dans l'abonnement. Lorsque vous configurez ces filtres, vous devez mettre à jour le schéma GraphQL pour refléter le nouvel argument :
```
...
type Subscription {
onSpecialTicketCreated(filter: String): Ticket
@aws_subscribe(mutations: ["createTicket"])
}
...
```
Le client peut ensuite envoyer une demande d'abonnement comme dans l'exemple suivant :
```
subscription onSpecialTicketCreated($filter: String) {
onSpecialTicketCreated(filter: $filter) {
id
group
description
priority
severity
}
}
```
Vous pouvez configurer la variable de requête comme dans l'exemple suivant :
```
{"filter" : "{\"severity\":{\"le\":2}}"}
```
L'utilitaire de `util.transform.toSubscriptionFilter()` résolution peut être implémenté dans le modèle de mappage des réponses aux abonnements pour appliquer le filtre défini dans l'argument d'abonnement pour chaque client :
```
import { util, extensions } from '@aws-appsync/utils';
export function request(ctx) {
// simplfy return null for the payload
return { payload: null };
}
export function response(ctx) {
const filter = ctx.args.filter;
extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
return null;
}
```
Grâce à cette stratégie, les clients peuvent définir leurs propres filtres qui utilisent une logique de filtrage améliorée et des opérateurs supplémentaires. Les filtres sont attribués lorsqu'un client donné invoque la requête d'abonnement via une WebSocket connexion sécurisée. Pour plus d'informations sur l'utilitaire de transformation pour un filtrage amélioré, notamment sur le format de la charge utile de la variable de `filter` requête, consultez la section Présentation des [JavaScriptrésolveurs](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html).
## Restrictions de filtrage améliorées supplémentaires
Vous trouverez ci-dessous plusieurs cas d'utilisation dans lesquels des restrictions supplémentaires sont imposées aux filtres améliorés :
+ Les filtres améliorés ne prennent pas en charge le filtrage pour les listes d'objets de niveau supérieur. Dans ce cas d'utilisation, les données publiées issues de la mutation seront ignorées pour les abonnements améliorés.
+ AWS AppSync prend en charge jusqu'à cinq niveaux de nidification. Les filtres appliqués aux champs de schéma après le niveau d'imbrication 5 seront ignorés. Prenons la réponse GraphQL ci-dessous. L'entrée `continent` sur le terrain `venue.address.country.metadata.continent` est autorisée car il s'agit d'un nid de niveau 5. Cependant, `financial` comme `venue.address.country.metadata.capital.financial` il s'agit d'un nid de niveau 6, le filtre ne fonctionnera pas :
```
{
"data": {
"onCreateFilterEvent": {
"venue": {
"address": {
"country": {
"metadata": {
"capital": {
"financial": "New York"
},
"continent" : "North America"
}
},
"state": "WA"
},
"builtYear": 2023
},
"private": false,
}
}
}
```
# Désinscription de WebSocket connexions à l'aide de filtres dans AWS AppSync
**Important**
À WebSockets partir du 13 mars 2025, vous pouvez créer une PubSub API en temps réel alimentée par AWS AppSync Events. Pour plus d'informations, consultez la section [Publier des événements via WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) le *Guide du développeur d'AWS AppSync événements*.
Dans AWS AppSync, vous pouvez vous désinscrire de force et fermer (invalider) une WebSocket connexion depuis un client connecté en fonction d'une logique de filtrage spécifique. Cela est utile dans les scénarios liés aux autorisations, par exemple lorsque vous supprimez un utilisateur d'un groupe.
L'invalidation de l'abonnement se produit en réponse à une charge utile définie dans une mutation. Nous vous recommandons de traiter les mutations utilisées pour invalider les connexions d'abonnement comme des opérations administratives dans votre API et de définir les autorisations en conséquence en limitant leur utilisation à un utilisateur administrateur, à un groupe ou à un service principal. Par exemple, en utilisant des directives d'autorisation de schéma telles que `@aws_auth(cognito_groups: ["Administrators"])` ou`@aws_iam`. Pour plus d'informations, consultez la section [Utilisation de modes d'autorisation supplémentaires](https://docs.aws.amazon.com/appsync/latest/devguide/security-authz.html#using-additional-authorization-modes).
Les filtres d'invalidation utilisent la même syntaxe et la même logique que les [filtres d'abonnement améliorés](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-enhanced-filtering.html). Définissez ces filtres à l'aide des utilitaires suivants :
+ `extensions.invalidateSubscriptions()`— Défini dans le gestionnaire de réponse du résolveur GraphQL pour une mutation.
+ `extensions.setSubscriptionInvalidationFilter()`— Défini dans le gestionnaire de réponses du résolveur GraphQL pour les abonnements liés à la mutation.
Pour plus d'informations sur les extensions de filtrage d'invalidation, consultez la section Présentation [JavaScriptdes résolveurs.](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)
## Utilisation de l'invalidation de l'abonnement
Pour voir comment fonctionne l'invalidation des abonnements AWS AppSync, utilisez le schéma GraphQL suivant :
```
type User {
userId: ID!
groupId: ID!
}
type Group {
groupId: ID!
name: String!
members: [ID!]!
}
type GroupMessage {
userId: ID!
groupId: ID!
message: String!
}
type Mutation {
createGroupMessage(userId: ID!, groupId : ID!, message: String!): GroupMessage
removeUserFromGroup(userId: ID!, groupId : ID!) : User @aws_iam
}
type Subscription {
onGroupMessageCreated(userId: ID!, groupId : ID!): GroupMessage
@aws_subscribe(mutations: ["createGroupMessage"])
}
type Query {
none: String
}
```
Définissez un filtre d'invalidation dans le code du résolveur de `removeUserFromGroup` mutations :
```
import { extensions } from '@aws-appsync/utils';
export function request(ctx) {
return { payload: null };
}
export function response(ctx) {
const { userId, groupId } = ctx.args;
extensions.invalidateSubscriptions({
subscriptionField: 'onGroupMessageCreated',
payload: { userId, groupId },
});
return { userId, groupId };
}
```
Lorsque la mutation est invoquée, les données définies dans l'`payload`objet sont utilisées pour annuler l'abonnement défini dans`subscriptionField`. Un filtre d'invalidation est également défini dans le modèle de mappage des réponses de l'`onGroupMessageCreated`abonnement.
Si la `extensions.invalidateSubscriptions()` charge utile contient un identifiant correspondant à celui IDs du client abonné tel que défini dans le filtre, l'abonnement correspondant est désabonné. De plus, la WebSocket connexion est fermée. Définissez le code de résolution d'abonnement pour l'`onGroupMessageCreated`abonnement :
```
import { util, extensions } from '@aws-appsync/utils';
export function request(ctx) {
// simplfy return null for the payload
return { payload: null };
}
export function response(ctx) {
const filter = { groupId: { eq: ctx.args.groupId } };
extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
const invalidation = { groupId: { eq: ctx.args.groupId }, userId: { eq: ctx.args.userId } };
extensions.setSubscriptionInvalidationFilter(util.transform.toSubscriptionFilter(invalidation));
return null;
}
```
Notez que le gestionnaire de réponse aux abonnements peut avoir des filtres d'abonnement et des filtres d'invalidation définis en même temps.
Supposons, par exemple, que le client A abonne un nouvel utilisateur avec l'ID `user-1` au groupe ayant l'ID `group-1` en utilisant la demande d'abonnement suivante :
```
onGroupMessageCreated(userId : "user-1", groupId: :"group-1"){...}
```
AWS AppSync exécute le résolveur d'abonnement, qui génère des filtres d'abonnement et d'invalidation tels que définis dans le modèle de mappage de `onGroupMessageCreated` réponses précédent. Pour le client A, les filtres d'abonnement autorisent l'envoi de données uniquement à`group-1`, et les filtres d'invalidation sont définis pour `user-1` les `group-1` deux.
Supposons maintenant que le client B abonne un utilisateur avec l'ID `user-2` à un groupe avec l'ID `group-2` en utilisant la demande d'abonnement suivante :
```
onGroupMessageCreated(userId : "user-2", groupId: :"group-2"){...}
```
AWS AppSync exécute le résolveur d'abonnement, qui génère des filtres d'abonnement et d'invalidation. Pour le client B, les filtres d'abonnement autorisent l'envoi de données uniquement à`group-2`, et les filtres d'invalidation sont définis pour les deux `user-2` et`group-2`.
Supposons ensuite qu'un nouveau message de groupe avec l'ID `message-1` soit créé à l'aide d'une demande de mutation, comme dans l'exemple suivant :
```
createGroupMessage(id: "message-1", groupId :
"group-1", message: "test message"){...}
```
Les clients abonnés correspondant aux filtres définis reçoivent automatiquement la charge utile de données suivante via WebSockets :
```
{
"data": {
"onGroupMessageCreated": {
"id": "message-1",
"groupId": "group-1",
"message": "test message",
}
}
}
```
Le client A reçoit le message car les critères de filtrage correspondent au filtre d'abonnement défini. Cependant, le client B ne reçoit pas le message, car l'utilisateur n'en fait pas partie`group-1`. De plus, la demande ne correspond pas au filtre d'abonnement défini dans le résolveur d'abonnement.
Enfin, supposons que cela `user-1` soit supprimé `group-1` lors de l'utilisation de la demande de mutation suivante :
```
removeUserFromGroup(userId: "user-1", groupId : "group-1"){...}
```
La mutation initie une invalidation d'abonnement telle que définie dans le code du gestionnaire de réponse du `extensions.invalidateSubscriptions()` résolveur. AWS AppSync désabonne ensuite le client A et ferme sa WebSocket connexion. Le client B n'est pas affecté, car la charge utile d'invalidation définie dans la mutation ne correspond pas à son utilisateur ou à son groupe.
Lorsqu'une connexion est AWS AppSync invalidée, le client reçoit un message confirmant qu'il est désabonné :
```
{
"message": "Subscription complete."
}
```
## Utilisation de variables contextuelles dans les filtres d'invalidation des abonnements
Comme pour les filtres d'abonnement améliorés, vous pouvez utiliser la [`context`variable](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) de l'extension du filtre d'invalidation d'abonnement pour accéder à certaines données.
Par exemple, il est possible de configurer une adresse e-mail comme charge utile d'invalidation lors de la mutation, puis de l'associer à l'attribut e-mail ou à la réclamation d'un utilisateur abonné autorisé par les groupes d'utilisateurs Amazon Cognito ou OpenID Connect. Le filtre d'invalidation défini dans l'invalidateur `extensions.setSubscriptionInvalidationFilter()` d'abonnement vérifie si l'adresse e-mail définie par la `extensions.invalidateSubscriptions()` charge utile de la mutation correspond à l'adresse e-mail récupérée à partir du jeton JWT de l'utilisateur, déclenchant ainsi l'invalidation. `context.identity.claims.email`
# Création d'un WebSocket client en temps réel dans AWS AppSync
**Important**
À WebSockets partir du 13 mars 2025, vous pouvez créer une PubSub API en temps réel alimentée par AWS AppSync Events. Pour plus d'informations, consultez la section [Publier des événements via WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) le *Guide du développeur d'AWS AppSync événements*.
AWS AppSyncLe WebSocket client en temps réel permet les abonnements GraphQL via un processus en plusieurs étapes. Le client établit d'abord une WebSocket connexion avec le point de terminaison AWS AppSync en temps réel, envoie un message d'initialisation de la connexion et attend un accusé de réception. Une fois la connexion établie, le client enregistre les abonnements en envoyant des messages de démarrage contenant des requêtes GraphQL uniques IDs . AWS AppSync confirme les abonnements réussis par des messages d'accusé de réception. Le client écoute ensuite les événements d'abonnement, qui sont déclenchés par les mutations correspondantes. Pour maintenir la connexion, AWS AppSync envoie régulièrement des messages de maintien en vie. Lorsque vous avez terminé, le client annule l'enregistrement des abonnements en envoyant des messages d'arrêt. Ce système prend en charge plusieurs abonnements sur une seule WebSocket connexion et prend en charge différents modes d'autorisation, notamment les clés API, les groupes d'utilisateurs Amazon Cognito, IAM et Lambda.
## WebSocket Implémentation du client en temps réel pour les abonnements GraphQL
Le schéma de séquence et les étapes suivants montrent le flux de travail des abonnements en temps réel entre le WebSocket client, le client HTTP et AWS AppSync.
![\[Sequence diagram showing WebSocket client, AppSync endpoints, and HTTP client interactions for real-time subscriptions.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/realtime-client-flow.png)
1. Le client établit une WebSocket connexion avec le point de terminaison AWS AppSync en temps réel. En cas d’erreur réseau, le client doit effectuer une interruption exponentielle instable. Pour plus d'informations, consultez la section [Exponential Backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) sur le AWS blog d'architecture.
1. (Facultatif) Une fois la WebSocket connexion établie, le client envoie un `connection_init` message.
1. S'`connection_init`il est envoyé, le client attend un `connection_ack` message de AWS AppSync. Ce message inclut un `connectionTimeoutMs` paramètre, qui est le temps d'attente maximal en millisecondes pour un message `"ka"` (keep-alive).
1. AWS AppSync envoie `"ka"` des messages périodiquement. Le client enregistre l'heure à laquelle il a reçu chaque `"ka"` message. Si le client ne reçoit aucun `"ka"` message dans les `connectionTimeoutMs` millisecondes, il doit fermer la connexion.
1. Le client enregistre l'abonnement en envoyant un message d'abonnement `start`. Une seule WebSocket connexion prend en charge plusieurs abonnements, même s'ils utilisent des modes d'autorisation différents.
1. Le client attend d'envoyer des `start_ack` messages AWS AppSync pour confirmer les abonnements réussis. En cas d'erreur, AWS AppSync renvoie un `"type": "error"` message.
1. Le client écoute les événements d'abonnement, qui sont envoyés après l'appel d'une mutation correspondante. Les requêtes et les mutations sont généralement envoyées au point `https://` de terminaison AWS AppSync GraphQL. Les abonnements passent par le point de terminaison AWS AppSync en temps réel à l'aide du WebSocket protocole secure (`wss://`).
1. Le client annule l'abonnement en envoyant un message d'abonnement `stop`.
1. Après avoir annulé tous les abonnements et vérifié qu'aucun message n'est transféré via le WebSocket, le client peut se déconnecter de la WebSocket connexion.
## Détails de la poignée de main pour établir la connexion WebSocket
Pour établir une connexion et initier une poignée de main réussie avec AWS AppSync, un WebSocket client a besoin des éléments suivants :
+ Le point final AWS AppSync en temps réel
+ En-têtes : contiennent des informations relatives au point de AWS AppSync terminaison et à l'autorisation. AWS AppSync prend en charge les trois méthodes suivantes pour fournir des en-têtes :
+ En-têtes via une chaîne de requête
+ Les informations d'en-tête sont codées sous forme de chaîne base64, dérivée d'un objet JSON stringifié. Cet objet JSON contient des informations relatives au AWS AppSync point de terminaison et à l'autorisation. Le contenu de l'objet JSON varie en fonction du mode d'autorisation.
+ En-têtes via `Sec-WebSocket-Protocol`
+ Une chaîne codée en Base64URL provenant de l'objet JSON sous forme de chaîne contenant des informations relatives au point de AWS AppSync terminaison et à l'autorisation est transmise en tant que protocole dans l'en-tête. `Sec-WebSocket-Protocol` Le contenu de l'objet JSON varie en fonction du mode d'autorisation.
+ En-têtes via des en-têtes HTTP standard :
+ Les en-têtes peuvent être transmis en tant qu'en-têtes HTTP standard dans la demande de connexion, de la même manière que les en-têtes sont transmis pour les requêtes GraphQL et les mutations. AWS AppSync Toutefois, le transfert d'en-têtes via des en-têtes HTTP standard n'est pas pris en charge pour les demandes de connexion API privées.
+ `payload`— Chaîne codée en Base64 de. `payload` La charge utile n'est nécessaire que si les en-têtes sont fournis à l'aide d'une chaîne de requête
Avec ces exigences, un WebSocket client peut se connecter à l'URL, qui contient le point de terminaison en temps réel avec la chaîne de requête, en utilisant `graphql-ws` comme WebSocket protocole.
### Découverte du point de terminaison en temps réel à partir du point de terminaison GraphQL
Le point de terminaison AWS AppSync GraphQL et le point de terminaison AWS AppSync en temps réel sont légèrement différents en termes de protocole et de domaine. Vous pouvez récupérer le point de terminaison GraphQL à l'aide de la commande AWS Command Line Interface (AWS CLI). `aws appsync get-graphql-api`
****AWS AppSync Point de terminaison GraphQL :****
`https://example1234567890000.appsync-api.us-east-1.amazonaws.com/graphql`
****AWS AppSync point final en temps réel :****
`wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql`
Les applications peuvent se connecter au point de terminaison AWS AppSync GraphQL (`https://`) à l'aide de n'importe quel client HTTP pour les requêtes et les mutations. Les applications peuvent se connecter au point de terminaison AWS AppSync en temps réel (`wss://`) en utilisant n'importe quel WebSocket client pour les abonnements.
Avec les noms de domaine personnalisés, vous pouvez interagir avec les deux points de terminaison en utilisant un seul domaine. Par exemple, si vous le configurez `api.example.com` en tant que domaine personnalisé, vous pouvez interagir avec votre GraphQL et vos points de terminaison en temps réel à l'aide des éléments suivants : URLs
**AWS AppSync point de terminaison GraphQL de domaine personnalisé :**
`https://api.example.com/graphql`
**AWS AppSync point de terminaison en temps réel de domaine personnalisé :**
`wss://api.example.com/graphql/realtime`
## Format des paramètres d'en-tête basé sur le mode d'autorisation de l' AWS AppSync API
Le format de l'`header`objet utilisé dans la chaîne de requête de connexion varie en fonction du mode d'autorisation de l' AWS AppSync API. Le `host` champ de l'objet fait référence au point de terminaison AWS AppSync GraphQL, qui est utilisé pour valider la connexion même si l'`wss://`appel est effectué par rapport au point de terminaison en temps réel. Pour initier la poignée de main et établir la connexion autorisée, `payload` doit être un objet JSON vide. La charge utile n'est nécessaire que si les en-têtes sont transmis via une chaîne de requête.
Les sections suivantes présentent les formats d'en-tête pour chaque mode d'autorisation.
### Clé API
#### En-tête de clé API
**Contenu de l'en-tête**
+ `"host": `: L'hôte du point de terminaison AWS AppSync GraphQL ou votre nom de domaine personnalisé.
+ `"x-api-key": `: clé d'API configurée pour l' AWS AppSync API.
**Exemple**
```
{
"host":"example1234567890000.appsync-api.us-east-1.amazonaws.com",
"x-api-key":"da2-12345678901234567890123456"
}
```
**En-têtes via une chaîne de requête**
Tout d'abord, un objet JSON contenant le `host` et `x-api-key` est converti en chaîne. Ensuite, cette chaîne est codée en utilisant le codage base64. La chaîne codée en base64 qui en résulte est ajoutée en tant que paramètre de requête nommé `header` à l' WebSocketURL pour établir la connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql?header=eyJob3N0IjoiZXhhbXBsZTEyMzQ1Njc4OTAwMDAuYXBwc3luYy1hcGkudXMtZWFzdC0xLmFtYXpvbmF3cy5jb20iLCJ4LWFtei1kYXRlIjoiMjAyMDA0MDFUMDAxMDEwWiIsIngtYXBpLWtleSI6ImRhMi16NHc0NHZoczV6Z2MzZHRqNXNranJsbGxqaSJ9&payload=e30=
```
Il est important de noter qu'en plus de l'objet d'en-tête codé en base64, un objet JSON vide \$1\$1 est également codé en base64 et inclus en tant que paramètre de requête distinct nommé `payload` dans l'URL. WebSocket
**En-têtes via `Sec-WebSocket-Protocol`**
Un objet JSON contenant le `host` et `x-api-key` est converti en chaîne puis codé à l'aide du codage Base64URL. La chaîne codée en Base64URL qui en résulte est préfixée par. `header-` Cette chaîne préfixée est ensuite utilisée comme nouveau sous-protocole en plus de figurer dans l'`Sec-WebSocket-Protocol`en-tête lors de `graphql-ws` l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel.
L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
L'`Sec-WebSocket-Protocol`en-tête contient la valeur suivante :
```
"sec-websocket-protocol" : ["graphql-ws", "header-ewogICAgImhvc3QiOiJleGFtcGxlMTIzNDU2Nzg5MDAwMC5hcHBzeW5jLWFwaS51cy1lYXN0LTEuYW1hem9uYXdzLmNvbSIsCiAgICAieC1hcGkta2V5IjoiZGEyLTEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Igp9"]
```
**En-têtes via des en-têtes HTTP standard**
Dans cette méthode, les informations relatives à l'hôte et à la clé d'API sont transmises à l'aide d'en-têtes HTTP standard lors de l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
Les en-têtes de demande incluraient les éléments suivants :
```
"sec-websocket-protocol" : ["graphql-ws"]
"host":"example1234567890000.appsync-api.us-east-1.amazonaws.com",
"x-api-key":"da2-12345678901234567890123456"
```
### Groupes d'utilisateurs Amazon Cognito et OpenID Connect (OIDC)
#### Amazon Cognito et en-tête OIDC
Contenu de l'en-tête :
+ `"Authorization": `: un jeton d'identification JWT. L'en-tête peut utiliser un [schéma Bearer](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1).
+ `"host": `: L'hôte du point de terminaison AWS AppSync GraphQL ou votre nom de domaine personnalisé.
Exemple :
```
{
"Authorization":"eyEXAMPLEiJjbG5xb3A5eW5MK09QYXIrMTJHWEFLSXBieU5WNHhsQjEXAMPLEnM2WldvPSIsImFsZyI6IlEXAMPLEn0.eyEXAMPLEiJhNmNmMjcwNy0xNjgxLTQ1NDItOWYxOC1lNjY0MTg2NjlkMzYiLCJldmVudF9pZCI6ImVkMzM5MmNkLWNjYTMtNGM2OC1hNDYyLTJlZGI3ZTNmY2FjZiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE1Njk0NTc3MTgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5hcC1zb3V0aGVhc3QtMi5hbWF6b25hd3MuY29tXC9hcC1zb3V0aGVhc3QtMl83OHY0SVZibVAiLCJleHAiOjE1Njk0NjEzMjAsImlhdCI6MTU2OTQ1NzcyMCwianRpIjoiNTgzZjhmYmMtMzk2MS00YzA4LWJhZTAtYzQyY2IxMTM5NDY5IiwiY2xpZW50X2lkIjoiM3FlajVlMXZmMzd1N3RoZWw0dG91dDJkMWwiLCJ1c2VybmFtZSI6ImVsb3EXAMPLEn0.B4EXAMPLEFNpJ6ikVp7e6DRee95V6Qi-zEE2DJH7sHOl2zxYi7f-SmEGoh2AD8emxQRYajByz-rE4Jh0QOymN2Ys-ZIkMpVBTPgu-TMWDyOHhDUmUj2OP82yeZ3wlZAtr_gM4LzjXUXmI_K2yGjuXfXTaa1mvQEBG0mQfVd7SfwXB-jcv4RYVi6j25qgow9Ew52ufurPqaK-3WAKG32KpV8J4-Wejq8t0c-yA7sb8EnB551b7TU93uKRiVVK3E55Nk5ADPoam_WYE45i3s5qVAP_-InW75NUoOCGTsS8YWMfb6ecHYJ-1j-bzA27zaT9VjctXn9byNFZmEXAMPLExw",
"host":"example1234567890000.appsync-api.us-east-1.amazonaws.com"
}
```
**En-têtes via une chaîne de requête**
Tout d'abord, un objet JSON contenant le `host` et `Authorization` est converti en chaîne. Ensuite, cette chaîne est codée en utilisant le codage base64. La chaîne codée en base64 qui en résulte est ajoutée en tant que paramètre de requête nommé `header` à l' WebSocket URL pour établir la connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql?header=eyJBdXRob3JpemF0aW9uIjoiZXlKcmFXUWlPaUpqYkc1eGIzQTVlVzVNSzA5UVlYSXJNVEpIV0VGTFNYQmllVTVXTkhoc1FqaFBWVzlZTW5NMldsZHZQU0lzSW1Gc1p5STZJbEpUTWpVMkluMC5leUp6ZFdJaU9pSmhObU5tTWpjd055MHhOamd4TFRRMU5ESXRPV1l4T0MxbE5qWTBNVGcyTmpsa016WWlMQ0psZG1WdWRGOXBaQ0k2SW1Wa016TTVNbU5rTFdOallUTXROR00yT0MxaE5EWXlMVEpsWkdJM1pUTm1ZMkZqWmlJc0luUnZhMlZ1WDNWelpTSTZJbUZqWTJWemN5SXNJbk5qYjNCbElqb2lZWGR6TG1OdloyNXBkRzh1YzJsbmJtbHVMblZ6WlhJdVlXUnRhVzRpTENKaGRYUm9YM1JwYldVaU9qRTFOamswTlRjM01UZ3NJbWx6Y3lJNkltaDBkSEJ6T2x3dlhDOWpiMmR1YVhSdkxXbGtjQzVoY0MxemIzVjBhR1ZoYzNRdE1pNWhiV0Y2YjI1aGQzTXVZMjl0WEM5aGNDMXpiM1YwYUdWaGMzUXRNbDgzT0hZMFNWWmliVkFpTENKbGVIQWlPakUxTmprME5qRXpNakFzSW1saGRDSTZNVFUyT1RRMU56Y3lNQ3dpYW5ScElqb2lOVGd6WmpobVltTXRNemsyTVMwMFl6QTRMV0poWlRBdFl6UXlZMkl4TVRNNU5EWTVJaXdpWTJ4cFpXNTBYMmxrSWpvaU0zRmxhalZsTVhabU16ZDFOM1JvWld3MGRHOTFkREprTVd3aUxDSjFjMlZ5Ym1GdFpTSTZJbVZzYjNKNllXWmxJbjAuQjRjZEp0aDNLRk5wSjZpa1ZwN2U2RFJlZTk1VjZRaS16RUUyREpIN3NIT2wyenhZaTdmLVNtRUdvaDJBRDhlbXhRUllhakJ5ei1yRTRKaDBRT3ltTjJZcy1aSWtNcFZCVFBndS1UTVdEeU9IaERVbVVqMk9QODJ5ZVozd2xaQXRyX2dNNEx6alhVWG1JX0syeUdqdVhmWFRhYTFtdlFFQkcwbVFmVmQ3U2Z3WEItamN2NFJZVmk2ajI1cWdvdzlFdzUydWZ1clBxYUstM1dBS0czMktwVjhKNC1XZWpxOHQwYy15QTdzYjhFbkI1NTFiN1RVOTN1S1JpVlZLM0U1NU5rNUFEUG9hbV9XWUU0NWkzczVxVkFQXy1Jblc3NU5Vb09DR1RzUzhZV01mYjZlY0hZSi0xai1iekEyN3phVDlWamN0WG45YnlORlptS0xwQTJMY3h3IiwiaG9zdCI6ImV4YW1wbGUxMjM0NTY3ODkwMDAwLmFwcHN5bmMtYXBpLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tIn0=&payload=e30=
```
Il est important de noter qu'en plus de l'objet d'en-tête codé en base64, un objet JSON vide \$1\$1 est également codé en base64 et inclus en tant que paramètre de requête distinct nommé `payload` dans l'URL. WebSocket
**En-têtes via `Sec-WebSocket-Protocol`**
Un objet JSON contenant le `host` et `Authorization` est converti en chaîne puis codé à l'aide du codage Base64URL. La chaîne codée en Base64URL qui en résulte est préfixée par. `header-` Cette chaîne préfixée est ensuite utilisée comme nouveau sous-protocole en plus de figurer dans l'`Sec-WebSocket-Protocol`en-tête lors de `graphql-ws` l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel.
L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
L'`Sec-WebSocket-Protocol`en-tête contient la valeur suivante :
```
"sec-websocket-protocol" : ["graphql-ws", "header-ewogICAgImhvc3QiOiJleGFtcGxlMTIzNDU2Nzg5MDAwMC5hcHBzeW5jLWFwaS51cy1lYXN0LTEuYW1hem9uYXdzLmNvbSIsCiAgICAieC1hcGkta2V5IjoiZGEyLTEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Igp9"]
```
**En-têtes via des en-têtes HTTP standard**
Dans cette méthode, les informations d'hôte et d'autorisation sont transmises à l'aide d'en-têtes HTTP standard lors de l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
Les en-têtes de demande incluraient les éléments suivants :
```
"sec-websocket-protocol" : ["graphql-ws"]
"Authorization":"eyEXAMPLEiJjbG5xb3A5eW5MK09QYXIrMTJHWEFLSXBieU5WNHhsQjEXAMPLEnM2WldvPSIsImFsZyI6IlEXAMPLEn0.eyEXAMPLEiJhNmNmMjcwNy0xNjgxLTQ1NDItOWYxOC1lNjY0MTg2NjlkMzYiLCJldmVudF9pZCI6ImVkMzM5MmNkLWNjYTMtNGM2OC1hNDYyLTJlZGI3ZTNmY2FjZiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE1Njk0NTc3MTgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5hcC1zb3V0aGVhc3QtMi5hbWF6b25hd3MuY29tXC9hcC1zb3V0aGVhc3QtMl83OHY0SVZibVAiLCJleHAiOjE1Njk0NjEzMjAsImlhdCI6MTU2OTQ1NzcyMCwianRpIjoiNTgzZjhmYmMtMzk2MS00YzA4LWJhZTAtYzQyY2IxMTM5NDY5IiwiY2xpZW50X2lkIjoiM3FlajVlMXZmMzd1N3RoZWw0dG91dDJkMWwiLCJ1c2VybmFtZSI6ImVsb3EXAMPLEn0.B4EXAMPLEFNpJ6ikVp7e6DRee95V6Qi-zEE2DJH7sHOl2zxYi7f-SmEGoh2AD8emxQRYajByz-rE4Jh0QOymN2Ys-ZIkMpVBTPgu-TMWDyOHhDUmUj2OP82yeZ3wlZAtr_gM4LzjXUXmI_K2yGjuXfXTaa1mvQEBG0mQfVd7SfwXB-jcv4RYVi6j25qgow9Ew52ufurPqaK-3WAKG32KpV8J4-Wejq8t0c-yA7sb8EnB551b7TU93uKRiVVK3E55Nk5ADPoam_WYE45i3s5qVAP_-InW75NUoOCGTsS8YWMfb6ecHYJ-1j-bzA27zaT9VjctXn9byNFZmEXAMPLExw",
"host":"example1234567890000.appsync-api.us-east-1.amazonaws.com"
```
### IAM
#### En-tête IAM
**Contenu de l'en-tête**
+ `"accept": "application/json, text/javascript"` : un paramètre `` constant.
+ `"content-encoding": "amz-1.0"` : un paramètre `` constant.
+ `"content-type": "application/json; charset=UTF-8"` : un paramètre `` constant.
+ `"host": `: Il s'agit de l'hôte du point de terminaison AWS AppSync GraphQL.
+ `"x-amz-date": `: L'horodatage doit être en UTC et au format ISO 8601 suivant : YYYYMMDD'T'HHMMSS'Z'. Par exemple, 20150830T123600Z est un horodatage valide. N'incluez pas de millisecondes dans l'horodatage. Pour plus d'informations, consultez la section [Gestion des dates dans la version 4 de Signature](https://docs.aws.amazon.com/general/latest/gr/sigv4-date-handling.html) dans le *Références générales AWS*.
+ `"X-Amz-Security-Token": `: le jeton de AWS session, qui est requis lors de l'utilisation d'informations d'identification de sécurité temporaires. Pour plus d'informations, consultez [Utilisation d'informations d'identification temporaires avec des ressources AWS](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_temp_use-resources.html) dans le *Guide de l'utilisateur IAM*.
+ `"Authorization": `: informations de signature de la version 4 (SigV4) pour le AWS AppSync point de terminaison. Pour plus d'informations sur le processus de signature, voir [Tâche 4 : ajouter la signature à la requête HTTP](https://docs.aws.amazon.com/general/latest/gr/sigv4-add-signature-to-request.html) dans le *Références générales AWS*.
La requête HTTP de signature SigV4 inclut une URL canonique, qui est le point de terminaison GraphQL AWS AppSync auquel `/connect` est ajouté. La AWS région du point de terminaison du service est la même région que celle dans laquelle vous utilisez l' AWS AppSync API, et le nom du service est « appsync ». La requête HTTP pour la signature est la suivante :
```
{
url: "https://example1234567890000.appsync-api.us-east-1.amazonaws.com/graphql/connect",
data: "{}",
method: "POST",
headers: {
"accept": "application/json, text/javascript",
"content-encoding": "amz-1.0",
"content-type": "application/json; charset=UTF-8",
}
}
```
**Exemple**
```
{
"accept": "application/json, text/javascript",
"content-encoding": "amz-1.0",
"content-type": "application/json; charset=UTF-8",
"host": "example1234567890000.appsync-api.us-east-1.amazonaws.com",
"x-amz-date": "20200401T001010Z",
"X-Amz-Security-Token": "AgEXAMPLEZ2luX2VjEAoaDmFwLXNvdXRoZWFEXAMPLEcwRQIgAh97Cljq7wOPL8KsxP3YtDuyc/9hAj8PhJ7Fvf38SgoCIQDhJEXAMPLEPspioOztj++pEagWCveZUjKEn0zyUhBEXAMPLEjj//////////8BEXAMPLExODk2NDgyNzg1NSIMo1mWnpESWUoYw4BkKqEFSrm3DXuL8w+ZbVc4JKjDP4vUCKNR6Le9C9pZp9PsW0NoFy3vLBUdAXEXAMPLEOVG8feXfiEEA+1khgFK/wEtwR+9zF7NaMMMse07wN2gG2tH0eKMEXAMPLEQX+sMbytQo8iepP9PZOzlZsSFb/dP5Q8hk6YEXAMPLEYcKZsTkDAq2uKFQ8mYUVA9EtQnNRiFLEY83aKvG/tqLWNnGlSNVx7SMcfovkFDqQamm+88y1OwwAEYK7qcoceX6Z7GGcaYuIfGpaX2MCCELeQvZ+8WxEgOnIfz7GYvsYNjLZSaRnV4G+ILY1F0QNW64S9Nvj+BwDg3ht2CrNvpwjVYlj9U3nmxE0UG5ne83LL5hhqMpm25kmL7enVgw2kQzmU2id4IKu0C/WaoDRuO2F5zE63vJbxN8AYs7338+4B4HBb6BZ6OUgg96Q15RA41/gIqxaVPxyTpDfTU5GfSLxocdYeniqqpFMtZG2n9d0u7GsQNcFkNcG3qDZm4tDo8tZbuym0a2VcF2E5hFEgXBa+XLJCfXi/77OqAEjP0x7Qdk3B43p8KG/BaioP5RsV8zBGvH1zAgyPha2rN70/tT13yrmPd5QYEfwzexjKrV4mWIuRg8NTHYSZJUaeyCwTom80VFUJXG+GYTUyv5W22aBcnoRGiCiKEYTLOkgXecdKFTHmcIAejQ9Welr0a196Kq87w5KNMCkcCGFnwBNFLmfnbpNqT6rUBxxs3X5ntX9d8HVtSYINTsGXXMZCJ7fnbWajhg/aox0FtHX21eF6qIGT8j1z+l2opU+ggwUgkhUUgCH2TfqBj+MLMVVvpgqJsPKt582caFKArIFIvO+9QupxLnEH2hz04TMTfnU6bQC6z1buVe7h+tOLnh1YPFsLQ88anib/7TTC8k9DsBTq0ASe8R2GbSEsmO9qbbMwgEaYUhOKtGeyQsSJdhSk6XxXThrWL9EnwBCXDkICMqdntAxyyM9nWsZ4bL9JHqExgWUmfWChzPFAqn3F4y896UqHTZxlq3WGypn5HHcem2Hqf3IVxKH1inhqdVtkryEiTWrI7ZdjbqnqRbl+WgtPtKOOweDlCaRs3R2qXcbNgVhleMk4IWnF8D1695AenU1LwHjOJLkCjxgNFiWAFEPH9aEXAMPLExA==",
"Authorization": "AWS4-HMAC-SHA256 Credential=XXXXXXXXXXXXXXXXXXX/20200401/us-east-1/appsync/aws4_request, SignedHeaders=accept;content-encoding;content-type;host;x-amz-date;x-amz-security-token, Signature=83EXAMPLEbcc1fe3ee69f75cd5ebbf4cb4f150e4f99cec869f149c5EXAMPLEdc"
}
```
**En-têtes via une chaîne de requête**
Tout d'abord, un objet JSON contenant le `host` (point de terminaison AWS AppSync GraphQL) et les autres en-têtes d'autorisation est converti en chaîne. Ensuite, cette chaîne est codée en utilisant le codage base64. La chaîne codée en base64 qui en résulte est ajoutée à l' WebSocket URL en tant que paramètre de requête nommé. `header` L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql?header=eyJBdXRob3JpemF0aW9uIjoiZXlKcmFXUWlPaUpqYkc1eGIzQTVlVzVNSzA5UVlYSXJNVEpIV0VGTFNYQmllVTVXTkhoc1FqaFBWVzlZTW5NMldsZHZQU0lzSW1Gc1p5STZJbEpUTWpVMkluMC5leUp6ZFdJaU9pSmhObU5tTWpjd055MHhOamd4TFRRMU5ESXRPV1l4T0MxbE5qWTBNVGcyTmpsa016WWlMQ0psZG1WdWRGOXBaQ0k2SW1Wa016TTVNbU5rTFdOallUTXROR00yT0MxaE5EWXlMVEpsWkdJM1pUTm1ZMkZqWmlJc0luUnZhMlZ1WDNWelpTSTZJbUZqWTJWemN5SXNJbk5qYjNCbElqb2lZWGR6TG1OdloyNXBkRzh1YzJsbmJtbHVMblZ6WlhJdVlXUnRhVzRpTENKaGRYUm9YM1JwYldVaU9qRTFOamswTlRjM01UZ3NJbWx6Y3lJNkltaDBkSEJ6T2x3dlhDOWpiMmR1YVhSdkxXbGtjQzVoY0MxemIzVjBhR1ZoYzNRdE1pNWhiV0Y2YjI1aGQzTXVZMjl0WEM5aGNDMXpiM1YwYUdWaGMzUXRNbDgzT0hZMFNWWmliVkFpTENKbGVIQWlPakUxTmprME5qRXpNakFzSW1saGRDSTZNVFUyT1RRMU56Y3lNQ3dpYW5ScElqb2lOVGd6WmpobVltTXRNemsyTVMwMFl6QTRMV0poWlRBdFl6UXlZMkl4TVRNNU5EWTVJaXdpWTJ4cFpXNTBYMmxrSWpvaU0zRmxhalZsTVhabU16ZDFOM1JvWld3MGRHOTFkREprTVd3aUxDSjFjMlZ5Ym1GdFpTSTZJbVZzYjNKNllXWmxJbjAuQjRjZEp0aDNLRk5wSjZpa1ZwN2U2RFJlZTk1VjZRaS16RUUyREpIN3NIT2wyenhZaTdmLVNtRUdvaDJBRDhlbXhRUllhakJ5ei1yRTRKaDBRT3ltTjJZcy1aSWtNcFZCVFBndS1UTVdEeU9IaERVbVVqMk9QODJ5ZVozd2xaQXRyX2dNNEx6alhVWG1JX0syeUdqdVhmWFRhYTFtdlFFQkcwbVFmVmQ3U2Z3WEItamN2NFJZVmk2ajI1cWdvdzlFdzUydWZ1clBxYUstM1dBS0czMktwVjhKNC1XZWpxOHQwYy15QTdzYjhFbkI1NTFiN1RVOTN1S1JpVlZLM0U1NU5rNUFEUG9hbV9XWUU0NWkzczVxVkFQXy1Jblc3NU5Vb09DR1RzUzhZV01mYjZlY0hZSi0xai1iekEyN3phVDlWamN0WG45YnlORlptS0xwQTJMY3h3IiwiaG9zdCI6ImV4YW1wbGUxMjM0NTY3ODkwMDAwLmFwcHN5bmMtYXBpLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tIn0=&payload=e30=
```
Il est important de noter qu'en plus de l'objet d'en-tête codé en base64, un objet JSON vide \$1\$1 est également codé en base64 et inclus en tant que paramètre de requête distinct nommé `payload` dans l'URL. WebSocket
**En-têtes via `Sec-WebSocket-Protocol`**
Un objet JSON contenant les en-têtes d'autorisation `host` et les autres est converti en chaîne puis codé à l'aide du codage Base64URL. La chaîne codée en Base64URL qui en résulte est préfixée par. `header-` Cette chaîne préfixée est ensuite utilisée comme nouveau sous-protocole en plus de figurer dans l'`Sec-WebSocket-Protocol`en-tête lors de `graphql-ws` l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel.
L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
L'`Sec-WebSocket-Protocol`en-tête contient la valeur suivante :
```
"sec-websocket-protocol" : ["graphql-ws", "header-ew0KICAiYWNjZXB0IjogImFwcGxpY2F0aW9uL2pzb24sIHRleHQvamF2YXNjcmlwdCIsDQogICJjb250ZW50LWVuY29kaW5nIjogImFtei0xLjAiLA0KICAiY29udGVudC10eXBlIjogImFwcGxpY2F0aW9uL2pzb247IGNoYXJzZXQ9VVRGLTgiLA0KICAiaG9zdCI6ICJleGFtcGxlMTIzNDU2Nzg5MDAwMC5hcHBzeW5jLWFwaS51cy1lYXN0LTEuYW1hem9uYXdzLmNvbSIsDQogICJ4LWFtei1kYXRlIjogIjIwMjAwNDAxVDAwMTAxMFoiLA0KICAiWC1BbXotU2VjdXJpdHktVG9rZW4iOiAiQWdFWEFNUExFWjJsdVgyVmpFQW9hRG1Gd0xYTnZkWFJvWldGRVhBTVBMRWN3UlFJZ0FoOTdDbGpxN3dPUEw4S3N4UDNZdER1eWMvOWhBajhQaEo3RnZmMzhTZ29DSVFEaEpFWEFNUExFUHNwaW9PenRqKytwRWFnV0N2ZVpVaktFbjB6eVVoQkVYQU1QTEVqai8vLy8vLy8vLy84QkVYQU1QTEV4T0RrMk5EZ3lOemcxTlNJTW8xbVducEVTV1VvWXc0QmtLcUVGU3JtM0RYdUw4dytaYlZjNEpLakRQNHZVQ0tOUjZMZTlDOXBacDlQc1cwTm9GeTN2TEJVZEFYRVhBTVBMRU9WRzhmZVhmaUVFQSsxa2hnRksvd0V0d1IrOXpGN05hTU1Nc2UwN3dOMmdHMnRIMGVLTUVYQU1QTEVRWCtzTWJ5dFFvOGllcFA5UFpPemxac1NGYi9kUDVROGhrNllFWEFNUExFWWNLWnNUa0RBcTJ1S0ZROG1ZVVZBOUV0UW5OUmlGTEVZODNhS3ZHL3RxTFdObkdsU05WeDdTTWNmb3ZrRkRxUWFtbSs4OHkxT3d3QUVZSzdxY29jZVg2WjdHR2NhWXVJZkdwYVgyTUNDRUxlUXZaKzhXeEVnT25JZno3R1l2c1lOakxaU2FSblY0RytJTFkxRjBRTlc2NFM5TnZqK0J3RGczaHQyQ3JOdnB3alZZbGo5VTNubXhFMFVHNW5lODNMTDVoaHFNcG0yNWttTDdlblZndzJrUXptVTJpZDRJS3UwQy9XYW9EUnVPMkY1ekU2M3ZKYnhOOEFZczczMzgrNEI0SEJiNkJaNk9VZ2c5NlExNVJBNDEvZ0lxeGFWUHh5VHBEZlRVNUdmU0x4b2NkWWVuaXFxcEZNdFpHMm45ZDB1N0dzUU5jRmtOY0czcURabTR0RG84dFpidXltMGEyVmNGMkU1aEZFZ1hCYStYTEpDZlhpLzc3T3FBRWpQMHg3UWRrM0I0M3A4S0cvQmFpb1A1UnNWOHpCR3ZIMXpBZ3lQaGEyck43MC90VDEzeXJtUGQ1UVlFZnd6ZXhqS3JWNG1XSXVSZzhOVEhZU1pKVWFleUN3VG9tODBWRlVKWEcrR1lUVXl2NVcyMmFCY25vUkdpQ2lLRVlUTE9rZ1hlY2RLRlRIbWNJQWVqUTlXZWxyMGExOTZLcTg3dzVLTk1Da2NDR0Zud0JORkxtZm5icE5xVDZyVUJ4eHMzWDVudFg5ZDhIVnRTWUlOVHNHWFhNWkNKN2ZuYldhamhnL2FveDBGdEhYMjFlRjZxSUdUOGoxeitsMm9wVStnZ3dVZ2toVVVnQ0gyVGZxQmorTUxNVlZ2cGdxSnNQS3Q1ODJjYUZLQXJJRkl2Tys5UXVweExuRUgyaHowNFRNVGZuVTZiUUM2ejFidVZlN2grdE9MbmgxWVBGc0xRODhhbmliLzdUVEM4azlEc0JUcTBBU2U4UjJHYlNFc21POXFiYk13Z0VhWVVoT0t0R2V5UXNTSmRoU2s2WHhYVGhyV0w5RW53QkNYRGtJQ01xZG50QXh5eU05bldzWjRiTDlKSHFFeGdXVW1mV0NoelBGQXFuM0Y0eTg5NlVxSFRaeGxxM1dHeXBuNUhIY2VtMkhxZjNJVnhLSDFpbmhxZFZ0a3J5RWlUV3JJN1pkamJxbnFSYmwrV2d0UHRLT093ZURsQ2FSczNSMnFYY2JOZ1ZobGVNazRJV25GOEQxNjk1QWVuVTFMd0hqT0pMa0NqeGdORmlXQUZFUEg5YUVYQU1QTEV4QT09IiwNCiAgIkF1dGhvcml6YXRpb24iOiAiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPVhYWFhYWFhYWFhYWFhYWFhYWFgvMjAyMDA0MDEvdXMtZWFzdC0xL2FwcHN5bmMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWFjY2VwdDtjb250ZW50LWVuY29kaW5nO2NvbnRlbnQtdHlwZTtob3N0O3gtYW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW4sIFNpZ25hdHVyZT04M0VYQU1QTEViY2MxZmUzZWU2OWY3NWNkNWViYmY0Y2I0ZjE1MGU0Zjk5Y2VjODY5ZjE0OWM1RVhBTVBMRWRjIg0KfQ"]
```
**En-têtes via des en-têtes HTTP standard**
Dans cette méthode, l'hôte et les autres informations d'autorisation sont transmises à l'aide d'en-têtes HTTP standard lors de l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
Les en-têtes de demande incluraient les éléments suivants :
```
"sec-websocket-protocol" : ["graphql-ws"]
"accept": "application/json, text/javascript",
"content-encoding": "amz-1.0",
"content-type": "application/json; charset=UTF-8",
"host": "example1234567890000.appsync-api.us-east-1.amazonaws.com",
"x-amz-date": "20200401T001010Z",
"X-Amz-Security-Token": "AgEXAMPLEZ2luX2VjEAoaDmFwLXNvdXRoZWFEXAMPLEcwRQIgAh97Cljq7wOPL8KsxP3YtDuyc/9hAj8PhJ7Fvf38SgoCIQDhJEXAMPLEPspioOztj++pEagWCveZUjKEn0zyUhBEXAMPLEjj//////////8BEXAMPLExODk2NDgyNzg1NSIMo1mWnpESWUoYw4BkKqEFSrm3DXuL8w+ZbVc4JKjDP4vUCKNR6Le9C9pZp9PsW0NoFy3vLBUdAXEXAMPLEOVG8feXfiEEA+1khgFK/wEtwR+9zF7NaMMMse07wN2gG2tH0eKMEXAMPLEQX+sMbytQo8iepP9PZOzlZsSFb/dP5Q8hk6YEXAMPLEYcKZsTkDAq2uKFQ8mYUVA9EtQnNRiFLEY83aKvG/tqLWNnGlSNVx7SMcfovkFDqQamm+88y1OwwAEYK7qcoceX6Z7GGcaYuIfGpaX2MCCELeQvZ+8WxEgOnIfz7GYvsYNjLZSaRnV4G+ILY1F0QNW64S9Nvj+BwDg3ht2CrNvpwjVYlj9U3nmxE0UG5ne83LL5hhqMpm25kmL7enVgw2kQzmU2id4IKu0C/WaoDRuO2F5zE63vJbxN8AYs7338+4B4HBb6BZ6OUgg96Q15RA41/gIqxaVPxyTpDfTU5GfSLxocdYeniqqpFMtZG2n9d0u7GsQNcFkNcG3qDZm4tDo8tZbuym0a2VcF2E5hFEgXBa+XLJCfXi/77OqAEjP0x7Qdk3B43p8KG/BaioP5RsV8zBGvH1zAgyPha2rN70/tT13yrmPd5QYEfwzexjKrV4mWIuRg8NTHYSZJUaeyCwTom80VFUJXG+GYTUyv5W22aBcnoRGiCiKEYTLOkgXecdKFTHmcIAejQ9Welr0a196Kq87w5KNMCkcCGFnwBNFLmfnbpNqT6rUBxxs3X5ntX9d8HVtSYINTsGXXMZCJ7fnbWajhg/aox0FtHX21eF6qIGT8j1z+l2opU+ggwUgkhUUgCH2TfqBj+MLMVVvpgqJsPKt582caFKArIFIvO+9QupxLnEH2hz04TMTfnU6bQC6z1buVe7h+tOLnh1YPFsLQ88anib/7TTC8k9DsBTq0ASe8R2GbSEsmO9qbbMwgEaYUhOKtGeyQsSJdhSk6XxXThrWL9EnwBCXDkICMqdntAxyyM9nWsZ4bL9JHqExgWUmfWChzPFAqn3F4y896UqHTZxlq3WGypn5HHcem2Hqf3IVxKH1inhqdVtkryEiTWrI7ZdjbqnqRbl+WgtPtKOOweDlCaRs3R2qXcbNgVhleMk4IWnF8D1695AenU1LwHjOJLkCjxgNFiWAFEPH9aEXAMPLExA==",
"Authorization": "AWS4-HMAC-SHA256 Credential=XXXXXXXXXXXXXXXXXXX/20200401/us-east-1/appsync/aws4_request, SignedHeaders=accept;content-encoding;content-type;host;x-amz-date;x-amz-security-token, Signature=83EXAMPLEbcc1fe3ee69f75cd5ebbf4cb4f150e4f99cec869f149c5EXAMPLEdc"
```
Pour signer la demande à l'aide d'un domaine personnalisé, procédez comme suit :
```
{
url: "https://api.example.com/graphql/connect",
data: "{}",
method: "POST",
headers: {
"accept": "application/json, text/javascript",
"content-encoding": "amz-1.0",
"content-type": "application/json; charset=UTF-8",
}
}
```
**Exemple**
```
{
"accept": "application/json, text/javascript",
"content-encoding": "amz-1.0",
"content-type": "application/json; charset=UTF-8",
"host": "api.example.com",
"x-amz-date": "20200401T001010Z",
"X-Amz-Security-Token": "AgEXAMPLEZ2luX2VjEAoaDmFwLXNvdXRoZWFEXAMPLEcwRQIgAh97Cljq7wOPL8KsxP3YtDuyc/9hAj8PhJ7Fvf38SgoCIQDhJEXAMPLEPspioOztj++pEagWCveZUjKEn0zyUhBEXAMPLEjj//////////8BEXAMPLExODk2NDgyNzg1NSIMo1mWnpESWUoYw4BkKqEFSrm3DXuL8w+ZbVc4JKjDP4vUCKNR6Le9C9pZp9PsW0NoFy3vLBUdAXEXAMPLEOVG8feXfiEEA+1khgFK/wEtwR+9zF7NaMMMse07wN2gG2tH0eKMEXAMPLEQX+sMbytQo8iepP9PZOzlZsSFb/dP5Q8hk6YEXAMPLEYcKZsTkDAq2uKFQ8mYUVA9EtQnNRiFLEY83aKvG/tqLWNnGlSNVx7SMcfovkFDqQamm+88y1OwwAEYK7qcoceX6Z7GGcaYuIfGpaX2MCCELeQvZ+8WxEgOnIfz7GYvsYNjLZSaRnV4G+ILY1F0QNW64S9Nvj+BwDg3ht2CrNvpwjVYlj9U3nmxE0UG5ne83LL5hhqMpm25kmL7enVgw2kQzmU2id4IKu0C/WaoDRuO2F5zE63vJbxN8AYs7338+4B4HBb6BZ6OUgg96Q15RA41/gIqxaVPxyTpDfTU5GfSLxocdYeniqqpFMtZG2n9d0u7GsQNcFkNcG3qDZm4tDo8tZbuym0a2VcF2E5hFEgXBa+XLJCfXi/77OqAEjP0x7Qdk3B43p8KG/BaioP5RsV8zBGvH1zAgyPha2rN70/tT13yrmPd5QYEfwzexjKrV4mWIuRg8NTHYSZJUaeyCwTom80VFUJXG+GYTUyv5W22aBcnoRGiCiKEYTLOkgXecdKFTHmcIAejQ9Welr0a196Kq87w5KNMCkcCGFnwBNFLmfnbpNqT6rUBxxs3X5ntX9d8HVtSYINTsGXXMZCJ7fnbWajhg/aox0FtHX21eF6qIGT8j1z+l2opU+ggwUgkhUUgCH2TfqBj+MLMVVvpgqJsPKt582caFKArIFIvO+9QupxLnEH2hz04TMTfnU6bQC6z1buVe7h+tOLnh1YPFsLQ88anib/7TTC8k9DsBTq0ASe8R2GbSEsmO9qbbMwgEaYUhOKtGeyQsSJdhSk6XxXThrWL9EnwBCXDkICMqdntAxyyM9nWsZ4bL9JHqExgWUmfWChzPFAqn3F4y896UqHTZxlq3WGypn5HHcem2Hqf3IVxKH1inhqdVtkryEiTWrI7ZdjbqnqRbl+WgtPtKOOweDlCaRs3R2qXcbNgVhleMk4IWnF8D1695AenU1LwHjOJLkCjxgNFiWAFEPH9aEXAMPLExA==",
"Authorization": "AWS4-HMAC-SHA256 Credential=XXXXXXXXXXXXXXXXXXX/20200401/us-east-1/appsync/aws4_request, SignedHeaders=accept;content-encoding;content-type;host;x-amz-date;x-amz-security-token, Signature=83EXAMPLEbcc1fe3ee69f75cd5ebbf4cb4f150e4f99cec869f149c5EXAMPLEdc"
}
```
**URL de demande avec chaîne de requête**
```
wss://api.example.com/graphql?header=eyEXAMPLEHQiOiJhcHBsaWNhdGlvbi9qc29uLCB0ZXh0L2phdmFEXAMPLEQiLCJjb250ZW50LWVuY29kaW5nIjoEXAMPLEEuMCIsImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9EXAMPLE47IGNoYXJzZXQ9VVRGLTgiLCJob3N0IjoiZXhhbXBsZEXAMPLENjc4OTAwMDAuYXBwc3luYy1hcGkudXMtZWFzdC0xLmFtYEXAMPLEcy5jb20iLCJ4LWFtei1kYXRlIjoiMjAyMDA0MDFUMDAxMDEwWiIsIlgtEXAMPLElY3VyaXR5LVRva2VuIjoiQWdvSmIzSnBaMmx1WDJWakVBb2FEbUZ3TFhOdmRYUm9aV0Z6ZEMweUlrY3dSUUlnQWg5N0NsanE3d09QTDhLc3hQM1l0RHV5Yy85aEFqOFBoSjdGdmYzOFNnb0NJUURoSllKYkpsbmpQc3Bpb096dGorK3BFYWdXQ3ZlWlVqS0VuMHp5VWhCbXhpck5CUWpqLy8vLy8vLy8vLzhCRUFBYUREY3hPRGsyTkRneU56ZzFOU0lNbzFtV25wRVNXVW9ZdzRCa0txRUZTcm0zRFh1TDh3K1piVmM0SktqRFA0dlVDS05SNkxlOUM5cFpwOVBzVzBOb0Z5M3ZMQlVkQVh3dDZQSld1T1ZHOGZlWGZpRUVBKzFraGdGSy93RXR3Uis5ekY3TmFNTU1zZTA3d04yZ0cydEgwZUtNVFhuOEF3QVFYK3NNYnl0UW84aWVwUDlQWk96bFpzU0ZiL2RQNVE4aGs2WWpHVGFMMWVZY0tac1RrREFxMnVLRlE4bVlVVkE5RXRRbk5SaUZMRVk4M2FLdkcvdHFMV05uR2xTTlZ4N1NNY2ZvdmtGRHFRYW1tKzg4eTFPd3dBRVlLN3Fjb2NlWDZaN0dHY2FZdUlmR3BhWDJNQ0NFTGVRdlorOFd4RWdPbklmejdHWXZzWU5qTFpTYVJuVjRHK0lMWTFGMFFOVzY0UzlOdmorQndEZzNodDJDck52cHdqVllsajlVM25teEUwVUc1bmU4M0xMNWhocU1wbTI1a21MN2VuVmd3MmtRem1VMmlkNElLdTBDL1dhb0RSdU8yRjV6RTYzdkpieE44QVlzNzMzOCs0QjRIQmI2Qlo2T1VnZzk2UTE1UkE0MS9nSXF4YVZQeHlUcERmVFU1R2ZTTHhvY2RZZW5pcXFwRk10WkcybjlkMHU3R3NRTmNGa05jRzNxRFptNHREbzh0WmJ1eW0wYTJWY0YyRTVoRkVnWEJhK1hMSkNmWGkvNzdPcUFFalAweDdRZGszQjQzcDhLRy9CYWlvUDVSc1Y4ekJHdkgxekFneVBoYTJyTjcwL3RUMTN5cm1QZDVRWUVmd3pleGpLclY0bVdJdVJnOE5USFlTWkpVYWV5Q3dUb204MFZGVUpYRytHWVRVeXY1VzIyYUJjbm9SR2lDaUtFWVRMT2tnWGVjZEtGVEhtY0lBZWpROVdlbHIwYTE5NktxODd3NUtOTUNrY0NHRm53Qk5GTG1mbmJwTnFUNnJVQnh4czNYNW50WDlkOEhWdFNZSU5Uc0dYWE1aQ0o3Zm5iV2FqaGcvYW94MEZ0SFgyMWVGNnFJR1Q4ajF6K2wyb3BVK2dnd1Vna2hVVWdDSDJUZnFCaitNTE1WVnZwZ3FKc1BLdDU4MmNhRktBcklGSXZPKzlRdXB4TG5FSDJoejA0VE1UZm5VNmJRQzZ6MWJ1VmU3aCt0T0xuaDFZUEZzTFE4OGFuaWIvN1RUQzhrOURzQlRxMEFTZThSMkdiU0VzbU85cWJiTXdnRWFZVWhPS3RHZXlRc1NKZGhTazZYeFhUaHJXTDlFbndCQ1hEa0lDTXFkbnRBeHl5TTluV3NaNGJMOUpIcUV4Z1dVbWZXQ2h6UEZBcW4zRjR5ODk2VXFIVFp4bHEzV0d5cG41SEhjZW0ySHFmM0lWeEtIMWluaHFkVnRrcnlFaVRXckk3WmRqYnFucVJibCtXZ3RQdEtPT3dlRGxDYVJzM1IycVhjYk5nVmhsZU1rNElXbkY4RDE2OTVBZW5VMUx3SGpPSkxrQ2p4Z05GaVdBRkVQSDlhTklhcXMvWnhBPT0iLCJBdXRob3JpemF0aW9uIjoiQVdTNC1ITUFDLVNIQTI1NiBDcmVkZW50aWFsPVhYWFhYWFhYWFhYWFhYWFhYWFgvMjAxOTEwMDIvdXMtZWFzdC0xEXAMPLE5bmMvYXdzNF9yZXF1ZXN0LCBTaWduZWRIZWFkZXJzPWFjY2VwdDtjb250ZWEXAMPLE29kaW5nO2NvbnRlbnQtdHlwZTtob3EXAMPLEW16LWRhdGU7eC1hbXotc2VjdXJpdHktdG9rZW4sIFNpZ25hdHVyZT04MzE4EXAMPLEiY2MxZmUzZWU2OWY3NWNkEXAMPLE0Y2I0ZjE1MGU0Zjk5Y2VjODY5ZjE0OWM1ZDAzNDEXAMPLEn0=&payload=e30=
```
**Note**
Une WebSocket connexion peut comporter plusieurs abonnements (même avec différents modes d'authentification). Une façon de mettre cela en œuvre consiste à créer une WebSocket connexion pour le premier abonnement, puis à la fermer lorsque le dernier abonnement n'est pas enregistré. Vous pouvez optimiser cela en attendant quelques secondes avant de fermer la WebSocket connexion, au cas où l'application serait abonnée immédiatement après le désenregistrement du dernier abonnement. Pour une application mobile, par exemple, lorsque vous passez d'un écran à un autre, lors du *démontage*, elle arrête un abonnement, et lors du *montage de* l'événement, elle lance un autre abonnement.
### Autorisation Lambda
#### En-tête d'autorisation Lambda
**Contenu de l'en-tête**
+ `"Authorization": `: valeur transmise en tant que`authorizationToken`.
+ `"host": `: L'hôte du point de terminaison AWS AppSync GraphQL ou votre nom de domaine personnalisé.
**Exemple**
```
{
"Authorization":"M0UzQzM1MkQtMkI0Ni00OTZCLUI1NkQtMUM0MTQ0QjVBRTczCkI1REEzRTIxLTk5NzItNDJENi1BQjMwLTFCNjRFNzQ2NzlCNQo=",
"host":"example1234567890000.appsync-api.us-east-1.amazonaws.com"
}
```
**En-têtes via une chaîne de requête**
Tout d'abord, un objet JSON contenant le `host` et `Authorization` est converti en chaîne. Ensuite, cette chaîne est codée en utilisant le codage base64. La chaîne codée en base64 qui en résulte est ajoutée en tant que paramètre de requête nommé `header` à l' WebSocket URL pour établir la connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql?header=eyJBdXRob3JpemF0aW9uIjoiZXlKcmFXUWlPaUpqYkc1eGIzQTVlVzVNSzA5UVlYSXJNVEpIV0VGTFNYQmllVTVXTkhoc1FqaFBWVzlZTW5NMldsZHZQU0lzSW1Gc1p5STZJbEpUTWpVMkluMC5leUp6ZFdJaU9pSmhObU5tTWpjd055MHhOamd4TFRRMU5ESXRPV1l4T0MxbE5qWTBNVGcyTmpsa016WWlMQ0psZG1WdWRGOXBaQ0k2SW1Wa016TTVNbU5rTFdOallUTXROR00yT0MxaE5EWXlMVEpsWkdJM1pUTm1ZMkZqWmlJc0luUnZhMlZ1WDNWelpTSTZJbUZqWTJWemN5SXNJbk5qYjNCbElqb2lZWGR6TG1OdloyNXBkRzh1YzJsbmJtbHVMblZ6WlhJdVlXUnRhVzRpTENKaGRYUm9YM1JwYldVaU9qRTFOamswTlRjM01UZ3NJbWx6Y3lJNkltaDBkSEJ6T2x3dlhDOWpiMmR1YVhSdkxXbGtjQzVoY0MxemIzVjBhR1ZoYzNRdE1pNWhiV0Y2YjI1aGQzTXVZMjl0WEM5aGNDMXpiM1YwYUdWaGMzUXRNbDgzT0hZMFNWWmliVkFpTENKbGVIQWlPakUxTmprME5qRXpNakFzSW1saGRDSTZNVFUyT1RRMU56Y3lNQ3dpYW5ScElqb2lOVGd6WmpobVltTXRNemsyTVMwMFl6QTRMV0poWlRBdFl6UXlZMkl4TVRNNU5EWTVJaXdpWTJ4cFpXNTBYMmxrSWpvaU0zRmxhalZsTVhabU16ZDFOM1JvWld3MGRHOTFkREprTVd3aUxDSjFjMlZ5Ym1GdFpTSTZJbVZzYjNKNllXWmxJbjAuQjRjZEp0aDNLRk5wSjZpa1ZwN2U2RFJlZTk1VjZRaS16RUUyREpIN3NIT2wyenhZaTdmLVNtRUdvaDJBRDhlbXhRUllhakJ5ei1yRTRKaDBRT3ltTjJZcy1aSWtNcFZCVFBndS1UTVdEeU9IaERVbVVqMk9QODJ5ZVozd2xaQXRyX2dNNEx6alhVWG1JX0syeUdqdVhmWFRhYTFtdlFFQkcwbVFmVmQ3U2Z3WEItamN2NFJZVmk2ajI1cWdvdzlFdzUydWZ1clBxYUstM1dBS0czMktwVjhKNC1XZWpxOHQwYy15QTdzYjhFbkI1NTFiN1RVOTN1S1JpVlZLM0U1NU5rNUFEUG9hbV9XWUU0NWkzczVxVkFQXy1Jblc3NU5Vb09DR1RzUzhZV01mYjZlY0hZSi0xai1iekEyN3phVDlWamN0WG45YnlORlptS0xwQTJMY3h3IiwiaG9zdCI6ImV4YW1wbGUxMjM0NTY3ODkwMDAwLmFwcHN5bmMtYXBpLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tIn0=&payload=e30=
```
Il est important de noter qu'en plus de l'objet d'en-tête codé en base64, un objet JSON vide \$1\$1 est également codé en base64 et inclus en tant que paramètre de requête distinct nommé `payload` dans l'URL. WebSocket
**En-têtes via `Sec-WebSocket-Protocol`**
Un objet JSON contenant le `host` et `Authorization` est converti en chaîne puis codé à l'aide du codage Base64URL. La chaîne codée en Base64URL qui en résulte est préfixée par. `header-` Cette chaîne préfixée est ensuite utilisée comme nouveau sous-protocole en plus de figurer dans l'`Sec-WebSocket-Protocol`en-tête lors de `graphql-ws` l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel.
L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
L'`Sec-WebSocket-Protocol`en-tête contient la valeur suivante :
```
"sec-websocket-protocol" : ["graphql-ws", "header-ewogICAgImhvc3QiOiJleGFtcGxlMTIzNDU2Nzg5MDAwMC5hcHBzeW5jLWFwaS51cy1lYXN0LTEuYW1hem9uYXdzLmNvbSIsCiAgICAieC1hcGkta2V5IjoiZGEyLTEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Igp9"]
```
**En-têtes via des en-têtes HTTP standard**
Dans cette méthode, les informations d'hôte et d'autorisation sont transmises à l'aide d'en-têtes HTTP standard lors de l'établissement de la WebSocket connexion avec le point de terminaison AWS AppSync en temps réel. L'URL de demande qui en résulte prend la forme suivante :
```
wss://example1234567890000.appsync-realtime-api.us-east-1.amazonaws.com/graphql
```
Les en-têtes de demande incluraient les éléments suivants :
```
"sec-websocket-protocol" : ["graphql-ws"]
"Authorization":"eyEXAMPLEiJjbG5xb3A5eW5MK09QYXIrMTJHWEFLSXBieU5WNHhsQjEXAMPLEnM2WldvPSIsImFsZyI6IlEXAMPLEn0.eyEXAMPLEiJhNmNmMjcwNy0xNjgxLTQ1NDItOWYxOC1lNjY0MTg2NjlkMzYiLCJldmVudF9pZCI6ImVkMzM5MmNkLWNjYTMtNGM2OC1hNDYyLTJlZGI3ZTNmY2FjZiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE1Njk0NTc3MTgsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5hcC1zb3V0aGVhc3QtMi5hbWF6b25hd3MuY29tXC9hcC1zb3V0aGVhc3QtMl83OHY0SVZibVAiLCJleHAiOjE1Njk0NjEzMjAsImlhdCI6MTU2OTQ1NzcyMCwianRpIjoiNTgzZjhmYmMtMzk2MS00YzA4LWJhZTAtYzQyY2IxMTM5NDY5IiwiY2xpZW50X2lkIjoiM3FlajVlMXZmMzd1N3RoZWw0dG91dDJkMWwiLCJ1c2VybmFtZSI6ImVsb3EXAMPLEn0.B4EXAMPLEFNpJ6ikVp7e6DRee95V6Qi-zEE2DJH7sHOl2zxYi7f-SmEGoh2AD8emxQRYajByz-rE4Jh0QOymN2Ys-ZIkMpVBTPgu-TMWDyOHhDUmUj2OP82yeZ3wlZAtr_gM4LzjXUXmI_K2yGjuXfXTaa1mvQEBG0mQfVd7SfwXB-jcv4RYVi6j25qgow9Ew52ufurPqaK-3WAKG32KpV8J4-Wejq8t0c-yA7sb8EnB551b7TU93uKRiVVK3E55Nk5ADPoam_WYE45i3s5qVAP_-InW75NUoOCGTsS8YWMfb6ecHYJ-1j-bzA27zaT9VjctXn9byNFZmEXAMPLExw",
"host":"example1234567890000.appsync-api.us-east-1.amazonaws.com"
```
## WebSocket Fonctionnement en temps réel
Après avoir initié une WebSocket poignée de main réussie avec AWS AppSync, le client doit envoyer un message suivant pour se connecter AWS AppSync pour différentes opérations. Ces messages nécessitent les données suivantes :
+ `type` : type de l'opération.
+ `id`: identifiant unique pour l'abonnement. Nous vous recommandons d'utiliser un UUID à cet effet.
+ `payload`: charge utile associée, en fonction du type d'opération.
Le `type` champ est le seul champ obligatoire ; les `payload` champs `id` et sont facultatifs.
### Séquence des événements
Pour lancer, établir, enregistrer et traiter correctement la demande d'abonnement, le client doit suivre la séquence suivante :
1. Initialisation de la connexion (`connection_init`)
1. Accusé de réception de connexion (`connection_ack`)
1. Inscription à l'abonnement (`start`)
1. Accusé de réception d'abonnement (`start_ack`)
1. Traitement de l'abonnement (`data`)
1. Annulation de l'abonnement (`stop`)
## Message d'initiation de connexion
(Facultatif) Après une poignée de main réussie, le client peut envoyer le `connection_init` message pour commencer à communiquer avec le point de terminaison AWS AppSync en temps réel. Le message est une chaîne obtenue en chaînant l'objet JSON comme suit :
```
{ "type": "connection_init" }
```
## Message d'accusé de réception de connexion
Après avoir envoyé le message `connection_init`, le client doit attendre le message `connection_ack`. Tous les messages envoyés avant réception `connection_ack` sont ignorés. Le message doit se lire comme suit :
```
{
"type": "connection_ack",
"payload": {
// Time in milliseconds waiting for ka message before the client should terminate the WebSocket connection
"connectionTimeoutMs": 300000
}
}
```
## Message « keep-alive »
Outre le message d'accusé de réception de connexion, le client reçoit régulièrement des messages de maintien en vie. Si le client ne reçoit pas de message de maintien en vie pendant le délai d'expiration de la connexion, il doit fermer la connexion. AWS AppSync continue d'envoyer ces messages et de gérer les abonnements enregistrés jusqu'à ce que la connexion soit automatiquement interrompue (après 24 heures). Les messages Keep-Alive sont des battements de cœur et le client n'a pas besoin d'en accuser réception.
```
{ "type": "ka" }
```
## Message d'inscription à l'abonnement
Une fois que le client a reçu un `connection_ack` message, il peut envoyer des messages d'enregistrement d'abonnement à AWS AppSync. Ce type de message est un objet JSON sous forme de chaîne qui contient les champs suivants :
+ `"id": `: ID de l'abonnement. Cet identifiant doit être unique pour chaque abonnement, sinon le serveur renvoie une erreur indiquant que l'identifiant d'abonnement est dupliqué.
+ `"type": "start"` : un paramètre `` constant.
+ `"payload":