Referencia de contexto de las plantillas de mapeo del solucionador

nota

Ahora admitimos de forma básica el tiempo de ejecución APPSYNC_JS y su documentación. Considere la opción de utilizar el tiempo de ejecución APPSYNC_JS y sus guías aquí.

AWS AppSync define un conjunto de variables y funciones para trabajar con plantillas de mapeo de solucionador. Esto simplifica las operaciones lógicas realizadas en los datos en GraphQL. En este documento se describen estas funciones y se proporcionan ejemplos para trabajar con plantillas.

Acceso a $context

La variable $context es un mapa que contiene toda la información contextual de la invocación al solucionador. Tiene la estructura siguiente:

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

nota

Si intenta obtener acceso a una entrada de diccionario o de mapa (como una entrada de context) usando su clave para obtener el valor, Velocity Template Language (VTL) le permite usar directamente la notación <dictionary-element>.<key-name>. Sin embargo, esto podría no funcionar en todos los casos, por ejemplo cuando los nombres de clave tengan caracteres especiales (como el guion bajo "_"). Recomendamos usar siempre la notación <dictionary-element>.get("<key-name>").

Cada campo del mapa $context se define de la siguiente manera:

Campos $context

arguments

Un mapa que contiene todos los argumentos de GraphQL de este campo.

identity

Un objeto que contiene información sobre el intermediario. Consulte Identidad para obtener más información acerca de la estructura de este campo.

source

Un mapa que contiene la resolución del campo principal.

stash

El "stash" es un mapa que está disponible dentro de cada solucionador y plantilla de mapeo de funciones. La misma instancia stash vive en una única ejecución de solucionador. Esto significa que puede utilizar el "stash" para pasar datos arbitrarios a plantillas de mapeo de solicitudes y respuestas, así como a funciones de un solucionador de canalización. El stash expone los mismos métodos que la estructura de datos del mapa de Java.

result

Un contenedor para los resultados de este solucionador. Este campo solo está disponible para las plantillas de mapeo de respuesta.

Por ejemplo, al solucionar el campo author de la siguiente consulta:

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

La variable $context completa que está disponible al procesar una plantilla de mapeo de respuesta podría ser:

{
  "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

Es el resultado de cualquier operación previa que se haya ejecutado en un solucionador de canalización.

Si la operación anterior era la plantilla de mapeo Antes del solucionador de canalización, entonces $ctx.prev.result representa el resultado de la evaluación de la plantilla y estará disponible para la primera función de la canalización.

Si la operación anterior era la primera función, entonces $ctx.prev.result representa el resultado de la primera función y estará disponible para la segunda función de la canalización.

Si la operación anterior era la última función, entonces $ctx.prev.result representa el resultado de la última función y estará disponible para la plantilla de mapeo Después del solucionador de canalización.

info

Un objeto que contiene información sobre la solicitud de GraphQL. Para obtener información sobre la estructura de este campo, consulte Información.

Identidad

La sección identity contiene información sobre el intermediario. La forma de esta sección depende del tipo de autorización de su API de AWS AppSync.

Para obtener más información sobre las opciones de seguridad de AWS AppSync, consulte Autorización y autenticación.

Autorización de API_KEY

El campo identity no se rellena.

Autorización de AWS_LAMBDA

La identity contiene la clave resolverContext, que contiene el mismo contenido resolverContext devuelto por la función de Lambda que autoriza la solicitud.

Autorización de AWS_IAM

La identity tiene el siguiente formato:

{
    "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
}

Autorización de AMAZON_COGNITO_USER_POOLS

La identity tiene el siguiente formato:

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

Cada campo se define de la siguiente manera:

accountId

El ID de la cuenta de AWS del intermediario.

claims

Las notificaciones que tiene el usuario.

cognitoIdentityAuthType

Autenticado o no según el tipo de identidad.

cognitoIdentityAuthProvider

Una lista separada por comas de la información del proveedor de identidad externo utilizada para obtener las credenciales que se usan para firmar la solicitud.

cognitoIdentityId

El ID de identidad de Amazon Cognito del intermediario.

cognitoIdentityPoolId

El ID de grupo de identidades de Amazon Cognito asociado al intermediario.

defaultAuthStrategy

La estrategia de autorización predeterminada para este intermediario (ALLOW o DENY).

issuer

El emisor del token.

sourceIp

La dirección IP de origen de la persona que realiza la llamada que AWS AppSync recibe. Si la solicitud no incluye el encabezado x-forwarded-for, el valor de IP de origen solo contiene una dirección IP de la conexión TCP. Si la solicitud incluye un encabezado x-forwarded-for, la IP de origen será una lista de las direcciones IP del encabezado x-forwarded-for, además de la dirección IP de la conexión TCP.

sub

El UUID del usuario autenticado.

user

El usuario de IAM.

userArn

Es el nombre de recurso de Amazon (ARN) del usuario de IAM.

username

El nombre de usuario del usuario autenticado. En el caso de una autorización AMAZON_COGNITO_USER_POOLS, el valor de nombre de usuario es el valor del atributo cognito:username. En el caso de una autorización AWS_IAM, el valor de nombre de usuario es el valor de la entidad principal del usuario de AWS. Si utiliza una autorización de IAM con credenciales proporcionadas desde grupos de identidad de Amazon Cognito, le recomendamos que use cognitoIdentityId.

Acceso a los encabezados de solicitud

AWS AppSync permite enviar encabezados personalizados de los clientes y obtener acceso a ellos desde los solucionadores de GraphQL utilizando $context.request.headers. Puede utilizar los valores de encabezado para acciones como insertar datos en un origen de datos o incluso efectuar comprobaciones de autorización. Puede usar uno o varios encabezados de solicitud usando $curl con una clave de API desde la línea de comandos, como se muestra en los siguientes ejemplos:

Ejemplo de encabezado único

Supongamos que establece un encabezado custom con un valor nadia como el siguiente:

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

Se puede obtener acceso a este encabezado con $context.request.headers.custom. Por ejemplo, podría encontrarse en la siguiente VTL para DynamoDB:

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

Ejemplo de varios encabezados

También puede pasar varios encabezados en una única solicitud y obtener acceso a ellos en la plantilla de mapeo de solucionadores. Por ejemplo, si el encabezado custom se define con dos valores:

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

Puede obtener acceso a ellos como una matriz, por ejemplo $context.request.headers.custom[1].

nota

AWS AppSync no expone el encabezado de la cookie en $context.request.headers.

Acceso al nombre de dominio personalizado de la solicitud

AWS AppSync admite la configuración de un dominio personalizado que puede usar para acceder a sus puntos de conexión de GraphQL y en tiempo real para sus API. Al hacer una solicitud con un nombre de dominio personalizado, puede obtener el nombre de dominio utilizando. $context.request.domainName

Cuando se utiliza el nombre de dominio de punto de conexión predeterminado de GraphQL, el valor es. null

Información

La sección info contiene información sobre la solicitud de GraphQL. Esta sección incluye la siguiente forma:

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

Cada campo se define de la siguiente manera:

fieldName

El nombre del campo que se está resolviendo actualmente.

parentTypeName

El nombre del tipo principal del campo que se está resolviendo actualmente.

variables

Un mapa que contiene todas las variables que se pasan a la solicitud de GraphQL.

selectionSetList

Una representación de lista de los campos del conjunto de selección de GraphQL. Solo se hace referencia a los campos con alias por el nombre de alias, no por el nombre de campo. El ejemplo siguiente muestra detalladamente esta estructura.

selectionSetGraphQL

Una representación en forma de cadena del conjunto de selección, formateado como lenguaje de definición de esquema (SDL) de GraphQL. Aunque los fragmentos no se combinan en el conjunto de selección, los fragmentos insertados se conservan, como se muestra en el ejemplo siguiente.

nota

Cuando se utiliza $utils.toJson() en context.info, los valores devueltos por selectionSetGraphQL y selectionSetList no se serializarán de forma predeterminada.

Por ejemplo, al resolver el campo getPost de la siguiente consulta:

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

La variable $context.info completa que está disponible al procesar una plantilla de mapeo podría ser:

{
  "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}"
}

selectionSetList expone solo los campos que pertenecen al tipo actual. Si el tipo actual es una interfaz o una unión, solo se exponen los campos seleccionados que pertenecen a la interfaz. Por ejemplo, en el caso del esquema siguiente:

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
}

Y en la siguiente consulta:

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

        ... on Blog {
            title
        }
    }
}

Cuando se llama a $ctx.info.selectionSetList con la resolución del campo Query.node, solo se expone id:

"selectionSetList": [
    "id"
]

Sanear datos entrantes

Las aplicaciones deben sanear datos entrantes que no sean de confianza para evitar que cualquier parte externa dé un uso fuera de lo previsto a una aplicación. Como el $context contiene datos entrantes del usuario en las propiedades como $context.arguments, $context.identity, $context.result, $context.info.variables y $context.request.headers, hay que tener cuidado de sanear sus valores en las plantillas de mapeo.

Dado que las plantillas de asignación representan archivos JSON, el saneamiento de la entrada la toma forma de escapar de caracteres reservados JSON a partir de cadenas que representan las entradas del usuario. Se recomienda usar la utilidad $util.toJson() para escapar caracteres JSON reservados de valores de cadenas sensibles al colocarlos en una plantilla de asignación.

Por ejemplo, en la siguiente plantilla de mapeo de la solicitud de Lambda, como hemos accedido a una cadena de entrada de cliente no segura ($context.arguments.id), la envolvemos con $util.toJson() para evitar que los caracteres JSON no escapados rompan la plantilla JSON.

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

A diferencia de la siguiente plantilla de asignación, donde insertamos $context.arguments.id directamente sin sanear. Esto no funciona en cadenas que contienen comillas sin escapar u otros caracteres reservados en JSON, y podrían dejar la plantilla abierta a errores.

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