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.
# AWS AppSync JavaScript vue d'ensemble des résolveurs
AWS AppSync vous permet de répondre aux requêtes GraphQL en effectuant des opérations sur vos sources de données. Pour chaque champ GraphQL sur lequel vous souhaitez exécuter une requête, une mutation ou un abonnement, un résolveur doit être joint.
Les résolveurs sont les connecteurs entre GraphQL et une source de données. Ils expliquent AWS AppSync comment traduire une requête GraphQL entrante en instructions pour votre source de données principale et comment traduire la réponse de cette source de données en réponse GraphQL. Avec AWS AppSync, vous pouvez écrire vos résolveurs en les utilisant JavaScript et les exécuter dans l'environnement AWS AppSync (`APPSYNC_JS`).
AWS AppSync vous permet d'écrire des résolveurs d'unités ou des résolveurs de pipeline composés de plusieurs AWS AppSync fonctions dans un pipeline.
## Fonctionnalités d'exécution prises en charge
Le AWS AppSync JavaScript moteur d'exécution fournit un sous-ensemble de JavaScript bibliothèques, d'utilitaires et de fonctionnalités. Pour une liste complète des fonctionnalités prises en charge par le `APPSYNC_JS` moteur d'exécution, voir [Fonctionnalités JavaScript d'exécution pour les résolveurs et les fonctions](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html).
## Résolveurs d'unités
Un résolveur d'unités est composé d'un code qui définit un gestionnaire de demandes et de réponses qui sont exécutés sur une source de données. Le gestionnaire de demandes prend un objet de contexte comme argument et renvoie la charge utile de la demande utilisée pour appeler votre source de données. Le gestionnaire de réponses reçoit une charge utile en retour de la source de données avec le résultat de la demande exécutée. Le gestionnaire de réponse transforme la charge utile en réponse GraphQL pour résoudre le champ GraphQL. Dans l'exemple ci-dessous, un résolveur extrait un élément d'une source de données DynamoDB :
```
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
return ddb.get({ key: { id: ctx.args.id } });
}
export const response = (ctx) => ctx.result;
```
## Anatomie d'un résolveur de JavaScript pipeline
Un résolveur de pipeline est composé d'un code qui définit un gestionnaire de requêtes et de réponses et d'une liste de fonctions. Chaque fonction possède un gestionnaire de **requêtes** et de **réponses** qu'elle exécute sur une source de données. Lorsqu'un résolveur de pipeline délègue des exécutions à une liste de fonctions, il n'est donc lié à aucune source de données. Les résolveurs d'unité et les fonctions sont des primitifs qui exécutent l'opération sur les sources de données.
### Gestionnaire de requêtes Pipeline Resolver
Le gestionnaire de requêtes d'un résolveur de pipeline (étape précédente) vous permet d'exécuter une certaine logique de préparation avant d'exécuter les fonctions définies.
### Liste des fonctions
La liste des fonctions d'un résolveur de pipeline est exécutée dans l'ordre. Le résultat de l'évaluation du gestionnaire de demandes du résolveur de pipeline est mis à la disposition de la première fonction sous forme de. `ctx.prev.result` Le résultat de l'évaluation de chaque fonction est disponible pour la fonction suivante sous forme de`ctx.prev.result`.
### Gestionnaire de réponses Pipeline Resolver
Le gestionnaire de réponse d'un résolveur de pipeline vous permet d'exécuter une certaine logique finale entre la sortie de la dernière fonction et le type de champ GraphQL attendu. La sortie de la dernière fonction de la liste des fonctions est disponible dans le gestionnaire de réponse du résolveur de pipeline sous `ctx.prev.result` la forme ou. `ctx.result`
### Flux d'exécution
Étant donné qu'un résolveur de pipeline comprend deux fonctions, la liste ci-dessous représente le flux d'exécution lorsque le résolveur est invoqué :
1. Gestionnaire de requêtes Pipeline Resolver
1. Fonction 1 : gestionnaire de demandes de fonctions
1. Fonction 1 : Appel de source de données
1. Fonction 1 : gestionnaire de réponse fonctionnelle
1. Fonction 2 : gestionnaire de demandes de fonctions
1. Fonction 2 : Appel de source de données
1. Fonction 2 : gestionnaire de réponse fonctionnelle
1. Gestionnaire de réponses Pipeline Resolver
![\[GraphQL request flow diagram showing interactions between request, data sources, and response components.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/appsync-js-resolver-logic.png)
### Utilitaires intégrés utiles à l'`APPSYNC_JS`exécution
Les utilitaires suivants peuvent vous aider si vous travaillez avec des résolveurs de pipeline.
#### ctx.stash
Le stash est un objet mis à disposition dans chaque résolveur et chaque gestionnaire de demandes et de réponses de fonctions. La même instance de stash passe par une seule exécution du résolveur. Cela signifie que vous pouvez utiliser le stash pour transmettre des données arbitraires entre les gestionnaires de requêtes et de réponses et entre les fonctions d'un résolveur de pipeline. Vous pouvez tester la réserve comme un JavaScript objet normal.
#### ctx.prev.result
`ctx.prev.result` représente le résultat de l'opération précédente exécutée dans le pipeline. Si l'opération précédente était le gestionnaire de demandes du résolveur de pipeline, elle `ctx.prev.result` est alors mise à la disposition de la première fonction de la chaîne. Si l'opération précédente est la première fonction, alors `ctx.prev.result` représente le résultat de la première fonction et il est disponible pour la seconde fonction du pipeline. Si l'opération précédente était la dernière fonction, elle `ctx.prev.result` représente la sortie de la dernière fonction et est mise à la disposition du gestionnaire de réponse du résolveur de pipeline.
#### util.error
L'utilitaire `util.error` est utile pour envoyer une erreur de champ. `util.error`L'utilisation à l'intérieur d'un gestionnaire de demandes ou de réponses de fonction génère immédiatement une erreur de champ, ce qui empêche l'exécution des fonctions suivantes. Pour plus de détails et pour d'autres `util.error` signatures, consultez les [fonctionnalités JavaScript d'exécution pour les résolveurs et les fonctions](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html).
#### Erreur Util.AppendError
`util.appendError`est similaire à`util.error()`, avec la principale différence qu'il n'interrompt pas l'évaluation du gestionnaire. Il signale plutôt qu'une erreur s'est produite dans le champ, mais permet d'évaluer le gestionnaire et, par conséquent, de renvoyer des données. L'utilisation de `util.appendError` dans une fonction ne perturbera pas le flux d'exécution du pipeline. Pour plus de détails et pour d'autres `util.error` signatures, consultez les [fonctionnalités JavaScript d'exécution relatives aux résolveurs et aux fonctions](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html).
#### Temps d'exécution. Retour anticipé
La `runtime.earlyReturn` fonction vous permet de revenir prématurément à n'importe quelle fonction de requête. L'utilisation de `runtime.earlyReturn` l'intérieur d'un gestionnaire de demandes de résolution sera renvoyée par le résolveur. L'appeler depuis un gestionnaire de demandes de AWS AppSync fonction retournera depuis la fonction et poursuivra l'exécution vers la fonction suivante du pipeline ou vers le gestionnaire de réponse du résolveur.
### Écrire des résolveurs de pipeline
Un résolveur de pipeline possède également un gestionnaire de requêtes et de réponses entourant l'exécution des fonctions du pipeline : son gestionnaire de demandes est exécuté avant la demande de la première fonction, et son gestionnaire de réponse est exécuté après la réponse de la dernière fonction. Le gestionnaire de requêtes Resolver peut configurer les données à utiliser par les fonctions du pipeline. Le gestionnaire de réponse du résolveur est chargé de renvoyer les données correspondant au type de sortie du champ GraphQL. Dans l'exemple ci-dessous, un gestionnaire de demandes de résolution définit `allowedGroups` ; les données renvoyées doivent appartenir à l'un de ces groupes. Cette valeur peut être utilisée par les fonctions du résolveur pour demander des données. Le gestionnaire de réponses du résolveur effectue une dernière vérification et filtre le résultat pour s'assurer que seuls les éléments appartenant aux groupes autorisés sont renvoyés.
```
import { util } from '@aws-appsync/utils';
/**
* Called before the request function of the first AppSync function in the pipeline.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function request(ctx) {
ctx.stash.allowedGroups = ['admin'];
ctx.stash.startedAt = util.time.nowISO8601();
return {};
}
/**
* Called after the response function of the last AppSync function in the pipeline.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
const result = [];
for (const item of ctx.prev.result) {
if (ctx.stash.allowedGroups.indexOf(item.group) > -1) result.push(item);
}
return result;
}
```
#### AWS AppSync Fonctions d'écriture
AWS AppSync les fonctions vous permettent d'écrire une logique commune que vous pouvez réutiliser dans plusieurs résolveurs de votre schéma. Par exemple, vous pouvez avoir une AWS AppSync fonction appelée `QUERY_ITEMS` qui est chargée de demander des éléments à partir d'une source de données Amazon DynamoDB. Pour les résolveurs avec lesquels vous souhaitez interroger des éléments, ajoutez simplement la fonction au pipeline du résolveur et fournissez l'index de requête à utiliser. La logique n'a pas besoin d'être réimplémentée.
## Sujets supplémentaires
**Rubriques**
+ [Exemple de résolveur de pipeline avec Amazon DynamoDB](https://docs.aws.amazon.com/appsync/latest/devguide/writing-code.html)
+ [Configuration des utilitaires pour l'`APPSYNC_JS`environnement d'exécution](https://docs.aws.amazon.com/appsync/latest/devguide/utility-resolvers.html)
+ [Regroupement et sources TypeScript de cartes pour l'environnement d'exécution `APPSYNC_JS`](https://docs.aws.amazon.com/appsync/latest/devguide/additional-utilities.html)
+ [Tester votre résolveur et vos gestionnaires de fonctions](https://docs.aws.amazon.com/appsync/latest/devguide/test-resolvers.html)
+ [Migration de VTL vers JavaScript](https://docs.aws.amazon.com/appsync/latest/devguide/migrating-resolvers.html)
+ [Choisir entre un accès direct à une source de données ou un proxy via une source de données Lambda](https://docs.aws.amazon.com/appsync/latest/devguide/choosing-data-source.html)
# Exemple de résolveur de pipeline avec Amazon DynamoDB
Supposons que vous souhaitiez associer un résolveur de pipeline à un champ nommé `getPost(id:ID!)` qui renvoie un `Post` type provenant d'une source de données Amazon DynamoDB avec la requête GraphQL suivante :
```
getPost(id:1){
id
title
content
}
```
Tout d'abord, attachez un résolveur simple à l'`Query.getPost`aide du code ci-dessous. Il s'agit d'un exemple de code de résolution simple. Aucune logique n'est définie dans le gestionnaire de demandes, et le gestionnaire de réponse renvoie simplement le résultat de la dernière fonction.
```
/**
* Invoked **before** the request handler of the first AppSync function in the pipeline.
* The resolver `request` handler allows to perform some preparation logic
* before executing the defined functions in your pipeline.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function request(ctx) {
return {}
}
/**
* Invoked **after** the response handler of the last AppSync function in the pipeline.
* The resolver `response` handler allows to perform some final evaluation logic
* from the output of the last function to the expected GraphQL field type.
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
return ctx.prev.result
}
```
Définissez ensuite la fonction `GET_ITEM` qui extrait un article de votre source de données :
```
import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'
/**
* Request a single item from the attached DynamoDB table datasource
* @param ctx the context object holds contextual information about the function invocation.
*/
export function request(ctx) {
const { id } = ctx.args
return ddb.get({ key: { id } })
}
/**
* Returns the result
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
const { error, result } = ctx
if (error) {
return util.appendError(error.message, error.type, result)
}
return ctx.result
}
```
En cas d'erreur lors de la requête, le gestionnaire de réponse de la fonction ajoute une erreur qui sera renvoyée au client appelant dans la réponse GraphQL. Ajoutez la `GET_ITEM` fonction à la liste des fonctions de votre résolveur. Lorsque vous exécutez la requête, le gestionnaire de requêtes de la `GET_ITEM` fonction utilise les utilitaires fournis par le module AWS AppSync DynamoDB pour créer une `DynamoDBGetItem` demande en utilisant la clé. `id` `ddb.get({ key: { id } })`génère l'`GetItem`opération appropriée :
```
{
"operation" : "GetItem",
"key" : {
"id" : { "S" : "1" }
}
}
```
AWS AppSync utilise la demande pour récupérer les données depuis Amazon DynamoDB. Une fois les données renvoyées, elles sont gérées par le gestionnaire de réponses de la `GET_ITEM` fonction, qui vérifie les erreurs puis renvoie le résultat.
```
{
"result" : {
"id": 1,
"title": "hello world",
"content": ""
}
}
```
Enfin, le gestionnaire de réponses du résolveur renvoie directement le résultat.
## Travailler avec des erreurs
Si une erreur se produit dans votre fonction lors d'une demande, elle sera disponible dans le gestionnaire de réponse de votre fonction dans`ctx.error`. Vous pouvez ajouter l'erreur à votre réponse GraphQL à l'aide `util.appendError` de l'utilitaire. Vous pouvez rendre l'erreur accessible aux autres fonctions du pipeline en utilisant le stash. Consultez l'exemple ci-dessous :
```
/**
* Returns the result
* @param ctx the context object holds contextual information about the function invocation.
*/
export function response(ctx) {
const { error, result } = ctx;
if (error) {
if (!ctx.stash.errors) ctx.stash.errors = []
ctx.stash.errors.push(ctx.error)
return util.appendError(error.message, error.type, result);
}
return ctx.result;
}
```
# Configuration des utilitaires pour l'`APPSYNC_JS`environnement d'exécution
AWS AppSync fournit deux bibliothèques qui facilitent le développement de résolveurs avec le `APPSYNC_JS` moteur d'exécution :
+ `@aws-appsync/eslint-plugin`- Détecte et corrige les problèmes rapidement pendant le développement.
+ `@aws-appsync/utils`- Fournit la validation de type et l'autocomplétion dans les éditeurs de code.
## Configuration du plugin eslint
[ESLint](https://eslint.org/)est un outil qui analyse statiquement votre code pour détecter rapidement les problèmes. Vous pouvez l'exécuter dans ESLint le cadre de votre pipeline d'intégration continue. `@aws-appsync/eslint-plugin`est un ESLint plugin qui détecte une syntaxe non valide dans votre code lorsque vous utilisez le `APPSYNC_JS` runtime. Le plugin vous permet d'obtenir rapidement des commentaires sur votre code pendant le développement sans avoir à transférer vos modifications dans le cloud.
`@aws-appsync/eslint-plugin`fournit deux ensembles de règles que vous pouvez utiliser pendant le développement.
**« plugin : @aws -appsync/base »** configure un ensemble de règles de base que vous pouvez utiliser dans votre projet :
| Règle | Description |
| --- | --- |
| non asynchrone | Les processus et les promesses asynchrones ne sont pas pris en charge. |
| sans attente | Les processus et les promesses asynchrones ne sont pas pris en charge. |
| pas de cours | Les cours ne sont pas pris en charge. |
| sans pour | forn'est pas pris en charge (sauf pour for-in etfor-of, qui sont pris en charge) |
| sans continuer | continue n’est pas pris en charge. |
| pas de générateurs | Les générateurs ne sont pas pris en charge. |
| aucun rendement | yield n’est pas pris en charge. |
| sans étiquettes | Les étiquettes ne sont pas prises en charge. |
| non, ça | thisle mot clé n'est pas pris en charge. |
| pas d'essai | La structure Try/Catch n'est pas prise en charge. |
| sans délai | Alors que les boucles ne sont pas prises en charge. |
| no-disallowed-unary-operators | \$1\$1--, et les opérateurs \$1 unaires ne sont pas autorisés. |
| no-disallowed-binary-operators | L'instanceofopérateur n'est pas autorisé. |
| sans promesse | Les processus et les promesses asynchrones ne sont pas pris en charge. |
**« plugin : @aws -appsync/recommended »** fournit des règles supplémentaires mais vous oblige également à ajouter des TypeScript configurations à votre projet.
| Règle | Description |
| --- | --- |
| aucune récursion | Les appels de fonction récursifs ne sont pas autorisés. |
| no-disallowed-methods | Certaines méthodes ne sont pas autorisées. Consultez la [référence](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html) pour un ensemble complet de fonctions intégrées prises en charge. |
| no-function-passing | Il n'est pas permis de transmettre des fonctions en tant qu'arguments à des fonctions. |
| no-function-reassign | Les fonctions ne peuvent pas être réattribuées. |
| no-function-return | Les fonctions ne peuvent pas être la valeur de retour des fonctions. |
Pour ajouter le plugin à votre projet, suivez les étapes d'installation et d'utilisation décrites dans [Getting Started with ESLint](https://eslint.org/docs/latest/user-guide/getting-started#installation-and-usage). Ensuite, installez le [plugin](https://www.npmjs.com/package/@aws-appsync/eslint-plugin) dans votre projet à l'aide de votre gestionnaire de packages de projet (par exemple, npm, yarn ou pnpm) :
```
$ npm install @aws-appsync/eslint-plugin
```
Dans votre `.eslintrc.{js,yml,json}` fichier, ajoutez **« plugin : @aws -appsync/base »** ou **« plugin : @aws -appsync/recommended** » à la propriété. `extends` L'extrait ci-dessous est un exemple de `.eslintrc` configuration de base pour : JavaScript
```
{
"extends": ["plugin:@aws-appsync/base"]
}
```
Pour utiliser l'ensemble de règles **« plugin : @aws -appsync/recommended »**, installez la dépendance requise :
```
$ npm install -D @typescript-eslint/parser
```
Créez ensuite un `.eslintrc.js` fichier :
```
{
"parser": "@typescript-eslint/parser",
"parserOptions": {
"ecmaVersion": 2018,
"project": "./tsconfig.json"
},
"extends": ["plugin:@aws-appsync/recommended"]
}
```
# Regroupement et sources TypeScript de cartes pour l'environnement d'exécution `APPSYNC_JS`
TypeScript améliore AWS AppSync le développement en garantissant la sécurité des types et la détection précoce des erreurs. Vous pouvez écrire TypeScript du code localement et le transpiler JavaScript avant de l'utiliser avec le `APPSYNC_JS` moteur d'exécution. Le processus commence par l'installation TypeScript et la configuration de tsconfig.json pour l'environnement. `APPSYNC_JS` Vous pouvez ensuite utiliser des outils de regroupement tels que esbuild pour compiler et regrouper le code. La CLI Amplify générera des types à partir du schéma GraphQL, ce qui vous permettra d'utiliser ces types dans le code du résolveur.
Vous pouvez utiliser des bibliothèques personnalisées et externes dans votre résolveur et votre code de fonction, à condition qu'elles soient conformes aux `APPSYNC_JS` exigences. Les outils de regroupement combinent le code dans un seul fichier à utiliser dans AWS AppSync. Des cartes sources peuvent être incluses pour faciliter le débogage.
## Tirer parti des bibliothèques et regrouper votre code
Dans votre résolveur et votre code de fonction, vous pouvez tirer parti des bibliothèques personnalisées et externes à condition qu'elles soient conformes aux `APPSYNC_JS` exigences. Cela permet de réutiliser le code existant dans votre application. Pour utiliser des bibliothèques définies par plusieurs fichiers, vous devez utiliser un outil de regroupement, tel que [esbuild](https://esbuild.github.io/), pour combiner votre code dans un seul fichier qui peut ensuite être enregistré dans votre AWS AppSync résolveur ou votre fonction.
Lorsque vous regroupez votre code, gardez les points suivants à l'esprit :
+ `APPSYNC_JS`supporte uniquement les ECMAScript modules (ESM).
+ `@aws-appsync/*`les modules sont intégrés dans votre code `APPSYNC_JS` et ne doivent pas être fournis avec celui-ci.
+ L'environnement `APPSYNC_JS` d'exécution est similaire à NodeJS dans la mesure où le code ne s'exécute pas dans un environnement de navigateur.
+ Vous pouvez inclure une carte source facultative. Cependant, n'incluez pas le contenu source.
Pour en savoir plus sur les cartes sources, reportez-vous à la section [Utilisation des cartes sources](#source-maps).
Par exemple, pour regrouper le code de votre résolveur situé à l'adresse`src/appsync/getPost.resolver.js`, vous pouvez utiliser la commande ESbuild CLI suivante :
```
$ esbuild --bundle \
--sourcemap=inline \
--sources-content=false \
--target=esnext \
--platform=node \
--format=esm \
--external:@aws-appsync/utils \
--outdir=out/appsync \
src/appsync/getPost.resolver.js
```
## Création de votre code et utilisation de TypeScript
[TypeScript](https://www.typescriptlang.org/)est un langage de programmation développé par Microsoft qui offre toutes JavaScript les fonctionnalités ainsi que le système de TypeScript saisie. Vous pouvez l'utiliser TypeScript pour écrire du code sécurisé et détecter les erreurs et les bogues au moment de la compilation avant d'enregistrer votre code dans. AWS AppSync Le `@aws-appsync/utils` package est entièrement dactylographié.
Le `APPSYNC_JS` moteur d'exécution ne prend pas TypeScript directement en charge. Vous devez d'abord transpiler votre TypeScript code en JavaScript code compatible avec le `APPSYNC_JS` moteur d'exécution avant de l'enregistrer. AWS AppSync Vous pouvez l'utiliser TypeScript pour écrire votre code dans votre environnement de développement intégré (IDE) local, mais notez que vous ne pouvez pas créer de TypeScript code dans la AWS AppSync console.
Pour commencer, assurez-vous que vous l'avez [TypeScript](https://www.typescriptlang.org/download)installé dans votre projet. Configurez ensuite vos paramètres de TypeScript transcompilation pour qu'ils fonctionnent avec le `APPSYNC_JS` moteur d'exécution à l'aide [TSConfig](https://www.typescriptlang.org/tsconfig)de. Voici un exemple de `tsconfig.json` fichier de base que vous pouvez utiliser :
```
// tsconfig.json
{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"noEmit": true,
"moduleResolution": "node",
}
}
```
Vous pouvez ensuite utiliser un outil de regroupement comme esbuild pour compiler et regrouper votre code. Par exemple, si votre AWS AppSync code se trouve dans un projet`src/appsync`, vous pouvez utiliser la commande suivante pour compiler et regrouper votre code :
```
$ esbuild --bundle \
--sourcemap=inline \
--sources-content=false \
--target=esnext \
--platform=node \
--format=esm \
--external:@aws-appsync/utils \
--outdir=out/appsync \
src/appsync/**/*.ts
```
### Utilisation du codegen Amplify
Vous pouvez utiliser la [CLI Amplify](https://docs.amplify.aws/cli/) pour générer les types de votre schéma. Dans le répertoire où se trouve votre `schema.graphql` fichier, exécutez la commande suivante et passez en revue les instructions pour configurer votre codegen :
```
$ npx @aws-amplify/cli codegen add
```
Pour régénérer votre codegen dans certaines circonstances (par exemple, lorsque votre schéma est mis à jour), exécutez la commande suivante :
```
$ npx @aws-amplify/cli codegen
```
Vous pouvez ensuite utiliser les types générés dans le code de votre résolveur. Par exemple, selon le schéma suivant :
```
type Todo {
id: ID!
title: String!
description: String
}
type Mutation {
createTodo(title: String!, description: String): Todo
}
type Query {
listTodos: Todo
}
```
Vous pouvez utiliser les types générés dans l'exemple de AWS AppSync fonction suivant :
```
import { Context, util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'
import { CreateTodoMutationVariables, Todo } from './API' // codegen
export function request(ctx: Context) {
ctx.args.description = ctx.args.description ?? 'created on ' + util.time.nowISO8601()
return ddb.put({ key: { id: util.autoId() }, item: ctx.args })
}
export function response(ctx) {
return ctx.result as Todo
}
```
### Utilisation de génériques dans TypeScript
Vous pouvez utiliser des génériques avec plusieurs des types fournis. Par exemple, l'extrait ci-dessous est un `Todo` type :
```
export type Todo = {
__typename: "Todo",
id: string,
title: string,
description?: string | null,
};
```
Vous pouvez écrire un résolveur pour un abonnement qui utilise. `Todo` Dans votre IDE, les définitions de type et les conseils de saisie automatique vous aideront à utiliser correctement l'utilitaire de `toSubscriptionFilter` transformation :
```
import { util, Context, extensions } from '@aws-appsync/utils'
import { Todo } from './API'
export function request(ctx: Context) {
return {}
}
export function response(ctx: Context) {
const filter = util.transform.toSubscriptionFilter({
title: { beginsWith: 'hello' },
description: { contains: 'created' },
})
extensions.setSubscriptionFilter(filter)
return null
}
```
## Linting vos paquets
Vous pouvez automatiquement pelucher vos bundles en important le `esbuild-plugin-eslint` plugin. Vous pouvez ensuite l'activer en fournissant une `plugins` valeur qui active les fonctionnalités eslint. Vous trouverez ci-dessous un extrait qui utilise l' JavaScript API esbuild dans un fichier appelé : `build.mjs`
```
/* eslint-disable */
import { build } from 'esbuild'
import eslint from 'esbuild-plugin-eslint'
import glob from 'glob'
const files = await glob('src/**/*.ts')
await build({
format: 'esm',
target: 'esnext',
platform: 'node',
external: ['@aws-appsync/utils'],
outdir: 'dist/',
entryPoints: files,
bundle: true,
plugins: [eslint({ useEslintrc: true })],
})
```
## Utilisation de cartes sources
Vous pouvez fournir une carte source en ligne (`sourcemap`) avec votre JavaScript code. Les cartes sources sont utiles lorsque vous regroupez JavaScript ou TypeScript codez et que vous souhaitez voir des références à vos fichiers source d'entrée dans vos journaux et dans vos messages d' JavaScript erreur d'exécution.
Vous `sourcemap` devez apparaître à la fin de votre code. Il est défini par une seule ligne de commentaire qui suit le format suivant :
```
//# sourceMappingURL=data:application/json;base64,
```
Voici un exemple :
```
//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsibGliLmpzIiwgImNvZGUuanMiXSwKICAibWFwcGluZ3MiOiAiO0FBQU8sU0FBUyxRQUFRO0FBQ3RCLFNBQU87QUFDVDs7O0FDRE8sU0FBUyxRQUFRLEtBQUs7QUFDM0IsU0FBTyxNQUFNO0FBQ2Y7IiwKICAibmFtZXMiOiBbXQp9Cg==
```
Les cartes sources peuvent être créées avec esbuild. L'exemple ci-dessous vous montre comment utiliser l' JavaScriptAPI esbuild pour inclure une carte source en ligne lors de la création et du regroupement du code :
```
/* eslint-disable */
import { build } from 'esbuild'
import eslint from 'esbuild-plugin-eslint'
import glob from 'glob'
const files = await glob('src/**/*.ts')
await build({
sourcemap: 'inline',
sourcesContent: false,
format: 'esm',
target: 'esnext',
platform: 'node',
external: ['@aws-appsync/utils'],
outdir: 'dist/',
entryPoints: files,
bundle: true,
plugins: [eslint({ useEslintrc: true })],
})
```
En particulier, les `sourcesContent` options `sourcemap` et spécifient qu'une carte source doit être ajoutée en ligne à la fin de chaque build, mais ne doit pas inclure le contenu source. Par convention, nous vous recommandons de ne pas inclure de contenu source dans votre`sourcemap`. Vous pouvez le désactiver dans esbuild en réglant `sources-content` sur`false`.
Pour illustrer le fonctionnement des cartes sources, consultez l'exemple suivant dans lequel un code de résolution fait référence à des fonctions d'assistance d'une bibliothèque d'assistance. Le code contient des instructions de journal dans le code du résolveur et dans la bibliothèque d'assistance :
**. /src/default.resolver.ts** (votre résolveur)
```
import { Context } from '@aws-appsync/utils'
import { hello, logit } from './helper'
export function request(ctx: Context) {
console.log('start >')
logit('hello world', 42, true)
console.log('< end')
return 'test'
}
export function response(ctx: Context): boolean {
hello()
return ctx.prev.result
}
```
**.src/helper.ts** (un fichier d'assistance)
```
export const logit = (...rest: any[]) => {
// a special logger
console.log('[logger]', ...rest.map((r) => `<${r}>`))
}
export const hello = () => {
// This just returns a simple sentence, but it could do more.
console.log('i just say hello..')
}
```
Lorsque vous créez et regroupez le fichier de résolution, votre code de résolution inclut une carte source intégrée. Lorsque votre résolveur s'exécute, les entrées suivantes apparaissent dans les CloudWatch journaux :
![\[CloudWatch log entries showing resolver code execution with inline source map information.\]](http://docs.aws.amazon.com/fr_fr/appsync/latest/devguide/images/cloudwatch-sourcemap.jpeg)
En regardant les entrées du CloudWatch journal, vous remarquerez que les fonctionnalités des deux fichiers ont été regroupées et s'exécutent simultanément. Le nom de fichier d'origine de chaque fichier est également clairement reflété dans les journaux.
# Tester votre résolveur et vos gestionnaires de fonctions dans AWS AppSync
Vous pouvez utiliser la commande `EvaluateCode` API pour tester à distance votre résolveur et vos gestionnaires de fonctions avec des données simulées avant d'enregistrer votre code dans un résolveur ou une fonction. Pour commencer à utiliser la commande, assurez-vous d'avoir ajouté l'`appsync:evaluatecode`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 à l'aide de la [AWS CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/index.html) ou [AWS SDKs](https://aws.amazon.com/tools/). Par exemple, pour tester votre code à l'aide de la CLI, il vous suffit de pointer sur votre fichier, de fournir un contexte et de spécifier le gestionnaire que vous souhaitez évaluer :
```
aws appsync evaluate-code \
--code file://code.js \
--function request \
--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": "{\"operation\":\"PutItem\",\"key\":{\"id\":{\"S\":\"record-id\"}},\"attributeValues\":{\"owner\":{\"S\":\"John doe\"},\"expectedVersion\":{\"N\":2},\"authorId\":{\"S\":\"Sammy Davis\"}}}",
"logs": [
"INFO - code.js:5:3: \"current id\" \"record-id\"",
"INFO - code.js:9:3: \"request evaluated\""
]
}
```
Le résultat de l'évaluation peut être analysé au format JSON, ce qui donne :
```
{
"operation": "PutItem",
"key": {
"id": {
"S": "record-id"
}
},
"attributeValues": {
"owner": {
"S": "John doe"
},
"expectedVersion": {
"N": 2
},
"authorId": {
"S": "Sammy Davis"
}
}
}
```
À l'aide du SDK, vous pouvez facilement intégrer des tests issus de votre suite de tests pour valider le comportement de votre code. Notre exemple ici utilise le [Jest Testing Framework](https://jestjs.io/), mais n'importe quelle suite de tests fonctionne. 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
```
# Migration de VTL vers in JavaScript AWS AppSync
AWS AppSync vous permet d'écrire votre logique métier pour vos résolveurs et fonctions à l'aide de VTL ou. JavaScript Dans les deux langages, vous rédigez une logique qui indique au AWS AppSync service comment interagir avec vos sources de données. Avec VTL, vous écrivez des modèles de mappage qui doivent être évalués en une chaîne codée en JSON valide. Avec JavaScript, vous écrivez des gestionnaires de requêtes et de réponses qui renvoient des objets. Vous ne renvoyez pas de chaîne codée en JSON.
Par exemple, utilisez le modèle de mappage VTL suivant pour obtenir un élément Amazon DynamoDB :
```
{
"operation": "GetItem",
"key": {
"id": $util.dynamodb.toDynamoDBJson($ctx.args.id),
}
}
```
L'utilitaire `$util.dynamodb.toDynamoDBJson` renvoie une chaîne codée en JSON. S'il `$ctx.args.id` est défini sur``, le modèle est évalué en une chaîne codée en JSON valide :
```
{
"operation": "GetItem",
"key": {
"id": {"S": ""},
}
}
```
Lorsque vous travaillez avec JavaScript, vous n'avez pas besoin d'imprimer des chaînes brutes codées en JSON dans votre code, et l'utilisation d'un utilitaire de ce type n'`toDynamoDBJson`est pas nécessaire. Voici un exemple équivalent du modèle de mappage ci-dessus :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
operation: 'GetItem',
key: {id: util.dynamodb.toDynamoDB(ctx.args.id)}
};
}
```
Une alternative consiste à utiliser `util.dynamodb.toMapValues` l'approche recommandée pour gérer un objet de valeurs :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
return {
operation: 'GetItem',
key: util.dynamodb.toMapValues({ id: ctx.args.id }),
};
}
```
Cela permet d'évaluer :
```
{
"operation": "GetItem",
"key": {
"id": {
"S": ""
}
}
}
```
**Note**
Nous recommandons d'utiliser le module DynamoDB avec les sources de données DynamoDB :
```
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
ddb.get({ key: { id: ctx.args.id } })
}
```
Autre exemple, prenez le modèle de mappage suivant pour placer un élément dans une source de données Amazon DynamoDB :
```
{
"operation" : "PutItem",
"key" : {
"id": $util.dynamodb.toDynamoDBJson($util.autoId()),
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
Lors de son évaluation, cette chaîne de modèle de mappage doit produire une chaîne codée en JSON valide. Lors de l'utilisation JavaScript, votre code renvoie directement l'objet de la requête :
```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
const { id = util.autoId(), ...values } = ctx.args;
return {
operation: 'PutItem',
key: util.dynamodb.toMapValues({ id }),
attributeValues: util.dynamodb.toMapValues(values),
};
}
```
qui évalue à :
```
{
"operation": "PutItem",
"key": {
"id": { "S": "2bff3f05-ff8c-4ed8-92b4-767e29fc4e63" }
},
"attributeValues": {
"firstname": { "S": "Shaggy" },
"age": { "N": 4 }
}
}
```
**Note**
Nous recommandons d'utiliser le module DynamoDB avec les sources de données DynamoDB :
```
import { util } from '@aws-appsync/utils'
import * as ddb from '@aws-appsync/utils/dynamodb'
export function request(ctx) {
const { id = util.autoId(), ...item } = ctx.args
return ddb.put({ key: { id }, item })
}
```
# Choisir entre un accès direct à une source de données ou un proxy via une source de données Lambda
Grâce à AWS AppSync l'`APPSYNC_JS`environnement d'exécution, vous pouvez écrire votre propre code qui implémente votre logique métier personnalisée en utilisant des AWS AppSync fonctions pour accéder à vos sources de données. Cela vous permet d'interagir directement avec des sources de données telles qu'Amazon DynamoDB, Aurora OpenSearch Serverless, Service APIs, HTTP AWS et d'autres services sans avoir à déployer de services ou d'infrastructures informatiques supplémentaires. AWS AppSync facilite également l'interaction avec une AWS Lambda fonction en configurant une source de données Lambda. Les sources de données Lambda vous permettent d'exécuter une logique métier complexe en utilisant l'ensemble complet des fonctionnalités AWS Lambda de résolution d'une requête GraphQL. Dans la plupart des cas, une AWS AppSync fonction directement connectée à sa source de données cible fournira toutes les fonctionnalités dont vous avez besoin. Dans les situations où vous devez implémenter une logique métier complexe qui n'est pas prise en charge par l'`APPSYNC_JS`environnement d'exécution, vous pouvez utiliser une source de données Lambda comme proxy pour interagir avec votre source de données cible.
| | | |
| --- |--- |--- |
| | Intégration directe des sources de données | Source de données Lambda en tant que proxy |
| Cas d'utilisation | AWS AppSync les fonctions interagissent directement avec les sources de données de l'API. | AWS AppSync les fonctions appelées Lambdas interagissent avec les sources de données de l'API. |
| Environnement d’exécution | APPSYNC\$1JS (JavaScript) | Tout environnement d'exécution Lambda pris en charge |
| Taille maximale du code | 32 000 caractères par fonction AWS AppSync | 50 Mo (compressés, pour le téléchargement direct) par Lambda |
| Modules externes | Limité - Fonctionnalités prises en charge par APPSYNC\$1JS uniquement | Oui |
| Appelez n'importe quel AWS service | Oui - Utilisation d'une source de données AWS AppSync HTTP | Oui - Utilisation du AWS SDK |
| Accès à l'en-tête de la demande | Oui | Oui |
| Accès réseau | Non | Oui |
| Accès au système de fichiers | Non | Oui |
| Journalisation et statistiques | Oui | Oui |
| Construisez et testez entièrement dans AppSync | Oui | Non |
| Démarrage à froid | Non | Non - Avec une simultanéité provisionnée |
| Scalabilité automatique | Oui, de manière transparente par AWS AppSync | Oui, tel que configuré dans Lambda |
| Tarification | Sans frais supplémentaires | Facturé pour l'utilisation de Lambda |
AWS AppSync les fonctions qui s'intègrent directement à leur source de données cible sont idéales pour les cas d'utilisation suivants :
+ Interaction avec Amazon DynamoDB, Aurora Serverless et Service OpenSearch
+ Interaction avec le protocole HTTP APIs et transmission des en-têtes entrants
+ Interaction avec AWS les services à l'aide de sources de données HTTP (avec signature AWS AppSync automatique des demandes avec le rôle de source de données fourni)
+ Mise en œuvre du contrôle d'accès avant d'accéder aux sources de données
+ Implémentation du filtrage des données récupérées avant de répondre à une demande
+ Implémentation d'une orchestration simple avec exécution séquentielle de AWS AppSync fonctions dans un pipeline de résolution
+ Contrôle des connexions de mise en cache et d'abonnement dans les requêtes et les mutations.
AWS AppSync les fonctions qui utilisent une source de données Lambda comme proxy sont idéales pour les cas d'utilisation suivants :
+ Utilisation d'un langage autre que JavaScript le langage VTL (Velocity Template Language)
+ Réglage et contrôle du processeur ou de la mémoire pour optimiser les performances
+ Importation de bibliothèques tierces ou demande de fonctionnalités non prises en charge dans `APPSYNC_JS`
+ Effectuer plusieurs demandes réseau and/or pour obtenir l'accès au système de fichiers pour répondre à une requête
+ Requêtes par lots à l'aide de la [configuration par lots.](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-lambda-js.html)