AWS AppSync referensi konteks template pemetaan resolver

catatan

Kami sekarang terutama mendukung runtime APPSYNC _JS dan dokumentasinya. Harap pertimbangkan untuk menggunakan runtime APPSYNC _JS dan panduannya di sini.

AWS AppSync mendefinisikan satu set variabel dan fungsi untuk bekerja dengan template pemetaan resolver. Ini membuat operasi logis pada data lebih mudah dengan GraphQL. Dokumen ini menjelaskan fungsi-fungsi tersebut dan memberikan contoh untuk bekerja dengan template.

Mengakses `$context`

$contextVariabel adalah peta yang menyimpan semua informasi kontekstual untuk pemanggilan resolver Anda. Ini memiliki struktur sebagai berikut:


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

catatan

Jika Anda mencoba mengakses entri kamus/peta (seperti entri dicontext) dengan kuncinya untuk mengambil nilai, Velocity Template Language (VTL) memungkinkan Anda langsung menggunakan notasi. <dictionary-element>.<key-name> Namun, ini mungkin tidak berfungsi untuk semua kasus, seperti ketika nama kunci memiliki karakter khusus (misalnya, garis bawah “_”). Kami menyarankan Anda selalu menggunakan <dictionary-element>.get("<key-name>") notasi.

Setiap bidang dalam $context peta didefinisikan sebagai berikut:

`$context`bidang

arguments: Peta yang berisi semua argumen GraphQL untuk bidang ini.
identity: Objek yang berisi informasi tentang penelepon. Untuk informasi selengkapnya tentang struktur bidang ini, lihat Identitas.
source: Peta yang berisi resolusi bidang induk.
stash: Stash adalah peta yang tersedia di dalam setiap resolver dan template pemetaan fungsi. Instans simpanan yang sama hidup melalui eksekusi resolver tunggal. Ini berarti Anda dapat menggunakan stash untuk meneruskan data arbitrer di seluruh template pemetaan permintaan dan respons, dan di seluruh fungsi dalam penyelesai pipeline. Stash mengekspos metode yang sama dengan struktur data Peta Java.

result

Wadah untuk hasil resolver ini. Bidang ini hanya tersedia untuk template pemetaan respons.

Misalnya, jika Anda menyelesaikan author bidang kueri berikut:


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

Kemudian $context variabel lengkap yang tersedia saat memproses template pemetaan respons mungkin:


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

Hasil dari operasi apa pun sebelumnya dieksekusi dalam resolver pipa.

Jika operasi sebelumnya adalah template Sebelum pemetaan pipeline resolver, maka $ctx.prev.result mewakili output dari evaluasi template dan tersedia untuk fungsi pertama dalam pipeline.

Jika operasi sebelumnya adalah fungsi pertama, maka $ctx.prev.result mewakili output dari fungsi pertama dan tersedia untuk fungsi kedua dalam pipa.

Jika operasi sebelumnya adalah fungsi terakhir, maka $ctx.prev.result mewakili output dari fungsi terakhir dan tersedia untuk template After mapping resolver pipeline.

info

Objek yang berisi informasi tentang permintaan GraphQL. Untuk struktur bidang ini, lihat Info.

Identitas

identityBagian ini berisi informasi tentang penelepon. Bentuk bagian ini tergantung pada jenis otorisasi Anda AWS AppSync API.

Untuk informasi selengkapnya tentang opsi AWS AppSync keamanan, lihat Otorisasi dan otentikasi.

API_KEYotorisasi

identityBidang tidak dihuni.

AWS_LAMBDAotorisasi

Berisi resolverContext kunci, identity berisi resolverContext konten yang sama yang dikembalikan oleh fungsi Lambda yang mengotorisasi permintaan.

AWS_IAMotorisasi

Ini identity memiliki bentuk sebagai berikut:


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

Ini identity memiliki bentuk sebagai berikut:


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

Setiap bidang didefinisikan sebagai berikut:

accountId: ID AWS akun penelepon.
claims: Klaim yang dimiliki pengguna.
cognitoIdentityAuthType: Entah diautentikasi atau tidak diautentikasi berdasarkan tipe identitas.
cognitoIdentityAuthProvider: Daftar informasi penyedia identitas eksternal yang dipisahkan koma yang digunakan dalam memperoleh kredensil yang digunakan untuk menandatangani permintaan.
cognitoIdentityId: ID identitas Amazon Cognito dari penelepon.
cognitoIdentityPoolId: ID kumpulan identitas Amazon Cognito yang terkait dengan pemanggil.
defaultAuthStrategy: Strategi otorisasi default untuk penelepon ini (ALLOWatauDENY).
issuer: Penerbit token.
sourceIp: Alamat IP sumber penelepon yang AWS AppSync menerima. Jika permintaan tidak menyertakan x-forwarded-for header, nilai IP sumber hanya berisi satu alamat IP dari TCP koneksi. Jika permintaan menyertakan x-forwarded-for header, IP sumber adalah daftar alamat IP dari x-forwarded-for header, selain alamat IP dari TCP koneksi.
sub: Dari pengguna UUID yang diautentikasi.
user: IAMPengguna.
userArn: Nama Sumber Daya Amazon (ARN) IAM pengguna.
username: Nama pengguna dari pengguna yang diautentikasi. Dalam hal AMAZON_COGNITO_USER_POOLS otorisasi, nilai nama pengguna adalah nilai atribut cognito:username. Dalam hal AWS_IAM otorisasi, nilai nama pengguna adalah nilai prinsipal AWS pengguna. Jika Anda menggunakan IAM otorisasi dengan kredensi yang dijual dari kumpulan identitas Amazon Cognito, kami sarankan Anda menggunakannya. cognitoIdentityId

Akses header permintaan

AWS AppSync mendukung meneruskan header khusus dari klien dan mengaksesnya di resolver GraphQL Anda dengan menggunakan. $context.request.headers Anda kemudian dapat menggunakan nilai header untuk tindakan seperti memasukkan data ke sumber data atau pemeriksaan otorisasi. Anda dapat menggunakan header permintaan tunggal atau beberapa menggunakan $curl dengan API kunci dari baris perintah, seperti yang ditunjukkan dalam contoh berikut:

Contoh header tunggal

Misalkan Anda menetapkan header custom dengan nilai nadia seperti berikut:


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

Ini kemudian dapat diakses dengan$context.request.headers.custom. Misalnya, mungkin berikut ini VTL untuk DynamoDB:


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

Beberapa contoh header

Anda juga dapat meneruskan beberapa header dalam satu permintaan dan mengaksesnya di template pemetaan resolver. Misalnya, jika custom header diatur dengan dua nilai:


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

Anda kemudian dapat mengakses ini sebagai array, seperti$context.request.headers.custom[1].

catatan

AWS AppSync tidak mengekspos header cookie di$context.request.headers.

Mengakses permintaan nama domain kustom

AWS AppSync mendukung konfigurasi domain kustom yang dapat Anda gunakan untuk mengakses GraphQL Anda dan titik akhir real-time untuk Anda. APIs Saat membuat permintaan dengan nama domain khusus, Anda bisa mendapatkan nama domain menggunakan$context.request.domainName.

Saat menggunakan nama domain titik akhir GraphQL default, nilainya adalah. null

Info

infoBagian ini berisi informasi tentang permintaan GraphQL. Bagian ini memiliki bentuk sebagai berikut:


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

Setiap bidang didefinisikan sebagai berikut:

fieldName: Nama bidang yang saat ini sedang diselesaikan.
parentTypeName: Nama tipe induk untuk bidang yang saat ini sedang diselesaikan.
variables: Peta yang menampung semua variabel yang diteruskan ke permintaan GraphQL.
selectionSetList: Sebuah daftar representasi bidang dalam set pilihan GraphQL. Bidang yang dialias hanya direferensikan dengan nama alias, bukan nama bidang. Contoh berikut menunjukkan ini secara rinci.
selectionSetGraphQL: Sebuah representasi string dari set seleksi, diformat sebagai GraphQL skema definisi bahasa (). SDL Meskipun fragmen tidak digabungkan ke dalam kumpulan seleksi, fragmen sebaris dipertahankan, seperti yang ditunjukkan pada contoh berikut.

catatan

Saat menggunakan $utils.toJson() oncontext.info, nilai yang selectionSetGraphQL dan selectionSetList kembali tidak diserialisasikan secara default.

Misalnya, jika Anda menyelesaikan getPost bidang kueri berikut:


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

Kemudian $context.info variabel lengkap yang tersedia saat memproses template pemetaan mungkin:


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

selectionSetListmengekspos hanya bidang yang termasuk dalam tipe saat ini. Jika tipe saat ini adalah antarmuka atau gabungan, hanya bidang yang dipilih milik antarmuka yang diekspos. Misalnya, diberikan skema berikut:


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
}

Dan query berikut:


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

        ... on Blog {
            title
        }
    }
}

Saat memanggil $ctx.info.selectionSetList pada resolusi Query.node bidang, hanya yang id diekspos:


"selectionSetList": [
    "id"
]

Masukan sanitasi

Aplikasi harus membersihkan input yang tidak tepercaya untuk mencegah pihak eksternal menggunakan aplikasi di luar penggunaan yang dimaksudkan. Karena $context berisi input pengguna di properti seperti$context.arguments,,,,$context.identity, dan $context.result $context.info.variables$context.request.headers, kehati-hatian harus dilakukan untuk membersihkan nilainya dalam templat pemetaan.

Karena template pemetaan mewakiliJSON, sanitasi input mengambil bentuk melarikan diri dari karakter yang JSON dicadangkan dari string yang mewakili input pengguna. Praktik terbaik adalah menggunakan $util.toJson() utilitas untuk menghindari karakter yang JSON dicadangkan dari nilai string sensitif saat menempatkannya ke dalam templat pemetaan.

Misalnya, dalam template pemetaan permintaan Lambda berikut, karena kami mengakses string input pelanggan yang tidak aman ($context.arguments.id), kami membungkusnya dengan $util.toJson() untuk mencegah karakter yang tidak terlolos merusak JSON template. JSON


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

Berbeda dengan template pemetaan di bawah ini, di mana kita langsung menyisipkan $context.arguments.id tanpa sanitasi. Ini tidak berfungsi untuk string yang berisi tanda kutip yang tidak di-escaped atau karakter JSON cadangan lainnya, dan dapat membiarkan template Anda terbuka untuk kegagalan.


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

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Panduan pemrograman template pemetaan Resolver

Referensi utilitas template pemetaan penyelesai

AWS AppSync referensi konteks template pemetaan resolver

catatan

Mengakses $context

catatan

$contextbidang

Identitas

Akses header permintaan

catatan

Mengakses permintaan nama domain kustom

Info

catatan

Masukan sanitasi

Mengakses `$context`

`$context`bidang