Ubah API permintaan dan tanggapan untuk HTTP APIs di API Gateway - APIGerbang Amazon
Mengubah permintaan APIMengubah tanggapan APIHeader yang dipesanContoh

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

Ubah API permintaan dan tanggapan untuk HTTP APIs di API Gateway

Anda dapat memodifikasi API permintaan 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 mengubah API permintaan dan tanggapan. HTTP APIs Untuk menggunakan pemetaan parameter, Anda menentukan parameter API permintaan atau 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.

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.

Tipe Sintaks Catatan
Nilai header $ request.header.name atau $ {request.header.name} Nama header tidak peka huruf besar/kecil. APIGateway 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.name atau $ {request.querystring.name} Nama string kueri peka huruf besar/kecil. APIGateway menggabungkan beberapa nilai dengan koma, misalnya"querystring1" "Value1,Value2".
Isi permintaan $ request.body.name atau $ {request.body.name} Ekspresi JSON jalur. Penurunan rekursif ($request.body..name)dan ekspresi filter (?(expression)) tidak didukung.
catatan

Saat Anda menentukan JSON jalur, API Gateway memotong badan permintaan pada 100 KB dan kemudian menerapkan ekspresi pemilihan. 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.name atau $ {request.path.name} 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 string Nilai konstan.
catatan

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

Mengubah tanggapan API

Anda menggunakan parameter respons untuk mengubah HTTP respons 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.

Tipe Sintaks
Header append|overwrite|remove:header.headername
Kode status overwrite:statuscode

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

Tipe Sintaks Catatan
Nilai header $ response.header.name atau $ {response.header.name} Nama header tidak peka huruf besar/kecil. APIGateway menggabungkan beberapa nilai header dengan koma, misalnya"header1": "value1,value2". Beberapa header dicadangkan. Untuk mempelajari selengkapnya, lihat Header yang dipesan.
Isi respons $response.body.name atau $ {response.body.name} Ekspresi JSON jalur. Descent rekursif ($response.body..name) dan ekspresi filter (?(expression)) tidak didukung.
catatan

Saat Anda menentukan JSON jalur, 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 string 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 API permintaan

Contoh berikut menambahkan header bernama header1 ke API permintaan sebelum mencapai integrasi backend Anda. APIGateway 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. Ketika integrasi mengembalikan kode status 500, API Gateway mengubah kode status menjadi 403, dan menambahkan header1 1 ke respons. Ketika 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" : {}}'