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

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

Cada campo no mapa $context é definido da seguinte forma:

Campos de $context

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.

Cada campo é definido da seguinte forma:

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

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:

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