Accès à la variable $context Assainissement des entrées

Référence contextuelle du modèle de mappage Resolver

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 AppSyncdéfinit un ensemble de variables et de fonctions permettant de travailler avec 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 n'est disponible que pour les modèles de mappage des réponses.

Par exemple, si vous résolvez le author 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 de mappage Before du résolveur de pipeline, elle $ctx.prev.result représente le résultat de l'évaluation du modèle et est mise à 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, elle $ctx.prev.result représente la sortie de la dernière fonction et est mise à la disposition du modèle After mapping du résolveur de pipeline.

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 options AWS AppSync de sécurité, consultez la section Autorisation et authentification.

Autorisation API_KEY

Le identity champ n'est pas renseigné.

Autorisation AWS_LAMBDA

identityIl contient la resolverContext clé, contenant le même resolverContext contenu renvoyé par la fonction Lambda autorisant la demande.

Autorisation AWS_IAM

identityIl a 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

identityIl a 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: L'identifiant du AWS 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: L'identifiant Amazon Cognito de l'appelant.
cognitoIdentityPoolId: L'ID du pool 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: Adresse IP source de l'appelant qui AWS 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: Le nom de ressource Amazon (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 de l'AWSutilisateur principal. Si vous utilisez l'autorisation IAM avec des informations d'identification provenant de pools d'identités Amazon Cognito, nous vous recommandons d'utiliser. cognitoIdentityId

En-têtes de demande d'accès

AWS AppSync permet de transmettre des en-têtes personnalisés depuis les clients et d'y accéder dans vos résolveurs GraphQL en utilisant. $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é d'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, il peut se trouver 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 de 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 du point de terminaison GraphQL par défaut, la valeur est. null

Infos

La section info contient des informations sur la demande GraphQL. Cette section se présente sous 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 dotés d'un alias sont référencés uniquement par le nom de l'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 le jeu de sélection, les fragments intégrés sont conservés, comme le montre l'exemple suivant.

Note

Lorsque vous utilisez $utils.toJson() oncontext.info, les valeurs renvoyées selectionSetGraphQL et celles selectionSetList renvoyées 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'expose 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, selon le 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
        }
    }
}

Lors de l'appel $ctx.info.selectionSetList à la résolution du Query.node champ, seul id 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 à nettoyer 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, parce 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 les caractères JSON non échappés de casser 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 échappés ou d'autres caractères réservés JSON, et cela peut entraîner l'échec de votre modèle.


## 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.
    }
}

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

Guide de programmation du modèle de mappage Resolver

Référence de l'utilitaire du modèle de mappage Resolver

Référence contextuelle du modèle de mappage Resolver

Note

Accès à la variable $context

Note

Champs de $context

Identity

En-têtes de demande d'accès

Note

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

Infos

Note

Assainissement des entrées

Accès à la variable `$context`

Champs de `$context`