Menggunakan template pemetaan untuk mengganti parameter permintaan dan respons API serta kode status

Parameter API Gateway standar dan templat pemetaan kode respons memungkinkan Anda memetakan parameter one-to-one dan memetakan keluarga kode status respons integrasi (dicocokkan dengan ekspresi reguler) ke kode status respons tunggal. Penggantian template pemetaan memberi Anda fleksibilitas untuk melakukan pemetaan many-to-one parameter; mengganti parameter setelah pemetaan API Gateway standar diterapkan; memetakan parameter secara kondisional berdasarkan konten isi atau nilai parameter lainnya; membuat parameter baru secara terprogram dengan cepat; dan ganti kode status yang dikembalikan oleh titik akhir integrasi Anda. Semua jenis parameter permintaan, header respons, atau kode status respons dapat diganti.

Berikut ini adalah contoh penggunaan untuk penggantian template pemetaan:

• Untuk membuat header baru (atau menimpa header yang ada) sebagai gabungan dari dua parameter

• Untuk mengganti kode respons ke kode sukses atau gagal berdasarkan isi tubuh

• Untuk memetakan ulang parameter secara kondisional berdasarkan isinya atau isi dari beberapa parameter lainnya

• Untuk mengulangi konten badan json dan memetakan ulang pasangan nilai kunci ke header atau string kueri

Untuk membuat penggantian template pemetaan, gunakan satu atau beberapa $contextvariabel berikut dalam templat pemetaan:

Minta templat pemetaan tubuh	Templat pemetaan tubuh respons
$context.requestOverride.header.header_name	$context.responseOverride.header.header_name
$context.requestOverride.path.path_name	$context.responseOverride.status
$context.requestOverride.querystring.querystring_name

catatan

Penggantian template pemetaan tidak dapat digunakan dengan titik akhir integrasi proxy, yang tidak memiliki pemetaan data. Untuk informasi selengkapnya tentang jenis integrasi, lihatPilih jenis integrasi API Gateway API.

penting

Override adalah final. Override hanya dapat diterapkan ke setiap parameter satu kali. Mencoba mengganti parameter yang sama beberapa kali akan menghasilkan 5XX respons dari Amazon API Gateway. Jika Anda harus mengganti parameter yang sama beberapa kali di seluruh template, kami sarankan membuat variabel dan menerapkan override di akhir template. Perhatikan bahwa template diterapkan hanya setelah seluruh template diuraikan. Lihat Tutorial: Ganti parameter permintaan API dan header dengan konsol API Gateway.

Tutorial berikut menunjukkan cara membuat dan menguji penggantian template pemetaan di konsol API Gateway. Tutorial ini menggunakan PetStore contoh API sebagai titik awal. Kedua tutorial berasumsi bahwa Anda telah membuat API PetStore sampel.

Tutorial: Ganti kode status respons API dengan konsol API Gateway

Untuk mengambil hewan peliharaan menggunakan API PetStore sampel, Anda menggunakan permintaan metode APIGET /pets/{petId}, di mana {petId} merupakan parameter jalur yang dapat mengambil nomor pada waktu proses.

Dalam tutorial ini, Anda akan mengganti kode respons GET metode ini dengan membuat template pemetaan yang $context.responseOverride.status memetakan 400 ketika kondisi kesalahan terdeteksi.

1. Masuk ke konsol API Gateway di https://console.aws.amazon.com/apigateway.

2. Di bawah API, pilih PetStore API, lalu pilih Resources.

3. Di pohon Resources, pilih GET metode di bawah/{petId}.

4. Pilih tab Uji. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.

5. Untuk PeTiD, masukkan-1, lalu pilih Test.

   Dalam hasilnya, Anda akan melihat dua hal:

   Pertama, badan Respons menunjukkan out-of-range kesalahan:

   {
     "errors": [
       {
         "key": "GetPetRequest.petId",
         "message": "The value is out of range."
       }
     ]
   }

   Kedua, baris terakhir di bawah kotak Log diakhiri dengan:Method completed with status: 200.

6. Pada tab Respons Integrasi, untuk Default - Respons, pilih Edit.

7. Pilih template Pemetaan.

8. Pilih Tambahkan templat pemetaan.

9. Untuk jenis Konten, masukkanapplication/json.

10. Untuk badan Template, masukkan yang berikut ini:

    #set($inputRoot = $input.path('$'))
    $input.json("$")
    #if($inputRoot.toString().contains("error"))
    #set($context.responseOverride.status = 400)
    #end

11. Pilih Simpan.

12. Pilih tab Uji.

13. Untuk PeTiD, masukkan. -1

14. Dalam hasilnya, Response Body menunjukkan out-of-range kesalahan:

    {
      "errors": [
        {
          "key": "GetPetRequest.petId",
          "message": "The value is out of range."
        }
      ]
    }

    Namun, baris terakhir di bawah kotak Log sekarang berakhir dengan:Method completed with status: 400.

Tutorial: Ganti parameter permintaan API dan header dengan konsol API Gateway

Dalam tutorial ini, Anda akan mengganti kode header permintaan GET metode dengan membuat template pemetaan yang memetakan $context.requestOverride.header.header_name ke header baru yang menggabungkan dua header lainnya.

1. Masuk ke konsol API Gateway di https://console.aws.amazon.com/apigateway.

2. Di bawah API, pilih PetStore API.

3. Di pohon Resources, pilih GET metode di bawah/pet.

4. Pada tab Permintaan metode, untuk pengaturan permintaan Metode, pilih Edit.

5. Pilih header permintaan HTTP, lalu pilih Tambah header.

6. Untuk Nama, masukkan header1.

7. Pilih Tambahkan header, lalu buat header kedua yang disebutheader2.

8. Pilih Simpan.

9. Pada tab Permintaan integrasi, untuk pengaturan permintaan Integrasi, pilih Edit.

10. Untuk Request body passthrough, pilih Bila tidak ada templat yang ditentukan (disarankan).

11. Pilih template Pemetaan, lalu lakukan hal berikut:

    1. Pilih Tambahkan templat pemetaan.

    2. Untuk jenis Konten, masukkanapplication/json.

    3. Untuk badan Template, masukkan yang berikut ini:

       #set($header1Override = "foo")
       #set($header3Value = "$input.params('header1')$input.params('header2')")
       $input.json("$")
       #set($context.requestOverride.header.header3 = $header3Value)
       #set($context.requestOverride.header.header1 = $header1Override)
       #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])

12. Pilih Simpan.

13. Pilih tab Uji.

14. Di bawah Header untuk {pets}, salin kode berikut:

    header1:header1Val
    header2:header2Val

15. Pilih Uji.

    Di Log, Anda akan melihat entri yang menyertakan teks ini:

    Endpoint request headers: {header3=header1Valheader2Val, 
    header2=header2Val, header1=foo, x-amzn-apigateway-api-id=<api-id>,
    Accept=application/json, multivalueheader=foo,header1Valheader2Val}

Contoh: Ganti parameter permintaan API dan header dengan API Gateway CLI

Contoh CLI berikut menunjukkan cara menggunakan put-integration perintah untuk mengganti kode respons:

aws apigateway put-integration --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --type <INTEGRATION_TYPE> --request-templates <REQUEST_TEMPLATE_MAP>

di mana <REQUEST_TEMPLATE_MAP>adalah peta dari jenis konten ke string template untuk diterapkan. Struktur peta tersebut adalah sebagai berikut:

Content_type1=template_string,Content_type2=template_string

atau, dalam sintaks JSON:

{"content_type1": "template_string"
...}

Contoh berikut menunjukkan cara menggunakan put-integration-response perintah untuk mengganti kode respons API:

aws apigateway put-integration-response --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --status-code <STATUS_CODE> --response-templates <RESPONSE_TEMPLATE_MAP>

di mana <RESPONSE_TEMPLATE_MAP>memiliki format yang sama seperti <REQUEST_TEMPLATE_MAP>di atas.

Contoh: Ganti parameter permintaan API dan header menggunakan SDK for JavaScript

Contoh berikut menunjukkan cara menggunakan put-integration perintah untuk mengganti kode respons:

Permintaan:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */
  requestTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegration(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Tanggapan:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  statusCode: 'STRING_VALUE', /* required */
  responseTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegrationResponse(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});