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.

Memahami integrasi proxy API Gateway Lambda

Amazon API Gateway Integrasi proxy Lambda adalah mekanisme sederhana, kuat, dan gesit untuk membangun API dengan pengaturan metode API tunggal. Integrasi proxy Lambda memungkinkan klien untuk memanggil fungsi Lambda tunggal 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 objek peristiwa ke fungsi Lambda terintegrasi, kecuali bahwa urutan parameter permintaan tidak dipertahankan. Data permintaan ini mencakup header permintaan, parameter string kueri, variabel jalur URL, payload, dan data konfigurasi API. Data konfigurasi dapat mencakup nama tahap penerapan saat ini, variabel tahap, identitas pengguna, atau konteks otorisasi (jika ada). Fungsi backend Lambda mengurai data permintaan masuk untuk menentukan respons yang dikembalikan. Agar API Gateway meneruskan keluaran Lambda sebagai respons API ke klien, fungsi Lambda harus mengembalikan hasil dalam format ini.

Karena API Gateway tidak 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 mengatur 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 templat khusus{proxy+}, placeholder ANY metode catch-all, atau keduanya. Klien dapat meneruskan input ke fungsi Lambda backend dalam permintaan masuk sebagai parameter permintaan atau payload 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 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 sebagai pengganti{proxy+}, dan menyertakan header yang diperlukan, parameter string kueri, atau payload yang berlaku.

Daftar berikut merangkum perilaku runtime dari metode API yang berbeda dengan integrasi proxy Lambda:

Baik sumber daya proxy {proxy+} dan sumber daya khusus dinyat {custom} akan 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 dapat mengatur inventaris produk online-nya berdasarkan nama departemen, kategori produk, dan jenis produk. Situs web toko kelontong kemudian dapat mewakili produk yang tersedia dengan variabel jalur templat 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:

Untuk memungkinkan pelanggan mencari produk yang tersedia, kategori produknya, dan departemen toko terkait, Anda dapat mengekspo GET /{proxy+} s satu metode dengan izin baca-saja. Demikian pula, untuk memungkinkan supervisor memperbarui inventaris produce departemen, Anda dapat mengatur metode tunggal lainnya PUT /produce/{proxy+} dengan read/write izin. Untuk mengizinkan kasir memperbarui total sayuran, 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. Bagaimanapun, 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, lihatSiapkan integrasi proxy dengan sumber daya proxy.

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 mengkomunikasikan dengan jelas kepada pengembang klien persyaratan backend, dan memberikan mekanisme umpan balik kesalahan yang kuat ketika persyaratan tidak terpenuhi.

Dukungan untuk header multi-nilai dan parameter string kueri

API Gateway mendukung beberapa header dan parameter string kueri yang memiliki nama yang sama. Multi-value header 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 dan Format keluaran fungsi Lambda untuk integrasi proxy.

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 dikirim API Gateway ke integrasi proxy Lambda.

Dalam contoh ini, kita mengasumsikan bahwa pemanggilan ke API Gateway adalah sebagai berikut:

curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1&parameter2=value1&parameter2=value2&parameter3=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
}

Dalam input ke fungsi Lambda backend, requestContext objek adalah peta pasangan kunci-nilai. Pada setiap pasangan, kuncinya adalah nama properti variabel $context, dan nilainya adalah nilai properti itu. API Gateway mungkin menambahkan kunci baru ke peta.

Tergantung 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.* $context.identity.* properti atau yang ada. Ketika jenis otorisasi ditentukan, ini menyebabkan API Gateway meneruskan informasi pengguna resmi ke titik akhir integrasi dalam requestContext.identity objek sebagai berikut:

Format keluaran 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:

Untuk mengaktifkan CORS untuk integrasi proxy Lambda, Anda harus menambahkan Access-Control-Allow-Origin:domain-name ke output. headers domain-namebisa * untuk nama domain apa pun. Output body disusun ke frontend sebagai payload respons metode. Jika body merupakan gumpalan biner, Anda dapat mengkodekannya sebagai Base64-encoded string dengan menyetel isBase64Encoded ke true dan mengonfigurasi */* sebagai Jenis Media Biner. Jika tidak, Anda dapat mengaturnya ke false atau membiarkannya tidak ditentukan.

Jika output fungsi memiliki format yang berbeda, API Gateway mengembalikan respons 502 Bad Gateway kesalahan.

Untuk mengembalikan respons dalam fungsi Lambda di Node.js, Anda dapat menggunakan perintah seperti berikut:

Dalam async fungsi Lambda di Node.js, sintaks yang setara adalah: