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.

Utilisation des résolveurs Amazon OpenSearch Service dans AWS AppSync

AWS AppSync prend en charge l'utilisation d'Amazon OpenSearch Service à partir de domaines que vous avez fournis sur votre propre AWS compte, à condition qu'ils n'existent pas dans unVPC. Une fois que vos domaines sont mis en service, vous pouvez vous y connecter à l'aide d'une source de données, puis vous pouvez configurer un résolveur dans le schéma afin d'effectuer des opérations GraphQL telles que des requêtes, des mutations et des abonnements. Ce didacticiel vous présente certains exemples courants.

Pour plus d'informations, consultez la référence du modèle de mappage du résolveur pour OpenSearch.

Configuration en un clic

Pour configurer automatiquement un point de terminaison GraphQL avec AWS AppSync Amazon OpenSearch Service configuré, vous pouvez utiliser ce AWS CloudFormation modèle :

Une fois le AWS CloudFormation déploiement terminé, vous pouvez passer directement à l'exécution de requêtes et de mutations GraphQL.

Création d'un nouveau domaine OpenSearch de service

Pour commencer à utiliser ce didacticiel, vous avez besoin d'un domaine OpenSearch de service existant. Si vous n'en avez pas, vous pouvez utiliser l'exemple suivant. Notez que la création d'un domaine de OpenSearch service peut prendre jusqu'à 15 minutes avant que vous puissiez passer à son intégration à une source de AWS AppSync données.

aws cloudformation create-stack --stack-name AppSyncOpenSearch \
--template-url https://s3.us-west-2.amazonaws.com/awsappsync/resources/elasticsearch/ESResolverCFTemplate.yaml \
--parameters ParameterKey=OSDomainName,ParameterValue=ddtestdomain ParameterKey=Tier,ParameterValue=development \
--capabilities CAPABILITY_NAMED_IAM

Vous pouvez lancer le AWS CloudFormation stack suivant dans la région USA West 2 (Oregon) sur votre AWS compte :

Configuration de la source de données pour le OpenSearch service

Une fois le domaine de OpenSearch service créé, accédez à votre AWS AppSync GraphQL API et choisissez l'onglet Sources de données. Choisissez Nouveau et entrez un nom convivial pour la source de données, tel que « oss ». Choisissez ensuite le OpenSearch domaine Amazon pour le type de source de données, choisissez la région appropriée et vous devriez voir votre domaine OpenSearch de service répertorié. Après l'avoir sélectionné, vous pouvez soit créer un nouveau rôle et AWS AppSync attribuer les autorisations appropriées au rôle, soit choisir un rôle existant, dont la politique intégrée est la suivante :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1234234",
            "Effect": "Allow",
            "Action": [
                "es:ESHttpDelete",
                "es:ESHttpHead",
                "es:ESHttpGet",
                "es:ESHttpPost",
                "es:ESHttpPut"
            ],
            "Resource": [
                "arn:aws:es:REGION:ACCOUNTNUMBER:domain/democluster/*"
            ]
        }
    ]
}

Vous devrez également établir une relation de confiance avec AWS AppSync pour ce rôle :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "appsync.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

En outre, le domaine de OpenSearch service possède sa propre politique d'accès que vous pouvez modifier via la console Amazon OpenSearch Service. Vous devrez ajouter une politique similaire à la suivante, avec les actions et les ressources appropriées pour le domaine OpenSearch de service. Notez que le rôle principal sera celui de la source de AppSync données. Si vous laissez la console le créer, vous le trouverez dans la IAM console.

{
    "Version": "2012-10-17",
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::ACCOUNTNUMBER:role/service-role/APPSYNC_DATASOURCE_ROLE"
        },
        "Action": [
            "es:ESHttpDelete",
            "es:ESHttpHead",
            "es:ESHttpGet",
            "es:ESHttpPost",
            "es:ESHttpPut"
        ],
        "Resource": "arn:aws:es:REGION:ACCOUNTNUMBER:domain/DOMAIN_NAME/*"
        }
    ]
}

Connexion d'un résolveur

Maintenant que la source de données est connectée à votre domaine de OpenSearch service, vous pouvez la connecter à votre schéma GraphQL à l'aide d'un résolveur, comme illustré dans l'exemple suivant :

 schema {
   query: Query
   mutation: Mutation
 }

 type Query {
   getPost(id: ID!): Post
   allPosts: [Post]
 }

 type Mutation {
   addPost(id: ID!, author: String, title: String, url: String, ups: Int, downs: Int, content: String): AWSJSON
 }

type Post {
  id: ID!
  author: String
  title: String
  url: String
  ups: Int
  downs: Int
  content: String
}
...

Notez qu'il y a un type Post défini par l'utilisateur avec un champ id. Dans les exemples suivants, nous supposons qu'il existe un processus (qui peut être automatisé) permettant de placer ce type dans votre domaine de OpenSearch service, qui correspondrait à une racine de chemin de/post/_doc, où se post trouve l'index. À partir de ce chemin racine, vous pouvez effectuer des recherches de documents individuels, des recherches par /id/post* caractères génériques ou des recherches multidocuments avec un chemin de. /post/_search Par exemple, si un autre type est appeléUser, vous pouvez indexer les documents sous un nouvel index appeléuser, puis effectuer des recherches avec un chemin de/user/_search.

Dans l'éditeur de schéma de la AWS AppSync console, modifiez le Posts schéma précédent pour inclure une searchPosts requête :

type Query {
  getPost(id: ID!): Post
  allPosts: [Post]
  searchPosts: [Post]
}

Enregistrez le schéma. Sur le côté droit, pour searchPosts, choisissez Attach resolver (Attacher un résolveur). Dans le menu Action, choisissez Update runtime, puis Unit Resolver (VTLuniquement). Choisissez ensuite votre source OpenSearch de données de service. Sous la section request mapping template (modèle de mappage de demande), sélectionnez dans la liste déroulante les Query posts (billets de requête) pour obtenir un modèle de base. Modifiez l'élément path en lui donnant la valeur /post/_search. Il devrait se présenter comme suit :

{
    "version":"2017-02-28",
    "operation":"GET",
    "path":"/post/_search",
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "from":0,
            "size":50
        }
    }
}

Cela suppose que le schéma précédent contient des documents indexés dans OpenSearch Service sous le post champ. Si vous structurez vos données différemment, vous devrez faire la mise à jour correspondante.

Dans la section du modèle de mappage des réponses, vous devez spécifier le _source filtre approprié si vous souhaitez récupérer les résultats des données d'une requête de OpenSearch service et les traduire vers GraphQL. Utilisez le modèle suivant :

[
    #foreach($entry in $context.result.hits.hits)
    #if( $velocityCount > 1 ) , #end
    $utils.toJson($entry.get("_source"))
    #end
]

Modification de vos recherches

Le modèle de mappage de demande précédent exécute une requête simple pour tous les enregistrements. Supposons que vous souhaitiez effectuer une recherche en fonction d'un auteur spécifique. Supposons également que vous vouliez que l'auteur soit un argument défini dans votre requête GraphQL. Dans l'éditeur de schéma de la AWS AppSync console, ajoutez une allPostsByAuthor requête :

type Query {
  getPost(id: ID!): Post
  allPosts: [Post]
  allPostsByAuthor(author: String!): [Post]
  searchPosts: [Post]
}

Choisissez maintenant Attach resolver et sélectionnez la source de données du OpenSearch service, mais utilisez l'exemple suivant dans le modèle de mappage des réponses :

{
    "version":"2017-02-28",
    "operation":"GET",
    "path":"/post/_search",
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "from":0,
            "size":50,
            "query":{
                "match" :{
                    "author": $util.toJson($context.arguments.author)
                }
            }
        }
    }
}

Notez que l'élément body est renseigné avec une requête terminologique concernant le champ author, qui est transmise à partir du client en tant qu'argument. Vous pouvez, le cas échéant, avoir certaines informations pré-renseignées, telles que le texte standard, ou encore utiliser d'autres utilitaires.

Si vous utilisez ce résolveur, renseignez la section response mapping template (modèle de mappage de réponse) avec les mêmes informations que dans l'exemple précédent.

Ajouter des données au OpenSearch service

Vous souhaiterez peut-être ajouter des données à votre domaine OpenSearch de service à la suite d'une mutation GraphQL. Il s'agit d'un puissant mécanisme de recherche, qui peut également avoir d'autres fonctions. Comme vous pouvez utiliser les abonnements GraphQL pour générer vos données en temps réel, il s'agit d'un mécanisme permettant d'informer les clients des mises à jour des données de votre OpenSearch domaine de service.

Retournez à la page Schéma de la AWS AppSync console et sélectionnez Attacher un résolveur pour la addPost() mutation. Sélectionnez à nouveau la source de données du OpenSearch service et utilisez le modèle de mappage des réponses suivant pour le Posts schéma :

{
    "version":"2017-02-28",
    "operation":"PUT",
    "path": $util.toJson("/post/_doc/$context.arguments.id"),
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "id": $util.toJson($context.arguments.id),
            "author": $util.toJson($context.arguments.author),
            "ups": $util.toJson($context.arguments.ups),
            "downs": $util.toJson($context.arguments.downs),
            "url": $util.toJson($context.arguments.url),
            "content": $util.toJson($context.arguments.content),
            "title": $util.toJson($context.arguments.title)
        }
    }
}

Comme auparavant, il s'agit d'un exemple de la façon dont vos données peuvent être structurées. Si vous avez des noms de champs ou des index différents, vous devez mettre à jour les éléments path et body en conséquence. Cet exemple montre également comment utiliser $context.arguments pour renseigner le modèle à partir de vos arguments de mutation GraphQL.

Avant de poursuivre, utilisez le modèle de mappage des réponses suivant, qui renverra le résultat de l'opération de mutation ou les informations d'erreur en sortie :

#if($context.error)
    $util.toJson($ctx.error)
#else
    $util.toJson($context.result)
#end

Récupération d'un document unique

Enfin, si vous souhaitez utiliser la getPost(id:ID) requête de votre schéma pour renvoyer un document individuel, recherchez cette requête dans l'éditeur de schéma de la AWS AppSync console et choisissez Attach resolver. Sélectionnez à nouveau la source de données du OpenSearch service et utilisez le modèle de mappage suivant :

{
    "version":"2017-02-28",
    "operation":"GET",
    "path": $util.toJson("post/_doc/$context.arguments.id"),
    "params":{
        "headers":{},
        "queryString":{},
        "body":{}
    }
}

Étant donné que l'élément path ci-dessus utilise l'argument id avec un corps vide, c'est un document unique qui est renvoyé. Cependant, vous devez utiliser le modèle de mappage de réponse suivant, car vous souhaitez renvoyer un seul élément et non une liste :

$utils.toJson($context.result.get("_source"))

Effectuer des requêtes et des mutations

Vous devriez maintenant être en mesure d'effectuer des opérations GraphQL sur votre domaine de OpenSearch service. Accédez à l'onglet Requêtes de la AWS AppSync console et ajoutez un nouvel enregistrement :

mutation addPost {
    addPost (
        id:"12345"
        author: "Fred"
        title: "My first book"
        content: "This will be fun to write!"
        url: "publisher website",
        ups: 100,
        downs:20 
       )
}

Vous verrez le résultat de la mutation sur la droite. De même, vous pouvez désormais exécuter une searchPosts requête sur votre domaine OpenSearch de service :

query searchPosts {
    searchPosts {
        id
        title
        author
        content
    }
}

Bonnes pratiques