Mengubah permintaan dan respons API untuk API HTTP di API Gateway

Anda dapat memodifikasi permintaan API dari klien sebelum mereka mencapai integrasi backend Anda. Anda juga dapat mengubah respons dari integrasi sebelum API Gateway mengembalikan respons ke klien. Anda menggunakan pemetaan parameter untuk memodifikasi permintaan API dan respons untuk API HTTP. Untuk menggunakan pemetaan parameter, Anda menentukan permintaan API atau parameter respons untuk dimodifikasi, dan menentukan cara memodifikasi parameter tersebut.

Mengubah permintaan API

Anda menggunakan parameter permintaan untuk mengubah permintaan sebelum mencapai integrasi backend Anda. Anda dapat memodifikasi header, string kueri, atau jalur permintaan.

Parameter permintaan adalah peta nilai kunci. Kunci mengidentifikasi lokasi parameter permintaan untuk diubah, dan bagaimana mengubahnya. Nilai menentukan data baru untuk parameter.

Tabel berikut menunjukkan kunci yang didukung.

Tombol pemetaan parameter
Tipe	Sintaks
Header	append|overwrite|remove:header.headername
String kueri	append|overwrite|remove:querystring.querystring-name
Jalur	overwrite:path

Tabel berikut menunjukkan nilai yang didukung yang dapat Anda petakan ke parameter.

Minta nilai pemetaan parameter
Tipe	Sintaks	Catatan
Nilai header	$ request.header. nama atau $ {request.header. nama}	Nama header tidak peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai header dengan koma, misalnya"header1": "value1,value2". Beberapa header dicadangkan. Untuk mempelajari selengkapnya, lihat Header yang dipesan.
Nilai string kueri	$request.querystring. nama atau $ {request.querystring. nama}	Nama string kueri peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai dengan koma, misalnya"querystring1" "Value1,Value2".
Isi permintaan	$ request.body. nama atau $ {request.body. nama}	Ekspresi jalur JSON. Penurunan rekursif ($request.body..name)dan ekspresi filter (?(expression)) tidak didukung. catatan Saat Anda menentukan jalur JSON, API Gateway memotong isi permintaan pada 100 KB dan kemudian menerapkan ekspresi seleksi. Untuk mengirim muatan yang lebih besar dari 100 KB, tentukan$request.body.
Jalur permintaan	$request.path atau $ {request.path}	Jalur permintaan, tanpa nama panggung.
Parameter jalur	$request.path. nama atau $ {request.path. nama}	Nilai parameter jalur dalam permintaan. Misalnya jika rutenya/pets/{petId}, Anda dapat memetakan petId parameter dari permintaan dengan$request.path.petId.
Variabel konteks	$ konteks. VariableName atau $ {context. VariableName}	Nilai variabel konteks. catatan Hanya karakter khusus . dan _ didukung.
Variabel tahap	$ StageVariables. VariableName atau $ {stageVariables. VariableName}	Nilai variabel tahap.
Nilai statis	tali	Nilai konstan.

catatan

Untuk menggunakan beberapa variabel dalam ekspresi seleksi, lampirkan variabel dalam tanda kurung. Misalnya, ${request.path.name} ${request.path.id}.

Mengubah respons API

Anda menggunakan parameter respons untuk mengubah respons HTTP dari integrasi backend sebelum mengembalikan respons ke klien. Anda dapat mengubah header atau kode status respons sebelum API Gateway mengembalikan respons ke klien.

Anda mengonfigurasi parameter respons untuk setiap kode status yang dikembalikan oleh integrasi Anda. Parameter respons adalah peta nilai kunci. Kunci mengidentifikasi lokasi parameter permintaan untuk diubah, dan bagaimana mengubahnya. Nilai menentukan data baru untuk parameter.

Tabel berikut menunjukkan kunci yang didukung.

Tombol pemetaan parameter respons
Tipe	Sintaks
Header	append|overwrite|remove:header.headername
Kode status	overwrite:statuscode

Tabel berikut menunjukkan nilai yang didukung yang dapat Anda petakan ke parameter.

Nilai pemetaan parameter respons
Tipe	Sintaks	Catatan
Nilai header	$ response.header. nama atau $ {response.header. nama}	Nama header tidak peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai header dengan koma, misalnya"header1": "value1,value2". Beberapa header dicadangkan. Untuk mempelajari selengkapnya, lihat Header yang dipesan.
Isi respons	$response.body. nama atau $ {response.body. nama}	Ekspresi jalur JSON. Descent rekursif ($response.body..name) dan ekspresi filter (?(expression)) tidak didukung. catatan Saat Anda menentukan jalur JSON, API Gateway memotong badan respons pada 100 KB dan kemudian menerapkan ekspresi pemilihan. Untuk mengirim muatan yang lebih besar dari 100 KB, tentukan$response.body.
Variabel konteks	$ konteks. VariableName atau $ {context. VariableName}	Nilai variabel konteks yang didukung.
Variabel tahap	$ StageVariables. VariableName atau $ {stageVariables. VariableName}	Nilai variabel tahap.
Nilai statis	tali	Nilai konstan.

catatan

Untuk menggunakan beberapa variabel dalam ekspresi seleksi, lampirkan variabel dalam tanda kurung. Misalnya, ${request.path.name} ${request.path.id}.

Header yang dipesan

Header berikut dicadangkan. Anda tidak dapat mengonfigurasi pemetaan permintaan atau respons untuk header ini.

• akses-kontrol-*

• apigw-*

• Otorisasi

• Koneksi

• Pengkodean Konten

• Content-Length

• Content-Location

• Diteruskan

• Jaga-Hidup

• Asal

• Proksi-Otentikasi

• Otorisasi Proksi

• TE

• Trailer

• Transfer-Encoding

• Peningkatan

• x-amz-*

• x-amzn-*

• X-Diteruskan-Untuk

• X-Forwarded-Host

• X-Diteruskan-Proto

• Melalui

Contoh

AWS CLI Contoh berikut mengkonfigurasi pemetaan parameter. Misalnya AWS CloudFormation template, lihat GitHub.

Menambahkan header ke permintaan API

Contoh berikut menambahkan header bernama header1 ke permintaan API sebelum mencapai integrasi backend Anda. API Gateway mengisi header dengan ID permintaan.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }' 

Ganti nama header permintaan

Contoh berikut mengganti nama header permintaan dari header1 ke. header2

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'

Mengubah respon dari integrasi

Contoh berikut mengkonfigurasi parameter respons untuk integrasi. Saat integrasi mengembalikan kode status 500, API Gateway mengubah kode status menjadi 403, dan menambahkan header1 1 ke respons. Saat integrasi mengembalikan kode status 404, API Gateway menambahkan error header ke respons.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'

Hapus pemetaan parameter yang dikonfigurasi

Contoh perintah berikut menghapus parameter permintaan yang dikonfigurasi sebelumnya untukappend:header.header1. Ini juga menghapus parameter respons yang dikonfigurasi sebelumnya untuk kode status 200.

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'