As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Referência de contexto do modelo de mapeamento do resolvedor do AWS AppSync
nota
Agora, oferecemos suporte principalmente ao runtime do APPSYNC_JS e sua documentação. Considere usar o runtime do APPSYNC_JS e seus guias disponíveis aqui.
AWS AppSync define um conjunto de variáveis e funções para trabalhar com modelos de mapeamento de resolvedor. Isso facilita as operações lógicas em dados com o GraphQL. Este documento descreve essas funções e fornece exemplos para trabalhar com modelos.
Acesso ao $context
A variável $context
é um mapa que contém todas as informações contextuais para a invocação do resolvedor. Ela tem a seguinte estrutura:
{ "arguments" : { ... }, "source" : { ... }, "result" : { ... }, "identity" : { ... }, "request" : { ... }, "info": { ... } }
nota
Se você está tentando acessar uma entrada de dicionário/mapa (como uma entrada em context
) com sua chave para recuperar o valor, a Velocity Template Language (VTL) permite usar diretamente a notação <dictionary-element>.<key-name>
. No entanto, isso pode não funcionar para todos os casos, como quando os nomes das chaves tiverem caracteres especiais (por exemplo, um sublinhado "_"). Recomendamos sempre usar a notação <dictionary-element>.get("<key-name>")
.
Cada campo no mapa $context
é definido da seguinte forma:
Campos de $context
-
arguments
-
Um mapa que contém todos os argumentos do GraphQL para este campo.
-
identity
-
Um objeto que contém informações sobre o chamador. Para obter mais informações sobre a estrutura desse campo, consulte Identidade.
-
source
-
Um mapa que contém a resolução do campo pai.
-
stash
-
O stash é um mapa disponibilizado dentro de cada modelo de mapeamento de resolvedor e função. A mesma instância stash passa por uma única execução do resolvedor. Isso significa que é possível usar o stash para passar dados arbitrários entre os modelos de mapeamento de solicitação e resposta e entre as funções em um resolvedor de pipeline. O stash expõe os mesmos métodos que a estrutura de dados do Java Map
.
-
result
-
Um contêiner para os resultados desse resolvedor. Esse campo só está disponível para modelos de mapeamento de resposta.
Por exemplo, se estiver resolvendo o campo
author
da seguinte consulta:query { getPost(id: 1234) { postId title content author { id name } } }
Em seguida, a variável
$context
completa que está disponível ao processar o modelo de mapeamento da resposta pode 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
-
O resultado de qualquer operação anterior executada em um resolvedor de pipeline.
Se a operação anterior foi o modelo de mapeamento Anterior do resolvedor de pipeline,
$ctx.prev.result
representa a saída da avaliação do modelo e será disponibilizado para a primeira função no pipeline.Se a operação anterior foi a primeira função,
$ctx.prev.result
representa a saída da primeira função e será disponibilizado para a segunda função no pipeline.Se a operação anterior foi a última função,
$ctx.prev.result
representa a saída da primeira função e será disponibilizado para o modelo de mapeamento Posterior do resolvedor de pipeline. -
info
-
Um objeto que contém informações sobre a solicitação do GraphQL. Para ver a estrutura desse campo, consulte Informações.
Identidade
A seção identity
contém informações sobre o chamador. A forma dessa seção depende do tipo de autorização da API do AWS AppSync.
Para obter mais informações sobre as opções de segurança do AWS AppSync, consulte Autorização e autenticação.
-
API_KEY
authorization -
O campo
identity
não está preenchido. AWS_LAMBDA
authorization-
identity
inclui a chaveresolverContext
que tem o mesmo conteúdo deresolverContext
retornado pela função do Lambda que autorizou a solicitação. -
AWS_IAM
authorization -
O
identity
tem o seguinte 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 }
-
AMAZON_COGNITO_USER_POOLS
authorization -
O
identity
tem o seguinte formato:{ "sub" : "uuid", "issuer" : "string", "username" : "string" "claims" : { ... }, "sourceIp" : ["x.x.x.x"], "defaultAuthStrategy" : "string" }
Cada campo é definido da seguinte forma:
-
accountId
-
O ID da conta da AWS do chamador.
-
claims
-
As reivindicações do usuário.
-
cognitoIdentityAuthType
-
Autenticado ou não autenticado com base no tipo de identidade.
-
cognitoIdentityAuthProvider
-
Uma lista separada por vírgulas das informações do provedor de identidade externo usada na obtenção das credenciais usadas para assinar a solicitação.
-
cognitoIdentityId
-
O ID de identidade do Amazon Cognito do chamador.
-
cognitoIdentityPoolId
-
O ID do banco de identidades do Amazon Cognito associado ao chamador.
-
defaultAuthStrategy
-
A estratégia de autorização padrão para este chamador (
ALLOW
ouDENY
). -
issuer
-
O emissor do token.
-
sourceIp
-
O endereço IP de origem do chamador que AWS AppSync recebe. Se a solicitação não incluir o cabeçalho
x-forwarded-for
, o valor do IP de origem conterá apenas um único endereço IP da conexão TCP. Se a solicitação inclui um cabeçalhox-forwarded-for
, o IP de origem será uma lista de endereços IP do cabeçalhox-forwarded-for
, além do endereço IP da conexão TCP. -
sub
-
O UUID do usuário autenticado.
-
user
-
O usuário do IAM.
-
userArn
-
O nome do recurso da Amazon (ARN) do usuário do IAM.
-
username
-
O nome do usuário autenticado. Em caso de autorização
AMAZON_COGNITO_USER_POOLS
, o valor do nome de usuário é o valor de username é o valor do atributo cognito:username. Em caso de autorização doAWS_IAM
, o valor de username é o valor da entidade principal do usuário da AWS. Se você estiver usando a autorização do IAM com credenciais fornecidas por bancos de identidades do Amazon Cognito, recomendamos utilizarcognitoIdentityId
.
Cabeçalhos de solicitação de acesso
O AWS AppSync oferece suporte ao envio de cabeçalhos personalizados de clientes e ao acesso deles nos resolvedores do GraphQL usando $context.request.headers
. Em seguida, você pode usar valores de cabeçalho para ações como inserir dados em uma fonte de dados ou até mesmo verificações de autorização. É possível utilizar cabeçalhos de solicitação por meio de $curl
com uma chave da API na linha de comando conforme mostrado nos exemplos a seguir:
Exemplo de cabeçalho único
Digamos que você defina um cabeçalho custom
com um valor de nadia
da seguinte forma:
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
Isso pode ser acessado com $context.request.headers.custom
. Por exemplo, ele pode estar no seguinte VTL para o DynamoDB:
"custom": $util.dynamodb.toDynamoDBJson($context.request.headers.custom)
Exemplo de vários cabeçalhos
Você também pode enviar vários cabeçalhos em uma única solicitação e acessá-los no modelo de mapeamento do resolvedor. Por exemplo, se o cabeçalho custom
foi definido com dois 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
Em seguida, você pode acessá-los como uma matriz, como $context.request.headers.custom[1]
.
nota
AWS AppSync não expõe o cabeçalho do cookie em $context.request.headers
.
Acessar o nome de domínio personalizado da solicitação
AWS AppSync oferece suporte à configuração de um domínio personalizado que você pode usar para acessar seu GraphQL e endpoints em tempo real para suas APIs. Ao fazer uma solicitação com um nome de domínio personalizado, você pode obter o nome de domínio usando $context.request.domainName
.
Ao usar o nome de domínio padrão do endpoint do GraphQL, o valor será null
.
Informações
A seção info
contém informações sobre a solicitação do GraphQL. Esta seção tem o seguinte formato:
{ "fieldName": "string", "parentTypeName": "string", "variables": { ... }, "selectionSetList": ["string"], "selectionSetGraphQL": "string" }
Cada campo é definido da seguinte forma:
-
fieldName
-
O nome do campo que está sendo resolvido no momento.
-
parentTypeName
-
O nome do tipo pai para o campo que está sendo resolvido no momento.
-
variables
-
Um mapa que contém todas as variáveis que são passadas para a solicitação do GraphQL.
-
selectionSetList
-
Uma representação de lista dos campos no conjunto de seleções do GraphQL. Os campos com alias serão referenciados somente pelo nome do alias, não pelo nome do campo. O exemplo a seguir mostra isso em detalhes.
-
selectionSetGraphQL
-
Uma representação de string do conjunto de seleções, formatada como linguagem de definição de esquema (SDL) do GraphQL. Embora os fragmentos não sejam mesclados no conjunto de seleções, os fragmentos inline são preservados, conforme mostrado no exemplo a seguir.
nota
Ao usar $utils.toJson()
em context.info
, os valores retornados por selectionSetGraphQL
e selectionSetList
não serão serializados por padrão.
Por exemplo, se estiver resolvendo o campo getPost
da seguinte 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 } }
Depois, a variável $context.info
completa que está disponível ao processar o modelo de mapeamento pode 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
expõe somente campos que pertencem ao tipo atual. Se o tipo atual for uma interface ou união, somente os campos selecionados que pertencem à interface serão expostos. Por exemplo, considerando o seguinte esquema:
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 }
E a seguinte consulta:
query { node(id: "post1") { id ... on Post { title } ... on Blog { title } } }
Ao chamar $ctx.info.selectionSetList
na resolução do campo Query.node
, somente id
é exposto:
"selectionSetList": [ "id" ]
Limpar entradas
Os aplicativos devem limpar entradas não confiáveis para impedir que qualquer parte externa use um aplicativo fora do uso pretendido. Como o $context
contém entradas do usuário em propriedades como $context.arguments
, $context.identity
, $context.result
, $context.info.variables
e $context.request.headers
, tome cuidado para limpar seus valores nos modelos de mapeamento.
Como os modelos de mapeamento representam JSON, a limpeza de entradas assume a forma de escape de caracteres reservados JSON de strings que representem entradas do usuário. É uma melhor prática usar o utilitário $util.toJson()
para o escape de caracteres reservados JSON de valores de string sensíveis ao colocá-los em um modelo de mapeamento.
Por exemplo, no modelo de mapeamento de solicitação do Lambda abaixo, como acessamos uma string de entrada de cliente insegura ($context.arguments.id
), ela foi encapsulada com $util.toJson()
para evitar que caracteres JSON sem escape corrompam o modelo JSON.
{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "postId": $util.toJson($context.arguments.id) } }
Ao contrário do modelo de mapeamento abaixo, em que inserimos $context.arguments.id
diretamente, sem limpeza. Isso não funcionará para strings contendo aspas duplas ou outros caracteres reservados JSON sem escape e sujeita seu modelo a falhas.
## 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. } }