Referensi pemetaan data API permintaan dan respons Amazon API Gateway

Bagian ini menjelaskan cara mengatur pemetaan data dari data permintaan metode, 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. API 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, lihatAPIReferensi variabel tahap gateway untuk REST APIs di API Gateway.

Topik

• Metode peta meminta data ke parameter permintaan integrasi
• Memetakan data respons integrasi ke header respons metode
• Memetakan permintaan 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.

Pada 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_EXPRESSION adalah JSONPath ekspresi untuk JSON bidang badan permintaan atau tanggapan.

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'. The STATIC_VALUE adalah string literal dan harus tertutup dalam sepasang tanda kutip tunggal.

contoh Pemetaan dari parameter permintaan metode di Open API

Contoh berikut menunjukkan API cuplikan Terbuka 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 JSON permintaan menggunakan JSONPathekspresi. Tabel berikut menunjukkan ekspresi pemetaan untuk badan permintaan metode dan JSON bidangnya.

contoh Pemetaan dari badan permintaan metode di Open API

Contoh berikut menunjukkan API cuplikan Terbuka yang memetakan 1) badan permintaan metode ke header permintaan integrasi, bernamabody-header, dan 2) JSON bidang tubuh, seperti yang dinyatakan oleh JSON ekspresi (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 respons integrasi	integration.response.header.PARAM_NAME
Header respons 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'. The STATIC_VALUE adalah string literal dan harus tertutup dalam sepasang tanda kutip tunggal.

contoh Pemetaan data dari respons integrasi di Open API

Contoh berikut menunjukkan API cuplikan Terbuka yang memetakan 1) respons integrasiredirect.url, JSONPath bidang ke location header respons permintaan; dan 2) x-app-id header respons integrasi ke header respons id metode.

...
"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",
            
}
...
                
            

Memetakan permintaan dan muatan respons antara metode dan integrasi

APIGateway 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.

VTLTemplate menggunakan JSONPath ekspresi, parameter lain seperti konteks panggilan 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 VTL skrip pemetaan. Namun, Anda dapat membuat template pemetaan dari awal tanpa menentukan model untuk struktur data payload.

Pilih templat VTL pemetaan

APIGateway 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 menggunakan application/json sebagai kunci default untuk memilih template pemetaan, jika sudah ditentukan. Jika tidak ada templat yang cocok dengan kunci ini, API Gateway meneruskan payload melalui unmapped jika passthroughBehaviorproperti 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 hal ini, API Gateway memilih template pemetaan yang ada application/json untuk memetakan payload respons. Jika tidak ada templat yang ditentukanapplication/json, API Gateway memilih templat pertama yang ada dan menggunakannya sebagai default untuk memetakan muatan respons. Demikian pula, API Gateway menggunakan template pertama yang ada ketika nilai Accept header yang ditentukan tidak cocok dengan kunci template yang ada. Jika tidak ada templat yang ditentukan, API Gateway hanya meneruskan payload respons melalui unmapped.

Misalnya, anggaplah sebuah API 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 MIME jenis yang digunakan dari Accept dan Content-Type header saat memilih template pemetaan. Misalnya, header "Content-Type: application/json; charset=UTF-8" akan memiliki template permintaan dengan application/json kunci yang dipilih.