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

• Memetakan data respons integrasi ke header respons metode

• Permintaan peta dan muatan respons antara metode dan integrasi

• Perilaku passthrough integrasi

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, PARAM_NAME adalah nama parameter permintaan metode dari jenis parameter yang diberikan. Itu harus cocok dengan ekspresi reguler'^[a-zA-Z0-9._$-]+$]'. Itu harus didefinisikan sebelum dapat direferensikan. JSONPath_EXPRESSIONadalah JSONPath ekspresi untuk bidang JSON dari badan permintaan atau respons.

catatan

"$"Awalan dihilangkan dalam sintaks ini.

Sumber data yang dipetakan	Ekspresi pemetaan
Jalur permintaan metode	method.request.path.PARAM_NAME
String kueri permintaan metode	method.request.querystring.PARAM_NAME
String kueri permintaan metode multi-nilai	method.request.multivaluequerystring.PARAM_NAME
Header permintaan metode	method.request.header.PARAM_NAME
Header permintaan metode multi-nilai	method.request.multivalueheader.PARAM_NAME
Badan permintaan metode	method.request.body
Metode permintaan badan (JsonPath)	method.request.body.JSONPath_EXPRESSION.
Variabel tahap	stageVariables.VARIABLE_NAME
Variabel konteks	context.VARIABLE_NAMEyang harus menjadi salah satu variabel konteks yang didukung.
Nilai statis	'STATIC_VALUE'. STATIC_VALUEIni 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, bernamamethodRequestHeaderParam, ke dalam parameter jalur permintaan integrasi, bernama integrationPathParam

• string kueri permintaan metode multi-nilai, bernamamethodRequestQueryParam, ke dalam string kueri permintaan integrasi, bernama integrationQueryParam

...
"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 Tabel berikut menunjukkan ekspresi pemetaan untuk badan permintaan metode dan bidang JSON nya.

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.PARAM_NAME
Header respon integrasi	integration.response.multivalueheader.PARAM_NAME
Badan respons integrasi	integration.response.body
Integrasi respon body (JsonPath)	integration.response.body.JSONPath_EXPRESSION
Variabel tahap	stageVariables.VARIABLE_NAME
Variabel konteks	context.VARIABLE_NAMEyang harus menjadi salah satu variabel konteks yang didukung.
Nilai statis	'STATIC_VALUE'. STATIC_VALUEIni 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) untuk memproses template pemetaan tubuh untuk permintaan integrasi dan respons integrasi. Templat pemetaan menerjemahkan payload permintaan metode ke muatan permintaan integrasi yang sesuai dan menerjemahkan badan respons integrasi ke badan respons metode.

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 memetakan payload dari permintaan metode ke permintaan integrasi yang sesuai atau untuk memetakan payload dari respons integrasi ke respons metode yang sesuai.

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.