Referência de contexto do modelo de mapeamento do resolvedor do AWS AppSync - AWS AppSync GraphQL

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 chave resolverContext que tem o mesmo conteúdo de resolverContext 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 ou DENY).

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çalho x-forwarded-for, o IP de origem será uma lista de endereços IP do cabeçalho x-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 do AWS_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 utilizar cognitoIdentityId.

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