Référence contextuelle du modèle de mappage du résolveur

AWS AppSyncdéfinit un ensemble de variables et de fonctions permettant d'utiliser des modèles de mappage de résolveurs. Cela facilite les opérations logiques sur les données avec GraphQL. Le présent document décrit ces fonctions et fournit des exemples d'utilisation des modèles.

Accès à la variable $context

La variable $context est un mappage qui contient toutes les informations contextuelles pour l'appel de votre résolveur. Elle présente la structure suivante :

{
   "arguments" : { ... },
   "source" : { ... },
   "result" : { ... },
   "identity" : { ... },
   "request" : { ... },
   "info": { ... }
}

Note

Si vous essayez d'accéder à une entrée de dictionnaire/de carte (telle qu'une entrée danscontext) à l'aide de sa clé pour récupérer la valeur, le Velocity Template Language (VTL) vous permet d'utiliser directement la notation<dictionary-element>.<key-name>. Toutefois, cela peut ne pas fonctionner dans tous les cas, notamment lorsque les noms des clés comprennent des caractères spéciaux (par exemple, un caractère de soulignement « _ »). Nous vous recommandons de toujours utiliser la notation <dictionary-element>.get("<key-name>").

Chaque champ dans le mappage $context est défini comme suit :

Champs de $context

arguments

Carte qui contient tous les arguments GraphQL pour ce champ.

identity

Objet qui contient des informations sur l’appelant. Pour en savoir plus sur la structure de ce champ, consultez Identité.

source

Carte contenant la résolution du champ parent.

stash

Le stash est une carte disponible dans chaque modèle de mappage de résolveur et de fonction. La même instance stash perdure pendant une exécution de résolveur. Cela signifie que vous pouvez utiliser le stash pour transmettre des données arbitraires sur des modèles de mappage de demande et de réponse, et sur des fonctions dans un résolveur de pipeline. Le stash expose les mêmes méthodes que la structure de données Java Map.

result

Un conteneur pour les résultats de ce résolveur. Ce champ est uniquement disponible pour les modèles de mappage des réponses.

Par exemple, si vous résolvez leauthor champ de la requête suivante :

query {
    getPost(id: 1234) {
        postId
        title
        content
        author {
            id
            name
        }
    }
}

Ensuite, la variable $context complète, disponible lors du traitement d'un modèle de mappage de réponse, peut être :

{
  "arguments" : {
    id: "1234"
  },
  "source": {},
  "result" : {
      "postId": "1234",
      "title": "Some title",
      "content": "Some content",
      "author": {
        "id": "5678",
        "name": "Author Name"
      }
  },
  "identity" : {
      "sourceIp" : ["x.x.x.x"],
      "userArn" : "arn:aws:iam::123456789012:user/appsync",
      "accountId" : "666666666666",
      "user" : "AIDAAAAAAAAAAAAAAAAAA"
  }
}

prev.result

Le résultat de toute opération précédente exécutée dans un résolveur de pipeline.

Si l'opération précédente était le modèle Before mapping du résolveur de pipeline, il$ctx.prev.result représente le résultat de l'évaluation du modèle et est mis à la disposition de la première fonction du pipeline.

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,$ctx.prev.result elle représente la sortie de la dernière fonction et est mise à disposition du modèle After mapping du résolveur de pipelines.

info

Objet qui contient des informations sur la demande GraphQL. Pour obtenir la structure de ce champ, veuillez consulter Infos.

Identity

La section identity contient les informations sur l'appelant. La forme de cette section dépend du type d'autorisation de votre API AWS AppSync.

Pour plus d'informations sur les optionsAWS AppSync de sécurité, voir Autorisation et authentification.

Autorisation API_KEY

Leidentity terrain n'est pas peuplé.

Autorisation AWS_LAMBDA

identitycontient laresolverContext clé, contenant le mêmeresolverContext contenu renvoyé par la fonction Lambda autorisant la demande.

Autorisation AWS_IAM

identityprésente la forme suivante :

{
    "accountId" : "string",
    "cognitoIdentityPoolId" : "string",
    "cognitoIdentityId" : "string",
    "sourceIp" : ["string"],
    "username" : "string", // IAM user principal
    "userArn" : "string",
    "cognitoIdentityAuthType" : "string", // authenticated/unauthenticated based on the identity type
    "cognitoIdentityAuthProvider" : "string" // the auth provider that was used to obtain the credentials
}

Autorisation AMAZON_COGNITO_USER_POOLS

identityprésente la forme suivante :

{
    "sub" : "uuid",
    "issuer" : "string",
    "username" : "string"
    "claims" : { ... },
    "sourceIp" : ["x.x.x.x"],
    "defaultAuthStrategy" : "string"
}

Chaque champ est défini comme suit :

accountId

ID duAWS compte de l'appelant.

claims

Demandes de l'utilisateur.

cognitoIdentityAuthType

Authentifié ou non authentifié en fonction du type d'identité.

cognitoIdentityAuthProvider

Liste séparée par des virgules des informations du fournisseur d'identité externe utilisées pour obtenir les informations d'identification utilisées pour signer la demande.

cognitoIdentityId

ID d'identité Amazon Cognito de l'appelant.

cognitoIdentityPoolId

ID de groupe d'identités Amazon Cognito associé à l'appelant.

defaultAuthStrategy

Stratégie d'autorisation par défaut pour cet appelant (ALLOW ou DENY).

issuer

Émetteur du jeton.

sourceIp

L'adresse IP source de l'appelant quiAWS AppSync reçoit. Si la demande n'inclut pas l'x-forwarded-foren-tête, la valeur IP source ne contient qu'une seule adresse IP provenant de la connexion TCP. Si la demande inclut un en-tête x-forwarded-for, l'adresse IP source est une liste d'adresses IP de l'en-tête x-forwarded-for en plus de l'adresse IP de la connexion TCP.

sub

UUID de l'utilisateur authentifié.

user

Utilisateur IAM.

userArn

L'Amazon Resource Name (ARN) de l'utilisateur IAM.

username

Nom de l'utilisateur authentifié. En cas d'autorisation AMAZON_COGNITO_USER_POOLS, la valeur de username est la valeur de l’attribut cognito:username. Dans le cas d'AWS_IAMune autorisation, la valeur du nom d'utilisateur est la valeur du principalAWS utilisateur. Si vous utilisez l'autorisation IAM avec des informations d'identification fournies par les pools d'identités Amazon Cognito, nous vous recommandons de l'utilisercognitoIdentityId.

En tête de la demande d'accès

AWS AppSync prend en charge la transmission d'en-têtes personnalisés depuis les clients et l'accès à ceux-ci dans vos résolveurs GraphQL à l'aide de$context.request.headers. Vous pouvez ensuite utiliser les valeurs d'en-tête pour des actions telles que l'insertion de données dans une source de données ou les contrôles d'autorisation. Vous pouvez utiliser un ou plusieurs en-têtes de demande à l'$curlaide d'une clé API depuis la ligne de commande, comme indiqué dans les exemples suivants :

Exemple d'en-tête unique

Supposons que vous définissiez un en-tête custom avec la valeur nadia, comme suit :

curl -XPOST -H "Content-Type:application/graphql" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql

Il est alors possible d'y accéder avec $context.request.headers.custom. Par exemple, elle peut être dans la VTL suivante pour DynamoDB :

"custom": $util.dynamodb.toDynamoDBJson($context.request.headers.custom)

Exemple d'en-tête multiple

Vous pouvez également transmettre plusieurs en-têtes dans une seule demande et y accéder dans le modèle de mappage des résolveurs. Par exemple, si l'customen-tête est défini avec deux valeurs :

curl -XPOST -H "Content-Type:application/graphql" -H "custom:bailey" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql

Vous pouvez ensuite y accéder comme s'il s'agissait d'un tableau : par exemple, $context.request.headers.custom[1].

Note

AWS AppSyncn'expose pas l'en-tête du cookie dans$context.request.headers.

Accédez au nom de domaine personnalisé de la demande

AWS AppSyncprend en charge la configuration d'un domaine personnalisé que vous pouvez utiliser pour accéder à votre GraphQL et aux points de terminaison en temps réel pour vos API. Lorsque vous faites une demande avec un nom de domaine personnalisé, vous pouvez obtenir le nom de domaine en utilisant$context.request.domainName.

Lorsque vous utilisez le nom de domaine de point de terminaison GraphQL par défaut, la valeur estnull.

Infos

La section info contient des informations sur la demande GraphQL. Cette section présente la forme suivante :

{
    "fieldName": "string",
    "parentTypeName": "string",
    "variables": { ... },
    "selectionSetList": ["string"],
    "selectionSetGraphQL": "string"
}

Chaque champ est défini comme suit :

fieldName

Nom du champ en cours de résolution.

parentTypeName

Nom du type parent du champ en cours de résolution.

variables

Carte qui contient toutes les variables transmises dans la demande GraphQL.

selectionSetList

Représentation sous forme de liste des champs du jeu de sélection GraphQL. Les champs aliasés sont uniquement référencés par le nom d'alias, et non par le nom du champ. L'exemple suivant détaille cela.

selectionSetGraphQL

Représentation sous forme de chaîne du jeu de sélection, formatée en langage SDL GraphQL. Bien que les fragments ne soient pas fusionnés dans l'ensemble de la sélection, les fragments en ligne sont conservés, comme montré dans l'exemple suivant.

Note

Lorsque vous utilisez$utils.toJson() oncontext.info, les valeurs queselectionSetGraphQL etselectionSetList renvoient ne sont pas sérialisées par défaut.

Par exemple, si vous résolvez le champ getPost de la requête suivante :

query {
  getPost(id: $postId) {
    postId
    title
    secondTitle: title
    content
    author(id: $authorId) {
      authorId
      name
    }
    secondAuthor(id: "789") {
      authorId
    }
    ... on Post {
      inlineFrag: comments: {
        id
      }
    }
    ... postFrag
  }
}

fragment postFrag on Post {
  postFrag: comments: {
    id
  }
}

Ensuite, la variable $context.info complète, disponible lors du traitement d'un modèle de mappage, peut être :

{
  "fieldName": "getPost",
  "parentTypeName": "Query",
  "variables": {
    "postId": "123",
    "authorId": "456"
  },
  "selectionSetList": [
    "postId",
    "title",
    "secondTitle"
    "content",
    "author",
    "author/authorId",
    "author/name",
    "secondAuthor",
    "secondAuthor/authorId",
    "inlineFragComments",
    "inlineFragComments/id",
    "postFragComments",
    "postFragComments/id"
  ],
  "selectionSetGraphQL": "{\n  getPost(id: $postId) {\n    postId\n    title\n    secondTitle: title\n    content\n    author(id: $authorId) {\n      authorId\n      name\n    }\n    secondAuthor(id: \"789\") {\n      authorId\n    }\n    ... on Post {\n      inlineFrag: comments {\n        id\n      }\n    }\n    ... postFrag\n  }\n}"
}

selectionSetListn'affiche que les champs appartenant au type actuel. Si le type actuel est une interface ou une union, seuls les champs sélectionnés appartenant à l'interface sont exposés. Par exemple, en fonction du schéma suivant :

type Query {
    node(id: ID!): Node
}

interface Node {
    id: ID
}

type Post implements Node {
    id: ID
    title: String
    author: String
}

type Blog implements Node {
    id: ID
    title: String
    category: String
}

Et la requête suivante :

query {
    node(id: "post1") {
        id
        ... on Post {
            title
        }

        ... on Blog {
            title
        }
    }
}

Lorsque vous appelez$ctx.info.selectionSetList à la résolution deQuery.node terrain, seulid est exposé :

"selectionSetList": [
    "id"
]

Assainissement des entrées

Les applications doivent assainir les entrées non approuvées pour empêcher toute utilisation non prévue de ces applications par une tierce partie. Comme il$context contient des entrées utilisateur dans des propriétés telles que$context.arguments$context.identity,$context.result,$context.info.variables, et$context.request.headers, il faut veiller à assainir leurs valeurs dans les modèles de mappage.

Étant donné que les modèles de mappage représentent JSON, l'assainissement des entrées consiste à échapper les caractères réservés JSON des chaînes représentant les entrées utilisateur. Il est recommandé d'utiliser l'utilitaire $util.toJson() pour échapper les caractères réservés JSON des valeurs de chaîne sensibles lors de leur insertion dans un modèle de mappage.

Par exemple, dans le modèle de mappage de requêtes Lambda suivant, étant donné que nous avons accédé à une chaîne de saisie client non sécurisée ($context.arguments.id), nous l'avons encapsulée$util.toJson() pour empêcher que des caractères JSON non échappés ne cassent le modèle JSON.

{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": $util.toJson($context.arguments.id)
    }
}

Contrairement au modèle de mappage ci-dessous, où nous insérons directement$context.arguments.id sans désinfection. Cela ne fonctionne pas pour les chaînes contenant des guillemets non cachés ou d'autres caractères réservés JSON, et votre modèle risque d'échouer.

## DO NOT DO THIS
{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "$context.arguments.id" ## Unsafe! Do not insert $context string values without escaping JSON characters.
    }
}