Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Referensi pemetaan data permintaan dan respons API Amazon API Gateway
Bagian ini menjelaskan cara mengatur pemetaan data dari data permintaan metode API, termasuk data lain yang disimpan dalam context, stage, atau utilvariabel, ke parameter permintaan integrasi yang sesuai dan dari data respons integrasi, termasuk data lainnya, ke parameter respons metode. Data permintaan metode mencakup parameter permintaan (jalur, string kueri, header) dan isi. Data respons integrasi mencakup parameter respons (header) dan badan. Untuk informasi lebih lanjut tentang menggunakan variabel tahap, lihatReferensi variabel tahap API Gateway untuk REST APIs di API Gateway.
Topik
Metode peta meminta data ke parameter permintaan integrasi
Parameter permintaan integrasi, dalam bentuk variabel jalur, string kueri atau header, dapat dipetakan dari parameter permintaan metode yang ditentukan dan payload.
Dalam tabel berikut,
adalah nama parameter permintaan metode dari jenis parameter yang diberikan. Itu harus cocok dengan ekspresi regulerPARAM_NAME
'^[a-zA-Z0-9._$-]+$]'
. Itu harus didefinisikan sebelum dapat direferensikan.
adalah JSONPath ekspresi untuk bidang JSON dari badan permintaan atau respons.JSONPath_EXPRESSION
catatan
"$"
Awalan dihilangkan dalam sintaks ini.
Sumber data yang dipetakan |
Ekspresi pemetaan |
---|---|
Jalur permintaan metode | method.request.path. |
String kueri permintaan metode | method.request.querystring. |
String kueri permintaan metode multi-nilai | method.request.multivaluequerystring. |
Header permintaan metode | method.request.header. |
Header permintaan metode multi-nilai | method.request.multivalueheader. |
Badan permintaan metode | method.request.body |
Metode permintaan badan (JsonPath) | method.request.body. . |
Variabel tahap | stageVariables. |
Variabel konteks | context. yang harus menjadi salah satu variabel konteks yang didukung. |
Nilai statis | . STATIC_VALUE Ini adalah string literal dan harus tertutup dalam sepasang tanda kutip tunggal. |
contoh Pemetaan dari parameter permintaan metode di OpenAPI
Contoh berikut menunjukkan cuplikan OpenAPI yang memetakan:
-
header permintaan metode, bernama
methodRequestHeaderParam
, ke dalam parameter jalur permintaan integrasi, bernamaintegrationPathParam
-
string kueri permintaan metode multi-nilai, bernama
methodRequestQueryParam
, ke dalam string kueri permintaan integrasi, bernamaintegrationQueryParam
... "requestParameters" : { "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam", "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam" } ...
Parameter permintaan integrasi juga dapat dipetakan dari bidang di badan permintaan JSON menggunakan ekspresi. JSONPath
contoh Pemetaan dari badan permintaan metode di OpenAPI
Contoh berikut menunjukkan cuplikan OpenAPI yang memetakan 1) badan permintaan metode ke header permintaan integrasi, bernamabody-header
, dan 2) bidang JSON dari tubuh, seperti yang diungkapkan oleh ekspresi JSON (petstore.pets[0].name
, tanpa awalan). $.
... "requestParameters" : { "integration.request.header.body-header" : "method.request.body", "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name", } ...
Memetakan data respons integrasi ke header respons metode
Parameter header respons metode dapat dipetakan dari header respons integrasi atau badan respons integrasi, $context
variabel, atau nilai statis. Tabel berikut menjelaskan metode respon ekspresi pemetaan header.
Sumber data yang dipetakan | Ekspresi pemetaan |
---|---|
Header respon integrasi | integration.response.header. |
Header respon integrasi | integration.response.multivalueheader. |
Badan respons integrasi | integration.response.body |
Integrasi respon body (JsonPath) | integration.response.body. |
Variabel tahap | stageVariables. |
Variabel konteks | context. yang harus menjadi salah satu variabel konteks yang didukung. |
Nilai statis | . STATIC_VALUE Ini adalah string literal dan harus tertutup dalam sepasang tanda kutip tunggal. |
contoh Pemetaan data dari respons integrasi di OpenAPI
Contoh berikut menunjukkan cuplikan OpenAPI yang memetakan 1) JSONPath kolom respons integrasiredirect.url
, ke dalam location
header respons permintaan; dan 2) header respons integrasi ke x-app-id
header respons metode. id
... "responseParameters" : { "method.response.header.location" : "integration.response.body.redirect.url", "method.response.header.id" : "integration.response.header.x-app-id", "method.response.header.items" : "integration.response.multivalueheader.item", } ...
Permintaan peta dan muatan respons antara metode dan integrasi
API Gateway menggunakan mesin Velocity Template Language (VTL)
Template VTL menggunakan JSONPath ekspresi, parameter lain seperti memanggil konteks dan variabel tahap, dan fungsi utilitas untuk memproses data JSON.
Jika model didefinisikan untuk menggambarkan struktur data muatan, API Gateway dapat menggunakan model untuk menghasilkan template pemetaan kerangka untuk permintaan integrasi atau respons integrasi. Anda dapat menggunakan template kerangka sebagai bantuan untuk menyesuaikan dan memperluas skrip VTL pemetaan. Namun, Anda dapat membuat template pemetaan dari awal tanpa menentukan model untuk struktur data payload.
Pilih templat pemetaan VTL
API Gateway menggunakan logika berikut untuk memilih template pemetaan, di Velocity Template Language (VTL)
Untuk payload permintaan, API Gateway menggunakan nilai Content-Type
header permintaan sebagai kunci untuk memilih template pemetaan untuk payload permintaan. Untuk payload respons, API Gateway menggunakan nilai Accept
header permintaan masuk sebagai kunci untuk memilih template pemetaan.
Ketika Content-Type
header tidak ada dalam permintaan, API Gateway mengasumsikan bahwa nilai defaultnya adalahapplication/json
. Untuk permintaan seperti itu, API Gateway digunakan application/json
sebagai kunci default untuk memilih template pemetaan, jika sudah ditentukan. Jika tidak ada template yang cocok dengan kunci ini, API Gateway meneruskan payload melalui unmapped jika properti PassThroughBehavior disetel ke or. WHEN_NO_MATCH
WHEN_NO_TEMPLATES
Ketika Accept
header tidak ditentukan dalam permintaan, API Gateway mengasumsikan bahwa nilai defaultnya adalahapplication/json
. Dalam kasus ini, API Gateway memilih template pemetaan yang ada application/json
untuk memetakan payload respons. Jika tidak ada template yang ditentukanapplication/json
, API Gateway memilih template pertama yang ada dan menggunakannya sebagai default untuk memetakan payload respons. Demikian pula, API Gateway menggunakan template pertama yang ada saat nilai Accept
header yang ditentukan tidak cocok dengan kunci template yang ada. Jika tidak ada template yang ditentukan, API Gateway hanya meneruskan payload respons melalui unmapped.
Misalnya, API memiliki application/json
template yang ditentukan untuk payload permintaan dan memiliki application/xml
template yang ditentukan untuk payload respons. Jika klien menetapkan"Content-Type :
application/json"
, dan "Accept : application/xml"
header dalam permintaan, muatan permintaan dan respons akan diproses dengan templat pemetaan yang sesuai. Jika Accept:application/xml
header tidak ada, template application/xml
pemetaan akan digunakan untuk memetakan payload respons. Untuk mengembalikan payload respons yang tidak dipetakan, Anda harus menyiapkan templat kosong untuk. application/json
Hanya tipe MIME yang digunakan dari Content-Type
header Accept
dan saat memilih template pemetaan. Misalnya, header "Content-Type: application/json; charset=UTF-8"
akan memiliki template permintaan dengan application/json
kunci yang dipilih.