Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Integrasi proxy Lambda di API Gateway
Bagian berikut menunjukkan cara menggunakan integrasi proxy Lambda.
**Topics**
+ [Memahami integrasi proxy API Gateway Lambda](#api-gateway-create-api-as-simple-proxy)
+ [Support untuk header multi-nilai dan parameter string kueri](#apigateway-multivalue-headers-and-parameters)
+ [Format input fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-input-format)
+ [Format output dari fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-output-format)
+ [Siapkan integrasi proxy Lambda untuk API Gateway menggunakan AWS CLI](set-up-lambda-proxy-integration-using-cli.md)
+ [Siapkan sumber daya proxy dengan integrasi proxy Lambda dengan definisi OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## Memahami integrasi proxy API Gateway Lambda
Integrasi proxy Amazon API Gateway Lambda adalah mekanisme yang sederhana, kuat, dan gesit untuk membangun API dengan penyiapan metode API tunggal. Integrasi proxy Lambda memungkinkan klien untuk memanggil satu fungsi Lambda di backend. Fungsi ini mengakses banyak sumber daya atau fitur AWS layanan lain, termasuk memanggil fungsi Lambda lainnya.
Dalam integrasi proxy Lambda, ketika klien mengirimkan permintaan API, API Gateway meneruskan ke fungsi Lambda terintegrasi [objek peristiwa](#api-gateway-simple-proxy-for-lambda-input-format), kecuali urutan parameter permintaan tidak dipertahankan. [Data permintaan](#api-gateway-simple-proxy-for-lambda-input-format) ini mencakup header permintaan, parameter string kueri, variabel jalur URL, payload, dan data konfigurasi API. Data konfigurasi dapat mencakup nama tahap penyebaran saat ini, variabel tahap, identitas pengguna, atau konteks otorisasi (jika ada). Fungsi backend Lambda mem-parsing data permintaan yang masuk untuk menentukan respons yang dikembalikan. [Agar API Gateway meneruskan output Lambda sebagai respons API ke klien, fungsi Lambda harus mengembalikan hasilnya dalam format ini.](#api-gateway-simple-proxy-for-lambda-output-format)
Karena API Gateway tidak terlalu banyak campur tangan antara klien dan fungsi Lambda backend untuk integrasi proxy Lambda, klien dan fungsi Lambda terintegrasi dapat beradaptasi dengan perubahan satu sama lain tanpa merusak pengaturan integrasi API yang ada. Untuk mengaktifkan ini, klien harus mengikuti protokol aplikasi yang diberlakukan oleh fungsi Lambda backend.
Anda dapat menyiapkan integrasi proxy Lambda untuk metode API apa pun. Tetapi integrasi proxy Lambda lebih kuat ketika dikonfigurasi untuk metode API yang melibatkan sumber daya proxy generik. Sumber daya proxy generik dapat dilambangkan dengan variabel jalur template khusus, placeholder metode catch-all `{proxy+}``ANY`, atau keduanya. Klien dapat meneruskan input ke fungsi Lambda backend dalam permintaan masuk sebagai parameter permintaan atau muatan yang berlaku. Parameter permintaan termasuk header, variabel jalur URL, parameter string kueri, dan payload yang berlaku. Fungsi Lambda terintegrasi memverifikasi semua sumber input sebelum memproses permintaan dan menanggapi klien dengan pesan kesalahan yang berarti jika ada input yang diperlukan yang hilang.
Saat memanggil metode API yang terintegrasi dengan metode HTTP generik `ANY` dan sumber daya generik`{proxy+}`, klien mengirimkan permintaan dengan metode HTTP tertentu sebagai pengganti. `ANY` Klien juga menentukan jalur URL tertentu, bukan`{proxy+}`, dan menyertakan header yang diperlukan, parameter string kueri, atau payload yang berlaku.
Daftar berikut merangkum perilaku runtime dari berbagai metode API dengan integrasi proxy Lambda:
+ `ANY /{proxy+}`: Klien harus memilih metode HTTP tertentu, harus menetapkan hierarki jalur sumber daya tertentu, dan dapat mengatur header, parameter string kueri, dan muatan yang berlaku untuk meneruskan data sebagai input ke fungsi Lambda terintegrasi.
+ `ANY /res`: Klien harus memilih metode HTTP tertentu dan dapat mengatur header, parameter string kueri, dan payload yang berlaku untuk meneruskan data sebagai input ke fungsi Lambda terintegrasi.
+ `GET|POST|PUT|... /{proxy+}`: Klien dapat mengatur hierarki jalur sumber daya tertentu, header apa pun, parameter string kueri, dan muatan yang berlaku untuk meneruskan data sebagai input ke fungsi Lambda terintegrasi.
+ `GET|POST|PUT|... /res/{path}/...`: Klien harus memilih segmen jalur tertentu (untuk `{path}` variabel) dan dapat mengatur header permintaan, parameter string kueri, dan payload yang berlaku untuk meneruskan data input ke fungsi Lambda terintegrasi.
+ `GET|POST|PUT|... /res`: Klien dapat memilih header permintaan, parameter string kueri, dan payload yang berlaku untuk meneruskan data input ke fungsi Lambda terintegrasi.
Baik sumber daya proxy `{proxy+}` dan sumber daya kustom `{custom}` dinyatakan sebagai variabel jalur templat. Namun `{proxy+}` dapat merujuk ke sumber daya apa pun di sepanjang hierarki jalur, sementara `{custom}` mengacu pada segmen jalur tertentu saja. Misalnya, toko kelontong mungkin mengatur inventaris produk online-nya berdasarkan nama departemen, kategori produksi, dan jenis produk. Situs web toko kelontong kemudian dapat mewakili produk yang tersedia dengan variabel jalur template berikut dari sumber daya khusus:. `/{department}/{produce-category}/{product-type}` Misalnya, apel diwakili oleh `/produce/fruit/apple` dan wortel oleh`/produce/vegetables/carrot`. Ini juga dapat digunakan `/{proxy+}` untuk mewakili departemen apa pun, kategori produk apa pun, atau jenis produk apa pun yang dapat dicari pelanggan saat berbelanja di toko online. Misalnya, `/{proxy+}` dapat merujuk ke salah satu item berikut:
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
Untuk memungkinkan pelanggan mencari produk apa pun yang tersedia, kategori produksinya, dan departemen toko terkait, Anda dapat mengekspos satu metode `GET /{proxy+}` dengan izin hanya-baca. Demikian pula, untuk memungkinkan supervisor memperbarui inventaris `produce` departemen, Anda dapat menyiapkan metode tunggal lain `PUT /produce/{proxy+}` dengan read/write izin. Untuk memungkinkan kasir memperbarui total sayuran yang sedang berjalan, Anda dapat mengatur `POST /produce/vegetables/{proxy+}` metode dengan read/write izin. Untuk membiarkan manajer toko melakukan tindakan apa pun yang mungkin pada produk apa pun yang tersedia, pengembang toko online dapat mengekspos `ANY /{proxy+}` metode dengan read/write izin. Dalam kasus apa pun, pada waktu berjalan, pelanggan atau karyawan harus memilih produk tertentu dari jenis tertentu di departemen yang dipilih, kategori produk tertentu di departemen yang dipilih, atau departemen tertentu.
Untuk informasi selengkapnya tentang menyiapkan integrasi proxy API Gateway, lihat[Siapkan integrasi proxy dengan sumber daya proxy](api-gateway-set-up-simple-proxy.md).
Integrasi proxy mengharuskan klien memiliki pengetahuan yang lebih rinci tentang persyaratan backend. Oleh karena itu, untuk memastikan kinerja aplikasi dan pengalaman pengguna yang optimal, pengembang backend harus berkomunikasi dengan jelas kepada pengembang klien persyaratan backend, dan memberikan mekanisme umpan balik kesalahan yang kuat ketika persyaratan tidak terpenuhi.
## Support untuk header multi-nilai dan parameter string kueri
API Gateway mendukung beberapa header dan parameter string kueri yang memiliki nama yang sama. Header multi-nilai serta header dan parameter nilai tunggal dapat digabungkan dalam permintaan dan tanggapan yang sama. Untuk informasi selengkapnya, lihat [Format input fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-input-format) dan [Format output dari fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-output-format).
## Format input fungsi Lambda untuk integrasi proxy
Dalam integrasi proxy Lambda, API Gateway memetakan seluruh permintaan klien ke `event` parameter input fungsi Lambda backend. Contoh berikut menunjukkan struktur peristiwa yang dikirimkan API Gateway ke integrasi proxy Lambda.
Dalam contoh ini, kami berasumsi bahwa pemanggilan ke API Gateway adalah sebagai berikut:
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
Outputnya terlihat seperti berikut:
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "IP",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
**catatan**
Dalam masukan:
`headers`Kuncinya hanya dapat berisi header nilai tunggal.
`multiValueHeaders`Kuncinya dapat berisi header multi-nilai serta header nilai tunggal.
Jika Anda menentukan nilai untuk keduanya `headers` dan`multiValueHeaders`, API Gateway menggabungkannya ke dalam satu daftar. Jika pasangan kunci-nilai yang sama ditentukan di keduanya, hanya nilai dari yang `multiValueHeaders` akan muncul dalam daftar gabungan.
Dalam input ke fungsi Lambda backend, `requestContext` objek adalah peta pasangan kunci-nilai. Di setiap pasangan, kuncinya adalah nama properti variabel [$context](api-gateway-mapping-template-reference.md#context-variable-reference), dan nilainya adalah nilai properti itu. API Gateway mungkin menambahkan kunci baru ke peta.
Bergantung pada fitur yang diaktifkan, `requestContext` peta dapat bervariasi dari API ke API. Misalnya, dalam contoh sebelumnya, tidak ada jenis otorisasi yang ditentukan, jadi tidak ada `$context.authorizer.*` atau `$context.identity.*` properti yang ada. Ketika jenis otorisasi ditentukan, ini menyebabkan API Gateway meneruskan informasi pengguna yang diotorisasi ke titik akhir integrasi dalam `requestContext.identity` objek sebagai berikut:
+ Ketika jenis otorisasi`AWS_IAM`, informasi pengguna yang berwenang mencakup `$context.identity.*` properti.
+ Ketika jenis otorisasi adalah `COGNITO_USER_POOLS` (Amazon Cognito Authorizer), informasi `$context.identity.cognito*` pengguna yang berwenang termasuk dan properti. `$context.authorizer.claims.*`
+ Ketika jenis otorisasi adalah `CUSTOM` (Lambda Authorizer), informasi pengguna yang berwenang `$context.authorizer.principalId` termasuk dan properti lain yang berlaku. `$context.authorizer.*`
## Format output dari fungsi Lambda untuk integrasi proxy
Dalam integrasi proxy Lambda, API Gateway memerlukan fungsi Lambda backend untuk mengembalikan output sesuai dengan format JSON berikut:
```
{
"isBase64Encoded": {{true|false}},
"statusCode": {{httpStatusCode}},
"headers": { "{{headerName}}": "{{headerValue}}", ... },
"multiValueHeaders": { "{{headerName}}": ["{{headerValue}}", "{{headerValue2}}", ...], ... },
"body": "{{...}}"
}
```
Dalam output:
+ `multiValueHeaders`Tombol `headers` dan dapat tidak ditentukan jika tidak ada header respons tambahan yang akan dikembalikan.
+ `headers`Kuncinya hanya dapat berisi header nilai tunggal.
+ `multiValueHeaders`Kuncinya dapat berisi header multi-nilai serta header nilai tunggal. Anda dapat menggunakan `multiValueHeaders` kunci untuk menentukan semua header tambahan Anda, termasuk yang bernilai tunggal.
+ Jika Anda menentukan nilai untuk keduanya `headers` dan`multiValueHeaders`, API Gateway menggabungkannya ke dalam satu daftar. Jika pasangan kunci-nilai yang sama ditentukan di keduanya, hanya nilai dari yang `multiValueHeaders` akan muncul dalam daftar gabungan.
Untuk mengaktifkan CORS untuk integrasi proxy Lambda, Anda harus `Access-Control-Allow-Origin:{{domain-name}}` menambahkan ke output. `headers` `{{domain-name}}`bisa `*` untuk nama domain apa pun. Output `body` disusun ke frontend sebagai payload respons metode. **Jika `body` adalah gumpalan biner, Anda dapat menyandikannya sebagai string yang dikodekan Base64 dengan mengatur `true` dan `isBase64Encoded` mengonfigurasi `*/*` sebagai Tipe Media Biner.** Jika tidak, Anda dapat mengaturnya ke `false` atau membiarkannya tidak ditentukan.
**catatan**
Untuk informasi selengkapnya tentang mengaktifkan dukungan biner, lihat[Mengaktifkan dukungan biner menggunakan konsol API Gateway](api-gateway-payload-encodings-configure-with-console.md). Untuk contoh fungsi Lambda, lihat. [Kembalikan media biner dari integrasi proxy Lambda di API Gateway](lambda-proxy-binary-media.md)
Jika output fungsi dari format yang berbeda, API Gateway mengembalikan respon `502 Bad Gateway` kesalahan.
Untuk mengembalikan respons dalam fungsi Lambda di Node.js, Anda dapat menggunakan perintah seperti berikut:
+ Untuk mengembalikan hasil yang sukses, hubungi`callback(null, {"statusCode": 200, "body": "results"})`.
+ Untuk melempar pengecualian, panggil`callback(new Error('internal server error'))`.
+ Untuk kesalahan sisi klien (jika, misalnya, parameter yang diperlukan tidak ada), Anda dapat memanggil `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` untuk mengembalikan kesalahan tanpa melempar pengecualian.
Dalam `async` fungsi Lambda di Node.js, sintaks yang setara adalah:
+ Untuk mengembalikan hasil yang sukses, hubungi`return {"statusCode": 200, "body": "results"}`.
+ Untuk melempar pengecualian, panggil`throw new Error("internal server error")`.
+ Untuk kesalahan sisi klien (jika, misalnya, parameter yang diperlukan tidak ada), Anda dapat memanggil `return {"statusCode": 400, "body": "Missing parameters of ..."}` untuk mengembalikan kesalahan tanpa melempar pengecualian.