Integrasi HTTP untuk REST API di API Gateway - APIGerbang Amazon

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

Integrasi HTTP untuk REST API di API Gateway

Anda dapat mengintegrasikan metode API dengan titik akhir HTTP menggunakan integrasi proxy HTTP atau integrasi kustom HTTP.

API Gateway mendukung port endpoint berikut: 80, 443 dan 1024-65535.

Dengan integrasi proxy, pengaturannya sederhana. Anda hanya perlu mengatur metode HTTP dan URI titik akhir HTTP, sesuai dengan persyaratan backend, jika Anda tidak peduli dengan pengkodean konten atau caching.

Dengan integrasi khusus, pengaturan lebih terlibat. Selain langkah-langkah penyiapan integrasi proxy, Anda perlu menentukan bagaimana data permintaan masuk dipetakan ke permintaan integrasi dan bagaimana data respons integrasi yang dihasilkan dipetakan ke respons metode.

Siapkan integrasi proxy HTTP di API Gateway

Untuk menyiapkan sumber daya proxy dengan tipe integrasi proxy HTTP, buat sumber daya API dengan parameter jalur serakah (misalnya,/parent/{proxy+}) dan integrasikan sumber daya ini dengan titik akhir backend HTTP (misalnya,https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}) pada metode. ANY Parameter jalur serakah harus berada di ujung jalur sumber daya.

Seperti sumber daya non-proxy, Anda dapat menyiapkan sumber daya proxy dengan integrasi proxy HTTP menggunakan konsol API Gateway, mengimpor file definisi OpenAPI, atau memanggil API Gateway REST API secara langsung. Untuk petunjuk mendetail tentang penggunaan konsol API Gateway guna mengonfigurasi sumber daya proxy dengan integrasi HTTP, lihatTutorial: Membuat REST API dengan integrasi proxy HTTP.

File definisi OpenAPI berikut menunjukkan contoh API dengan sumber daya proxy yang terintegrasi dengan situs web. PetStore

OpenAPI 3.0
{ "openapi": "3.0.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "parameters": [ { "name": "proxy", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } }, "servers": [ { "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/test" } } } ] }
OpenAPI 2.0
{ "swagger": "2.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } } }

Dalam contoh ini, kunci cache dideklarasikan pada parameter method.request.path.proxy jalur sumber daya proxy. Ini adalah pengaturan default saat Anda membuat API menggunakan konsol API Gateway. Jalur dasar API (/test, sesuai dengan tahap) dipetakan ke PetStore halaman situs web (/petstore). Permintaan integrasi tunggal mencerminkan seluruh PetStore situs web menggunakan variabel jalur serakah API dan metode catch-allANY. Contoh berikut menggambarkan pencerminan ini.

  • Tetapkan ANY sebagai GET dan {proxy+} sebagai pets

    Permintaan metode dimulai dari frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1

    Permintaan integrasi dikirim ke backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1

    Instance run-time dari ANY metode dan sumber daya proxy keduanya valid. Panggilan mengembalikan 200 OK respons dengan muatan yang berisi batch pertama hewan peliharaan, seperti yang dikembalikan dari backend.

  • Tetapkan ANY sebagai GET dan {proxy+} sebagai pets?type=dog

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1

    Permintaan integrasi dikirim ke backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1

    Instance run-time dari ANY metode dan sumber daya proxy keduanya valid. Panggilan mengembalikan 200 OK respons dengan payload yang berisi batch pertama dog tertentu, seperti yang dikembalikan dari backend.

  • Tetapkan ANY sebagai GET dan {proxy+} sebagai pets/{petId}

    Permintaan metode dimulai dari frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1

    Permintaan integrasi dikirim ke backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1

    Instance run-time dari ANY metode dan sumber daya proxy keduanya valid. Panggilan mengembalikan 200 OK respons dengan muatan yang berisi hewan peliharaan yang ditentukan, seperti yang dikembalikan dari backend.

  • Tetapkan ANY sebagai POST dan {proxy+} sebagai pets

    Permintaan metode dimulai dari frontend:

    POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }

    Permintaan integrasi dikirim ke backend:

    POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }

    Instance run-time dari ANY metode dan sumber daya proxy keduanya valid. Panggilan mengembalikan 200 OK respons dengan muatan yang berisi hewan peliharaan yang baru dibuat, seperti yang dikembalikan dari backend.

  • Tetapkan ANY sebagai GET dan {proxy+} sebagai pets/cat

    Permintaan metode dimulai dari frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat

    Permintaan integrasi dikirim ke backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat

    Instance run-time dari jalur sumber daya proxy tidak sesuai dengan titik akhir backend dan permintaan yang dihasilkan tidak valid. Akibatnya, 400 Bad Request respons dikembalikan dengan pesan kesalahan berikut.

    { "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] }
  • Tetapkan ANY sebagai GET dan {proxy+} sebagai null

    Permintaan metode dimulai dari frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test

    Permintaan integrasi dikirim ke backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets

    Sumber daya yang ditargetkan adalah induk dari sumber daya proxy, tetapi instance run-time dari ANY metode ini tidak ditentukan dalam API pada sumber daya tersebut. Akibatnya, GET permintaan ini mengembalikan 403 Forbidden respons dengan pesan Missing Authentication Token kesalahan seperti yang dikembalikan oleh API Gateway. Jika API mengekspos GET metode ANY or pada sumber daya induk (/), panggilan akan menampilkan 404 Not Found respons dengan Cannot GET /petstore pesan yang dikembalikan dari backend.

Untuk permintaan klien apa pun, jika URL titik akhir yang ditargetkan tidak valid atau kata kerja HTTP valid tetapi tidak didukung, backend mengembalikan respons. 404 Not Found Untuk metode HTTP yang tidak didukung, 403 Forbidden respons dikembalikan.

Siapkan integrasi kustom HTTP di API Gateway

Dengan integrasi kustom HTTP, Anda memiliki kontrol lebih besar atas data mana yang harus diteruskan antara metode API dan integrasi API dan cara meneruskan data. Anda melakukan ini menggunakan pemetaan data.

Sebagai bagian dari penyiapan permintaan metode, Anda menetapkan properti requestParameters pada sumber daya Metode. Ini menyatakan parameter permintaan metode mana, yang disediakan dari klien, yang akan dipetakan ke parameter permintaan integrasi atau properti badan yang berlaku sebelum dikirim ke backend. Kemudian, sebagai bagian dari penyiapan permintaan integrasi, Anda menetapkan properti requestParameters pada sumber daya Integrasi yang sesuai untuk menentukan pemetaan. parameter-to-parameter Anda juga mengatur properti requestTemplates untuk menentukan templat pemetaan, satu untuk setiap jenis konten yang didukung. Metode pemetaan template memetakan parameter permintaan, atau isi, ke badan permintaan integrasi.

Demikian pula, sebagai bagian dari pengaturan respons metode, Anda mengatur properti ResponseParameters pada sumber daya. MethodResponse Ini menyatakan parameter respons metode mana, yang akan dikirim ke klien, yang akan dipetakan dari parameter respons integrasi atau properti tubuh tertentu yang berlaku yang dikembalikan dari backend. Kemudian, sebagai bagian dari pengaturan respons integrasi, Anda mengatur properti ResponseParameters pada sumber daya yang IntegrationResponsesesuai untuk menentukan pemetaan. parameter-to-parameter Anda juga mengatur peta ResponseTemplates untuk menentukan templat pemetaan, satu untuk setiap jenis konten yang didukung. Template pemetaan memetakan parameter respons integrasi, atau properti badan respons integrasi, ke badan respons metode.

Untuk informasi selengkapnya tentang menyiapkan templat pemetaan, lihatTransformasi data untuk REST APIs di API Gateway.