Configuration en un clic Configuration manuelle Tester votre GraphQL API

Utilisation de résolveurs de pipeline dans AWS AppSync

Note

Nous prenons désormais principalement en charge le runtime APPSYNC _JS et sa documentation. Pensez à utiliser le runtime APPSYNC _JS et ses guides ici.

AWS AppSync fournit un moyen simple de connecter un champ GraphQL à une source de données unique via des résolveurs unitaires. Toutefois, l'exécution d'une seule opération peut ne pas être suffisante. Les résolveurs de pipeline offrent la possibilité d'exécuter des opérations en série sur des sources de données. Créez des fonctions dans votre API et associez-les à un résolveur de pipeline. L'exécution de chaque fonction est acheminée jusqu'à l'autre, jusqu'à ce qu'il ne reste plus aucune fonction à exécuter. Avec les résolveurs de pipeline, vous pouvez désormais créer des flux de travail plus complexes directement dans le AWS AppSync pipeline. Dans ce didacticiel, vous construisez une application simple d'affichage de photos, dans laquelle les utilisateurs peuvent publier et visualiser les images publiées par leurs amis.

Configuration en un clic

Si vous souhaitez configurer automatiquement le point de terminaison GraphQL AWS AppSync avec tous les résolveurs configurés et les AWS ressources nécessaires, vous pouvez utiliser le modèle suivant : AWS CloudFormation

Cette pile crée les ressources suivantes dans votre compte :

IAMRôle AWS AppSync pour accéder aux ressources de votre compte
2 tables DynamoDB
1 groupe d'utilisateurs Amazon Cognito
2 groupes d'utilisateurs Amazon Cognito
3 utilisateurs de groupes d'utilisateurs Amazon Cognito
1 AWS AppSync API

À la fin du processus de création de la AWS CloudFormation pile, vous recevez un e-mail pour chacun des trois utilisateurs Amazon Cognito créés. Chaque e-mail contient un mot de passe temporaire que vous utilisez pour vous connecter à la console en tant qu'utilisateur Amazon Cognito. AWS AppSync Enregistrez les mots de passe pour le rappel du didacticiel.

Configuration manuelle

Si vous préférez exécuter manuellement un step-by-step processus via la AWS AppSync console, suivez le processus de configuration ci-dessous.

Configuration de vos AWS AppSync ressources non liées

Il API communique avec deux tables DynamoDB : une table d'images qui stocke des images et une table d'amis qui stocke les relations entre les utilisateurs. APIIl est configuré pour utiliser le groupe d'utilisateurs Amazon Cognito comme type d'authentification. La AWS CloudFormation pile suivante configure ces ressources dans le compte.

Création de votre GraphQL API

Pour créer le GraphQL API dans : AWS AppSync

Ouvrez la AWS AppSync console, choisissez Build From Scratch, puis Start.
Définissez le nom du API àAppSyncTutorial-PicturesViewer.
Sélectionnez Create (Créer).

La AWS AppSync console crée un nouveau GraphQL API pour vous en utilisant le mode d'authentification par API clé. Vous pouvez utiliser la console pour configurer le reste de GraphQL API et exécuter des requêtes sur celui-ci pour le reste de ce didacticiel.

Configuration du GraphQL API

Vous devez le configurer AWS AppSync API avec le groupe d'utilisateurs Amazon Cognito que vous venez de créer.

Sélectionnez l'onglet Settings.
Dans la section Authorization Type (Type d'autorisation), choisissez Amazon Cognito User Pool (Groupe d'utilisateurs Amazon Cognito).
Sous Configuration du groupe d'utilisateurs, choisissez US- WEST -2 pour la AWS région.
Choisissez le groupe UserPool d'utilisateurs AppSyncTutorial-.
Choisissez DENYcomme action par défaut.
Laissez le champ Regex du AppId client vide.
Choisissez Save (Enregistrer).

Le API est désormais configuré pour utiliser le groupe d'utilisateurs Amazon Cognito comme type d'autorisation.

Configuration des sources de données pour les tables DynamoDB

Une fois les tables DynamoDB créées, accédez à votre AWS AppSync API GraphQL dans la console et choisissez l'onglet Sources de données. Vous allez maintenant créer une source de données AWS AppSync pour chacune des tables DynamoDB que vous venez de créer.

Choisissez l'onglet Source de données.
Choisissez New (Nouveau) pour créer une nouvelle source de données.
Pour le nom de la source de données, saisissez PicturesDynamoDBTable.
Pour le type de source de données, choisissez Table Amazon DynamoDB.
Pour la région, choisissez US- WEST -2.
Dans la liste des tables, choisissez la table AppSyncTutorial-Pictures DynamoDB.
Dans la section Créer ou utiliser un rôle existant, choisissez Rôle existant.
Choisissez le rôle qui vient d'être créé à partir du CloudFormation modèle. Si vous n'avez pas modifié le ResourceNamePrefix, le nom du rôle doit être AppSyncTutorial-D. ynamoDBRole
Sélectionnez Create (Créer).

Répétez le même processus pour la table des amis. Le nom de la table DynamoDB doit AppSyncTutorialêtre -Friends si vous n'avez pas modifié ResourceNamePrefixle paramètre au moment de créer la pile. CloudFormation

Création du schéma GraphQL

Maintenant que les sources de données sont connectées à vos tables DynamoDB, créons un schéma GraphQL. Dans l'éditeur de schéma de la AWS AppSync console, assurez-vous que votre schéma correspond au schéma suivant :


schema {
    query: Query
    mutation: Mutation
}

type Mutation {
    createPicture(input: CreatePictureInput!): Picture!
    @aws_auth(cognito_groups: ["Admins"])
    createFriendship(id: ID!, target: ID!): Boolean
    @aws_auth(cognito_groups: ["Admins"])
}

type Query {
    getPicturesByOwner(id: ID!): [Picture]
    @aws_auth(cognito_groups: ["Admins", "Viewers"])
}

type Picture {
    id: ID!
    owner: ID!
    src: String
}

input CreatePictureInput {
    owner: ID!
    src: String!
}

Choisissez Save Schema (Enregistrer le schéma) pour enregistrer votre schéma.

Certains des champs de schéma ont été annotés avec la directive @aws_auth. La configuration d'action API par défaut étant définie sur DENY, tous les utilisateurs qui ne sont pas membres des groupes mentionnés dans la directive @aws_auth sont API rejetés. Pour plus d'informations sur la manière de sécuriser votreAPI, vous pouvez consulter la page Sécurité. Dans ce cas, seuls les utilisateurs administrateurs ont accès à la mutation. createPictureet Mutation. createFriendshipchamps, tandis que les utilisateurs membres des groupes d'administrateurs ou de spectateurs peuvent accéder à la requête. getPicturesByChamp du propriétaire. Tous les autres utilisateurs n'ont pas accès.

Configuration des résolveurs

Maintenant que vous avez un schéma GraphQL valide et deux sources de données, vous pouvez attacher des résolveurs aux champs GraphQL sur le schéma. APIIl offre les fonctionnalités suivantes :

Créez une image à l'aide de la mutation. createPicturechamp
Créez de l'amitié grâce à la mutation. createFriendshipchamp
Récupérez une photo via la requête. getPicturechamp

Mutation. createPicture

Dans l'éditeur de schéma de la AWS AppSync console, sur le côté droit, choisissez Attach Resolver forcreatePicture(input: CreatePictureInput!): Picture!. Choisissez la source de données PicturesDynamoDBTableDynamoDB. Dans la section request mapping template (modèle de mappage de requête), ajoutez le modèle suivant :


#set($id = $util.autoId())

{
    "version" : "2018-05-29",

    "operation" : "PutItem",

    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($id),
        "owner": $util.dynamodb.toDynamoDBJson($ctx.args.input.owner)
    },

    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args.input)
}

Dans la section response mapping template (modèle de mappage de réponse), ajoutez le modèle suivant :


#if($ctx.error)
    $util.error($ctx.error.message, $ctx.error.type)
#end
$util.toJson($ctx.result)

La fonctionnalité de création d'image est créée. Vous enregistrez une image dans le tableau Images, en utilisant un identifiant de l'image généré UUID aléatoirement et en utilisant le nom d'utilisateur Cognito en tant que propriétaire de l'image.

Mutation. createFriendship

Dans l'éditeur de schéma de la AWS AppSync console, sur le côté droit, choisissez Attach Resolver forcreateFriendship(id: ID!, target: ID!): Boolean. Choisissez la source de données FriendsDynamoDBTableDynamoDB. Dans la section request mapping template (modèle de mappage de requête), ajoutez le modèle suivant :


#set($userToFriendFriendship = { "userId" : "$ctx.args.id", "friendId": "$ctx.args.target" })
#set($friendToUserFriendship = { "userId" : "$ctx.args.target", "friendId": "$ctx.args.id" })
#set($friendsItems = [$util.dynamodb.toMapValues($userToFriendFriendship), $util.dynamodb.toMapValues($friendToUserFriendship)])

{
    "version" : "2018-05-29",
    "operation" : "BatchPutItem",
    "tables" : {
        ## Replace 'AppSyncTutorial-' default below with the ResourceNamePrefix you provided in the CloudFormation template
        "AppSyncTutorial-Friends": $util.toJson($friendsItems)
    }
}

Important : Dans le modèle de BatchPutItemdemande, le nom exact de la table DynamoDB doit figurer. Le nom de table par défaut est AppSyncTutorial-Friends. Si vous utilisez le mauvais nom de table, un message d'erreur s'affiche lorsque AppSync vous essayez d'assumer le rôle fourni.

Par souci de simplicité dans ce didacticiel, procédez comme si la demande d'amitié avait été approuvée et enregistrez l'entrée de relation directement dans le AppSyncTutorialFriendstableau.

En effet, vous stockez deux éléments pour chaque amitié car la relation est bidirectionnelle. Pour plus d'informations sur les meilleures pratiques d'Amazon DynamoDB en matière de many-to-many représentation des relations, consultez la section Meilleures pratiques DynamoDB.

Dans la section response mapping template (modèle de mappage de réponse), ajoutez le modèle suivant :


#if($ctx.error)
    $util.error($ctx.error.message, $ctx.error.type)
#end
true

Remarque : Assurez-vous que votre modèle de requête contient le bon nom de table. Le nom par défaut est AppSyncTutorial-Friends, mais le nom de votre table peut être différent si vous modifiez le CloudFormation ResourceNamePrefixparamètre.

Requête. getPicturesByPropriétaire

Maintenant que vous avez des relations d'amitié et des images, vous devez offrir aux utilisateurs la possibilité de voir les photos de leurs amis. Pour satisfaire à cette exigence, vous devez d'abord vérifier que le demandeur est ami avec le propriétaire, puis demander les images.

Cette fonctionnalité requiert deux opérations de source de données, vous allez donc créer deux fonctions. La première fonction vérifie si le demandeur et le propriétaire sont amis. isFriend La deuxième fonction, getPicturesByOwner, récupère les photos demandées à partir d'un identifiant de propriétaire. Examinons le flux d'exécution ci-dessous pour le résolveur proposé sur la requête. getPicturesByChamp du propriétaire :

Modèle de mappage Avant : préparer le contexte et les arguments d'entrée du champ.
isFriend fonction : Vérifie si le demandeur est le propriétaire de l'image. Dans le cas contraire, il vérifie si les utilisateurs demandeur et propriétaire sont amis en effectuant une opération GetItem DynamoDB sur la table des amis.
getPicturesByFonction propriétaire : récupère les images de la table Pictures à l'aide d'une opération de requête DynamoDB sur l'index secondaire global owner-index.
Modèle de mappage Après : mappe les résultats d'images pour que les attributs DynamoDB mappent correctement vers les champs de type GraphQL attendus.

Créez d'abord les fonctions.

isFriend Fonction

Choisissez l'onglet Functions (Fonctions).
Choisissez Create Function (Créer une fonction) pour créer une fonction.
Pour le nom de la source de données, saisissez FriendsDynamoDBTable.
Pour le nom de la fonction, saisissez isFriend.

Dans la zone de texte du modèle de mappage de requête, collez le modèle suivant :


#set($ownerId = $ctx.prev.result.owner)
#set($callerId = $ctx.prev.result.callerId)

## if the owner is the caller, no need to make the check
#if($ownerId == $callerId)
    #return($ctx.prev.result)
#end

{
    "version" : "2018-05-29",

    "operation" : "GetItem",

    "key" : {
        "userId" : $util.dynamodb.toDynamoDBJson($callerId),
        "friendId" : $util.dynamodb.toDynamoDBJson($ownerId)
    }
}

Dans la zone de texte du modèle de mappage de réponse, collez le modèle suivant :


#if($ctx.error)
    $util.error("Unable to retrieve friend mapping message: ${ctx.error.message}", $ctx.error.type)
#end

## if the users aren't friends
#if(!$ctx.result)
    $util.unauthorized()
#end

$util.toJson($ctx.prev.result)

Choisissez Create Function (Créer une fonction).

Résultat : vous avez créé la isFriendfonction.

getPicturesByFonction du propriétaire

Choisissez l'onglet Functions (Fonctions).
Choisissez Create Function (Créer une fonction) pour créer une fonction.
Pour le nom de la source de données, saisissez PicturesDynamoDBTable.
Pour le nom de la fonction, saisissez getPicturesByOwner.

Dans la zone de texte du modèle de mappage de requête, collez le modèle suivant :


{
    "version" : "2018-05-29",

    "operation" : "Query",

    "query" : {
        "expression": "#owner = :owner",
        "expressionNames": {
            "#owner" : "owner"
        },
        "expressionValues" : {
            ":owner" : $util.dynamodb.toDynamoDBJson($ctx.prev.result.owner)
        }
    },

    "index": "owner-index"
}

Dans la zone de texte du modèle de mappage de réponse, collez le modèle suivant :


#if($ctx.error)
    $util.error($ctx.error.message, $ctx.error.type)
#end

$util.toJson($ctx.result)

Choisissez Create Function (Créer une fonction).

Résultat : vous avez créé la fonction getPicturesByOwner. Maintenant que les fonctions ont été créées, attachez un résolveur de pipeline à la requête. getPicturesByChamp du propriétaire.

Dans l'éditeur de schéma de la AWS AppSync console, sur le côté droit, choisissez Attach Resolver forQuery.getPicturesByOwner(id: ID!): [Picture]. Sur la page suivante, choisissez le lien Convert to pipeline resolver (Convertir en résolveur de pipeline) qui s'affiche sous la source de données dans la liste déroulante. Utilisez ce qui suit pour le modèle de mappage Avant :


#set($result = { "owner": $ctx.args.id, "callerId": $ctx.identity.username })
$util.toJson($result)

Dans la section after mapping template (modèle de mappage après), utilisez ce qui suit :


#foreach($picture in $ctx.result.items)
    ## prepend "src://" to picture.src property
    #set($picture['src'] = "src://${picture['src']}")
#end
$util.toJson($ctx.result.items)

Choisissez Create Resolver (Créer un résolveur). Vous avez réussi à joindre votre première résolveur de pipeline. Sur la même page, ajoutez les deux fonctions que vous avez précédemment créées. Dans la section des fonctions, choisissez Ajouter une fonction, puis choisissez ou tapez le nom de la première fonction, isFriend. Ajoutez la deuxième fonction en suivant le même processus pour la fonction getPicturesByOwner. Assurez-vous que la isFriendfonction apparaît en premier dans la liste, suivie de la fonction getPicturesByPropriétaire. Vous pouvez utiliser les flèches vers le haut et vers le bas pour réorganiser l'ordre d'exécution des fonctions dans le pipeline.

Maintenant que le résolveur de pipeline est créé et que vous avez attaché les fonctions, testons le API GraphQL nouvellement créé.

Tester votre GraphQL API

Tout d'abord, vous devez remplir les images et les relations d'amitié en exécutant quelques mutations à l'aide de l'utilisateur administrateur que vous avez créé. Sur le côté gauche de la AWS AppSync console, choisissez l'onglet Requêtes.

createPicture Mutation

Dans AWS AppSync la console, choisissez l'onglet Requêtes.
Choisissez Login With User Pools (Connexion avec les groupes d'utilisateur).
Dans le modal, entrez l'ID de client d'exemple Cognito créé par la CloudFormation pile (par exemple, 37solo6mmhh7k4v63cqdfgdg5d).
Entrez le nom d'utilisateur que vous avez passé en paramètre à la CloudFormation pile. La valeur par défaut est nadia.
Utilisez le mot de passe temporaire qui a été envoyé à l'e-mail que vous avez fourni en tant que paramètre à la CloudFormation pile (par exemple, UserPoolUserEmail).
Choisissez Login (Connexion). Vous devriez maintenant voir le bouton renommé Logout nadia, ou le nom d'utilisateur que vous avez choisi lors de la création de la CloudFormation pile (c'est-à-dire, UserPoolUsername).

Envoyons quelques createPicturemutations pour remplir le tableau des images. Exécutez la requête GraphQL suivante dans la console :


mutation {
  createPicture(input:{
    owner: "nadia"
    src: "nadia.jpg"
  }) {
    id
    owner
    src
  }
}

La réponse doit être similaire à ce qui suit :


{
  "data": {
    "createPicture": {
      "id": "c6fedbbe-57ad-4da3-860a-ffe8d039882a",
      "owner": "nadia",
      "src": "nadia.jpg"
    }
  }
}

Ajoutons quelques images de plus :


mutation {
  createPicture(input:{
    owner: "shaggy"
    src: "shaggy.jpg"
  }) {
    id
    owner
    src
  }
}


mutation {
  createPicture(input:{
    owner: "rex"
    src: "rex.jpg"
  }) {
    id
    owner
    src
  }
}

Vous avez ajouté trois images en utilisant nadia en tant qu'utilisateur administrateur.

createFriendship Mutation

Nous allons ajouter une entrée d'amitié. Exécutez les mutations suivantes dans la console.

Remarque : vous devez être connecté en tant qu'utilisateur administrateur (l'utilisateur administrateur par défaut est nadia).


mutation {
  createFriendship(id: "nadia", target: "shaggy")
}

La réponse doit être similaire à ce qui suit :


{
  "data": {
    "createFriendship": true
  }
}

nadia et shaggy sont amis. rex n'est ami avec personne.

getPicturesByRequête du propriétaire

Pour cette étape, connectez-vous en tant qu'utilisateur nadia à l'aide des groupes d'utilisateurs Cognito, en utilisant les informations d'identification définies au début de ce didacticiel. Comme nadia, extrayez les images détenues par shaggy.


query {
    getPicturesByOwner(id: "shaggy") {
        id
        owner
        src
    }
}

Comme nadia et shaggy sont amis, la requête devrait renvoyer l'image adéquate.


{
  "data": {
    "getPicturesByOwner": [
      {
        "id": "05a16fba-cc29-41ee-a8d5-4e791f4f1079",
        "owner": "shaggy",
        "src": "src://shaggy.jpg"
      }
    ]
  }
}

De même, si nadia essaie d'extraire ses propres images,elle réussira. Le résolveur de pipeline a été optimisé pour éviter d'exécuter l'isFriend GetItem opération dans ce cas. Essayez la requête suivante :


query {
    getPicturesByOwner(id: "nadia") {
        id
        owner
        src
    }
}

Si vous activez la journalisation sur votre API (dans le volet Paramètres), que vous définissez le niveau de débogage sur et que vous réexécutez la même requête, les journaux d'exécution du champ sont renvoyés. ALL En consultant les journaux, vous pouvez déterminer si la isFriendfonction est revenue tôt au stade du modèle de mappage des demandes :


{
  "errors": [],
  "mappingTemplateType": "Request Mapping",
  "path": "[getPicturesByOwner]",
  "resolverArn": "arn:aws:appsync:us-west-2:XXXX:apis/XXXX/types/Query/fields/getPicturesByOwner",
  "functionArn": "arn:aws:appsync:us-west-2:XXXX:apis/XXXX/functions/o2f42p2jrfdl3dw7s6xub2csdfs",
  "functionName": "isFriend",
  "earlyReturnedValue": {
    "owner": "nadia",
    "callerId": "nadia"
  },
  "context": {
    "arguments": {
      "id": "nadia"
    },
    "prev": {
      "result": {
        "owner": "nadia",
        "callerId": "nadia"
      }
    },
    "stash": {},
    "outErrors": []
  },
  "fieldInError": false
}

La earlyReturnedValueclé représente les données renvoyées par la directive #return.

Enfin, même si Rex est membre du Viewers Cognito UserPool Group, et parce que Rex n'est ami avec personne, il ne pourra accéder à aucune des photos détenues par Shaggy ou Nadia. Si vous vous connectez en tant que rex dans la console et exécutez la requête suivante :


query {
    getPicturesByOwner(id: "nadia") {
        id
        owner
        src
    }
}

Vous obtenez l'erreur de non autorisation suivante :


{
  "data": {
    "getPicturesByOwner": null
  },
  "errors": [
    {
      "path": [
        "getPicturesByOwner"
      ],
      "data": null,
      "errorType": "Unauthorized",
      "errorInfo": null,
      "locations": [
        {
          "line": 2,
          "column": 9,
          "sourceName": null
        }
      ],
      "message": "Not Authorized to access getPicturesByOwner on type Query"
    }
  ]
}

Vous avez réussi à mettre en place une autorisation complexe à l'aide de résolveurs de pipeline.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Utilisation des résolveurs sans serveur Aurora

Utilisation des opérations Delta Sync sur des sources de données versionnées