Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# AWS AppSync referensi template pemetaan resolver untuk Lambda
<a name="resolver-mapping-template-reference-lambda"></a>

**catatan**  
Kami sekarang terutama mendukung runtime APPSYNC\$1JS dan dokumentasinya. [Harap pertimbangkan untuk menggunakan runtime APPSYNC\$1JS dan panduannya di sini.](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)

Anda dapat menggunakan AWS AppSync fungsi dan resolver untuk menjalankan fungsi Lambda yang terletak di akun Anda. Anda dapat membentuk payload permintaan dan respons dari fungsi Lambda Anda sebelum mengembalikannya ke klien Anda. Anda juga dapat menggunakan template pemetaan untuk memberikan petunjuk AWS AppSync tentang sifat operasi yang akan dipanggil. Bagian ini menjelaskan template pemetaan yang berbeda untuk operasi Lambda yang didukung.

## Meminta template pemetaan
<a name="request-mapping-template"></a>

Templat pemetaan permintaan Lambda menangani bidang yang terkait dengan fungsi Lambda Anda:

```
{
  "version": string,
  "operation": Invoke|BatchInvoke,
  "payload": any type,
  "invocationType": RequestResponse|Event
}
```

Ini adalah representasi skema JSON dari template pemetaan permintaan Lambda saat diselesaikan:

```
{
  "definitions": {},
  "$schema": "https://json-schema.org/draft-06/schema#",
  "$id": "https://aws.amazon.com/appsync/request-mapping-template.json",
  "type": "object",
  "properties": {
    "version": {
      "$id": "/properties/version",
      "type": "string",
      "enum": [
        "2018-05-29"
      ],
      "title": "The Mapping template version.",
      "default": "2018-05-29"
    },
    "operation": {
      "$id": "/properties/operation",
      "type": "string",
      "enum": [
        "Invoke",
        "BatchInvoke"
      ],
      "title": "The Mapping template operation.",
      "description": "What operation to execute.",
      "default": "Invoke"
    },
    "payload": {},
    "invocationType": {
      "$id": "/properties/invocationType",
      "type": "string",
      "enum": [
        "RequestResponse",
        "Event"
      ],
      "title": "The Mapping template invocation type.",
      "description": "What invocation type to execute.",
      "default": "RequestResponse"
    }
  },
  "required": [
    "version",
    "operation"
  ],
  "additionalProperties": false
}
```

Berikut adalah contoh yang menggunakan `invoke` operasi dengan data payloadnya menjadi `getPost` bidang dari skema GraphQL bersama dengan argumennya dari konteksnya:

```
{
  "version": "2018-05-29",
  "operation": "Invoke",
  "payload": {
    "field": "getPost",
    "arguments": $util.toJson($context.arguments)
  }
}
```

Seluruh dokumen pemetaan diteruskan sebagai input ke fungsi Lambda Anda sehingga contoh sebelumnya sekarang terlihat seperti ini:

```
{
  "version": "2018-05-29",
  "operation": "Invoke",
  "payload": {
    "field": "getPost",
    "arguments": {
      "id": "postId1"
    }
  }
}
```

### Versi
<a name="version"></a>

Umum untuk semua template pemetaan permintaan, `version` mendefinisikan versi yang digunakan template. `version`Diperlukan dan merupakan nilai statis:

```
"version": "2018-05-29"
```

### Operasi
<a name="operation"></a>

Sumber data Lambda memungkinkan Anda menentukan dua operasi di `operation` bidang: `Invoke` dan. `BatchInvoke` `Invoke`Operasi ini memungkinkan AWS AppSync untuk memanggil fungsi Lambda Anda untuk setiap penyelesai bidang GraphQL. `BatchInvoke`menginstruksikan permintaan batch AWS AppSync untuk bidang GraphQL saat ini. Bidang `operation` wajib diisi.

Untuk`Invoke`, template pemetaan permintaan yang diselesaikan cocok dengan muatan input fungsi Lambda. Mari kita memodifikasi contoh di atas:

```
{
  "version": "2018-05-29",
  "operation": "Invoke",
    "payload": {
      "arguments": $util.toJson($context.arguments)
    }
}
```

Ini diselesaikan dan diteruskan ke fungsi Lambda, yang bisa terlihat seperti ini:

```
{
  "version": "2018-05-29",
  "operation": "Invoke",
    "payload": {
      "arguments": {
        "id": "postId1"
      }
    }
}
```

Untuk`BatchInvoke`, template pemetaan diterapkan ke setiap penyelesai bidang dalam batch. Untuk keringkasan, AWS AppSync gabungkan semua `payload` nilai template pemetaan yang diselesaikan ke dalam daftar di bawah satu objek yang cocok dengan templat pemetaan. Contoh template berikut menunjukkan penggabungan:

```
{
  "version": "2018-05-29",
  "operation": "BatchInvoke",
  "payload": $util.toJson($context)
}
```

Template ini diselesaikan ke dalam dokumen pemetaan berikut:

```
{
  "version": "2018-05-29",
  "operation": "BatchInvoke",
  "payload": [
    {...}, // context for batch item 1
    {...}, // context for batch item 2
    {...}  // context for batch item 3
  ]
}
```

Setiap elemen `payload` daftar sesuai dengan satu item batch. Fungsi Lambda juga diharapkan mengembalikan respons berbentuk daftar yang cocok dengan urutan item yang dikirim dalam permintaan:

```
[
  { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 1
  { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 2
  { "data": {...}, "errorMessage": null, "errorType": null }  // result for batch item 3
]
```

### Payload
<a name="payload"></a>

`payload`Bidang adalah wadah yang digunakan untuk meneruskan JSON yang terbentuk dengan baik ke fungsi Lambda. Jika `operation` bidang diatur ke`BatchInvoke`, AWS AppSync membungkus `payload` nilai yang ada ke dalam daftar. `payload`Bidang ini opsional.

### Jenis doa
<a name="async-invocation-type"></a>

Sumber data Lambda memungkinkan Anda menentukan dua jenis pemanggilan: dan. `RequestResponse` `Event` [Jenis pemanggilan identik dengan tipe pemanggilan yang ditentukan dalam API Lambda.](https://docs.aws.amazon.com//lambda/latest/api/API_Invoke.html) Jenis `RequestResponse` AWS AppSync pemanggilan memungkinkan memanggil fungsi Lambda Anda secara sinkron untuk menunggu respons. `Event`Pemanggilan memungkinkan Anda untuk menjalankan fungsi Lambda Anda secara asinkron. [Untuk informasi selengkapnya tentang cara Lambda menangani permintaan jenis `Event` pemanggilan, lihat Pemanggilan asinkron.](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html) `invocationType`Bidang ini opsional. Jika bidang ini tidak termasuk dalam permintaan, AWS AppSync akan default ke jenis `RequestResponse` pemanggilan.

Untuk `invocationType` bidang apa pun, permintaan yang diselesaikan cocok dengan muatan input fungsi Lambda. Mari kita memodifikasi contoh di atas:

```
{
  "version": "2018-05-29",
  "operation": "Invoke",
  "invocationType": "Event"
  "payload": {
    "arguments": $util.toJson($context.arguments)
  }
}
```

Ini diselesaikan dan diteruskan ke fungsi Lambda, yang bisa terlihat seperti ini:

```
{
  "version": "2018-05-29",
  "operation": "Invoke",
  "invocationType": "Event",
  "payload": {
    "arguments": {
      "id": "postId1"
    }
  }
}
```

Saat `BatchInvoke` operasi digunakan bersama dengan bidang jenis `Event` pemanggilan, AWS AppSync gabungkan penyelesai bidang dengan cara yang sama seperti yang disebutkan di atas, dan permintaan diteruskan ke fungsi Lambda Anda sebagai peristiwa asinkron dengan daftar nilai. `payload` Kami menyarankan Anda menonaktifkan caching resolver untuk resolver tipe `Event` pemanggilan karena ini tidak akan dikirim ke Lambda jika ada cache hit.

## Templat pemetaan respons
<a name="response-mapping-template"></a>

Seperti sumber data lainnya, fungsi Lambda Anda mengirimkan respons AWS AppSync yang harus dikonversi ke tipe GraphQL.

Hasil dari fungsi Lambda diatur pada `context` objek yang tersedia melalui properti Velocity Template Language (VTL). `$context.result`

Jika bentuk respons fungsi Lambda Anda sama persis dengan bentuk tipe GraphQL, Anda dapat meneruskan respons menggunakan templat pemetaan respons berikut:

```
$util.toJson($context.result)
```

Tidak ada bidang wajib atau batasan bentuk yang berlaku untuk template pemetaan respons. Namun, karena GraphQL diketik dengan kuat, template pemetaan yang diselesaikan harus sesuai dengan jenis GraphQL yang diharapkan.

## Respons batch fungsi Lambda
<a name="aws-appsync-resolver-mapping-template-reference-lambda-batched-response"></a>

Jika `operation` bidang diatur ke`BatchInvoke`, AWS AppSync mengharapkan daftar item kembali dari fungsi Lambda. AWS AppSync Untuk memetakan setiap hasil kembali ke item permintaan asli, daftar respons harus sesuai dengan ukuran dan urutan. Ini valid untuk memiliki `null` item dalam daftar respons; `$ctx.result` diatur ke *null* sesuai.

## Resolver Lambda Langsung
<a name="direct-lambda-resolvers"></a>

Jika Anda ingin menghindari penggunaan template pemetaan sepenuhnya, AWS AppSync dapat memberikan payload default ke fungsi Lambda Anda dan respons fungsi Lambda default ke tipe GraphQL. Anda dapat memilih untuk menyediakan template permintaan, template respons, atau tidak, dan AWS AppSync menanganinya sesuai dengan itu.

### Templat pemetaan permintaan Lambda langsung
<a name="lambda-mapping-template-bypass-request"></a>

Ketika template pemetaan permintaan tidak disediakan, AWS AppSync akan mengirim `Context` objek langsung ke fungsi Lambda Anda sebagai `Invoke` operasi. Untuk informasi lebih lanjut tentang struktur objek `Context`, lihat [AWS AppSync referensi konteks template pemetaan resolver](resolver-context-reference.md).

### Templat pemetaan respons Lambda langsung
<a name="lambda-mapping-template-bypass-response"></a>

Ketika template pemetaan respons tidak disediakan, AWS AppSync lakukan salah satu dari dua hal setelah menerima respons fungsi Lambda Anda. Jika Anda tidak menyediakan template pemetaan permintaan atau jika Anda menyediakan template pemetaan permintaan dengan versi`2018-05-29`, responsnya akan setara dengan template pemetaan respons berikut:

```
#if($ctx.error)
     $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
 #end
 $util.toJson($ctx.result)
```

Jika Anda menyediakan templat dengan versinya`2017-02-28`, logika respons berfungsi setara dengan templat pemetaan respons berikut:

```
$util.toJson($ctx.result)
```

Secara dangkal, bypass template pemetaan beroperasi mirip dengan menggunakan templat pemetaan tertentu seperti yang ditunjukkan pada contoh sebelumnya. Namun, di balik layar, evaluasi template pemetaan dielakkan sepenuhnya. Karena langkah evaluasi template dilewati, aplikasi mungkin mengalami lebih sedikit overhead dan latensi selama respons dalam beberapa skenario dibandingkan dengan fungsi Lambda dengan template pemetaan respons yang perlu dievaluasi. 

### Penanganan kesalahan khusus dalam respons Resolver Lambda Langsung
<a name="lambda-mapping-template-bypass-errors"></a>

Anda dapat menyesuaikan respons kesalahan dari fungsi Lambda yang dipanggil Direct Lambda Resolvers dengan memunculkan pengecualian khusus. Contoh berikut menunjukkan cara membuat pengecualian kustom menggunakan JavaScript:

```
class CustomException extends Error {
  constructor(message) {
    super(message);
    this.name = "CustomException";
  }
}
 
throw new CustomException("Custom message");
```

Ketika pengecualian dinaikkan, `errorType` dan `errorMessage` adalah `name` dan`message`, masing-masing, dari kesalahan khusus yang dilemparkan.

Jika `errorType` ada`UnauthorizedException`, AWS AppSync mengembalikan pesan default (`"You are not authorized to make this call."`) bukan pesan kustom.

Cuplikan berikut adalah contoh respons GraphQL yang menunjukkan kustom: `errorType`

```
{
  "data": {
    "query": null
  },
  "errors": [
    {
      "path": [
        "query"
      ],
      "data": null,
      "errorType": "CustomException",
      "errorInfo": null,
      "locations": [
        {
          "line": 5,
          "column": 10,
          "sourceName": null
        }
      ],
      "message": "Custom Message"
    }
  ]
}
```

### Resolver Lambda Langsung: Batching diaktifkan
<a name="lambda-resolvers-batching"></a>

Anda dapat mengaktifkan batching untuk Resolver Lambda Langsung Anda dengan mengonfigurasi `maxBatchSize` pada resolver Anda. Bila `maxBatchSize` disetel ke nilai yang lebih besar daripada `0` untuk penyelesai Lambda Langsung, AWS AppSync kirimkan permintaan dalam batch ke fungsi Lambda Anda dalam ukuran hingga. `maxBatchSize` 

Menyetel `maxBatchSize` ke `0` pada penyelesai Lambda Langsung mematikan batching.

Untuk informasi lebih lanjut tentang cara kerja batching dengan resolver Lambda, lihat. [Kasus penggunaan lanjutan: Batching](tutorial-lambda-resolvers.md#advanced-use-case-batching)

#### Meminta template pemetaan
<a name="lambda-resolvers-batching-request-template"></a>

Ketika batching diaktifkan dan template pemetaan permintaan tidak disediakan, AWS AppSync mengirimkan daftar `Context` objek sebagai `BatchInvoke` operasi langsung ke fungsi Lambda Anda.

#### Templat pemetaan respons
<a name="lambda-resolvers-batching-response-template"></a>

Saat batching diaktifkan dan templat pemetaan respons tidak disediakan, logika respons setara dengan templat pemetaan respons berikut:

```
#if( $context.result && $context.result.errorMessage )
      $utils.error($context.result.errorMessage, $context.result.errorType,
      $context.result.data)
#else
      $utils.toJson($context.result.data)
#end
```

Fungsi Lambda harus mengembalikan daftar hasil dalam urutan yang sama dengan daftar `Context` objek yang dikirim. Anda dapat mengembalikan kesalahan individu dengan memberikan `errorMessage` dan `errorType` untuk hasil tertentu. Setiap hasil dalam daftar memiliki format berikut:

```
{
   "data" : { ... }, // your data
   "errorMessage" : { ... }, // optional, if included an error entry is added to the "errors" object in the AppSync response 
   "errorType" : { ... } // optional, the error type
}
```

**catatan**  
Bidang lain dalam objek hasil saat ini diabaikan.

#### Menangani kesalahan dari Lambda
<a name="lambda-resolvers-batching-error-handling"></a>

Anda dapat mengembalikan kesalahan untuk semua hasil dengan melempar pengecualian atau kesalahan dalam fungsi Lambda Anda. Jika permintaan payload atau ukuran respons untuk permintaan batch Anda terlalu besar, Lambda mengembalikan kesalahan. Dalam hal ini, Anda harus mempertimbangkan untuk mengurangi `maxBatchSize` atau mengurangi ukuran muatan respons.

Untuk informasi tentang penanganan kesalahan individu, lihat[Mengembalikan kesalahan individu](tutorial-lambda-resolvers.md#returning-individual-errors).

#### Contoh fungsi Lambda
<a name="sample-lambda-function"></a>

Dengan menggunakan skema di bawah ini, Anda dapat membuat Resolver Lambda Langsung untuk penyelesai bidang dan mengaktifkan `Post.relatedPosts` pengelompokan dengan mengatur di atas: `maxBatchSize` `0`

```
schema {
    query: Query
    mutation: Mutation
}

type Query {
    getPost(id:ID!): Post
    allPosts: [Post]
}

type Mutation {
    addPost(id: ID!, author: String!, title: String, content: String, url: String): Post!
}

type Post {
    id: ID!
    author: String!
    title: String
    content: String
    url: String
    ups: Int
    downs: Int
    relatedPosts: [Post]
}
```

Dalam kueri berikut, fungsi Lambda akan dipanggil dengan kumpulan permintaan untuk diselesaikan: `relatedPosts`

```
query getAllPosts {
  allPosts {
    id
    relatedPosts {
      id
    }
  }
}
```

Implementasi sederhana dari fungsi Lambda disediakan di bawah ini:

```
const posts = {
  1: {
    id: '1',
    title: 'First book',
    author: 'Author1',
    url: 'https://amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1',
    ups: '100',
    downs: '10',
  },
  2: {
    id: '2',
    title: 'Second book',
    author: 'Author2',
    url: 'https://amazon.com',
    content: 'SAMPLE TEXT AUTHOR 2 SAMPLE TEXT AUTHOR 2 SAMPLE TEXT',
    ups: '100',
    downs: '10',
  },
  3: { id: '3', title: 'Third book', author: 'Author3', url: null, content: null, ups: null, downs: null },
  4: {
    id: '4',
    title: 'Fourth book',
    author: 'Author4',
    url: 'https://www.amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4',
    ups: '1000',
    downs: '0',
  },
  5: {
    id: '5',
    title: 'Fifth book',
    author: 'Author5',
    url: 'https://www.amazon.com/',
    content: 'SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT',
    ups: '50',
    downs: '0',
  },
}

const relatedPosts = {
  1: [posts['4']],
  2: [posts['3'], posts['5']],
  3: [posts['2'], posts['1']],
  4: [posts['2'], posts['1']],
  5: [],
}
exports.handler = async (event) => {
  console.log('event ->', event)
  // retrieve the ID of each post
  const ids = event.map((context) => context.source.id)
  // fetch the related posts for each post id
  const related = ids.map((id) => relatedPosts[id])

  // return the related posts; or an error if none were found
  return related.map((r) => {
    if (r.length > 0) {
      return { data: r }
    } else {
      return { data: null, errorMessage: 'Not found', errorType: 'ERROR' }
    }
  })
}
```