Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Referencia de contexto de las plantillas de mapeo del solucionador de AWS AppSync
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 claveresolverContext
, que contiene el mismo contenidoresolverContext
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
oDENY
). -
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 encabezadox-forwarded-for
, la IP de origen será una lista de las direcciones IP del encabezadox-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ónAWS_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 usecognitoIdentityId
.
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. } }