Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Kembangkan REST APIs di API Gateway
[Di Amazon API Gateway, Anda membuat REST API sebagai kumpulan entitas yang dapat diprogram yang dikenal sebagai sumber daya API Gateway.](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) Misalnya, Anda menggunakan [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)resource untuk merepresentasikan API yang dapat berisi kumpulan entitas [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html).
Setiap `Resource` entitas dapat memiliki satu atau lebih sumber daya [Metode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). A `Method` adalah permintaan masuk yang dikirimkan oleh klien dan dapat berisi parameter permintaan berikut: parameter jalur, header, atau parameter string kueri. Selain itu, tergantung pada metode HTTP, permintaan dapat berisi badan. Metode Anda mendefinisikan bagaimana klien mengakses ekspos. `Resource` [Untuk mengintegrasikan `Method` dengan titik akhir backend, juga dikenal sebagai titik akhir integrasi, Anda membuat sumber daya Integrasi.](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) Ini meneruskan permintaan masuk ke URI titik akhir integrasi tertentu. Jika perlu, Anda dapat mengubah parameter permintaan atau badan permintaan untuk memenuhi persyaratan backend, atau Anda dapat membuat integrasi proxy, di mana API Gateway mengirimkan seluruh permintaan dalam format standar ke URI endpoint integrasi dan kemudian langsung mengirimkan respons ke klien.
Untuk tanggapan, Anda dapat membuat [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)sumber daya untuk mewakili respons yang diterima oleh klien dan Anda membuat [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)sumber daya untuk mewakili respons yang dikembalikan oleh backend. Gunakan respons integrasi untuk mengubah data respons backend sebelum mengembalikan data ke klien atau meneruskan respons backend apa adanya ke klien.
## Contoh sumber daya untuk REST API
Diagram berikut menunjukkan bagaimana API Gateway mengimplementasikan request/response model ini untuk proxy HTTP dan integrasi non-proxy HTTP untuk sumber daya. `GET /pets` Klien mengirimkan `x-version:beta` header ke API Gateway dan API Gateway mengirimkan kode `204` status ke klien.
Dalam integrasi non-proxy, API Gateway melakukan transformasi data untuk memenuhi persyaratan backend, dengan memodifikasi permintaan integrasi dan respons integrasi. Dalam integrasi non-proxy, Anda dapat mengakses isi dalam permintaan metode tetapi Anda mengubahnya dalam permintaan integrasi. Ketika titik akhir integrasi mengembalikan respons dengan badan, Anda mengakses dan mengubahnya dalam respons integrasi. Anda tidak dapat memodifikasi tubuh dalam respons metode.
Dalam integrasi proxy, titik akhir integrasi memodifikasi permintaan dan respons. API Gateway tidak mengubah permintaan integrasi atau respons integrasi, dan mengirimkan permintaan masuk ke backend apa adanya.
Terlepas dari jenis integrasi, klien mengirim permintaan ke API Gateway dan API Gateway merespons secara sinkron.
------
#### [ Non-proxy integration ]
![\[Diagram integrasi non-proxy API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/develop-non-proxy.png)
------
#### [ Proxy integration ]
![\[Diagram integrasi proxy API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/develop-proxy.png)
------
Contoh log eksekusi berikut menunjukkan API Gateway apa yang akan masuk ke dalam contoh sebelumnya. Untuk kejelasan, beberapa nilai dan log awal telah dihapus:
------
#### [ Non-proxy integration ]
```
Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678
Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets
Wed Feb 12 23:56:44 UTC 2025 : Method request path: {}
Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {}
Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta}
Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations:
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta}
Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations:
Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms
Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT}
Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations:
Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null)
Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345}
Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution
Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204
```
------
#### [ Proxy integration ]
```
Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678
Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets
Wed Feb 12 23:59:42 UTC 2025 : Method request path: {}
Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {}
Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta}
Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations:
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta}
Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations:
Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets
Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms
Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT}
Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations:
Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations:
Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT}
Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution
Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204
```
------
Untuk mengimpor API serupa dan mengujinya di API Konsol Manajemen AWS, lihat [contoh API](api-gateway-create-api-from-example.md).
## Fitur REST API tambahan untuk pengembangan
API Gateway mendukung fitur tambahan untuk pengembangan REST API Anda. Misalnya, untuk membantu pelanggan memahami API Anda, Anda dapat memberikan dokumentasi untuk API. Untuk mengaktifkannya, tambahkan [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html)sumber daya untuk entitas API yang didukung.
[Untuk mengontrol cara klien memanggil API, gunakan [izin IAM](permissions.md), [otorisasi Lambda](apigateway-use-lambda-authorizer.md), atau kumpulan pengguna Amazon Cognito.](apigateway-integrate-with-cognito.md) Untuk mengukur penggunaan API Anda, siapkan [rencana penggunaan](api-gateway-api-usage-plans.md) untuk membatasi permintaan API. Anda dapat mengaktifkan ini saat membuat atau memperbarui API Anda.
Diagram berikut menunjukkan fitur yang tersedia untuk pengembangan REST API dan di mana dalam model permintaan/respons fitur ini dikonfigurasi.
![\[Diagram fitur API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/develop-features.png)
Untuk pengantar tentang cara membuat API, lihat[Tutorial: Buat REST API dengan integrasi proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Untuk mempelajari informasi selengkapnya tentang kemampuan API Gateway yang mungkin Anda gunakan saat mengembangkan REST API, lihat topik berikut. Topik ini berisi informasi konseptual dan prosedur yang dapat Anda lakukan menggunakan konsol API Gateway, API Gateway REST API AWS CLI, atau salah satu topik. AWS SDKs
**Topics**
+ [Contoh sumber daya untuk REST API](#rest-api-develop-example)
+ [Fitur REST API tambahan untuk pengembangan](#rest-api-develop-details)
+ [Jenis titik akhir API untuk REST APIs di API Gateway](api-gateway-api-endpoint-types.md)
+ [Kebijakan keamanan untuk REST APIs di API Gateway](apigateway-security-policies.md)
+ [Jenis alamat IP untuk REST APIs di API Gateway](api-gateway-ip-address-type.md)
+ [Metode untuk REST APIs di API Gateway](how-to-method-settings.md)
+ [Kontrol dan kelola akses ke REST APIs di API Gateway](apigateway-control-access-to-api.md)
+ [Integrasi untuk REST APIs di API Gateway](how-to-integration-settings.md)
+ [Minta validasi untuk REST APIs di API Gateway](api-gateway-method-request-validation.md)
+ [Transformasi data untuk REST APIs di API Gateway](rest-api-data-transformations.md)
+ [Tanggapan gateway untuk REST APIs di API Gateway](api-gateway-gatewayResponse-definition.md)
+ [CORS untuk REST APIs di API Gateway](how-to-cors.md)
+ [Jenis media biner untuk REST APIs di API Gateway](api-gateway-payload-encodings.md)
+ [Panggil REST APIs di API Gateway](how-to-call-api.md)
+ [Kembangkan REST APIs menggunakan OpenAPI di API Gateway](api-gateway-import-api.md)
# Jenis titik akhir API untuk REST APIs di API Gateway
Jenis *[titik akhir API](api-gateway-basic-concept.md#apigateway-definition-api-endpoints)* mengacu pada nama host API. Jenis titik akhir API dapat *dioptimalkan secara tepi*, *Regional*, atau *pribadi*, tergantung dari mana sebagian besar lalu lintas API Anda berasal.
## Titik akhir API yang dioptimalkan tepi
*[Titik akhir API yang dioptimalkan tepi](api-gateway-basic-concept.md#apigateway-definition-edge-optimized-api-endpoint)* biasanya merutekan permintaan ke CloudFront Point of Presence (POP) terdekat, yang dapat membantu jika klien Anda didistribusikan secara geografis. Ini adalah tipe endpoint default untuk API Gateway REST APIs.
Edge dioptimalkan APIs menggunakan huruf besar pada nama [header HTTP (misalnya](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers),). `Cookie`
CloudFront mengurutkan cookie HTTP dalam urutan alami dengan nama cookie sebelum meneruskan permintaan ke asal Anda. Untuk informasi selengkapnya tentang cara CloudFront memproses cookie, lihat [Caching Konten Berdasarkan Cookie](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html).
Nama domain kustom apa pun yang Anda gunakan untuk API yang dioptimalkan tepi berlaku di semua wilayah.
## Titik akhir API regional
*[Titik akhir API Regional](api-gateway-basic-concept.md#apigateway-definition-regional-api-endpoint)* ditujukan untuk klien di Wilayah yang sama. Ketika klien yang berjalan pada instans EC2 memanggil API di Wilayah yang sama, atau ketika API dimaksudkan untuk melayani sejumlah kecil klien dengan permintaan tinggi, API Regional mengurangi overhead koneksi.
Untuk API Regional, nama domain kustom apa pun yang Anda gunakan khusus untuk Wilayah tempat API diterapkan. Jika Anda menerapkan API Regional di beberapa Wilayah, API tersebut dapat memiliki nama domain kustom yang sama di semua Wilayah. Anda dapat menggunakan domain khusus bersama dengan Amazon Route 53 untuk melakukan tugas seperti perutean [berbasis latensi](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-latency). Untuk informasi selengkapnya, lihat [Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md) dan [Siapkan nama domain kustom yang dioptimalkan tepi di API Gateway](how-to-edge-optimized-custom-domain-name.md).
Titik akhir API regional meneruskan semua nama header melalui apa adanya.
**catatan**
Dalam kasus di mana klien API tersebar secara geografis, mungkin masih masuk akal untuk menggunakan titik akhir API Regional, bersama dengan CloudFront distribusi Amazon Anda sendiri untuk memastikan bahwa API Gateway tidak mengaitkan API dengan distribusi yang dikendalikan layanan. CloudFront Untuk informasi selengkapnya tentang kasus penggunaan ini, lihat [Bagaimana cara mengatur API Gateway dengan CloudFront distribusi saya sendiri?](https://repost.aws/knowledge-center/api-gateway-cloudfront-distribution) .
## Titik akhir API pribadi
*[Titik akhir API pribadi adalah titik akhir](api-gateway-basic-concept.md#apigateway-definition-private-api-endpoint)* API yang hanya dapat diakses dari Amazon Virtual Private Cloud (VPC) menggunakan titik akhir VPC antarmuka, yang merupakan antarmuka jaringan titik akhir (ENI) yang Anda buat di VPC Anda. Untuk informasi selengkapnya, lihat [REST pribadi APIs di API Gateway](apigateway-private-apis.md).
Titik akhir API pribadi meneruskan semua nama header melalui apa adanya.
# Mengubah jenis titik akhir API publik atau pribadi di API Gateway
Mengubah tipe titik akhir API mengharuskan Anda memperbarui konfigurasi API. Anda dapat mengubah jenis API yang ada menggunakan konsol API Gateway, the AWS CLI, atau AWS SDK untuk API Gateway. Jenis titik akhir tidak dapat diubah lagi hingga perubahan saat ini selesai, tetapi API Anda akan tersedia.
Perubahan tipe endpoint berikut didukung:
+ Dari yang dioptimalkan tepi ke Regional atau pribadi
+ Dari Regional hingga yang dioptimalkan tepi atau pribadi
+ Dari pribadi ke Regional
Anda tidak dapat mengubah API pribadi menjadi API yang dioptimalkan tepi.
Jika Anda mengubah API publik dari yang dioptimalkan tepi ke Regional atau sebaliknya, perhatikan bahwa API yang dioptimalkan tepi mungkin memiliki perilaku yang berbeda dari API Regional. Misalnya, API yang dioptimalkan tepi menghapus header. `Content-MD5` Setiap nilai MD5 hash yang diteruskan ke backend dapat dinyatakan dalam parameter string permintaan atau properti tubuh. Namun, API Regional meneruskan header ini, meskipun mungkin memetakan ulang nama header ke beberapa nama lain. Memahami perbedaan akan membantu Anda memutuskan cara memperbarui API yang dioptimalkan tepi ke API Regional atau dari API Regional ke API yang dioptimalkan tepi.
**Topics**
+ [Menggunakan konsol API Gateway untuk mengubah jenis titik akhir API](#migrate-api-using-console)
+ [Gunakan AWS CLI untuk mengubah tipe titik akhir API](#migrate-api-using-aws-cli)
## Menggunakan konsol API Gateway untuk mengubah jenis titik akhir API
Untuk mengubah jenis titik akhir API API Anda, lakukan salah satu set langkah berikut:
**Untuk mengonversi titik akhir publik dari Regional atau yang dioptimalkan tepi dan sebaliknya**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih **pengaturan API**.
1. Di bagian **detail API**, pilih **Edit**.
1. **Untuk **jenis endpoint API**, pilih **Edge-optimized atau Regional**.**
1. Pilih **Simpan perubahan**.
1. Menerapkan ulang API Anda sehingga perubahan akan berlaku.
**Untuk mengonversi titik akhir pribadi ke titik akhir Regional**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Edit kebijakan sumber daya untuk API Anda untuk menghapus penyebutan VPCs atau titik akhir VPC sehingga panggilan API dari luar VPC Anda maupun di dalam VPC Anda akan berhasil.
1. Pilih **pengaturan API**.
1. Di bagian **detail API**, pilih **Edit**.
1. Untuk **jenis titik akhir API**, pilih **Regional**.
1. Pilih **Simpan perubahan**.
1. Hapus kebijakan sumber daya dari API Anda.
1. Menerapkan ulang API Anda sehingga perubahan akan berlaku.
Karena Anda memigrasikan tipe titik akhir dari pribadi ke Regional, API Gateway mengubah jenis alamat IP menjadi. IPv4 Untuk informasi selengkapnya, lihat [Jenis alamat IP untuk REST APIs di API Gateway](api-gateway-ip-address-type.md).
**Untuk mengonversi titik akhir Regional menjadi titik akhir pribadi**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Buat kebijakan sumber daya yang memberikan akses ke titik akhir VPC atau VPC Anda. Untuk informasi selengkapnya, lihat [Langkah 3: Siapkan kebijakan sumber daya untuk API pribadi](apigateway-private-api-create.md#apigateway-private-api-set-up-resource-policy).
1. Pilih **pengaturan API**.
1. Di bagian **detail API**, pilih **Edit**.
1. Untuk **jenis endpoint API**, pilih **Private**.
1. (Opsional) Untuk **titik akhir VPC IDs, pilih titik akhir** VPC yang ingin Anda kaitkan dengan IDs API pribadi Anda.
1. Pilih **Simpan perubahan**.
1. Menerapkan ulang API Anda sehingga perubahan akan berlaku.
Karena Anda memigrasikan tipe endpoint dari Regional ke private, API Gateway mengubah tipe alamat IP menjadi dualstack. Untuk informasi selengkapnya, lihat [Jenis alamat IP untuk REST APIs di API Gateway](api-gateway-ip-address-type.md).
## Gunakan AWS CLI untuk mengubah tipe titik akhir API
[update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)Perintah berikut memperbarui API yang dioptimalkan tepi ke API Regional:
```
aws apigateway update-rest-api \
--rest-api-id a1b2c3 \
--patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL
```
Respons yang berhasil memiliki kode status `200 OK` dan muatan yang mirip dengan berikut ini:
```
{
"createdDate": "2017-10-16T04:09:31Z",
"description": "Your first API with Amazon API Gateway. This is a sample API that integrates via HTTP with our demo Pet Store endpoints",
"endpointConfiguration": {
"types": "REGIONAL"
},
"id": "a1b2c3",
"name": "PetStore imported as edge-optimized"
}
```
[update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)Perintah berikut memperbarui API Regional ke API yang dioptimalkan tepi:
```
aws apigateway update-rest-api \
--rest-api-id a1b2c3 \
--patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE
```
Karena [put-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-rest-api.html)untuk memperbarui definisi API, itu tidak berlaku untuk memperbarui jenis titik akhir API.
# Kebijakan keamanan untuk REST APIs di API Gateway
*Kebijakan keamanan* adalah kombinasi standar dari versi TLS minimum dan cipher suite yang ditawarkan oleh API Gateway. Saat klien Anda membuat handshake TLS ke API atau nama domain kustom Anda, kebijakan keamanan memberlakukan versi TLS dan cipher suite yang diterima oleh API Gateway. Kebijakan keamanan melindungi nama domain Anda APIs dan kustom dari masalah keamanan jaringan seperti gangguan dan penyadapan antara klien dan server.
API Gateway mendukung kebijakan keamanan lama dan kebijakan keamanan yang ditingkatkan. `TLS_1_0`dan `TLS_1_2` merupakan kebijakan keamanan warisan. Gunakan kebijakan keamanan ini untuk kompatibilitas mundur. Kebijakan apa pun yang dimulai `SecurityPolicy_` adalah kebijakan keamanan yang ditingkatkan. Gunakan kebijakan ini untuk beban kerja yang diatur, tata kelola lanjutan, atau untuk menggunakan kriptografi pascakuantum. Jika Anda menggunakan kebijakan keamanan yang ditingkatkan, Anda juga harus menetapkan mode akses titik akhir untuk tata kelola tambahan. Untuk informasi selengkapnya, lihat [Mode akses titik akhir](#apigateway-security-policies-endpoint-access-mode).
## Bagaimana API Gateway menerapkan kebijakan keamanan
Contoh berikut menunjukkan bagaimana API Gateway menerapkan kebijakan keamanan menggunakan kebijakan `SecurityPolicy_TLS13_1_3_2025_09` keamanan sebagai contoh.
Kebijakan `SecurityPolicy_TLS13_1_3_2025_09` keamanan menerima lalu lintas TLS 1.3 dan menolak lalu lintas TLS 1.2 dan TLS 1.0. Untuk lalu lintas TLS 1.3, kebijakan keamanan menerima rangkaian sandi berikut:
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway tidak menerima cipher suite lainnya. Misalnya, kebijakan keamanan akan menolak lalu lintas TLS 1.3 yang menggunakan `AES128-SHA` cipher suite. Untuk informasi selengkapnya tentang versi dan cipher TLS yang didukung, lihat. [Kebijakan keamanan yang didukung](apigateway-security-policies-list.md)
Untuk memantau protokol TLS dan cipher klien yang digunakan untuk mengakses API Gateway Anda, Anda dapat menggunakan variabel `$context.tlsVersion` dan `$context.cipherSuite` konteks dalam log akses Anda. Untuk informasi selengkapnya, lihat [Pantau REST APIs di API Gateway](rest-api-monitor.md).
## Mode akses titik akhir
Mode akses titik akhir adalah parameter tambahan yang harus Anda tentukan untuk API REST atau nama domain kustom apa pun yang menggunakan kebijakan keamanan yang ditingkatkan yang dimulai dengan `SecurityPolicy_`. Anda melakukannya saat membuat sumber daya atau jika Anda mengubah kebijakan keamanan dari kebijakan lama menjadi kebijakan yang disempurnakan.
Saat mode akses titik akhir disetel ke`STRICT`, permintaan apa pun ke REST API atau nama domain kustom Anda harus melewati pemeriksaan berikut:
+ Permintaan harus berasal dari jenis titik akhir API Gateway yang sama dengan sumber daya Anda. Permintaan ini bisa berasal dari titik akhir Regional, titik akhir yang dioptimalkan untuk edge, atau titik akhir privat.
+ Jika Anda menggunakan endpoint Regional atau pribadi, API Gateway menggunakan pencocokan host SNI. Jika Anda menggunakan titik akhir yang dioptimalkan tepi, API Gateway sesuai dengan perlindungan fronting domain CloudFront. Untuk informasi selengkapnya, lihat [Domain fronting.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions)
Jika salah satu dari kondisi ini tidak terpenuhi, API Gateway menolak permintaan tersebut. Kami menyarankan Anda menggunakan mode akses `STRICT` titik akhir jika memungkinkan.
Untuk memigrasikan API atau nama domain yang ada agar menggunakan mode akses titik akhir yang ketat, perbarui kebijakan keamanan Anda terlebih dahulu ke kebijakan keamanan yang disempurnakan dan tetapkan mode akses titik akhir. `BASIC` Setelah Anda memvalidasi lalu lintas dan log akses Anda, atur mode akses titik akhir ke. `STRICT` Saat Anda memigrasikan mode akses titik akhir dari `STRICT` ke`BASIC`, titik akhir Anda tidak akan tersedia selama sekitar 15 menit saat perubahan menyebar.
Anda tidak boleh menyetel mode akses titik akhir `STRICT` untuk arsitektur aplikasi tertentu dan sebagai gantinya mengatur mode akses titik akhir ke. `BASIC` Tabel berikut menunjukkan beberapa arsitektur aplikasi dan rekomendasi sehingga REST API atau nama domain kustom Anda dapat menggunakan mode akses `STRICT` endpoint.
| Arsitektur | Migrasi yang disarankan |
| --- | --- |
| Menggunakan titik akhir VPC untuk mengakses nama domain kustom publik. | Arsitektur ini menggunakan lalu lintas tipe cross-endpoint. Kami menyarankan Anda untuk bermigrasi ke[Nama domain khusus untuk pribadi APIs di API Gateway](apigateway-private-custom-domains.md). |
| Menggunakan metode apa pun untuk memanggil API pribadi yang tidak menggunakan nama domain khusus atau nama DNS pribadi. | Arsitektur ini menciptakan ketidakcocokan antara header host dan SNI yang digunakan dalam jabat tangan TLS dan tidak melewati CloudFront batasan fronting domain. Kami menyarankan Anda memigrasikan VPC Anda untuk menggunakan DNS pribadi. |
| Menggunakan domain sharding untuk mendistribusikan konten di beberapa domain atau subdomain. | Arsitektur ini menciptakan ketidakcocokan antara header host dan SNI yang digunakan dalam jabat tangan TLS dan tidak melewati CloudFront batasan fronting domain. Kami menyarankan Anda menggunakan `HTTP/2` dan bermigrasi dari anti-pola ini. |
Berikut ini adalah pertimbangan untuk menggunakan mode akses titik akhir:
+ Jika mode akses titik akhir API atau nama domain adalah`STRICT`, Anda tidak dapat mengubah jenis titik akhir. Untuk mengubah tipe titik akhir, pertama-tama ubah mode akses titik akhir menjadi. `BASIC`
+ Setelah Anda mengubah mode akses titik akhir dari `BASIC` ke`STRICT`, ada penundaan 15 menit bagi API Gateway untuk menerapkan mode akses titik akhir yang ketat.
+ Jika Anda mengubah kebijakan keamanan dari kebijakan yang dimulai dengan `SecurityPolicy_` kebijakan lama, Anda harus membatalkan pengaturan mode akses titik akhir. `""`
## Pertimbangan-pertimbangan
Berikut ini adalah pertimbangan untuk kebijakan keamanan untuk REST APIs di API Gateway:
+ Anda dapat mengimpor kebijakan keamanan dalam file definisi OpenAPI. Untuk informasi selengkapnya, lihat [x-amazon-apigateway-endpoint-modus aksesx-amazon-apigateway-security-kebijakan](openapi-extensions-security-policy.md).
+ API Anda dapat dipetakan ke nama domain khusus dengan kebijakan keamanan yang berbeda dari API Anda. Saat Anda memanggil nama domain kustom tersebut, API Gateway menggunakan kebijakan keamanan API untuk menegosiasikan jabat tangan TLS. Jika Anda menonaktifkan titik akhir API default, hal ini dapat memengaruhi cara penelepon dapat menjalankan API Anda.
+ Jika Anda mengubah kebijakan keamanan Anda, dibutuhkan sekitar 15 menit untuk pembaruan selesai. Anda dapat memantau `apiStatus` API Anda. Saat API Anda diperbarui, `apiStatus` adalah `UPDATING` dan ketika selesai, itu akan terjadi`AVAILABLE`. Ketika status API Anda`UPDATING`, Anda masih dapat memanggilnya.
+ API Gateway mendukung kebijakan keamanan pada semua APIs. Namun, Anda hanya dapat memilih kebijakan keamanan untuk REST APIs. API Gateway hanya mendukung kebijakan `TLS_1_2` keamanan untuk HTTP atau WebSocket APIs.
+ Anda tidak dapat memperbarui kebijakan keamanan untuk API dari `TLS_1_0` ke`TLS_1_2`.
+ Beberapa kebijakan keamanan mendukung rangkaian sandi ECDSA dan RSA. Jika Anda menggunakan jenis kebijakan ini dengan nama domain kustom, rangkaian sandi cocok dengan jenis kunci sertifikat yang disediakan pelanggan, baik RSA atau ECDSA. Jika Anda menggunakan jenis kebijakan ini dengan REST API, cipher suite cocok dengan cipher suite yang kompatibel dengan tipe sertifikat RSA.
# Kebijakan keamanan yang didukung
Tabel berikut menjelaskan [kebijakan keamanan](apigateway-security-policies.md) yang dapat ditentukan untuk setiap jenis endpoint REST API dan jenis nama domain kustom. Kebijakan ini memungkinkan Anda untuk mengontrol koneksi masuk. API Gateway hanya mendukung TLS 1.2 saat keluar. Anda dapat memperbarui kebijakan keamanan untuk API atau nama domain kustom kapan saja.
Kebijakan yang terkandung `FIPS` dalam judul kompatibel dengan Federal Information Processing Standard (FIPS), yang merupakan standar pemerintah AS dan Kanada yang menetapkan persyaratan keamanan untuk modul kriptografi yang melindungi informasi sensitif. Untuk mempelajari lebih lanjut, lihat [Federal Information Processing Standard (FIPS) 140](https://aws.amazon.com/compliance/fips/) di halaman *Kepatuhan Keamanan AWS Cloud*.
Semua kebijakan FIPS memanfaatkan modul kriptografi yang divalidasi AWS-LC FIPS. Untuk mempelajari lebih lanjut, lihat halaman [Modul Kriptografi AWS-LC di situs Program Validasi Modul](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) *Kriptografi NIST*.
Kebijakan yang terkandung `PQ` dalam judul menggunakan [Post-Quantum Cryptography (PQC)](https://aws.amazon.com/security/post-quantum-cryptography/) untuk menerapkan algoritma pertukaran kunci hibrida untuk TLS guna memastikan kerahasiaan lalu lintas terhadap ancaman komputasi kuantum masa depan.
Kebijakan yang terdapat `PFS` dalam judul menggunakan [Perfect Forward Secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy) untuk memastikan kunci sesi tidak dikompromikan.
Kebijakan yang berisi keduanya `FIPS` dan `PQ` dalam judulnya mendukung kedua fitur ini.
## Kebijakan keamanan default
Saat Anda membuat REST API atau domain kustom baru, sumber daya akan ditetapkan kebijakan keamanan default. Tabel berikut menunjukkan kebijakan keamanan default untuk sumber daya ini.
| **Sumber Daya** | **Nama kebijakan keamanan default** |
| --- | --- |
| Regional APIs | TLS\$11\$10 |
| Dioptimalkan tepi APIs | TLS\$11\$10 |
| Pribadi APIs | TLS\$11\$12 |
| Domain regional | TLS\$11\$12 |
| Domain yang dioptimalkan tepi | TLS\$11\$12 |
| Domain privat | TLS\$11\$12 |
## Kebijakan keamanan yang didukung untuk nama domain Regional APIs dan pribadi dan kustom
Tabel berikut menjelaskan kebijakan keamanan yang dapat ditentukan untuk nama domain Regional dan pribadi APIs dan kustom:
| **Kebijakan keamanan** | **Versi TLS yang didukung** | **Cipher yang didukung** |
| --- | --- | --- |
| SecurityPolicy\$1 TLS13 \$11\$13\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$13\$1FIPS\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$1FIPS\$1PFS\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$1PFS\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS13 \$11\$12\$12021\$106 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$12 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## Kebijakan keamanan yang didukung untuk nama domain yang dioptimalkan tepi APIs dan kustom
Tabel berikut menjelaskan kebijakan keamanan yang dapat ditentukan untuk nama domain kustom yang dioptimalkan tepi APIs dan dioptimalkan tepi:
| **Nama kebijakan keamanan** | **Versi TLS yang didukung** | **Cipher yang didukung** |
| --- | --- | --- |
| SecurityPolicy\$1 TLS13 \$12025\$1TEPI | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS12 \$1PFS\$12025\$1TEPI | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| SecurityPolicy\$1 TLS12 \$12018\$1TEPI | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
| TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-security-policies-list.html) |
## Nama sandi OpenSSL dan RFC
OpenSSL dan IETF RFC 5246 menggunakan nama yang berbeda untuk cipher yang sama. Tabel berikut memetakan nama OpenSSL ke nama RFC untuk setiap cipher. Untuk informasi selengkapnya, lihat [cipher](https://docs.openssl.org/1.1.1/man1/ciphers/) di Dokumentasi OpenSSL.
| **Nama sandi OpenSSL** | **Nama sandi RFC** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1 SHA256 | TLS\$1AES\$1128\$1GCM\$1 SHA256 |
| TLS\$1AES\$1256\$1GCM\$1 SHA384 | TLS\$1AES\$1256\$1GCM\$1 SHA384 |
| TLS\$1 \$1 \$1 CHACHA20 POLY1305 SHA256 | TLS\$1 \$1 \$1 CHACHA20 POLY1305 SHA256 |
| ECDHE-RSA- -GCM- AES128 SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1 SHA256 |
| ECDHE-RSA- - AES128 SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1 SHA256 |
| ECDHE-RSA- -SHA AES128 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| ECDHE-RSA- -GCM- AES256 SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1 SHA384 |
| ECDHE-RSA- - AES256 SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1 SHA384 |
| ECDHE-RSA- -SHA AES256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-GCM- SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1 SHA256 |
| AES256-GCM- SHA384 | TLS\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1 SHA384 |
| AES128-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1 SHA256 |
| AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA |
| AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA |
| DES- CBC3 -SHA | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA |
# Cara mengubah kebijakan keamanan
Anda dapat mengubah kebijakan keamanan untuk API Anda. Jika Anda mengirim lalu lintas ke Anda APIs melalui nama domain kustom Anda, API dan nama domain kustom tidak perlu memiliki kebijakan keamanan yang sama. Saat Anda memanggil nama domain kustom tersebut, API Gateway menggunakan kebijakan keamanan API untuk menegosiasikan jabat tangan TLS. Namun, untuk konsistensi, kami menyarankan Anda menggunakan kebijakan keamanan yang sama untuk nama domain dan API kustom Anda.
Jika Anda mengubah kebijakan keamanan Anda, dibutuhkan sekitar 15 menit untuk pembaruan selesai. Anda dapat memantau `apiStatus` API Anda. Saat API Anda diperbarui, `apiStatus` adalah `UPDATING` dan ketika selesai, itu akan terjadi`AVAILABLE`. Saat API Anda diperbarui, Anda masih dapat memanggilnya.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengubah kebijakan keamanan API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih **pengaturan API**, lalu pilih **Edit**.
1. Untuk **kebijakan Keamanan**, pilih kebijakan baru yang dimulai dengan`SecurityPolicy_`.
1. Untuk **mode akses Endpoint**, pilih **Strict**.
1. Pilih **Simpan perubahan**.
Menerapkan ulang API Anda agar perubahan diterapkan. Karena Anda mengubah mode akses titik akhir menjadi ketat, akan memakan waktu sekitar 15 menit agar perubahan menyebar sepenuhnya.
------
#### [ AWS CLI ]
[update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)Perintah berikut memperbarui API untuk menggunakan kebijakan `SecurityPolicy_TLS13_1_3_2025_09` keamanan:
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
Outputnya akan terlihat seperti berikut:
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
"rootResourceId": "efg456"
}
```
[update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)Perintah berikut memperbarui API yang menggunakan kebijakan keamanan yang disempurnakan untuk menggunakan kebijakan `TLS_1_0` keamanan.
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "TLS_1_0"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": ""
}
]'
```
Outputnya akan terlihat seperti berikut:
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a new security policy",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"securityPolicy": "TLS_1_0",
"rootResourceId": "efg456"
}
```
------
# Jenis alamat IP untuk REST APIs di API Gateway
Saat membuat API, Anda menentukan jenis alamat IP yang dapat menjalankan API Anda. Anda dapat memilih IPv4 untuk menyelesaikan IPv4 alamat untuk menjalankan API Anda, atau Anda dapat memilih dualstack untuk mengizinkan keduanya IPv4 dan IPv6 alamat menjalankan API Anda. Kami menyarankan Anda mengatur jenis alamat IP ke dualstack untuk mengurangi kelelahan ruang IP atau untuk postur keamanan Anda. [Untuk informasi selengkapnya tentang manfaat dari jenis alamat IP dualstack, lihat IPv6 di. AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)
Untuk membatasi API hanya IPv6 lalu lintas, Anda dapat membuat kebijakan sumber daya dan membatasi alamat IP sumber hanya IPv6 untuk rentang. Anda dapat mengubah jenis alamat IP dengan memperbarui konfigurasi API. Perubahan ini akan segera berlaku, dan Anda tidak perlu menerapkan ulang API Anda. Untuk informasi selengkapnya, lihat [Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example)
## Pertimbangan untuk jenis alamat IP
Pertimbangan berikut dapat memengaruhi penggunaan jenis alamat IP Anda:
+ Jenis alamat IP default untuk semua Regional dan yang dioptimalkan tepi APIs adalah. IPv4
+ Private hanya APIs dapat memiliki tipe alamat IP dualstack.
+ Jika Anda mengubah jenis alamat IP untuk API yang ada dari IPv4 ke dualstack, konfirmasikan bahwa kebijakan apa pun yang mengontrol akses ke Anda APIs telah diperbarui untuk IPv6 memperhitungkan panggilan. Ketika Anda mengubah jenis alamat IP, perubahan akan segera berlaku.
+ Jika Anda memigrasikan tipe titik akhir API dari Regional atau yang dioptimalkan tepi ke pribadi, API Gateway mengubah jenis alamat IP menjadi dualstack. Untuk informasi selengkapnya, lihat [Mengubah jenis titik akhir API publik atau pribadi di API Gateway](apigateway-api-migration.md).
+ Jika Anda memigrasikan tipe titik akhir API dari pribadi ke Regional, Anda harus menyetel jenis alamat IP ke dualstack. Setelah migrasi titik akhir selesai, Anda dapat mengubah jenis alamat IP menjadi IPv4. Untuk informasi selengkapnya, lihat [Mengubah jenis titik akhir API publik atau pribadi di API Gateway](apigateway-api-migration.md).
+ API Anda dapat dipetakan ke nama domain khusus dengan jenis alamat IP yang berbeda dari API Anda. Jika Anda menonaktifkan titik akhir API default, hal ini dapat memengaruhi cara penelepon dapat menjalankan API Anda.
+ Anda tidak dapat menggunakan file definisi eksternal untuk mengonfigurasi jenis alamat IP API Anda.
# Mengubah jenis alamat IP dari REST API
Anda dapat mengubah jenis alamat IP dengan memperbarui konfigurasi API. Anda dapat memperbarui konfigurasi API dengan menggunakan Konsol Manajemen AWS, the AWS CLI CloudFormation, atau AWS SDK. Jika Anda mengubah jenis alamat IP API, Anda tidak menerapkan ulang API agar perubahan diterapkan. Sebelum Anda mengubah jenis alamat IP, konfirmasikan bahwa kebijakan apa pun yang mengontrol akses ke Anda APIs telah diperbarui ke akun untuk IPv6 panggilan.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengubah jenis alamat IP dari REST API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih **pengaturan API**, lalu pilih **Edit**.
1. Untuk jenis alamat IP, pilih salah satu **IPv4**atau **Dualstack**.
1. Pilih **Simpan perubahan**.
Perubahan pada konfigurasi API Anda akan segera berlaku.
------
#### [ AWS CLI ]
[update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)Perintah berikut memperbarui API untuk memiliki tipe alamat IP dualstack:
```
aws apigateway update-rest-api \
--rest-api-id abcd1234 \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
Outputnya akan terlihat seperti berikut:
```
{
"id": "abcd1234",
"name": "MyAPI",
"description": "My API with a dualstack IP address type",
"createdDate": "2025-02-04T11:47:06-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"tags": {},
"disableExecuteApiEndpoint": false,
"rootResourceId": "efg456"
}
```
------
# Metode untuk REST APIs di API Gateway
Di API Gateway, metode API mewujudkan [permintaan metode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) dan [respons metode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). Anda menyiapkan metode API untuk menentukan apa yang harus atau harus dilakukan klien untuk mengirimkan permintaan untuk mengakses layanan di backend dan untuk menentukan tanggapan yang diterima klien sebagai imbalannya. Untuk masukan, Anda dapat memilih parameter permintaan metode, atau muatan yang berlaku, agar klien dapat menyediakan data yang diperlukan atau opsional pada waktu berjalan. Untuk output, Anda menentukan kode status respons metode, header, dan badan yang berlaku sebagai target untuk memetakan data respons backend, sebelum dikembalikan ke klien. Untuk membantu pengembang klien memahami perilaku dan format input dan output API Anda, Anda dapat [mendokumentasikan](api-gateway-documenting-api.md) API Anda dan [memberikan pesan kesalahan yang tepat](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) untuk [permintaan yang tidak valid](api-gateway-method-request-validation.md).
Permintaan metode API adalah permintaan HTTP. Untuk menyiapkan permintaan metode, Anda mengonfigurasi metode HTTP (atau kata kerja), jalur ke [sumber daya](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API, header, parameter string kueri yang berlaku. Anda juga mengonfigurasi payload ketika metode HTTP adalah`POST`,`PUT`, atau`PATCH`. Misalnya, untuk mengambil hewan peliharaan menggunakan [API PetStore sampel](api-gateway-create-api-from-example.md), Anda menentukan permintaan metode API`GET /pets/{petId}`, di mana `{petId}` merupakan parameter jalur yang dapat mengambil nomor pada waktu proses.
```
GET /pets/1
Host: apigateway.us-east-1.amazonaws.com
...
```
Jika klien menentukan jalur yang salah, misalnya, `/pet/1` atau `/pets/one` bukan`/pets/1`, pengecualian dilemparkan.
Respons metode API adalah respons HTTP dengan kode status yang diberikan. Untuk integrasi non-proxy, Anda harus menyiapkan respons metode untuk menentukan target pemetaan yang diperlukan atau opsional. Ini mengubah header atau badan respons integrasi ke header atau badan respons metode terkait. Pemetaan dapat sesederhana [transformasi identitas](https://en.wikipedia.org/wiki/Identity_transform) yang melewati header atau badan melalui integrasi apa adanya. Misalnya, respons `200` metode berikut menunjukkan contoh passthrough dari respons integrasi yang berhasil apa adanya.
```
200 OK
Content-Type: application/json
...
{
"id": "1",
"type": "dog",
"price": "$249.99"
}
```
Pada prinsipnya, Anda dapat menentukan respons metode yang sesuai dengan respons tertentu dari backend. Biasanya, ini melibatkan respons 2XX, 4XX, dan 5XX. Namun, ini mungkin tidak praktis, karena seringkali Anda mungkin tidak tahu sebelumnya semua tanggapan yang mungkin dikembalikan oleh backend. Dalam praktiknya, Anda dapat menetapkan satu respons metode sebagai default untuk menangani respons yang tidak diketahui atau tidak dipetakan dari backend. Ini adalah praktik yang baik untuk menetapkan respons 500 sebagai default. Bagaimanapun, Anda harus menyiapkan setidaknya satu respons metode untuk integrasi non-proxy. Jika tidak, API Gateway mengembalikan respons kesalahan 500 ke klien bahkan ketika permintaan berhasil di backend.
Untuk mendukung SDK yang diketik dengan kuat, seperti Java SDK, untuk API Anda, Anda harus menentukan model data untuk input untuk permintaan metode, dan menentukan model data untuk output dari respons metode.
## Prasyarat
Sebelum menyiapkan metode API, verifikasi hal berikut:
+ Anda harus memiliki metode yang tersedia di API Gateway. Ikuti petunjuk dalam [Tutorial: Membuat REST API dengan integrasi non-proxy HTTP](api-gateway-create-api-step-by-step.md).
+ Jika Anda ingin metode berkomunikasi dengan fungsi Lambda, Anda harus sudah membuat peran pemanggilan Lambda dan peran eksekusi Lambda di IAM. Anda juga harus membuat fungsi Lambda yang dengannya metode Anda akan berkomunikasi. AWS Lambda Untuk membuat peran dan fungsi, gunakan instruksi dalam [Buat fungsi Lambda untuk integrasi non-proxy Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda)[Pilih tutorial AWS Lambda integrasi](getting-started-with-lambda-integration.md).
+ Jika Anda ingin metode berkomunikasi dengan integrasi proxy HTTP atau HTTP, Anda harus sudah membuat, dan memiliki akses ke, URL titik akhir HTTP yang dengannya metode Anda akan berkomunikasi.
+ Verifikasi bahwa sertifikat Anda untuk titik akhir proxy HTTP dan HTTP didukung oleh API Gateway. Untuk detailnya lihat[Otoritas sertifikat yang didukung API Gateway untuk integrasi proxy HTTP dan HTTP di API Gateway](api-gateway-supported-certificate-authorities-for-http-endpoints.md).
**Topics**
+ [Prasyarat](#method-setting-prerequisites)
+ [Siapkan permintaan metode di API Gateway](api-gateway-method-settings-method-request.md)
+ [Siapkan respons metode di API Gateway](api-gateway-method-settings-method-response.md)
+ [Siapkan metode menggunakan konsol API Gateway](how-to-set-up-method-using-console.md)
# Siapkan permintaan metode di API Gateway
Menyiapkan permintaan metode melibatkan melakukan tugas-tugas berikut, setelah membuat [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)sumber daya:
1. Membuat API baru atau memilih entitas [Sumber Daya](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API yang ada.
1. Membuat sumber daya [Metode](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) API yang merupakan kata kerja HTTP spesifik pada API `Resource` baru atau yang dipilih. Tugas ini dapat dibagi lagi menjadi sub tugas berikut:
+ Menambahkan metode HTTP ke permintaan metode
+ Mengkonfigurasi parameter permintaan
+ Mendefinisikan model untuk badan permintaan
+ Memberlakukan skema otorisasi
+ Mengaktifkan validasi permintaan
Anda dapat melakukan tugas-tugas ini menggunakan metode berikut:
+ [Konsol API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)
+ AWS CLI [perintah ([create-resource dan put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html))](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)
+ AWS [Fungsi SDK (misalnya, di Node.js, [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) dan putMethod)](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property)
+ [API Gateway REST API ([sumber daya: buat dan metode:put](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html)).](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)
**Topics**
+ [Siapkan sumber daya API](#setup-method-resources)
+ [Siapkan metode HTTP](#setup-method-add-http-method)
+ [Siapkan parameter permintaan metode](#setup-method-request-parameters)
+ [Siapkan model permintaan metode](#setup-method-request-model)
+ [Siapkan otorisasi permintaan metode](#setup-method-request-authorization)
+ [Siapkan validasi permintaan metode](#setup-method-request-validation)
## Siapkan sumber daya API
Di API Gateway API, Anda mengekspos sumber daya yang dapat dialamatkan sebagai pohon entitas [Sumber Daya](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) API, dengan sumber daya root (`/`) di bagian atas hierarki. Sumber daya root relatif terhadap URL dasar API, yang terdiri dari titik akhir API dan nama panggung. Di konsol API Gateway, URI dasar ini disebut sebagai **URI Invoke** dan ditampilkan di editor tahap API setelah API diterapkan.
Titik akhir API dapat berupa nama host default atau nama domain khusus. Nama host default adalah dari format berikut:
```
{api-id}.execute-api.{region}.amazonaws.com
```
Dalam format ini, ini *\$1api-id\$1* mewakili pengenal API yang dihasilkan oleh API Gateway. `{region}`Variabel mewakili AWS Region (misalnya,`us-east-1`) yang Anda pilih saat membuat API. Nama domain kustom adalah nama yang ramah pengguna di bawah domain internet yang valid. Misalnya, jika Anda telah mendaftarkan domain internet`example.com`, salah satu dari `*.example.com` adalah nama domain kustom yang valid. Untuk informasi selengkapnya, lihat [membuat nama domain kustom](how-to-custom-domains.md).
Untuk [API PetStore sampel](api-gateway-create-api-from-example.md), sumber daya root (`/`) mengekspos toko hewan peliharaan. Sumber `/pets` daya mewakili koleksi hewan peliharaan yang tersedia di toko hewan peliharaan. Ini `/pets/{petId}` mengekspos hewan peliharaan individu dari pengenal yang diberikan ()`petId`. Parameter jalur `{petId}` adalah bagian dari parameter permintaan.
Untuk menyiapkan sumber daya API, Anda memilih sumber daya yang ada sebagai induknya, lalu membuat sumber daya turunan di bawah sumber daya induk ini. Anda mulai dengan sumber daya root sebagai induk, menambahkan sumber daya ke induk ini, menambahkan sumber daya lain ke sumber daya turunan ini sebagai induk baru, dan seterusnya, ke pengenal induknya. Kemudian Anda menambahkan sumber daya bernama ke induk.
Perintah [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) berikut mengambil semua sumber daya API:
```
aws apigateway get-resources --rest-api-id apiId
```
Untuk PetStore contoh API, outputnya terlihat seperti berikut:
```
{
"items": [
{
"path": "/pets",
"resourceMethods": {
"GET": {}
},
"id": "6sxz2j",
"pathPart": "pets",
"parentId": "svzr2028x8"
},
{
"path": "/pets/{petId}",
"resourceMethods": {
"GET": {}
},
"id": "rjkmth",
"pathPart": "{petId}",
"parentId": "6sxz2j"
},
{
"path": "/",
"id": "svzr2028x8"
}
]
}
```
Setiap item mencantumkan pengidentifikasi sumber daya (`id`) dan, kecuali sumber daya root, induk langsungnya (`parentId`), serta nama sumber daya (`pathPart`). Sumber daya root istimewa karena tidak memiliki induk. Setelah memilih sumber daya sebagai induk, gunakan perintah berikut untuk menambahkan sumber daya anak:
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id parentId \
--path-part resourceName
```
Misalnya, untuk menambahkan makanan hewan untuk dijual di PetStore situs web, gunakan perintah berikut:
```
aws apigateway create-resource --rest-api-id a1b2c3 \
--parent-id svzr2028x8 \
--path-part food
```
Outputnya akan terlihat seperti berikut:
```
{
"path": "/food",
"pathPart": "food",
"id": "xdsvhp",
"parentId": "svzr2028x8"
}
```
### Menggunakan sumber daya proxy untuk merampingkan penyiapan API
Seiring pertumbuhan bisnis, PetStore pemilik dapat memutuskan untuk menambahkan makanan, mainan, dan barang-barang terkait hewan peliharaan lainnya untuk dijual. Untuk mendukung ini, Anda dapat menambahkan`/food`,`/toys`, dan sumber daya lainnya di bawah sumber daya root. Di bawah setiap kategori penjualan, Anda mungkin juga ingin menambahkan lebih banyak sumber daya, seperti`/food/{type}/{item}`,`/toys/{type}/{item}`, dll. Ini bisa membosankan. Jika Anda memutuskan untuk menambahkan lapisan tengah `{subtype}` ke jalur sumber daya untuk mengubah hierarki jalur menjadi`/food/{type}/{subtype}/{item}`,`/toys/{type}/{subtype}/{item}`, dll., Perubahan akan merusak pengaturan API yang ada. Untuk menghindari hal ini, Anda dapat menggunakan [sumber daya proxy](api-gateway-set-up-simple-proxy.md) API Gateway untuk mengekspos sekumpulan sumber daya API sekaligus.
API Gateway mendefinisikan sumber daya proxy sebagai placeholder untuk sumber daya yang akan ditentukan saat permintaan dikirimkan. Sumber daya proxy diekspresikan oleh parameter jalur khusus`{proxy+}`, sering disebut sebagai parameter jalur serakah. `+`Tanda tersebut menunjukkan sumber daya anak mana pun yang ditambahkan padanya. `/parent/{proxy+}`Placeholder adalah singkatan dari sumber daya apa pun yang cocok dengan pola jalur. `/parent/*` Anda dapat menggunakan string apa pun untuk nama parameter jalur serakah.
Perintah [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) berikut membuat sumber daya proxy di bawah root (): `/{proxy+}`
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id rootResourceId \
--path-part {proxy+}
```
Outputnya akan terlihat seperti berikut:
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "234jdr",
"parentId": "svzr2028x8"
}
```
Untuk contoh `PetStore` API, Anda dapat menggunakan `/{proxy+}` untuk mewakili `/pets` dan`/pets/{petId}`. Sumber daya proxy ini juga dapat mereferensikan sumber daya lain (yang ada atau to-be-added)`/food/{type}/{item}`, seperti`/toys/{type}/{item}`,, dll., Atau`/food/{type}/{subtype}/{item}`,`/toys/{type}/{subtype}/{item}`, dll. Pengembang backend menentukan hierarki sumber daya dan pengembang klien bertanggung jawab untuk memahaminya. API Gateway hanya meneruskan apa pun yang dikirimkan klien ke backend.
API dapat memiliki lebih dari satu sumber daya proxy. Misalnya, sumber daya proxy berikut diizinkan dalam API, dengan asumsi `/parent/{proxy+}` bukan induk yang sama dengan. `/parent/{child}/{proxy+}`
```
/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}
```
Ketika sumber daya proxy memiliki saudara kandung non-proxy, sumber daya saudara dikecualikan dari representasi sumber daya proxy. Untuk contoh sebelumnya, `/{proxy+}` mengacu pada sumber daya apa pun di bawah sumber daya root kecuali sumber daya. `/parent[/*]` Dengan kata lain, permintaan metode terhadap sumber daya tertentu lebih diutamakan daripada permintaan metode terhadap sumber daya generik pada tingkat hierarki sumber daya yang sama.
Tabel berikut menunjukkan cara API Gateway merutekan permintaan ke sumber daya berikut untuk `prod` tahap API.
```
ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog
```
| Permintaan | Rute yang dipilih | Penjelasan |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | Permintaan sepenuhnya cocok dengan sumber daya ini. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | Variabel jalur `/pets/{proxy+}` serakah menangkap permintaan ini. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | Variabel jalur `/{proxy+}` serakah menangkap permintaan ini. |
Sumber daya proxy tidak dapat memiliki sumber daya anak. Sumber daya API apa pun `{proxy+}` setelahnya berlebihan dan ambigu. Sumber daya proxy berikut tidak diizinkan dalam API.
```
/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}
```
## Siapkan metode HTTP
[Permintaan metode API dienkapsulasi oleh sumber daya Metode API Gateway.](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) Untuk mengatur permintaan metode, Anda harus terlebih dahulu membuat instance `Method` sumber daya, menyetel setidaknya metode HTTP dan jenis otorisasi pada metode.
Terkait erat dengan sumber daya proxy, API Gateway mendukung metode HTTP`ANY`. `ANY`Metode ini mewakili setiap metode HTTP yang akan disediakan pada waktu berjalan. Ini memungkinkan Anda untuk menggunakan penyiapan metode API tunggal untuk semua metode HTTP yang didukung`DELETE`,`GET`,`HEAD`,`OPTIONS`,`PATCH`,`POST`, dan`PUT`.
Anda dapat mengatur `ANY` metode pada sumber daya non-proxy juga. Menggabungkan `ANY` metode dengan sumber daya proxy, Anda mendapatkan penyiapan metode API tunggal untuk semua metode HTTP yang didukung terhadap sumber daya API apa pun. Selain itu, backend dapat berkembang tanpa merusak pengaturan API yang ada.
Sebelum menyiapkan metode API, pertimbangkan siapa yang dapat memanggil metode tersebut. Atur jenis otorisasi sesuai dengan rencana Anda. Untuk akses terbuka, atur ke`NONE`. Untuk menggunakan izin IAM, atur jenis otorisasi ke. `AWS_IAM` Untuk menggunakan fungsi otorisasi Lambda, setel properti ini ke. `CUSTOM` Untuk menggunakan kumpulan pengguna Amazon Cognito, setel jenis otorisasi ke. `COGNITO_USER_POOLS`
Perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut membuat permintaan metode untuk `ANY` kata kerja menggunakan izin IAM untuk mengontrol aksesnya.
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method ANY \
--authorization-type AWS_IAM
```
Untuk membuat permintaan metode API dengan jenis otorisasi yang berbeda, lihat[Siapkan otorisasi permintaan metode](#setup-method-request-authorization).
## Siapkan parameter permintaan metode
Parameter permintaan metode adalah cara bagi klien untuk menyediakan data input atau konteks eksekusi yang diperlukan untuk menyelesaikan permintaan metode. Parameter metode dapat berupa parameter jalur, header, atau parameter string kueri. Sebagai bagian dari pengaturan permintaan metode, Anda harus mendeklarasikan parameter permintaan yang diperlukan agar tersedia untuk klien. Untuk integrasi non-proxy, Anda dapat menerjemahkan parameter permintaan ini ke formulir yang kompatibel dengan persyaratan backend.
Misalnya, untuk permintaan `GET /pets/{petId}` metode, variabel `{petId}` jalur adalah parameter permintaan yang diperlukan. Anda dapat mendeklarasikan parameter jalur ini saat memanggil `put-method` perintah. AWS CLI Perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut menciptakan metode dengan parameter path yang diperlukan:
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id rjkmth \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.path.petId=true
```
Jika parameter tidak diperlukan, Anda dapat mengaturnya ke `false` dalam`request-parameters`. Misalnya, jika `GET /pets` metode menggunakan parameter string kueri opsional dari`type`, dan parameter header opsional`age`, Anda dapat mendeklarasikannya menggunakan perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut:
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.type=false,method.request.header.age=false
```
Alih-alih formulir singkat ini, Anda dapat menggunakan string JSON untuk mengatur nilai`request-parameters`:
```
'{"method.request.querystring.type":false,"method.request.header.age":false}'
```
Dengan pengaturan ini, klien dapat menanyakan hewan peliharaan berdasarkan jenis:
```
GET /pets?type=dog
```
Dan klien dapat menanyakan anjing-anjingnya yang masih kecil sebagai berikut:
```
GET /pets?type=dog
age:puppy
```
Untuk informasi tentang cara memetakan parameter permintaan metode ke parameter permintaan integrasi, lihat[Integrasi untuk REST APIs di API Gateway](how-to-integration-settings.md).
## Siapkan model permintaan metode
Untuk metode API yang dapat mengambil data input dalam payload, Anda dapat menggunakan model. Sebuah model diekspresikan dalam [skema JSON draft 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) dan menjelaskan struktur data dari badan permintaan. Dengan model, klien dapat menentukan bagaimana membangun payload permintaan metode sebagai input. Lebih penting lagi, API Gateway menggunakan model untuk [memvalidasi permintaan](api-gateway-method-request-validation.md), [menghasilkan SDK](how-to-generate-sdk.md), dan menginisialisasi template pemetaan untuk menyiapkan integrasi di konsol API Gateway. Untuk informasi tentang cara membuat [model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), lihat [Memahami model data](models-mappings-models.md).
Tergantung pada jenis konten, payload metode dapat memiliki format yang berbeda. Sebuah model diindeks terhadap jenis media dari muatan yang diterapkan. API Gateway menggunakan header `Content-Type` permintaan untuk menentukan jenis konten. Untuk mengatur model permintaan metode, tambahkan pasangan kunci-nilai `"media-type":"model-name"` format ke `requestModels` peta saat memanggil perintah. AWS CLI `put-method`
Untuk menggunakan model yang sama terlepas dari jenis konten, tentukan `$default` sebagai kunci.
Misalnya, untuk menyetel model pada payload JSON dari permintaan `POST /pets` metode API PetStore contoh, Anda dapat menggunakan perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut:
```
aws apigateway put-method \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method POST \
--authorization-type "NONE" \
--request-models '{"application/json":"petModel"}'
```
Di sini, `petModel` adalah nilai `name` properti dari [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)sumber daya yang menggambarkan hewan peliharaan. Definisi skema yang sebenarnya dinyatakan sebagai nilai string JSON dari [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema)properti sumber daya. `Model`
Di Java, atau SDK lain yang diketik kuat, dari API, data input dilemparkan sebagai `petModel` kelas yang berasal dari definisi skema. Dengan model permintaan, data input dalam SDK yang dihasilkan dilemparkan ke `Empty` kelas, yang berasal dari `Empty` model default. Dalam hal ini, klien tidak dapat membuat instance kelas data yang benar untuk memberikan input yang diperlukan.
## Siapkan otorisasi permintaan metode
Untuk mengontrol siapa yang dapat memanggil metode API, Anda dapat mengonfigurasi [jenis otorisasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) pada metode. Anda dapat menggunakan jenis ini untuk memberlakukan salah satu otorisasi yang didukung, termasuk peran dan kebijakan IAM (`AWS_IAM`), kumpulan pengguna Amazon Cognito ()`COGNITO_USER_POOLS`, atau pemberi otorisasi Lambda (). `CUSTOM`
Untuk menggunakan izin IAM untuk mengotorisasi akses ke metode API, setel properti `authorization-type` input ke. **AWS\$1IAM** Saat Anda menyetel opsi ini, API Gateway memverifikasi tanda tangan pemanggil berdasarkan kredensional pemanggil. Jika pengguna terverifikasi memiliki izin untuk memanggil metode, ia menerima permintaan tersebut. Jika tidak, ia menolak permintaan dan pemanggil menerima respons kesalahan yang tidak sah. Panggilan ke metode tidak berhasil kecuali pemanggil memiliki izin untuk memanggil metode API. Kebijakan IAM berikut memberikan izin kepada pemanggil untuk memanggil metode API apa pun yang dibuat dalam metode yang sama: Akun AWS
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:*:*:*"
}
]
}
```
------
Untuk informasi selengkapnya, lihat [Kontrol akses ke REST API dengan izin IAM](permissions.md).
Saat ini, Anda hanya dapat memberikan kebijakan ini kepada pengguna, grup, dan peran dalam pemilik API Akun AWS. Pengguna dari yang berbeda Akun AWS dapat memanggil metode API hanya jika diizinkan untuk mengambil peran dalam pemilik API Akun AWS dengan izin yang diperlukan untuk memanggil `execute-api:Invoke` tindakan. Untuk informasi tentang izin lintas akun, lihat [Menggunakan Peran IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).
Anda dapat menggunakan AWS CLI, AWS SDK, atau klien REST API, seperti [Postman](https://www.postman.com/), yang mengimplementasikan [penandatanganan Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html).
Untuk menggunakan otorisasi Lambda untuk mengotorisasi akses ke metode API, setel properti `authorization-type` input ke `CUSTOM` dan setel properti [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId)input ke nilai properti dari otorisasi Lambda yang sudah ada. [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) Authorizer Lambda yang direferensikan dapat dari `TOKEN` tipe atau. `REQUEST` Untuk informasi tentang membuat otorisasi Lambda, lihat. [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md)
Untuk menggunakan kumpulan pengguna Amazon Cognito untuk mengotorisasi akses ke metode API, setel properti `authorization-type` input ke `COGNITO_USER_POOLS` dan setel properti [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId)input ke nilai [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id)properti `COGNITO_USER_POOLS` otorisasi yang telah dibuat. Untuk informasi tentang membuat otorisasi kumpulan pengguna Amazon Cognito, lihat. [Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi](apigateway-integrate-with-cognito.md)
## Siapkan validasi permintaan metode
Anda dapat mengaktifkan validasi permintaan saat menyiapkan permintaan metode API. Anda harus terlebih dahulu membuat [validator permintaan](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html)Perintah berikut membuat validator permintaan body-only.
```
aws apigateway create-request-validator \
--rest-api-id 7zw9uyk9kl \
--name bodyOnlyValidator \
--validate-request-body \
--no-validate-request-parameters
```
Outputnya akan terlihat seperti berikut:
```
{
"validateRequestParameters": false,
"validateRequestBody": true,
"id": "jgpyy6",
"name": "bodyOnlyValidator"
}
```
Anda dapat menggunakan validator permintaan ini, untuk menggunakan validasi permintaan sebagai bagian dari pengaturan permintaan metode. Perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut membuat permintaan metode yang mengharuskan badan permintaan masuk untuk mencocokkan `PetModel` dan memiliki dua parameter permintaan yang tidak diperlukan:
```
aws apigateway put-method \
--rest-api-id 7zw9uyk9kl \
--resource-id xdsvhp \
--http-method PUT \
--authorization-type "NONE" \
--request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \
--request-models '{"application/json":"petModel"}' \
--request-validator-id jgpyy6
```
Untuk menyertakan parameter permintaan dalam validasi permintaan, Anda harus mengatur `validateRequestParameters` `true` untuk validator permintaan, dan menetapkan parameter permintaan khusus ke `true` dalam perintah. `put-method`
# Siapkan respons metode di API Gateway
Respons metode API merangkum output dari permintaan metode API yang akan diterima klien. Data output mencakup kode status HTTP, beberapa header, dan mungkin badan.
Dengan integrasi non-proxy, parameter dan badan respons yang ditentukan dapat dipetakan dari data respons integrasi terkait atau dapat diberikan nilai statis tertentu sesuai dengan pemetaan. Pemetaan ini ditentukan dalam respons integrasi. Pemetaan dapat menjadi transformasi identik yang melewati respons integrasi melalui apa adanya.
Dengan integrasi proxy, API Gateway meneruskan respons backend ke respons metode secara otomatis. Anda tidak perlu menyiapkan respons metode API. Namun, dengan integrasi proxy Lambda, fungsi Lambda harus mengembalikan hasil format [keluaran ini agar API](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) Gateway berhasil memetakan respons integrasi ke respons metode.
[https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters)
Saat menyetel kode status untuk metode API, Anda harus memilih salah satu sebagai default untuk menangani respons integrasi kode status yang tidak terduga. Masuk akal untuk ditetapkan `500` sebagai default karena ini sama dengan mentransmisikan respons yang tidak dipetakan sebagai kesalahan sisi server. Untuk alasan instruksional, konsol API Gateway menetapkan `200` respons sebagai default. Tetapi Anda dapat mengatur ulang ke `500` respons.
Untuk mengatur respons metode, Anda harus membuat permintaan metode.
## Mengatur kode status respons metode
Kode status dari respon metode mendefinisikan jenis respon. Misalnya, tanggapan 200, 400, dan 500 menunjukkan keberhasilan, kesalahan sisi klien dan respons kesalahan sisi server, masing-masing.
Untuk menyiapkan kode status respons metode, setel [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode)properti ke kode status HTTP. [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)Perintah berikut menciptakan respon `200` metode.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200
```
## Siapkan parameter respons metode
Parameter respons metode menentukan header mana yang diterima klien sebagai respons terhadap permintaan metode terkait. Parameter respons juga menentukan target yang API Gateway memetakan parameter respons integrasi, sesuai dengan pemetaan yang ditentukan dalam respons integrasi metode API.
Untuk mengatur parameter respons metode, tambahkan ke [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters)peta pasangan `MethodResponse` kunci-nilai format. `"{parameter-name}":"{boolean}"` [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)Perintah berikut menetapkan `my-header` header.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false
```
## Siapkan model respons metode
Model respons metode mendefinisikan format badan respons metode. Menyiapkan model respons metode diperlukan saat Anda membuat SDK yang diketik kuat untuk API. Ini memastikan bahwa output dilemparkan ke kelas yang sesuai di Java atau Objective-C. Dalam kasus lain, pengaturan model adalah opsional.
Sebelum menyiapkan model respons, Anda harus terlebih dahulu membuat model di API Gateway. Untuk melakukannya, Anda dapat memanggil `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)` perintah. Perintah [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) berikut membuat `PetStorePet` model untuk menggambarkan tubuh respons terhadap permintaan metode. `GET /pets/{petId}`
```
aws apigateway create-model \
--rest-api-id vaz7da96z6 \
--content-type application/json \
--name PetStorePet \
--schema '{ \
"$schema": "http://json-schema.org/draft-04/schema#", \
"title": "PetStorePet", \
"type": "object", \
"properties": { \
"id": { "type": "number" }, \
"type": { "type": "string" }, \
"price": { "type": "number" } \
} \
}'
```
Hasilnya dibuat sebagai [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)sumber daya API Gateway.
Untuk mengatur model respons metode untuk menentukan format payload, tambahkan pasangan nilai kunci “application/json”:”PetStorePet” ke peta sumber daya. [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)Perintah berikut membuat respons metode yang menggunakan model respons untuk menentukan format payload:
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false \
--response-models '{"application/json":"PetStorePet"}'
```
# Siapkan metode menggunakan konsol API Gateway
Saat membuat metode menggunakan konsol REST API, Anda mengonfigurasi permintaan integrasi dan permintaan metode. Secara default, API Gateway membuat respons `200` metode untuk metode Anda.
Petunjuk berikut menunjukkan cara mengedit pengaturan permintaan metode dan cara membuat respons metode tambahan untuk metode Anda.
**Topics**
+ [Mengedit permintaan metode API Gateway di konsol API Gateway](#how-to-method-settings-callers-console)
+ [Menyiapkan respons metode API Gateway menggunakan konsol API Gateway](#how-to-method-response-settings-console)
## Mengedit permintaan metode API Gateway di konsol API Gateway
Instruksi ini mengasumsikan Anda telah membuat permintaan metode Anda. Untuk informasi selengkapnya tentang cara membuat metode, lihat[Menyiapkan permintaan integrasi API menggunakan konsol API Gateway](how-to-method-settings-console.md).
1. Di panel **Resources**, pilih metode Anda, lalu pilih tab **Permintaan metode**.
1. Di bagian **Pengaturan permintaan metode**, pilih **Edit**.
1. Untuk **Otorisasi**, pilih otorisasi yang tersedia.
1. Untuk mengaktifkan akses terbuka ke metode untuk pengguna mana pun, pilih **Tidak Ada**. Langkah ini dapat dilewati jika pengaturan default belum diubah.
1. Untuk menggunakan izin IAM untuk mengontrol akses klien ke metode, pilih. `AWS_IAM` Dengan pilihan ini, hanya pengguna peran IAM dengan kebijakan IAM yang benar dilampirkan yang diizinkan untuk memanggil metode ini.
Untuk membuat peran IAM, tentukan kebijakan akses dengan format seperti berikut:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/"
]
}
]
}
```
------
Dalam kebijakan akses ini, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` adalah ARN metode Anda. Anda dapat menemukan ARN metode Anda dengan memilih metode pada halaman **Sumber Daya**. Untuk informasi selengkapnya tentang menyetel izin IAM, lihat. [Kontrol akses ke REST API dengan izin IAM](permissions.md)
Untuk membuat peran IAM, Anda dapat menyesuaikan instruksi dalam tutorial berikut,[Buat fungsi Lambda untuk integrasi non-proxy Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda).
1. Untuk menggunakan otorisasi Lambda, pilih token atau otorisasi permintaan. Buat otorisasi Lambda agar pilihan ini ditampilkan di menu tarik-turun. Untuk informasi tentang cara membuat otorisasi Lambda, lihat. [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md)
1. Untuk menggunakan kumpulan pengguna Amazon Cognito, pilih kumpulan pengguna yang tersedia di bawah otorisasi kumpulan pengguna **Cognito**. Buat kumpulan pengguna di Amazon Cognito dan otorisasi kumpulan pengguna Amazon Cognito di API Gateway agar pilihan ini ditampilkan di menu tarik-turun. Untuk informasi tentang cara membuat otorisasi kumpulan pengguna Amazon Cognito, lihat. [Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi](apigateway-integrate-with-cognito.md)
1. Untuk menentukan validasi permintaan, pilih nilai dari menu tarik-turun **Permintaan Validator**. Untuk menonaktifkan validasi permintaan, pilih **Tidak Ada**. Untuk informasi selengkapnya tentang setiap opsi, lihat[Minta validasi untuk REST APIs di API Gateway](api-gateway-method-request-validation.md).
1. Pilih **kunci API yang diperlukan** untuk meminta kunci API. Saat diaktifkan, kunci API digunakan dalam [rencana penggunaan](api-gateway-api-usage-plans.md) untuk membatasi lalu lintas klien.
1. (Opsional) Untuk menetapkan nama operasi di Java SDK API ini, yang dihasilkan oleh API Gateway, untuk **nama Operasi**, masukkan nama. Misalnya, untuk permintaan metode`GET /pets/{petId}`, nama operasi Java SDK yang sesuai adalah, secara default,`GetPetsPetId`. Nama ini dibangun dari kata kerja HTTP metode (`GET`) dan nama variabel jalur sumber daya (`Pets`dan`PetId`). Jika Anda menetapkan nama operasi sebagai`getPetById`, nama operasi SDK menjadi`GetPetById`.
1. Untuk menambahkan parameter string kueri ke metode, lakukan hal berikut:
1. Pilih **parameter string Kueri URL**, lalu pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan nama parameter string kueri.
1. Pilih **Diperlukan** jika parameter string kueri yang baru dibuat akan digunakan untuk validasi permintaan. Untuk informasi selengkapnya tentang validasi permintaan, lihat[Minta validasi untuk REST APIs di API Gateway](api-gateway-method-request-validation.md).
1. Pilih **Caching** jika parameter string kueri yang baru dibuat akan digunakan sebagai bagian dari kunci caching. Untuk informasi lebih lanjut tentang caching, lihat[Gunakan metode atau parameter integrasi sebagai kunci cache untuk mengindeks respons yang di-cache](api-gateway-caching.md#enable-api-gateway-cache-keys).
Untuk menghapus parameter string kueri, pilih **Hapus**.
1. Untuk menambahkan parameter header ke metode, lakukan hal berikut:
1. Pilih **header permintaan HTTP**, lalu pilih **Tambah header**.
1. Untuk **Nama**, masukkan nama header.
1. Pilih **Diperlukan** jika header yang baru dibuat akan digunakan untuk validasi permintaan. Untuk informasi selengkapnya tentang validasi permintaan, lihat[Minta validasi untuk REST APIs di API Gateway](api-gateway-method-request-validation.md).
1. Pilih **Caching** jika header yang baru dibuat akan digunakan sebagai bagian dari kunci caching. Untuk informasi lebih lanjut tentang caching, lihat[Gunakan metode atau parameter integrasi sebagai kunci cache untuk mengindeks respons yang di-cache](api-gateway-caching.md#enable-api-gateway-cache-keys).
Untuk menghapus header, pilih **Hapus**.
1. Untuk mendeklarasikan format payload permintaan metode dengan,, atau kata kerja `PATCH` HTTP `POST``PUT`, pilih **Request body**, dan lakukan hal berikut:
1. Pilih **Tambah model**.
1. Untuk **Content-type**, masukkan tipe MIME (misalnya,). `application/json`
1. Untuk **Model**, pilih model dari menu tarik-turun. Model yang tersedia saat ini untuk API mencakup default `Empty` dan `Error` model serta model apa pun yang telah Anda buat dan tambahkan ke koleksi [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) API. Untuk informasi selengkapnya tentang membuat model, lihat[Model data untuk REST APIs](models-mappings-models.md).
**catatan**
Model ini berguna untuk memberi tahu klien tentang format data yang diharapkan dari muatan. Sangat membantu untuk menghasilkan template pemetaan kerangka. Penting untuk menghasilkan SDK API yang diketik dengan kuat dalam bahasa seperti Java, C \$1, Objective-C, dan Swift. Ini hanya diperlukan jika validasi permintaan diaktifkan terhadap muatan.
1. Pilih **Simpan**.
## Menyiapkan respons metode API Gateway menggunakan konsol API Gateway
Metode API dapat memiliki satu atau lebih tanggapan. Setiap respons diindeks oleh kode status HTTP-nya. Secara default, konsol API Gateway menambahkan `200` respons ke respons metode. Anda dapat memodifikasinya, misalnya, agar metode dikembalikan `201` sebagai gantinya. Anda dapat menambahkan tanggapan lain, misalnya, untuk penolakan akses dan `409` `500` untuk variabel tahap yang tidak diinisialisasi yang digunakan.
Untuk menggunakan konsol API Gateway untuk memodifikasi, menghapus, atau menambahkan respons ke metode API, ikuti petunjuk berikut.
1. Di panel **Resources**, pilih metode Anda, lalu pilih tab **Respons metode**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Di bagian **Pengaturan respons metode**, pilih **Buat respons**.
1. Untuk **kode status HTTP**, masukkan kode status HTTP seperti`200`,`400`, atau`500`.
Ketika respons yang dikembalikan ke backend tidak memiliki respons metode yang sesuai yang ditentukan, API Gateway gagal mengembalikan respons ke klien. Sebaliknya, ia mengembalikan respons `500 Internal server error` kesalahan.
1. Pilih **Tambahkan header**.
1. Untuk **nama Header**, masukkan nama.
Untuk mengembalikan header dari backend ke klien, tambahkan header dalam respons metode.
1. Pilih **Tambahkan model** untuk menentukan format badan respons metode.
Masukkan jenis media payload respons untuk **jenis Konten** dan pilih model dari menu tarik-turun **Model**.
1. Pilih **Simpan**.
Untuk mengubah respons yang ada, navigasikan ke respons metode Anda, lalu pilih **Edit**. Untuk mengubah **kode status HTTP**, pilih **Hapus** dan buat respons metode baru.
Untuk setiap respons yang dikembalikan dari backend, Anda harus memiliki respons yang kompatibel yang dikonfigurasi sebagai respons metode. Namun, header respons metode konfigurasi dan model payload bersifat opsional kecuali Anda memetakan hasil dari backend ke respons metode sebelum kembali ke klien. Selain itu, model payload respons metode penting jika Anda membuat SDK yang diketik kuat untuk API Anda.
# Kontrol dan kelola akses ke REST APIs di API Gateway
API Gateway mendukung beberapa mekanisme untuk mengontrol dan mengelola akses ke API Anda.
Anda dapat menggunakan mekanisme berikut untuk otentikasi dan otorisasi:
+ **Kebijakan sumber daya** memungkinkan Anda membuat kebijakan berbasis sumber daya untuk mengizinkan atau menolak akses ke APIs dan metode Anda dari alamat IP sumber tertentu atau titik akhir VPC. Untuk informasi selengkapnya, lihat [Kontrol akses ke REST API dengan kebijakan sumber daya API Gateway](apigateway-resource-policies.md).
+ **Peran dan kebijakan AWS IAM standar** menawarkan kontrol akses yang fleksibel dan kuat yang dapat diterapkan ke seluruh API atau metode individual. Peran dan kebijakan IAM dapat digunakan untuk mengontrol siapa yang dapat membuat dan mengelola Anda APIs, serta siapa yang dapat memanggilnya. Untuk informasi selengkapnya, lihat [Kontrol akses ke REST API dengan izin IAM](permissions.md).
+ **Tag IAM** dapat digunakan bersama dengan kebijakan IAM untuk mengontrol akses. Untuk informasi selengkapnya, lihat [Menggunakan tag untuk mengontrol akses ke sumber daya API API Gateway REST API](apigateway-tagging-iam-policy.md).
+ **Kebijakan titik akhir untuk titik akhir VPC antarmuka** [memungkinkan Anda melampirkan kebijakan sumber daya IAM ke titik akhir VPC antarmuka untuk meningkatkan keamanan pribadi Anda. APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html) Untuk informasi selengkapnya, lihat [Menggunakan kebijakan titik akhir VPC secara pribadi APIs di API Gateway](apigateway-vpc-endpoint-policies.md).
+ **Pengotorisasi Lambda adalah** fungsi Lambda yang mengontrol akses ke metode REST API menggunakan otentikasi token pembawa — serta informasi yang dijelaskan oleh header, jalur, string kueri, variabel tahap, atau parameter permintaan variabel konteks. Authorizer Lambda digunakan untuk mengontrol siapa yang dapat menjalankan metode REST API. Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md).
+ **Kumpulan pengguna Amazon Cognito** memungkinkan Anda membuat solusi otentikasi dan otorisasi yang dapat disesuaikan untuk REST Anda. APIs Kumpulan pengguna Amazon Cognito digunakan untuk mengontrol siapa yang dapat menjalankan metode REST API. Untuk informasi selengkapnya, lihat [Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi](apigateway-integrate-with-cognito.md).
Anda dapat menggunakan mekanisme berikut untuk melakukan tugas lain yang terkait dengan kontrol akses:
+ **Berbagi sumber daya lintas asal (CORS)** memungkinkan Anda mengontrol cara REST API merespons permintaan sumber daya lintas domain. Untuk informasi selengkapnya, lihat [CORS untuk REST APIs di API Gateway](how-to-cors.md).
+ **Sertifikat SSL sisi klien** dapat digunakan untuk memverifikasi bahwa permintaan HTTP ke sistem backend Anda berasal dari API Gateway. Untuk informasi selengkapnya, lihat [Buat dan konfigurasikan sertifikat SSL untuk otentikasi backend di API Gateway](getting-started-client-side-ssl-authentication.md).
+ **AWS WAF**dapat digunakan untuk melindungi API Gateway API Anda dari eksploitasi web umum. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md).
Anda dapat menggunakan mekanisme berikut untuk melacak dan membatasi akses yang telah Anda berikan kepada klien yang berwenang:
+ **Paket penggunaan** memungkinkan Anda memberikan **kunci API** kepada pelanggan Anda—lalu melacak dan membatasi penggunaan tahapan dan metode API Anda untuk setiap kunci API. Lihat informasi yang lebih lengkap di [Paket penggunaan dan kunci API untuk REST APIs di API Gateway](api-gateway-api-usage-plans.md).
# Kontrol akses ke REST API dengan kebijakan sumber daya API Gateway
Kebijakan *sumber daya* Amazon API Gateway adalah dokumen kebijakan JSON yang Anda lampirkan ke API untuk mengontrol apakah prinsipal tertentu (biasanya peran atau grup IAM) dapat memanggil API. Anda dapat menggunakan kebijakan sumber daya API Gateway untuk memungkinkan API Anda dipanggil dengan aman oleh:
+ Pengguna dari AWS akun tertentu.
+ Rentang alamat IP sumber tertentu atau blok CIDR.
+ Cloud pribadi virtual tertentu (VPCs) atau titik akhir VPC (di akun apa pun).
Anda dapat melampirkan kebijakan sumber daya untuk semua jenis titik akhir API di API Gateway dengan menggunakan, AWS CLI Konsol Manajemen AWS, atau. AWS SDKs Untuk [pribadi APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html), Anda dapat menggunakan kebijakan sumber daya bersama dengan kebijakan titik akhir VPC untuk mengontrol prinsipal mana yang memiliki akses ke sumber daya dan tindakan mana. Untuk informasi selengkapnya, lihat [Menggunakan kebijakan titik akhir VPC secara pribadi APIs di API Gateway](apigateway-vpc-endpoint-policies.md).
Kebijakan sumber daya API Gateway berbeda dari kebijakan berbasis identitas IAM. Kebijakan berbasis identitas IAM dilampirkan pada pengguna, grup, atau peran IAM dan menentukan tindakan apa yang dapat dilakukan identitas tersebut pada sumber daya mana. Kebijakan sumber daya API Gateway dilampirkan ke sumber daya. Anda dapat menggunakan kebijakan sumber daya API Gateway bersama dengan kebijakan IAM. Untuk informasi lebih lanjut, lihat [Kebijakan Berbasis Identitas dan Kebijakan Berbasis Sumber Daya](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html).
**Topics**
+ [Mengakses ikhtisar bahasa kebijakan untuk Amazon API Gateway](apigateway-control-access-policy-language-overview.md)
+ [Bagaimana kebijakan sumber daya API Gateway memengaruhi alur kerja otorisasi](apigateway-authorization-flow.md)
+ [Contoh kebijakan sumber daya API Gateway](apigateway-resource-policies-examples.md)
+ [Membuat dan melampirkan kebijakan sumber daya API Gateway ke API](apigateway-resource-policies-create-attach.md)
+ [AWS kunci kondisi yang dapat digunakan dalam kebijakan sumber daya API Gateway](apigateway-resource-policies-aws-condition-keys.md)
# Mengakses ikhtisar bahasa kebijakan untuk Amazon API Gateway
Halaman ini menjelaskan elemen dasar yang digunakan dalam kebijakan sumber daya Amazon API Gateway.
Kebijakan sumber daya ditentukan menggunakan sintaks yang sama dengan kebijakan IAM. Untuk informasi bahasa kebijakan selengkapnya, lihat [Gambaran Umum Kebijakan IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) dan [Referensi AWS Identity and Access Management Kebijakan](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) di *Panduan Pengguna IAM*.
Untuk informasi tentang cara AWS layanan memutuskan apakah permintaan yang diberikan harus diizinkan atau ditolak, lihat [Menentukan Apakah Permintaan Diizinkan atau Ditolak](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow).
## Elemen umum dalam kebijakan akses
Dalam arti yang paling mendasar, kebijakan sumber daya berisi elemen-elemen berikut:
+ **Sumber daya** - APIs adalah sumber daya Amazon API Gateway yang dapat Anda izinkan atau tolak izinnya. Dalam sebuah kebijakan, Anda menggunakan Nama Sumber Daya Amazon (ARN) untuk mengidentifikasi sumber daya. Anda juga dapat menggunakan sintaks singkat, yang API Gateway secara otomatis diperluas ke ARN penuh saat Anda menyimpan kebijakan sumber daya. Untuk mempelajari selengkapnya, lihat [Contoh kebijakan sumber daya API Gateway](apigateway-resource-policies-examples.md).
Untuk format `Resource` elemen lengkap, lihat[Format sumber daya izin untuk menjalankan API di API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-resource-format-for-executing-api).
+ **Tindakan** - Untuk setiap sumber daya, Amazon API Gateway mendukung serangkaian operasi. Anda mengidentifikasi operasi sumber daya yang Anda izinkan (atau tolak) dengan menggunakan kata kunci tindakan.
Misalnya, `execute-api:Invoke` izin akan memungkinkan izin pengguna untuk memanggil API atas permintaan klien.
Untuk format `Action` elemen, lihat[Format tindakan izin untuk menjalankan API di API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-action-format-for-executing-api).
+ **Efek** — Apa efeknya ketika pengguna meminta tindakan tertentu—ini bisa berupa salah satu atau. `Allow` `Deny` Anda juga dapat secara eksplisit menolak akses ke sumber daya, yang mungkin Anda lakukan untuk memastikan bahwa pengguna tidak dapat mengaksesnya, bahkan jika kebijakan lain memberikan akses.
**catatan**
“Penyangkalan implisit” adalah hal yang sama dengan “tolak secara default”.
“Penyangkalan implisit” berbeda dari “penolakan eksplisit”. Untuk informasi selengkapnya, lihat [Perbedaan Antara Menyangkal Secara Default dan Penolakan Eksplisit](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#AccessPolicyLanguage_Interplay).
+ **Principal** — Akun atau pengguna mengizinkan akses ke tindakan dan sumber daya dalam pernyataan. Dalam kebijakan sumber daya, prinsipal adalah pengguna atau akun yang menerima izin ini.
Contoh kebijakan sumber daya berikut menunjukkan elemen kebijakan umum sebelumnya. Kebijakan memberikan akses ke API di bawah yang ditentukan *account-id* dalam yang ditentukan *region* untuk setiap pengguna yang alamat IP sumbernya ada di blok *123.4.5.6/24* alamat. Kebijakan menolak semua akses ke API jika IP sumber pengguna tidak berada dalam jangkauan.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:*"
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:*",
"Condition": {
"NotIpAddress": {
"aws:SourceIp": "123.4.5.6/24"
}
}
}
]
}
```
------
# Bagaimana kebijakan sumber daya API Gateway memengaruhi alur kerja otorisasi
Saat API Gateway mengevaluasi kebijakan sumber daya yang dilampirkan ke API Anda, hasilnya dipengaruhi oleh jenis autentikasi yang telah Anda tetapkan untuk API, seperti yang diilustrasikan dalam diagram alur di bagian berikut.
**Topics**
+ [Kebijakan sumber daya API Gateway saja](#apigateway-authorization-flow-resource-policy-only)
+ [Lambda otorisasi dan kebijakan sumber daya](#apigateway-authorization-flow-lambda)
+ [Autentikasi IAM dan kebijakan sumber daya](#apigateway-authorization-flow-iam)
+ [Autentikasi Amazon Cognito dan kebijakan sumber daya](#apigateway-authorization-flow-cognito)
+ [Tabel hasil evaluasi kebijakan](#apigateway-resource-policies-iam-policies-interaction)
## Kebijakan sumber daya API Gateway saja
Dalam alur kerja ini, kebijakan sumber daya API Gateway dilampirkan ke API, tetapi tidak ada jenis otentikasi yang ditentukan untuk API. Evaluasi kebijakan melibatkan pencarian izin eksplisit berdasarkan kriteria masuk penelepon. Penolakan implisit atau penolakan eksplisit apa pun menghasilkan penolakan penelepon.
![\[Alur otorisasi kebijakan sumber daya saja.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/apigateway-auth-resource-policy-only.png)
Berikut ini adalah contoh kebijakan sumber daya semacam itu.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
## Lambda otorisasi dan kebijakan sumber daya
Dalam alur kerja ini, otorisasi Lambda dikonfigurasi untuk API selain kebijakan sumber daya. Kebijakan sumber daya dievaluasi dalam dua fase. Sebelum memanggil otorisasi Lambda, API Gateway terlebih dahulu mengevaluasi kebijakan dan memeriksa setiap penolakan eksplisit. Jika ditemukan, penelepon ditolak aksesnya segera. Jika tidak, otorisasi Lambda dipanggil, dan mengembalikan [dokumen kebijakan](api-gateway-lambda-authorizer-output.md), yang dievaluasi bersama dengan kebijakan sumber daya. Jika otorisasi Anda menggunakan caching, API Gateway mungkin menampilkan dokumen kebijakan yang di-cache. Hasilnya ditentukan berdasarkan [Tabel A](#apigateway-resource-policies-iam-policies-interaction).
Contoh kebijakan sumber daya berikut mengizinkan panggilan hanya dari titik akhir VPC yang ID titik akhir VPC-nya. `vpce-1a2b3c4d` Selama evaluasi “pra-auth”, hanya panggilan yang berasal dari titik akhir VPC yang ditunjukkan dalam contoh yang diizinkan untuk bergerak maju dan mengevaluasi otorisasi Lambda. Semua panggilan yang tersisa diblokir. Alur kerja otorisasi ini sama jika Anda menggunakan nama domain khusus untuk API pribadi.
![\[Alur otorisasi untuk kebijakan sumber daya dan otorisasi Lambda.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/apigateway-auth-lambda-resource-policy.png)
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}
```
------
## Autentikasi IAM dan kebijakan sumber daya
Dalam alur kerja ini, Anda mengonfigurasi autentikasi IAM untuk API selain kebijakan sumber daya. Setelah Anda mengautentikasi pengguna dengan layanan IAM, API mengevaluasi kebijakan yang dilampirkan pada pengguna dan kebijakan sumber daya. Hasilnya bervariasi berdasarkan apakah pemanggil berada di tempat yang sama Akun AWS atau terpisah Akun AWS, dari pemilik API.
Jika pemanggil dan pemilik API berasal dari akun terpisah, kebijakan IAM dan kebijakan sumber daya secara eksplisit mengizinkan pemanggil untuk melanjutkan. Untuk informasi lebih lanjut, lihat [Tabel B](#apigateway-resource-policies-iam-policies-interaction).
Namun, jika pemanggil dan pemilik API sama Akun AWS, maka kebijakan pengguna IAM atau kebijakan sumber daya harus secara eksplisit mengizinkan pemanggil untuk melanjutkan. Untuk informasi lebih lanjut, lihat [Tabel A](#apigateway-resource-policies-iam-policies-interaction).
![\[Alur otorisasi untuk kebijakan sumber daya dan otentikasi IAM.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/apigateway-auth-iam-resource-policy.png)
Berikut ini adalah contoh kebijakan sumber daya lintas akun. Dengan asumsi kebijakan IAM berisi efek allow, kebijakan sumber daya ini hanya mengizinkan panggilan dari VPC yang ID VPCnya. `vpc-2f09a348` Untuk informasi lebih lanjut, lihat [Tabel B](#apigateway-resource-policies-iam-policies-interaction).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/"
],
"Condition" : {
"StringEquals": {
"aws:SourceVpc": "vpc-2f09a348"
}
}
}
]
}
```
------
## Autentikasi Amazon Cognito dan kebijakan sumber daya
Dalam alur kerja ini, kumpulan [pengguna Amazon Cognito](apigateway-integrate-with-cognito.md) dikonfigurasi untuk API selain kebijakan sumber daya. API Gateway pertama kali mencoba untuk mengautentikasi pemanggil melalui Amazon Cognito. Ini biasanya dilakukan melalui [token JWT](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) yang disediakan oleh penelepon. Jika otentikasi berhasil, kebijakan sumber daya dievaluasi secara independen, dan izin eksplisit diperlukan. Penyangkalan atau “tidak mengizinkan atau menyangkal” menghasilkan penyangkalan. Berikut ini adalah contoh kebijakan sumber daya yang dapat digunakan bersama dengan kumpulan pengguna Amazon Cognito.
![\[Alur otorisasi untuk kebijakan sumber daya dan otorisasi Amazon Cognito.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/apigateway-auth-cognito-resource-policy.png)
Berikut ini adalah contoh kebijakan sumber daya yang mengizinkan panggilan hanya dari sumber tertentu IPs, dengan asumsi bahwa token otentikasi Amazon Cognito berisi izin. Untuk informasi lebih lanjut, lihat [Tabel B](#apigateway-resource-policies-iam-policies-interaction).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/",
"Condition": {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
## Tabel hasil evaluasi kebijakan
Tabel A mencantumkan perilaku yang dihasilkan saat akses ke API Gateway API dikendalikan oleh kebijakan IAM atau otorisasi Lambda dan kebijakan sumber daya API Gateway, keduanya sama. Akun AWS
| **Kebijakan IAM (atau otorisasi Lambda)** | **Kebijakan sumber daya API Gateway** | **Perilaku yang dihasilkan** |
| --- | --- | --- |
| Izinkan | Izinkan | Izinkan |
| Izinkan | Tidak Memungkinkan atau Menyangkal | Izinkan |
| Izinkan | Menyangkal | Penolakan jelas |
| Tidak Memungkinkan atau Menyangkal | Izinkan | Izinkan |
| Tidak Memungkinkan atau Menyangkal | Tidak Memungkinkan atau Menyangkal | Penyangkalan Implisit |
| Tidak Memungkinkan atau Menyangkal | Menyangkal | Penolakan jelas |
| Menyangkal | Izinkan | Penolakan jelas |
| Menyangkal | Tidak Memungkinkan atau Menyangkal | Penolakan jelas |
| Menyangkal | Menyangkal | Penolakan jelas |
Tabel B mencantumkan perilaku yang dihasilkan saat akses ke API Gateway API dikendalikan oleh kebijakan IAM atau otorisasi kumpulan pengguna Amazon Cognito dan kebijakan sumber daya API Gateway, yang berbeda. Akun AWS Jika salah satu diam (tidak mengizinkan atau menolak), akses lintas akun ditolak. Ini karena akses lintas akun mengharuskan kebijakan sumber daya dan kebijakan IAM atau otorisasi kumpulan pengguna Amazon Cognito secara eksplisit memberikan akses.
| **Kebijakan IAM (atau otorisasi kumpulan pengguna Amazon Cognito)** | **Kebijakan sumber daya API Gateway** | **Perilaku yang dihasilkan** |
| --- | --- | --- |
| Izinkan | Izinkan | Izinkan |
| Izinkan | Tidak Memungkinkan atau Menyangkal | Penyangkalan Implisit |
| Izinkan | Menyangkal | Penolakan jelas |
| Tidak Memungkinkan atau Menyangkal | Izinkan | Penyangkalan Implisit |
| Tidak Memungkinkan atau Menyangkal | Tidak Memungkinkan atau Menyangkal | Penyangkalan Implisit |
| Tidak Memungkinkan atau Menyangkal | Menyangkal | Penolakan jelas |
| Menyangkal | Izinkan | Penolakan jelas |
| Menyangkal | Tidak Memungkinkan atau Menyangkal | Penolakan jelas |
| Menyangkal | Menyangkal | Penolakan jelas |
# Contoh kebijakan sumber daya API Gateway
Halaman ini menyajikan beberapa contoh kasus penggunaan umum untuk kebijakan sumber daya API Gateway.
Contoh kebijakan berikut menggunakan sintaks yang disederhanakan untuk menentukan sumber daya API. Sintaks yang disederhanakan ini adalah cara singkat yang dapat Anda rujuk ke sumber daya API, alih-alih menentukan Nama Sumber Daya Amazon (ARN) lengkap. API Gateway mengonversi sintaks yang disingkat menjadi ARN lengkap saat Anda menyimpan kebijakan. Misalnya, Anda dapat menentukan sumber daya `execute-api:/stage-name/GET/pets` dalam kebijakan sumber daya. API Gateway mengonversi sumber daya menjadi `arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets` saat Anda menyimpan kebijakan sumber daya. API Gateway membangun ARN lengkap dengan menggunakan Wilayah saat ini, ID akun AWS Anda, dan ID REST API yang terkait dengan kebijakan sumber daya. Anda dapat menggunakan `execute-api:/*` untuk mewakili semua tahapan, metode, dan jalur di API saat ini. Untuk informasi tentang bahasa kebijakan akses, lihat [Mengakses ikhtisar bahasa kebijakan untuk Amazon API Gateway](apigateway-control-access-policy-language-overview.md).
**Topics**
+ [Contoh: Izinkan peran di AWS akun lain untuk menggunakan API](#apigateway-resource-policies-cross-account-example)
+ [Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber](#apigateway-resource-policies-source-ip-address-example)
+ [Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber saat menggunakan API pribadi](#apigateway-resource-policies-source-ip-address-vpc-example)
+ [Contoh: Izinkan lalu lintas API pribadi berdasarkan titik akhir VPC atau VPC sumber](#apigateway-resource-policies-source-vpc-example)
## Contoh: Izinkan peran di AWS akun lain untuk menggunakan API
Contoh kebijakan sumber daya berikut memberikan akses API dalam satu AWS akun ke dua peran di akun yang berbeda AWS melalui protokol [Signature Version 4 (SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html)) atau Signature [Version 4a (Sigv4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works)). Secara khusus, peran pengembang dan administrator untuk AWS akun yang diidentifikasi oleh `account-id-2` diberikan `execute-api:Invoke` tindakan untuk menjalankan `GET` tindakan pada `pets` sumber daya (API) di AWS akun Anda.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/developer",
"arn:aws:iam::111122223333:role/Admin"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}
```
------
## Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber
Contoh kebijakan sumber daya berikut menyangkal (memblokir) lalu lintas masuk ke API dari dua blok alamat IP sumber yang ditentukan.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ]
}
}
}
]
}
```
------
Jika Anda menggunakan kebijakan pengguna IAM atau kebijakan sumber daya API Gateway untuk mengontrol akses ke API Gateway atau API Gateway apa pun APIs, konfirmasikan bahwa kebijakan Anda diperbarui untuk menyertakan rentang IPv6 alamat. Kebijakan yang tidak diperbarui untuk menangani IPv6 alamat dapat memengaruhi akses klien ke API Gateway saat mereka mulai menggunakan titik akhir dualstack. Untuk informasi selengkapnya, lihat [Menggunakan IPv6 alamat dalam kebijakan IAM](api-ref.md#api-reference-service-endpoints-dualstack-iam).
## Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber saat menggunakan API pribadi
Contoh kebijakan sumber daya berikut menyangkal (memblokir) lalu lintas masuk ke API pribadi dari dua blok alamat IP sumber yang ditentukan. Saat menggunakan pribadi APIs, titik akhir VPC untuk `execute-api` menulis ulang alamat IP sumber asli. `aws:VpcSourceIp`Kondisi memfilter permintaan terhadap alamat IP pemohon asli.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"]
}
}
}
]
}
```
------
## Contoh: Izinkan lalu lintas API pribadi berdasarkan titik akhir VPC atau VPC sumber
Contoh kebijakan sumber daya berikut mengizinkan lalu lintas masuk ke API pribadi hanya dari virtual private cloud (VPC) atau titik akhir VPC tertentu.
Contoh kebijakan sumber daya ini menentukan VPC sumber:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpc": "vpc-1a2b3c4d"
}
}
}
]
}
```
------
Contoh kebijakan sumber daya ini menentukan titik akhir VPC sumber:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"StringNotEquals": {
"aws:SourceVpce": "vpce-1a2b3c4d"
}
}
}
]
}
```
------
# Membuat dan melampirkan kebijakan sumber daya API Gateway ke API
Agar pengguna dapat mengakses API Anda dengan memanggil layanan eksekusi API, Anda harus membuat kebijakan sumber daya API Gateway dan melampirkan kebijakan tersebut ke API. Saat Anda melampirkan kebijakan ke API Anda, kebijakan tersebut menerapkan izin dalam kebijakan ke metode di API. Jika memperbarui kebijakan sumber daya, Anda harus menerapkan API.
**Topics**
+ [Prasyarat](#apigateway-resource-policies-prerequisites)
+ [Melampirkan kebijakan sumber daya ke API Gateway API](#apigateway-resource-policies-create-attach-procedure)
+ [Memecahkan masalah kebijakan sumber daya Anda](#apigateway-resource-policies-troubleshoot)
## Prasyarat
Untuk memperbarui kebijakan sumber daya API Gateway, Anda memerlukan `apigateway:UpdateRestApiPolicy` izin dan `apigateway:PATCH` izin.
Untuk API Regional atau yang dioptimalkan tepi, Anda dapat melampirkan kebijakan sumber daya ke API saat Anda membuatnya, atau setelah diterapkan. Untuk API pribadi, Anda tidak dapat menerapkan API tanpa kebijakan sumber daya. Untuk informasi selengkapnya, lihat [REST pribadi APIs di API Gateway](apigateway-private-apis.md).
## Melampirkan kebijakan sumber daya ke API Gateway API
Prosedur berikut menunjukkan cara melampirkan kebijakan sumber daya ke API Gateway API.
------
#### [ Konsol Manajemen AWS ]
**Untuk melampirkan kebijakan sumber daya ke API Gateway API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Di panel navigasi utama, pilih **Kebijakan sumber daya**.
1. Pilih **Buat kebijakan**.
1. (Opsional) **Pilih templat** untuk menghasilkan contoh kebijakan.
Dalam contoh kebijakan, placeholder dilampirkan dalam double curly braces (). `"{{placeholder}}"` Ganti masing-masing placeholder, termasuk kawat gigi keriting, dengan informasi yang diperlukan.
1. Jika Anda tidak menggunakan salah satu contoh templat, masukkan kebijakan sumber daya Anda.
1. Pilih **Simpan perubahan**.
Jika API telah digunakan sebelumnya di konsol API Gateway, Anda harus menerapkannya kembali agar kebijakan sumber daya diterapkan.
------
#### [ AWS CLI ]
Untuk menggunakan AWS CLI untuk membuat API baru dan melampirkan kebijakan sumber daya ke dalamnya, gunakan [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)perintah berikut:
```
aws apigateway create-rest-api \
--name "api-name" \
--policy "{\"jsonEscapedPolicyDocument\"}"
```
Untuk menggunakan AWS CLI untuk melampirkan kebijakan sumber daya ke API yang ada, gunakan [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)perintah berikut:
```
aws apigateway update-rest-api \
--rest-api-id api-id \
--patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"'
```
Anda juga dapat melampirkan kebijakan sumber daya Anda sebagai `policy.json` file terpisah dan memasukkannya ke dalam [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)perintah Anda. [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)Perintah berikut membuat API baru dengan kebijakan sumber daya:
```
aws apigateway create-rest-api \
--name "api-name" \
--policy file://policy.json
```
`policy.json`adalah kebijakan sumber daya API Gateway, seperti[Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example).
------
#### [ AWS CloudFormation ]
Anda dapat menggunakan CloudFormation untuk membuat API dengan kebijakan sumber daya. Contoh berikut membuat REST API dengan contoh kebijakan sumber daya,[Contoh: Tolak lalu lintas API berdasarkan alamat atau rentang IP sumber](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example).
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: testapi
Policy:
Statement:
- Action: 'execute-api:Invoke'
Effect: Allow
Principal: '*'
Resource: 'execute-api:/*'
- Action: 'execute-api:Invoke'
Effect: Deny
Principal: '*'
Resource: 'execute-api:/*'
Condition:
IpAddress:
'aws:SourceIp': ["192.0.2.0/24", "198.51.100.0/24" ]
Version: 2012-10-17
Resource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'helloworld'
MethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref Resource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: MOCK
RequestTemplates:
application/json: '{"statusCode": 200}'
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: '{}'
MethodResponses:
- StatusCode: 200
ResponseModels:
application/json: 'Empty'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- MethodGet
Properties:
RestApiId: !Ref Api
StageName: test
```
------
## Memecahkan masalah kebijakan sumber daya Anda
Panduan pemecahan masalah berikut dapat membantu menyelesaikan masalah dengan kebijakan sumber daya Anda.
### API saya mengembalikan \$1"Message” :"User: anonymous tidak diizinkan untuk melakukan: execute-api:invoke on resource: arn:aws:execute-api:us-east-1: \$1\$1\$1\$1\$1\$1\$1\$1/\$1\$1\$1\$1/\$1\$1\$1\$1/ "\$1
Dalam kebijakan sumber daya Anda, jika Anda menetapkan Principal ke AWS prinsipal, seperti berikut ini:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111111111111:role/developer",
"arn:aws:iam::111111111111:role/Admin"
]
},
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/stage/GET/pets"
]
}
]
}
```
------
Anda harus menggunakan `AWS_IAM` otorisasi untuk setiap metode di API Anda, atau API Anda mengembalikan pesan kesalahan sebelumnya. Untuk petunjuk selengkapnya tentang cara mengaktifkan `AWS_IAM` otorisasi untuk suatu metode, lihat[Metode untuk REST APIs di API Gateway](how-to-method-settings.md).
### Kebijakan sumber daya saya tidak diperbarui
Jika memperbarui kebijakan sumber daya setelah API dibuat, Anda harus menerapkan API untuk menyebarkan perubahan setelah Anda melampirkan kebijakan yang diperbarui. Memperbarui atau menyimpan kebijakan saja tidak akan mengubah perilaku runtime API. Untuk informasi selengkapnya tentang penerapan API Anda, lihat[Menerapkan REST APIs di API Gateway](how-to-deploy-api.md).
### Kebijakan sumber daya saya mengembalikan kesalahan berikut: Dokumen kebijakan tidak valid. Silakan periksa sintaks kebijakan dan pastikan bahwa Prinsipal valid.
Untuk mengatasi masalah kesalahan ini, sebaiknya periksa sintaks kebijakan terlebih dahulu. Untuk informasi selengkapnya, lihat [Mengakses ikhtisar bahasa kebijakan untuk Amazon API Gateway](apigateway-control-access-policy-language-overview.md). Kami juga menyarankan Anda memeriksa bahwa semua prinsipal yang ditentukan valid dan belum dihapus.
Selain itu, jika API Anda berada di [Wilayah keikutsertaan](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#optinregion), verifikasi bahwa semua akun dalam kebijakan sumber daya mengaktifkan Region.
# AWS kunci kondisi yang dapat digunakan dalam kebijakan sumber daya API Gateway
Tabel berikut berisi kunci AWS kondisi yang dapat digunakan dalam kebijakan sumber daya APIs di API Gateway untuk setiap jenis otorisasi.
Untuk informasi selengkapnya tentang kunci AWS kondisi, lihat [Kunci Konteks Kondisi AWS Global](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html).
| **Kunci kondisi** | **Kriteria** | **Kebutuhan`AuthN`?** | **Jenis otorisasi** |
| --- | --- | --- | --- |
| aws:CurrentTime | Tidak ada | Tidak | Semua |
| aws:EpochTime | Tidak ada | Tidak | Semua |
| aws:TokenIssueTime | Kunci hanya ada dalam permintaan yang ditandatangani menggunakan kredensyal keamanan sementara. | Ya | IAM |
| aws:MultiFactorAuthPresent | Kunci hanya ada dalam permintaan yang ditandatangani menggunakan kredensyal keamanan sementara. | Ya | IAM |
| aws:MultiFactorAuthAge | Kunci hadir hanya jika MFA hadir dalam permintaan. | Ya | IAM |
| aws:PrincipalAccount | Tidak ada | Ya | IAM |
| aws:PrincipalArn | Tidak ada | Ya | IAM |
| aws:PrincipalOrgID | Kunci ini disertakan dalam konteks permintaan hanya jika kepala sekolah adalah anggota organisasi. | Ya | IAM |
| aws:PrincipalOrgPaths | Kunci ini disertakan dalam konteks permintaan hanya jika kepala sekolah adalah anggota organisasi. | Ya | IAM |
| aws:PrincipalTag | Kunci ini disertakan dalam konteks permintaan jika prinsipal menggunakan pengguna IAM dengan tag terlampir. Ini disertakan untuk prinsipal yang menggunakan peran IAM dengan tag yang disematkan atau tag sesi. | Ya | IAM |
| aws:PrincipalType | Tidak ada | Ya | IAM |
| aws:Referer | Kunci hadir hanya jika nilai disediakan oleh pemanggil di header HTTP. | Tidak | Semua |
| aws:SecureTransport | Tidak ada | Tidak | Semua |
| aws:SourceArn | Tidak ada | Tidak | Semua |
| aws:SourceIp | Tidak ada | Tidak | Semua |
| aws:SourceVpc | Kunci ini hanya dapat digunakan untuk pribadi APIs. | Tidak | Semua |
| aws:SourceVpce | Kunci ini hanya dapat digunakan untuk pribadi APIs. | Tidak | Semua |
| aws:VpcSourceIp | Kunci ini hanya dapat digunakan untuk pribadi APIs. | Tidak | Semua |
| aws:UserAgent | Kunci hadir hanya jika nilai disediakan oleh pemanggil di header HTTP. | Tidak | Semua |
| aws:userid | Tidak ada | Ya | IAM |
| aws:username | Tidak ada | Ya | IAM |
# Kontrol akses ke REST API dengan izin IAM
Anda mengontrol akses ke Amazon API Gateway API dengan [izin IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) dengan mengontrol akses ke dua proses komponen API Gateway berikut:
+ Untuk membuat, menerapkan, dan mengelola API di API Gateway, Anda harus memberikan izin pengembang API untuk melakukan tindakan yang diperlukan yang didukung oleh komponen manajemen API API Gateway.
+ Untuk memanggil API yang diterapkan atau menyegarkan cache API, Anda harus memberikan izin pemanggil API untuk melakukan tindakan IAM yang diperlukan yang didukung oleh komponen eksekusi API API Gateway.
Kontrol akses untuk dua proses melibatkan model izin yang berbeda, dijelaskan selanjutnya.
## Model izin API Gateway untuk membuat dan mengelola API
[Untuk mengizinkan pengembang API membuat dan mengelola API di API Gateway, Anda harus [membuat kebijakan izin IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) yang memungkinkan pengembang API tertentu untuk membuat, memperbarui, menerapkan, melihat, atau menghapus entitas API yang diperlukan.](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) Anda melampirkan kebijakan izin ke pengguna, peran, atau grup.
Untuk memberikan akses dan menambahkan izin bagi pengguna, grup, atau peran Anda:
+ Pengguna dan grup di AWS IAM Identity Center:
Buat rangkaian izin. Ikuti instruksi di [Buat rangkaian izin](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) dalam *Panduan Pengguna AWS IAM Identity Center *.
+ Pengguna yang dikelola di IAM melalui penyedia identitas:
Buat peran untuk federasi identitas. Ikuti instruksi dalam [Buat peran untuk penyedia identitas pihak ketiga (federasi)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) dalam *Panduan Pengguna IAM*.
+ Pengguna IAM:
+ Buat peran yang dapat diambil pengguna Anda. Ikuti instruksi dalam [Buat peran untuk pengguna IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) dalam *Panduan Pengguna IAM*.
+ (Tidak disarankan) Lampirkan kebijakan langsung ke pengguna atau tambahkan pengguna ke grup pengguna. Ikuti petunjuk dalam [Menambahkan izin ke pengguna (konsol)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) dalam *Panduan Pengguna IAM*.
Untuk informasi selengkapnya tentang cara menggunakan model izin ini, lihat[Kebijakan berbasis identitas API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
## Model izin API Gateway untuk menjalankan API
Untuk mengizinkan pemanggil API menjalankan API atau menyegarkan caching, Anda harus membuat kebijakan IAM yang mengizinkan pemanggil API tertentu untuk menjalankan metode API yang memungkinkan otentikasi pengguna diaktifkan. Pengembang API menetapkan `authorizationType` properti metode `AWS_IAM` agar pemanggil mengirimkan kredensi pengguna untuk diautentikasi. API Gateway mendukung Signature Version 4a (Sigv4a) dan Signature Version 4 (SigV4) untuk mengautentikasi kredensi pengguna. Untuk informasi selengkapnya, lihat [Versi AWS Tanda Tangan 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Kemudian, Anda melampirkan kebijakan ke pengguna, peran, atau grup.
[Dalam pernyataan kebijakan izin IAM ini, `Resource` elemen IAM berisi daftar metode API yang diterapkan yang diidentifikasi oleh kata kerja HTTP dan jalur sumber daya API Gateway yang diberikan.](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `Action`Elemen IAM berisi tindakan eksekusi API Gateway API yang diperlukan. Tindakan ini mencakup `execute-api:Invoke` atau`execute-api:InvalidateCache`, di mana `execute-api` menunjuk komponen eksekusi API yang mendasari API Gateway.
Untuk informasi selengkapnya tentang cara menggunakan model izin ini, lihat[Kontrol akses untuk menjalankan API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
Ketika API terintegrasi dengan AWS layanan (misalnya, AWS Lambda) di bagian belakang, API Gateway juga harus memiliki izin untuk mengakses AWS sumber daya terintegrasi (misalnya, menjalankan fungsi Lambda) atas nama pemanggil API. Untuk memberikan izin ini, buat peran IAM dari **AWS layanan untuk jenis API Gateway**. Saat Anda membuat peran ini di konsol Manajemen IAM, peran yang dihasilkan ini berisi kebijakan kepercayaan IAM berikut yang mendeklarasikan API Gateway sebagai entitas tepercaya yang diizinkan untuk mengambil peran:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Jika Anda membuat peran IAM dengan memanggil [perintah create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) CLI atau metode SDK yang sesuai, Anda harus memberikan kebijakan kepercayaan di atas sebagai parameter input. `assume-role-policy-document` Jangan mencoba membuat kebijakan semacam itu secara langsung di konsol Manajemen IAM atau memanggil perintah AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) atau metode SDK yang sesuai.
Agar API Gateway memanggil AWS layanan terintegrasi, Anda juga harus melampirkan kebijakan izin IAM yang sesuai peran ini untuk memanggil layanan terintegrasi AWS . Misalnya, untuk memanggil fungsi Lambda, Anda harus menyertakan kebijakan izin IAM berikut dalam peran IAM:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
------
Perhatikan bahwa Lambda mendukung kebijakan akses berbasis sumber daya, yang menggabungkan kebijakan kepercayaan dan izin. Saat mengintegrasikan API dengan fungsi Lambda menggunakan konsol API Gateway, Anda tidak diminta untuk menyetel peran IAM ini secara eksplisit, karena konsol menetapkan izin berbasis sumber daya pada fungsi Lambda untuk Anda, dengan persetujuan Anda.
**catatan**
Untuk memberlakukan kontrol akses ke AWS layanan, Anda dapat menggunakan model izin berbasis pemanggil, di mana kebijakan izin langsung dilampirkan ke pengguna atau grup pemanggil, atau model izin berbasis peran, di mana kebijakan izin dilampirkan ke peran IAM yang dapat diasumsikan oleh API Gateway. Kebijakan izin mungkin berbeda dalam kedua model. Misalnya, kebijakan berbasis pemanggil memblokir akses sementara kebijakan berbasis peran mengizinkannya. Anda dapat memanfaatkan ini untuk mengharuskan pengguna mengakses AWS layanan hanya melalui API Gateway API.
# Kontrol akses untuk menjalankan API
Di bagian ini, Anda mempelajari tentang model izin untuk mengontrol akses ke API Anda menggunakan izin IAM. Ketika otorisasi IAM diaktifkan, klien harus menggunakan Signature Version 4a (Sigv4a) dan Sigv4a Versi Tanda Tangan 4 (SigV4) untuk menandatangani permintaan mereka dengan kredensi. AWS Untuk informasi selengkapnya, lihat [Versi AWS Tanda Tangan 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html).
Pada bagian ini, kami menampilkan templat pernyataan kebijakan IAM dan referensi pernyataan kebijakan. Referensi pernyataan kebijakan mencakup format `Action` dan `Resource` bidang yang terkait dengan layanan eksekusi API. Gunakan referensi ini untuk membuat pernyataan kebijakan IAM Anda. Saat membuat pernyataan kebijakan IAM, Anda mungkin perlu mempertimbangkan bagaimana kebijakan sumber daya API Gateway memengaruhi alur kerja otorisasi. Untuk informasi selengkapnya, lihat [Bagaimana kebijakan sumber daya API Gateway memengaruhi alur kerja otorisasi](apigateway-authorization-flow.md).
Untuk pribadi APIs, Anda harus menggunakan kombinasi kebijakan sumber daya API Gateway dan kebijakan titik akhir VPC. Untuk informasi selengkapnya, lihat topik berikut:
+ [Kontrol akses ke REST API dengan kebijakan sumber daya API Gateway](apigateway-resource-policies.md)
+ [Menggunakan kebijakan titik akhir VPC secara pribadi APIs di API Gateway](apigateway-vpc-endpoint-policies.md)
## Kontrol siapa yang dapat memanggil metode API Gateway API dengan kebijakan IAM
Untuk mengontrol siapa yang dapat atau tidak dapat memanggil API yang diterapkan dengan izin IAM, buat dokumen kebijakan IAM dengan izin yang diperlukan. Template untuk dokumen kebijakan semacam itu ditampilkan sebagai berikut.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Permission",
"Action": [
"execute-api:Execution-operation"
],
"Resource": [
"arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path"
]
}
]
}
```
------
Di sini, `Permission` akan diganti oleh `Allow` atau `Deny` tergantung pada apakah Anda ingin memberikan atau mencabut izin yang disertakan. `Execution-operation`akan digantikan oleh operasi yang didukung oleh layanan eksekusi API. `METHOD_HTTP_VERB`singkatan dari kata kerja HTTP yang didukung oleh sumber daya yang ditentukan. `Resource-path`adalah placeholder untuk jalur URL dari `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` instance API yang diterapkan yang mendukung hal tersebut. `METHOD_HTTP_VERB` Untuk informasi selengkapnya, lihat [Referensi pernyataan kebijakan IAM untuk menjalankan API di API Gateway](#api-gateway-calling-api-permissions).
**catatan**
Agar kebijakan IAM efektif, Anda harus mengaktifkan autentikasi IAM pada metode API dengan menyetel properti `AWS_IAM` metode. `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` Gagal melakukannya akan membuat metode API ini dapat diakses publik.
Misalnya, untuk memberikan izin kepada pengguna untuk melihat daftar hewan peliharaan yang diekspos oleh API tertentu, tetapi untuk menolak izin pengguna untuk menambahkan hewan peliharaan ke daftar, Anda dapat menyertakan pernyataan berikut dalam kebijakan IAM:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets"
]
}
]
}
```
------
Untuk memberikan izin kepada pengguna untuk melihat hewan peliharaan tertentu yang diekspos oleh API yang dikonfigurasi sebagai`GET /pets/{petId}`, Anda dapat menyertakan pernyataan berikut dalam kebijakan IAM:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2"
]
}
]
}
```
------
## Referensi pernyataan kebijakan IAM untuk menjalankan API di API Gateway
Informasi berikut menjelaskan format Action and Resource dari pernyataan kebijakan IAM tentang izin akses untuk menjalankan API.
### Format tindakan izin untuk menjalankan API di API Gateway
`Action`Ekspresi pelaksana API memiliki format umum berikut:
```
execute-api:action
```
di *action* mana tindakan pelaksana API yang tersedia:
+ **\$1**, yang mewakili semua tindakan berikut.
+ **Invoke**, digunakan untuk memanggil API atas permintaan klien.
+ **InvalidateCache**, digunakan untuk membatalkan cache API atas permintaan klien.
### Format sumber daya izin untuk menjalankan API di API Gateway
`Resource`Ekspresi pelaksana API memiliki format umum berikut:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier
```
di mana:
+ *region*adalah AWS wilayah (seperti **us-east-1** atau **\$1** untuk semua AWS wilayah) yang sesuai dengan API yang diterapkan untuk metode tersebut.
+ *account-id*adalah Id AWS akun 12 digit dari pemilik REST API.
+ *api-id*adalah pengidentifikasi API Gateway yang telah ditetapkan ke API untuk metode tersebut.
+ *stage-name*adalah nama tahap yang terkait dengan metode.
+ *HTTP-VERB*adalah kata kerja HTTP untuk metode ini. Ini bisa menjadi salah satu dari yang berikut: GET, POST, PUT, DELETE, PATCH.
+ *resource-path-specifier*adalah jalan menuju metode yang diinginkan.
**catatan**
Jika Anda menentukan wildcard (`*`), `Resource` ekspresi akan menerapkan wildcard ke ekspresi lainnya.
Beberapa contoh ekspresi sumber daya meliputi:
+ **arn:aws:execute-api:\$1:\$1:\$1**untuk jalur sumber daya apa pun di tahap apa pun, untuk API apa pun di AWS wilayah mana pun.
+ **arn:aws:execute-api:us-east-1:\$1:\$1**untuk jalur sumber daya apa pun di tahap apa pun, untuk API apa pun di AWS wilayah`us-east-1`.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1**untuk jalur sumber daya apa pun di tahap apa pun, untuk API dengan pengenal *api-id* di AWS wilayah us-east-1.
+ **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1**untuk jalur sumber daya apa pun pada tahap`test`, untuk API dengan pengenal *api-id* di AWS wilayah us-east-1.
Untuk mempelajari selengkapnya, lihat [Referensi API Gateway Amazon Resource Name (ARN)](arn-format-reference.md).
# Contoh kebijakan IAM untuk izin eksekusi API
Untuk model izin dan informasi latar belakang lainnya, lihat[Kontrol akses untuk menjalankan API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
Pernyataan kebijakan berikut memberikan izin kepada pengguna untuk memanggil metode POST apa pun di sepanjang jalur`mydemoresource`, pada tahap`test`, untuk API dengan pengenal`a123456789`, dengan asumsi API yang sesuai telah diterapkan ke wilayah AWS us-east-1:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*"
]
}
]
}
```
------
Contoh pernyataan kebijakan berikut memberikan izin kepada pengguna untuk memanggil metode apa pun di jalur sumber daya`petstorewalkthrough/pets`, dalam tahap apa pun, untuk API dengan pengenal`a123456789`, di AWS wilayah mana pun di mana API terkait telah digunakan:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets"
]
}
]
}
```
------
# Menggunakan kebijakan titik akhir VPC secara pribadi APIs di API Gateway
Untuk meningkatkan keamanan API pribadi Anda, Anda dapat membuat kebijakan titik akhir VPC. Kebijakan titik akhir VPC adalah kebijakan sumber daya IAM yang Anda lampirkan ke titik akhir VPC. Untuk informasi selengkapnya, lihat [Mengontrol Akses ke Layanan dengan VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html).
Anda mungkin ingin membuat kebijakan titik akhir VPC untuk melakukan tugas-tugas berikut.
+ Izinkan hanya organisasi atau sumber daya tertentu untuk mengakses titik akhir VPC Anda dan menjalankan API Anda.
+ Gunakan satu kebijakan dan hindari kebijakan berbasis sesi atau berbasis peran untuk mengontrol lalu lintas ke API Anda.
+ Kencangkan perimeter keamanan aplikasi Anda saat bermigrasi dari tempat ke AWS lokasi.
## Pertimbangan kebijakan titik akhir VPC
Berikut ini adalah pertimbangan untuk kebijakan titik akhir VPC Anda:
+ Identitas invoker dievaluasi berdasarkan nilai `Authorization` header. Kebijakan titik akhir VPC dievaluasi terlebih dahulu, lalu API Gateway mengevaluasi permintaan, berdasarkan jenis otorisasi yang dikonfigurasi pada permintaan metode. Tabel berikut menunjukkan bagaimana kebijakan titik akhir VPC dievaluasi berdasarkan isi nilai header. `Authorization`
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-vpc-endpoint-policies.html)
+ [Jika kontrol akses Anda bergantung pada penggunaan token pembawa, seperti Lambda atau otorisasi Amazon Cognito, Anda dapat mengontrol perimeter keamanan Anda dengan menggunakan properti sumber daya.](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties)
+ Jika kontrol otorisasi Anda menggunakan otorisasi IAM, Anda dapat mengontrol perimeter keamanan Anda dengan menggunakan [properti sumber daya](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties) dan [properti](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-principal) prinsipal.
+ Kebijakan titik akhir VPC dapat digunakan bersama dengan kebijakan sumber daya API Gateway. Kebijakan sumber daya API Gateway menentukan prinsipal mana yang dapat mengakses API. Kebijakan endpoint menentukan siapa yang dapat mengakses VPC dan mana yang APIs dapat dipanggil dari titik akhir VPC. API pribadi Anda memerlukan kebijakan sumber daya tetapi Anda tidak perlu membuat kebijakan titik akhir VPC kustom.
## Contoh kebijakan titik akhir VPC
Anda dapat membuat kebijakan untuk titik akhir Amazon Virtual Private Cloud untuk Amazon API Gateway yang dapat Anda tentukan berikut ini.
+ Prinsipal yang dapat melakukan tindakan.
+ Tindakan yang dapat dilakukan.
+ Sumber daya yang dapat memiliki tindakan yang dilakukan pada mereka.
Ini mungkin tergantung pada isi header otorisasi Anda. Untuk informasi selengkapnya, lihat [Pertimbangan kebijakan titik akhir VPC](#apigateway-vpc-endpoint-policies-considerations). Untuk kebijakan contoh tambahan, lihat [Contoh kebijakan perimeter data](https://github.com/aws-samples/data-perimeter-policy-examples) di GitHub situs web.
Untuk melampirkan kebijakan ke titik akhir VPC, Anda harus menggunakan konsol VPC. Untuk informasi selengkapnya, lihat [Mengontrol Akses ke Layanan dengan VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html).
## Contoh 1: Kebijakan titik akhir VPC yang memberikan akses ke dua APIs
Contoh kebijakan berikut memberikan akses ke hanya dua spesifik APIs melalui titik akhir VPC yang dilampirkan kebijakan tersebut.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*",
"arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*"
]
}
]
}
```
------
## Contoh 2: Kebijakan titik akhir VPC yang memberikan akses ke metode GET
Contoh kebijakan berikut memberi pengguna akses ke `GET` metode untuk API tertentu melalui titik akhir VPC tempat kebijakan dilampirkan.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": "*",
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*"
]
}
]
}
```
------
## Contoh 3: Kebijakan titik akhir VPC yang memberikan akses pengguna tertentu ke API tertentu
Contoh kebijakan berikut memberikan akses pengguna tertentu ke API tertentu melalui titik akhir VPC tempat kebijakan dilampirkan.
Dalam hal ini, karena kebijakan membatasi akses ke prinsipal IAM tertentu, Anda harus menyetel metode ke atau`authorizationType`. `AWS_IAM` `NONE`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Principal": {
"AWS": [
"arn:aws:iam::123412341234:user/MyUser"
]
},
"Action": [
"execute-api:Invoke"
],
"Effect": "Allow",
"Resource": [
"arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*"
]
}
]
}
```
------
## Contoh 4: Kebijakan titik akhir VPC yang memberikan pengguna akses ke nama domain khusus tertentu dan setiap API yang dipetakan ke domain
Contoh kebijakan berikut memberi pengguna akses ke nama domain khusus khusus untuk pribadi APIs melalui titik akhir VPC tempat kebijakan dilampirkan. Dengan kebijakan ini, selama pengguna telah membuat asosiasi akses nama domain antara titik akhir VPC dan nama domain kustom dan diberikan akses untuk memanggil nama domain kustom dan API pribadi apa pun yang dipetakan ke nama domain kustom, pengguna dapat memanggil apa pun APIs yang dipetakan ke nama domain kustom ini. Untuk informasi selengkapnya, lihat [Nama domain khusus untuk pribadi APIs di API Gateway](apigateway-private-custom-domains.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"*"
],
"Condition": {
"ArnEquals": {
"execute-api:viaDomainArn": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6",
}
}
}
]
}
```
------
## Contoh 5: Kebijakan titik akhir VPC yang memberikan atau menolak akses ke sumber daya spesifik dan domain APIs
Contoh kebijakan berikut memberi pengguna akses ke sumber daya tertentu APIs dan domain. Dengan kebijakan ini, selama pengguna telah membuat asosiasi akses nama domain antara titik akhir VPC dan nama domain kustom dan diberikan akses untuk memanggil nama domain kustom dan API pribadi apa pun yang dipetakan ke nama domain kustom, pengguna dapat memanggil sumber daya pribadi dan domain yang diizinkan. APIs Untuk informasi selengkapnya, lihat [Nama domain khusus untuk pribadi APIs di API Gateway](apigateway-private-custom-domains.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6",
"arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/*"
]
},
{
"Effect": "Deny",
"Principal": {
"AWS": "*"
},
"Action": "execute-api:Invoke",
"Resource": [
"arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/admin/*",
"arn:aws:execute-api:us-west-2:111122223333:bcd123455/*"
]
}
]
}
```
------
## Contoh 6: Kebijakan titik akhir VPC yang memberikan atau menolak akses oleh kepala sekolah dan sumber daya milik suatu organisasi
Contoh kebijakan berikut memberikan akses ke kepala sekolah dan sumber daya milik organisasi.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Condition": {
"StringEquals": {
"aws:ResourceOrgID": "o-abcd1234",
"aws:PrincipalOrgID": "o-abcd1234"
}
},
"Action": "*",
"Resource": "*",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources"
}
]
}
```
------
# Gunakan tag untuk mengontrol akses ke REST APIs di API Gateway
Izin untuk mengakses REST APIs dapat disetel dengan baik menggunakan kontrol akses berbasis atribut dalam kebijakan IAM.
Lihat informasi yang lebih lengkap di [Menggunakan tag untuk mengontrol akses ke sumber daya API API Gateway REST API](apigateway-tagging-iam-policy.md).
# Gunakan otorisasi API Gateway Lambda
Gunakan *Lambda Authorizer (sebelumnya dikenal sebagai otorisasi* *kustom) untuk mengontrol akses ke API* Anda. Saat klien membuat permintaan ke metode API Anda, API Gateway memanggil otorisasi Lambda Anda. Authorizer Lambda mengambil identitas pemanggil sebagai input dan mengembalikan kebijakan IAM sebagai output.
Gunakan otorisasi Lambda untuk menerapkan skema otorisasi khusus. Skema Anda dapat menggunakan parameter permintaan untuk menentukan identitas pemanggil atau menggunakan strategi otentikasi token pembawa seperti OAuth atau SALL. Buat otorisasi Lambda di konsol API API Gateway REST API, menggunakan AWS CLI, atau SDK. AWS
## Alur kerja otorisasi otorisasi Lambda
Diagram berikut menunjukkan alur kerja otorisasi untuk otorisasi Lambda.
![\[Alur kerja otorisasi API Gateway Lambda\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/custom-auth-workflow.png)
**Alur kerja otorisasi API Gateway Lambda**
1. Klien memanggil metode pada API Gateway API, meneruskan token pembawa atau parameter permintaan.
1. API Gateway memeriksa apakah permintaan metode dikonfigurasi dengan otorisasi Lambda. Jika ya, API Gateway memanggil fungsi Lambda.
1. Fungsi Lambda mengautentikasi pemanggil. Fungsi ini dapat mengautentikasi dengan cara-cara berikut:
+ Dengan memanggil OAuth penyedia untuk mendapatkan token OAuth akses.
+ Dengan memanggil penyedia SAFL untuk mendapatkan pernyataan SAFL.
+ Dengan membuat kebijakan IAM berdasarkan nilai parameter permintaan.
+ Dengan mengambil kredensi dari database.
1. Fungsi Lambda mengembalikan kebijakan IAM dan pengidentifikasi utama. Jika fungsi Lambda tidak mengembalikan informasi itu, panggilan gagal.
1. API Gateway mengevaluasi kebijakan IAM.
+ Jika akses ditolak, API Gateway mengembalikan kode status HTTP yang sesuai, seperti`403 ACCESS_DENIED`.
+ Jika akses diizinkan, API Gateway akan memanggil metode.
Jika Anda mengaktifkan caching otorisasi, API Gateway menyimpan kebijakan agar fungsi otorisasi Lambda tidak dipanggil lagi. Pastikan kebijakan Anda berlaku untuk semua sumber daya dan metode di seluruh API Anda.
Anda dapat menyesuaikan `403 ACCESS_DENIED` atau tanggapan `401 UNAUTHORIZED` gateway. Untuk mempelajari selengkapnya, lihat [Tanggapan gateway untuk REST APIs di API Gateway](api-gateway-gatewayResponse-definition.md).
## Memilih jenis otorisasi Lambda
Ada dua jenis otorisasi Lambda:
**Minta otorisasi Lambda berbasis parameter (otorisasi) `REQUEST`**
`REQUEST`Authorizer menerima identitas pemanggil dalam kombinasi header, parameter string kueri, dan variabel [`stageVariables`](api-gateway-mapping-template-reference.md#stagevariables-template-reference). [`$context`](api-gateway-mapping-template-reference.md#context-variable-reference) Anda dapat menggunakan `REQUEST` otorisasi untuk membuat kebijakan berbutir halus berdasarkan informasi dari beberapa sumber identitas, seperti variabel dan konteks. `$context.path` `$context.httpMethod`
Jika Anda mengaktifkan caching otorisasi untuk `REQUEST` otorisasi, API Gateway memverifikasi bahwa semua sumber identitas yang ditentukan ada dalam permintaan. Jika sumber identifikasi tertentu hilang, null, atau kosong, API Gateway mengembalikan respons `401 Unauthorized` HTTP tanpa memanggil fungsi otorisasi Lambda. Ketika beberapa sumber identitas didefinisikan, mereka semua digunakan untuk mendapatkan kunci cache otorisasi, dengan urutan dipertahankan. Anda dapat menentukan kunci cache berbutir halus dengan menggunakan beberapa sumber identitas.
Jika Anda mengubah salah satu bagian kunci cache, dan menerapkan ulang API Anda, otorisasi akan membuang dokumen kebijakan yang di-cache dan membuat yang baru.
Jika Anda mematikan caching otorisasi untuk `REQUEST` otorisasi, API Gateway langsung meneruskan permintaan ke fungsi Lambda.
**Pengotorisasi Lambda berbasis token (otorisasi) `TOKEN`**
`TOKEN`Authorizer menerima identitas penelepon dalam token pembawa, seperti JSON Web Token (JWT) atau token. OAuth
Jika Anda mengaktifkan caching otorisasi untuk `TOKEN` otorisasi, nama header yang ditentukan dalam sumber token menjadi kunci cache.
Selain itu, Anda dapat menggunakan validasi token untuk memasukkan RegEx pernyataan. API Gateway melakukan validasi awal token input terhadap ekspresi ini dan memanggil fungsi otorisasi Lambda setelah validasi berhasil. Ini membantu mengurangi panggilan ke API Anda.
`IdentityValidationExpression`Properti ini didukung hanya untuk `TOKEN` otorisasi. Untuk informasi selengkapnya, lihat [x-amazon-apigateway-authorizer objek](api-gateway-swagger-extensions-authorizer.md).
**catatan**
Kami menyarankan Anda menggunakan `REQUEST` otorisasi untuk mengontrol akses ke API Anda. Anda dapat mengontrol akses ke API berdasarkan beberapa sumber identitas saat menggunakan `REQUEST` otorisasi, dibandingkan dengan satu sumber identitas saat menggunakan `TOKEN` otorisasi. Selain itu, Anda dapat memisahkan kunci cache menggunakan beberapa sumber identitas untuk `REQUEST` otorisasi.
## Contoh fungsi Lambda `REQUEST` authorizer
Kode contoh berikut membuat fungsi otorisasi Lambda yang memungkinkan permintaan jika `HeaderAuth1` header yang disediakan klien, parameter `QueryString1` kueri, dan variabel tahap `StageVar1` semua cocok dengan nilai yang ditentukan,, dan`headerValue1`, `queryValue1` masing-masing. `stageValue1`
------
#### [ Node.js ]
```
// A simple request-based authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header, QueryString1
// query parameter, and stage variable of StageVar1 all match
// specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
// respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var pathParameters = event.pathParameters;
var stageVariables = event.stageVariables;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var restApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var method = apiGatewayArnTmp[2];
var resource = '/'; // root resource
if (apiGatewayArnTmp[3]) {
resource += apiGatewayArnTmp[3];
}
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1"
&& stageVariables.StageVar1 === "stageValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Help function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17'; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple request-based authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied headerauth1 header, QueryString1
# query parameter, and stage variable of StageVar1 all match
# specified values of 'headerValue1', 'queryValue1', and 'stageValue1',
# respectively.
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
pathParameters = event['pathParameters']
stageVariables = event['stageVariables']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
restApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
method = apiGatewayArnTmp[2]
resource = '/'
if (apiGatewayArnTmp[3]):
resource += apiGatewayArnTmp[3]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return response
else:
print('unauthorized')
response = generateDeny('me', event['methodArn'])
return response
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17'
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
return authResponse
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
Dalam contoh ini, fungsi Lambda Authorizer memeriksa parameter input dan bertindak sebagai berikut:
+ Jika semua nilai parameter yang diperlukan cocok dengan nilai yang diharapkan, fungsi authorizer mengembalikan respons `200 OK` HTTP dan kebijakan IAM yang terlihat seperti berikut, dan permintaan metode berhasil:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
+ Jika tidak, fungsi authorizer mengembalikan respon `401 Unauthorized` HTTP, dan permintaan metode gagal.
Selain mengembalikan kebijakan IAM, fungsi otorisasi Lambda juga harus mengembalikan pengenal utama pemanggil. Secara opsional, ini dapat mengembalikan `context` objek yang berisi informasi tambahan yang dapat diteruskan ke backend integrasi. Untuk informasi selengkapnya, lihat [Keluaran dari otorisasi API Gateway Lambda](api-gateway-lambda-authorizer-output.md).
Dalam kode produksi, Anda mungkin perlu mengautentikasi pengguna sebelum memberikan otorisasi. Anda dapat menambahkan logika otentikasi dalam fungsi Lambda dengan memanggil penyedia otentikasi seperti yang diarahkan dalam dokumentasi untuk penyedia tersebut.
## Contoh fungsi Lambda `TOKEN` authorizer
Kode contoh berikut membuat fungsi otorisasi `TOKEN` Lambda yang memungkinkan pemanggil untuk memanggil metode jika nilai token yang disediakan klien adalah. `allow` Penelepon tidak diizinkan untuk memanggil permintaan jika nilai tokennya. `deny` Jika nilai token adalah `unauthorized` atau string kosong, fungsi authorizer mengembalikan `401 UNAUTHORIZED` respons.
------
#### [ Node.js ]
```
// A simple token-based authorizer example to demonstrate how to use an authorization token
// to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
// a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
// the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty
// string, the authorizer function returns an HTTP 401 status code. For any other token value,
// the authorizer returns an HTTP 500 status code.
// Note that token values are case-sensitive.
export const handler = function(event, context, callback) {
var token = event.authorizationToken;
switch (token) {
case 'allow':
callback(null, generatePolicy('user', 'Allow', event.methodArn));
break;
case 'deny':
callback(null, generatePolicy('user', 'Deny', event.methodArn));
break;
case 'unauthorized':
callback("Unauthorized"); // Return a 401 Unauthorized response
break;
default:
callback("Error: Invalid token"); // Return a 500 Invalid token response
}
};
// Help function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17';
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke';
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
```
------
#### [ Python ]
```
# A simple token-based authorizer example to demonstrate how to use an authorization token
# to allow or deny a request. In this example, the caller named 'user' is allowed to invoke
# a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke
# the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty
# string, the authorizer function returns an HTTP 401 status code. For any other token value,
# the authorizer returns an HTTP 500 status code.
# Note that token values are case-sensitive.
import json
def lambda_handler(event, context):
token = event['authorizationToken']
if token == 'allow':
print('authorized')
response = generatePolicy('user', 'Allow', event['methodArn'])
elif token == 'deny':
print('unauthorized')
response = generatePolicy('user', 'Deny', event['methodArn'])
elif token == 'unauthorized':
print('unauthorized')
raise Exception('Unauthorized') # Return a 401 Unauthorized response
return 'unauthorized'
try:
return json.loads(response)
except BaseException:
print('unauthorized')
return 'unauthorized' # Return a 500 error
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17'
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
```
------
Dalam contoh ini, ketika API menerima permintaan metode, API Gateway meneruskan token sumber ke fungsi otorisasi Lambda ini di atribut. `event.authorizationToken` Fungsi otorisasi Lambda membaca token dan bertindak sebagai berikut:
+ Jika nilai token`allow`, fungsi authorizer mengembalikan respons `200 OK` HTTP dan kebijakan IAM yang terlihat seperti berikut, dan permintaan metode berhasil:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
+ Jika nilai token`deny`, fungsi authorizer mengembalikan respons `200 OK` HTTP dan kebijakan `Deny` IAM yang terlihat seperti berikut, dan permintaan metode gagal:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/"
}
]
}
```
------
**catatan**
Di luar lingkungan pengujian, API Gateway mengembalikan respons `403 Forbidden` HTTP dan permintaan metode gagal.
+ Jika nilai token `unauthorized` atau string kosong, fungsi authorizer mengembalikan respons `401 Unauthorized` HTTP, dan panggilan metode gagal.
+ Jika token adalah hal lain, klien menerima `500 Invalid token` respons, dan panggilan metode gagal.
Selain mengembalikan kebijakan IAM, fungsi otorisasi Lambda juga harus mengembalikan pengenal utama pemanggil. Secara opsional, ini dapat mengembalikan `context` objek yang berisi informasi tambahan yang dapat diteruskan ke backend integrasi. Untuk informasi selengkapnya, lihat [Keluaran dari otorisasi API Gateway Lambda](api-gateway-lambda-authorizer-output.md).
Dalam kode produksi, Anda mungkin perlu mengautentikasi pengguna sebelum memberikan otorisasi. Anda dapat menambahkan logika otentikasi dalam fungsi Lambda dengan memanggil penyedia otentikasi seperti yang diarahkan dalam dokumentasi untuk penyedia tersebut.
## Contoh tambahan fungsi otorisasi Lambda
Daftar berikut menunjukkan contoh tambahan fungsi otorisasi Lambda. Anda dapat membuat fungsi Lambda di akun yang sama, atau akun lain, dari tempat Anda membuat API.
Untuk contoh fungsi Lambda sebelumnya, Anda dapat menggunakan built-in [AWSLambdaBasicExecutionRole](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html), karena fungsi ini tidak memanggil layanan lain AWS . Jika fungsi Lambda Anda memanggil AWS layanan lain, Anda harus menetapkan peran eksekusi IAM ke fungsi Lambda. Untuk membuat peran, ikuti instruksi dalam [Peran AWS Lambda Eksekusi](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html).
**Contoh tambahan fungsi otorisasi Lambda**
+ Untuk contoh aplikasi, lihat [Buka Perbankan Brasil - Sampel GitHub Otorisasi pada](https://github.com/aws-samples/openbanking-brazilian-auth-samples).
+ Untuk contoh fungsi Lambda lainnya, lihat [ aws-apigateway-lambda-authorizer-blueprints](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints) on. GitHub
+ Anda dapat membuat otorisasi Lambda yang mengautentikasi pengguna menggunakan kumpulan pengguna Amazon Cognito dan mengotorisasi penelepon berdasarkan penyimpanan kebijakan menggunakan Izin Terverifikasi. Untuk informasi selengkapnya, lihat [Kontrol akses berdasarkan atribut identitas dengan Izin Terverifikasi](apigateway-lambda-authorizer-verified-permissions.md).
+ Konsol Lambda menyediakan cetak biru Python, yang dapat Anda gunakan dengan memilih **Gunakan** cetak biru dan memilih cetak biru. **api-gateway-authorizer-python**
# Konfigurasikan otorisasi Lambda API Gateway
Setelah membuat fungsi Lambda, Anda mengonfigurasi fungsi Lambda sebagai otorisasi untuk API Anda. Anda kemudian mengonfigurasi metode Anda untuk memanggil otorisasi Lambda Anda untuk menentukan apakah pemanggil dapat memanggil metode Anda. Anda dapat membuat fungsi Lambda di akun yang sama, atau akun lain, dari tempat Anda membuat API.
[Anda dapat menguji otorisasi Lambda Anda menggunakan alat bawaan di konsol API Gateway atau dengan menggunakan Postman.](https://www.postman.com/) Untuk petunjuk tentang cara menggunakan Postman untuk menguji fungsi otorisasi Lambda Anda, lihat. [Panggil API dengan otorisasi API Gateway Lambda](call-api-with-api-gateway-lambda-authorization.md)
## Konfigurasikan otorisasi Lambda (konsol)
Prosedur berikut menunjukkan cara membuat otorisasi Lambda di konsol API Gateway REST API. Untuk mempelajari lebih lanjut tentang berbagai jenis otorisasi Lambda, lihat. [Memilih jenis otorisasi Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-choose)
------
#### [ REQUEST authorizer ]
**Untuk mengkonfigurasi otorisasi `REQUEST` Lambda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API, lalu pilih **Authorizers**.
1. Pilih **Buat Authorizer**.
1. Untuk **nama Authorizer**, masukkan nama untuk otorisasi.
1. Untuk **jenis Authorizer**, pilih **Lambda**.
1. Untuk **fungsi Lambda**, pilih Wilayah AWS tempat Anda membuat fungsi otorisasi Lambda Anda, lalu masukkan nama fungsi.
1. Biarkan **peran panggilan Lambda kosong** agar konsol API Gateway REST API menetapkan kebijakan berbasis sumber daya. Kebijakan ini memberikan izin API Gateway untuk menjalankan fungsi otorisasi Lambda. Anda juga dapat memilih untuk memasukkan nama peran IAM untuk mengizinkan API Gateway menjalankan fungsi otorisasi Lambda. Untuk peran contoh, lihat[Buat peran IAM yang dapat diasumsikan](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies).
1. **Untuk **payload acara Lambda**, pilih Minta.**
1. Untuk **tipe sumber Identity**, pilih tipe parameter. Jenis parameter yang didukung adalah`Header`,`Query string`,`Stage variable`, dan`Context`. Untuk menambahkan lebih banyak sumber identitas, pilih **Tambah parameter**.
1. Untuk men-cache kebijakan otorisasi yang dihasilkan oleh otorisasi, biarkan **caching Otorisasi** tetap aktif. Saat caching kebijakan diaktifkan, Anda dapat mengubah nilai **TTL**. Menyetel **TTL** ke nol menonaktifkan caching kebijakan.
Jika Anda mengaktifkan caching, otorisasi Anda harus mengembalikan kebijakan yang berlaku untuk semua metode di seluruh API. Untuk menegakkan kebijakan khusus metode, gunakan variabel konteks dan. `$context.path` `$context.httpMethod`
1. Pilih **Buat Authorizer**.
------
#### [ TOKEN authorizer ]
**Untuk mengkonfigurasi otorisasi `TOKEN` Lambda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API, lalu pilih **Authorizers**.
1. Pilih **Buat Authorizer**.
1. Untuk **nama Authorizer**, masukkan nama untuk otorisasi.
1. Untuk **jenis Authorizer**, pilih **Lambda**.
1. Untuk **fungsi Lambda**, pilih Wilayah AWS tempat Anda membuat fungsi otorisasi Lambda Anda, lalu masukkan nama fungsi.
1. Biarkan **peran panggilan Lambda kosong** agar konsol API Gateway REST API menetapkan kebijakan berbasis sumber daya. Kebijakan ini memberikan izin API Gateway untuk menjalankan fungsi otorisasi Lambda. Anda juga dapat memilih untuk memasukkan nama peran IAM untuk mengizinkan API Gateway menjalankan fungsi otorisasi Lambda. Untuk peran contoh, lihat[Buat peran IAM yang dapat diasumsikan](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies).
1. **Untuk **payload acara Lambda, pilih Token**.**
1. Untuk **sumber Token**, masukkan nama header yang berisi token otorisasi. Penelepon harus menyertakan header nama ini untuk mengirim token otorisasi ke otorisasi Lambda.
1. (Opsional) Untuk **validasi Token**, masukkan RegEx pernyataan. API Gateway melakukan validasi awal token input terhadap ekspresi ini dan memanggil authorizer setelah validasi berhasil.
1. Untuk men-cache kebijakan otorisasi yang dihasilkan oleh otorisasi, biarkan **caching Otorisasi** tetap aktif. Saat caching kebijakan diaktifkan, nama header yang ditentukan dalam **sumber Token** menjadi kunci cache. Saat caching kebijakan diaktifkan, Anda dapat mengubah nilai **TTL**. Menyetel **TTL** ke nol menonaktifkan caching kebijakan.
Jika Anda mengaktifkan caching, otorisasi Anda harus mengembalikan kebijakan yang berlaku untuk semua metode di seluruh API. **Untuk menerapkan kebijakan khusus metode, Anda dapat menonaktifkan caching Otorisasi.**
1. Pilih **Buat Authorizer**.
------
Setelah Anda membuat otorisasi Lambda Anda, Anda dapat mengujinya. Prosedur berikut menunjukkan cara menguji otorisasi Lambda Anda.
------
#### [ REQUEST authorizer ]
**Untuk menguji otorisasi `REQUEST` Lambda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih nama otorisasi Anda.
1. Di bawah **Pengotorisasi uji**, masukkan nilai untuk sumber identitas Anda.
Jika Anda menggunakan[Contoh fungsi Lambda `REQUEST` authorizer](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-request-lambda-function-create), lakukan hal berikut:
1. Pilih **Header** dan enter**headerValue1**, lalu pilih **Tambah parameter**.
1. Di bawah **Jenis sumber identitas**, pilih **String kueri** dan masukkan**queryValue1**, lalu pilih **Tambah parameter**.
1. Di bawah **Identity source type**, pilih **Stage variable** dan enter**stageValue1**.
Anda tidak dapat memodifikasi variabel konteks untuk pemanggilan pengujian, tetapi Anda dapat memodifikasi template peristiwa pengujian **API Gateway Authorizer** untuk fungsi Lambda Anda. Kemudian, Anda dapat menguji fungsi otorisasi Lambda Anda dengan variabel konteks yang dimodifikasi. Untuk informasi selengkapnya, lihat [Menguji fungsi Lambda di konsol](https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html) di Panduan *AWS Lambda Pengembang*.
1. Pilih **Test Authorizer**.
------
#### [ TOKEN authorizer ]
**Untuk menguji otorisasi `TOKEN` Lambda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih nama otorisasi Anda.
1. Di bawah **Pengotorisasi uji**, masukkan nilai untuk token Anda.
Jika Anda menggunakan[Contoh fungsi Lambda `TOKEN` authorizer](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create), lakukan hal berikut:
1. Untuk **AuthorizationToken**, masukkan. **allow**
1. Pilih **Test Authorizer**.
Jika otorisasi Lambda Anda berhasil menolak permintaan di lingkungan pengujian, pengujian akan merespons dengan respons HTTP. `200 OK` Namun, di luar lingkungan pengujian, API Gateway mengembalikan respons `403 Forbidden` HTTP dan permintaan metode gagal.
------
## Konfigurasikan otorisasi Lambda ()AWS CLI
Perintah [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) berikut menunjukkan untuk membuat authorizer Lambda menggunakan. AWS CLI
------
#### [ REQUEST authorizer ]
Perintah [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) berikut membuat `REQUEST` authorizer dan menggunakan variabel `Authorizer` header dan `accountId` konteks sebagai sumber identitas:
```
aws apigateway create-authorizer \
--rest-api-id 1234123412 \
--name 'First_Request_Custom_Authorizer' \
--type REQUEST \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \
--identity-source 'method.request.header.Authorization,context.accountId' \
--authorizer-result-ttl-in-seconds 300
```
------
#### [ TOKEN authorizer ]
Perintah [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) berikut membuat `TOKEN` authorizer dan menggunakan `Authorization` header sebagai sumber identitas:
```
aws apigateway create-authorizer \
--rest-api-id 1234123412 \
--name 'First_Token_Custom_Authorizer' \
--type TOKEN \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \
--identity-source 'method.request.header.Authorization' \
--authorizer-result-ttl-in-seconds 300
```
------
Setelah Anda membuat otorisasi Lambda Anda, Anda dapat mengujinya. [test-invoke-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-authorizer.html)Perintah berikut menguji otorisasi Lambda:
```
aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \
--authorizer-id efg1234 \
--headers Authorization='Value'
```
## Konfigurasikan metode untuk menggunakan otorisasi Lambda (konsol)
Setelah mengonfigurasi otorisasi Lambda, Anda harus melampirkannya ke metode untuk API Anda. Jika otorisasi Anda menggunakan caching otorisasi, pastikan Anda memperbarui kebijakan untuk mengontrol akses untuk metode tambahan.
**Untuk mengonfigurasi metode API untuk menggunakan otorisasi Lambda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API.
1. Pilih **Sumber Daya**, lalu pilih metode baru atau pilih metode yang ada.
1. Pada tab **Permintaan metode**, di bawah **Pengaturan permintaan metode**, pilih **Edit**.
1. Untuk **Authorizer**, dari menu dropdown, pilih Lambda Authorizer yang baru saja Anda buat.
1. (Opsional) Jika Anda ingin meneruskan token otorisasi ke backend, pilih header permintaan **HTTP**. Pilih **Tambahkan header**, lalu tambahkan nama header otorisasi. Untuk **Nama**, masukkan nama header yang cocok dengan nama **sumber Token** yang Anda tentukan saat membuat otorisasi Lambda untuk API. Langkah ini tidak berlaku untuk `REQUEST` otorisasi.
1. Pilih **Simpan**.
1. Pilih **Deploy API** untuk menerapkan API ke panggung. Untuk `REQUEST` otorisasi yang menggunakan variabel tahap, Anda juga harus menentukan variabel tahap yang diperlukan dan menentukan nilainya saat berada di halaman **Tahapan**.
## Konfigurasikan metode untuk menggunakan otorisasi Lambda ()AWS CLI
Setelah mengonfigurasi otorisasi Lambda, Anda harus melampirkannya ke metode untuk API Anda. Anda dapat membuat metode baru atau menggunakan operasi tambalan untuk melampirkan otorisasi ke metode yang ada. Jika otorisasi Anda menggunakan caching otorisasi, pastikan Anda memperbarui kebijakan untuk mengontrol akses untuk metode tambahan.
Perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut membuat metode baru yang menggunakan authorizer Lambda:
```
aws apigateway put-method --rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--authorization-type CUSTOM \
--authorizer-id efg1234
```
Perintah [update-method berikut memperbarui metode](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) yang ada untuk menggunakan Lambda authorizer:
```
aws apigateway update-method \
--rest-api-id 1234123412 \
--resource-id a1b2c3 \
--http-method PUT \
--patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234"
```
# Masukan ke otorisasi Lambda API Gateway
Bagian berikut menjelaskan format input dari API Gateway ke otorisasi Lambda.
## `TOKEN`format masukan
Untuk Authorizer Lambda (sebelumnya dikenal sebagai otorisasi kustom) dari `TOKEN` jenisnya, Anda harus menentukan header kustom sebagai **Sumber Token** saat Anda mengonfigurasi otorisasi untuk API Anda. Klien API harus meneruskan token otorisasi yang diperlukan di header tersebut dalam permintaan yang masuk. Setelah menerima permintaan metode masuk, API Gateway mengekstrak token dari header kustom. Kemudian melewati token sebagai `authorizationToken` properti dari `event` objek fungsi Lambda, selain metode ARN sebagai properti: `methodArn`
```
{
"type":"TOKEN",
"authorizationToken":"{caller-supplied-token}",
"methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
```
Dalam contoh ini, `type` properti menentukan jenis authorizer, yang merupakan `TOKEN` authorizer. `{caller-supplied-token}`Berasal dari header otorisasi dalam permintaan klien, dan dapat berupa nilai string apa pun. `methodArn`Ini adalah ARN dari permintaan metode yang masuk dan diisi oleh API Gateway sesuai dengan konfigurasi otorisasi Lambda.
## `REQUEST`format masukan
Untuk `REQUEST` jenis pengotorisasi Lambda, API Gateway meneruskan parameter permintaan ke fungsi Lambda otorisasi sebagai bagian dari objek. `event` Parameter permintaan termasuk header, parameter jalur, parameter string kueri, variabel tahap, dan beberapa variabel konteks permintaan. Pemanggil API dapat mengatur parameter jalur, header, dan parameter string kueri. Pengembang API harus menyetel variabel stage selama penerapan API dan API Gateway menyediakan konteks permintaan pada waktu berjalan.
**catatan**
Parameter jalur dapat diteruskan sebagai parameter permintaan ke fungsi otorisasi Lambda, tetapi tidak dapat digunakan sebagai sumber identitas.
Contoh berikut menunjukkan input ke `REQUEST` authorizer untuk metode API (`GET /request`) dengan integrasi proxy:
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
`requestContext`Ini adalah peta pasangan kunci-nilai dan sesuai dengan variabel [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference). Hasilnya bergantung pada API.
API Gateway mungkin menambahkan kunci baru ke peta. Untuk informasi selengkapnya tentang input fungsi Lambda dalam integrasi proxy Lambda, lihat. [Format input fungsi Lambda untuk integrasi proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format)
# Keluaran dari otorisasi API Gateway Lambda
Output fungsi otorisasi Lambda adalah objek mirip kamus, yang harus menyertakan pengenal utama (`principalId`) dan dokumen kebijakan () yang berisi daftar pernyataan kebijakan. `policyDocument` Outputnya juga dapat menyertakan `context` peta yang berisi pasangan kunci-nilai. Jika API menggunakan paket penggunaan ([https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource)disetel ke`AUTHORIZER`), fungsi otorisasi Lambda harus mengembalikan salah satu kunci API paket penggunaan sebagai nilai properti. `usageIdentifierKey`
Berikut ini menunjukkan contoh output ini.
------
#### [ JSON ]
****
```
{
"principalId": "yyyyyyyy",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"stringKey": "value",
"numberKey": "1",
"booleanKey": "true"
},
"usageIdentifierKey": "{api-key}"
}
```
------
Di sini, pernyataan kebijakan menentukan apakah akan mengizinkan atau menolak (`Effect`) layanan eksekusi API Gateway untuk memanggil (`Action`) metode API yang ditentukan (`Resource`). Anda mungkin perlu mengontrol akses ke beberapa sumber daya berdasarkan otorisasi Anda. Anda dapat menggunakan wild card (`*`) untuk menentukan jenis sumber daya (metode). Untuk informasi tentang menyetel kebijakan yang valid untuk memanggil API, lihat[Referensi pernyataan kebijakan IAM untuk menjalankan API di API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-calling-api-permissions).
Untuk metode ARN yang diaktifkan otorisasi, misalnya`arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]`, panjang maksimum adalah 1600 byte. Nilai parameter jalur, ukuran yang ditentukan pada waktu berjalan, dapat menyebabkan panjang ARN melebihi batas. Ketika ini terjadi, klien API akan menerima `414 Request URI too long` respons.
Selain itu, ARN Sumber Daya, seperti yang ditunjukkan dalam keluaran pernyataan kebijakan oleh otorisasi, saat ini dibatasi hingga 512 karakter. Untuk alasan ini, Anda tidak boleh menggunakan URI dengan token JWT dengan panjang yang signifikan dalam URI permintaan. Anda dapat dengan aman meneruskan token JWT di header permintaan, sebagai gantinya.
Anda dapat mengakses `principalId` nilai dalam template pemetaan menggunakan `$context.authorizer.principalId` variabel. Ini berguna jika Anda ingin meneruskan nilai ke backend. Untuk informasi selengkapnya, lihat [Variabel konteks untuk transformasi data](api-gateway-mapping-template-reference.md#context-variable-reference).
Anda dapat mengakses`stringKey`,`numberKey`, atau `booleanKey` nilai (misalnya,, `"value"``"1"`, atau`"true"`) `context` peta dalam templat pemetaan dengan memanggil`$context.authorizer.stringKey`,, atau `$context.authorizer.numberKey``$context.authorizer.booleanKey`, masing-masing. Nilai yang dikembalikan semuanya dirangkai. Perhatikan bahwa Anda tidak dapat mengatur objek atau array JSON sebagai nilai yang valid dari kunci apa pun di `context` peta.
Anda dapat menggunakan `context` peta untuk mengembalikan kredensi cache dari otorisasi ke backend, menggunakan templat pemetaan permintaan integrasi. Hal ini memungkinkan backend untuk memberikan pengalaman pengguna yang lebih baik dengan menggunakan kredensi cache untuk mengurangi kebutuhan untuk mengakses kunci rahasia dan membuka token otorisasi untuk setiap permintaan.
Untuk integrasi proxy Lambda, API Gateway meneruskan `context` objek dari otorisasi Lambda langsung ke fungsi Lambda backend sebagai bagian dari input. `event` Anda dapat mengambil pasangan `context` kunci-nilai dalam fungsi Lambda dengan memanggil. `$event.requestContext.authorizer.key`
`{api-key}`singkatan dari kunci API dalam rencana penggunaan tahap API. Untuk informasi selengkapnya, lihat [Paket penggunaan dan kunci API untuk REST APIs di API Gateway](api-gateway-api-usage-plans.md).
Berikut ini menunjukkan contoh output dari contoh Lambda authorizer. Output contoh berisi pernyataan kebijakan untuk memblokir (`Deny`) panggilan ke `GET` metode untuk `dev` tahap API (`ymy8tbxw7b`) dari AWS account (`123456789012`).
------
#### [ JSON ]
****
```
{
"principalId": "user",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
}
]
}
}
```
------
# Panggil API dengan otorisasi API Gateway Lambda
Setelah mengonfigurasi otorisasi Lambda (sebelumnya dikenal sebagai otorisasi khusus) dan menerapkan API, Anda harus menguji API dengan otorisasi Lambda diaktifkan. [Untuk ini, Anda memerlukan klien REST, seperti cURL atau Postman.](https://www.postman.com/) Untuk contoh berikut, kami menggunakan Postman.
**catatan**
**Saat memanggil metode berkemampuan pengotorisasi, API Gateway tidak mencatat panggilan CloudWatch jika token yang diperlukan untuk `TOKEN` otorisasi tidak disetel, nol, atau tidak valid oleh ekspresi validasi Token yang ditentukan.** Demikian pula, API Gateway tidak mencatat panggilan CloudWatch jika salah satu sumber identitas yang diperlukan untuk `REQUEST` otorisasi tidak disetel, nol, atau kosong.
Berikut ini, kami menunjukkan cara menggunakan Postman untuk memanggil atau menguji API dengan otorisasi `TOKEN` Lambda. Metode ini dapat diterapkan untuk memanggil API dengan `REQUEST` otorisasi Lambda, jika Anda menentukan parameter path, header, atau string kueri yang diperlukan secara eksplisit.
**Untuk memanggil API dengan `TOKEN` otorisasi khusus**
1. Buka **Postman**, pilih metode **GET**, dan tempel URL **Invoke API ke bidang URL** yang berdekatan.
Tambahkan header token otorisasi Lambda dan atur nilainya. `allow` Pilih **Kirim**.
![\[Panggil API dengan otorisasi Lambda mengizinkan token\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/custom-auth-call-api-with-allow-token.png)
Tanggapan menunjukkan bahwa otorisasi API Gateway Lambda mengembalikan respons **200 OK** dan berhasil mengotorisasi panggilan untuk mengakses titik akhir HTTP (http://httpbin.org/get) yang terintegrasi dengan metode.
1. Masih di Postman, ubah nilai header token otorisasi Lambda menjadi. `deny` Pilih **Kirim**.
![\[Panggil API dengan token penolakan otorisasi Lambda\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/custom-auth-call-api-with-deny-token.png)
Tanggapan menunjukkan bahwa otorisasi API Gateway Lambda mengembalikan respons **403 Forbidden** tanpa mengotorisasi panggilan untuk mengakses titik akhir HTTP.
1. **Di Postman, ubah nilai `unauthorized` header token otorisasi Lambda menjadi dan pilih Kirim.**
![\[Panggil API dengan token tidak sah otorisasi Lambda\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/custom-auth-call-api-with-unauthorized-token.png)
Respons menunjukkan bahwa API Gateway mengembalikan respons **401 Tidak Sah** tanpa mengotorisasi panggilan untuk mengakses titik akhir HTTP.
1. Sekarang, ubah nilai header token otorisasi Lambda menjadi. `fail` Pilih **Kirim**.
![\[Panggil API dengan token gagal otorisasi Lambda\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/custom-auth-call-api-with-fail-token.png)
Respons menunjukkan bahwa API Gateway mengembalikan respon **500 Internal Server Error** tanpa mengotorisasi panggilan untuk mengakses endpoint HTTP.
# Konfigurasikan otorisasi Lambda API Gateway lintas akun
Anda sekarang juga dapat menggunakan AWS Lambda fungsi dari AWS akun yang berbeda sebagai fungsi otorisasi API Anda. Setiap akun dapat berada di wilayah mana pun di mana Amazon API Gateway tersedia. Fungsi otorisasi Lambda dapat menggunakan strategi otentikasi token pembawa seperti atau SALL. OAuth Ini memudahkan untuk mengelola dan berbagi fungsi otorisasi Lambda pusat secara terpusat di beberapa API Gateway. APIs
Di bagian ini, kami menunjukkan cara mengonfigurasi fungsi otorisasi Lambda lintas akun menggunakan konsol Amazon API Gateway.
Petunjuk ini mengasumsikan bahwa Anda sudah memiliki API Gateway API di satu AWS akun dan fungsi otorisasi Lambda di akun lain.
## Konfigurasikan otorisasi Lambda lintas akun menggunakan konsol API Gateway
Masuk ke konsol Amazon API Gateway di akun yang memiliki API Anda di dalamnya, lalu lakukan hal berikut:
1. Pilih API Anda, lalu di panel navigasi utama, pilih **Authorizers**.
1. Pilih **Buat Authorizer**.
1. Untuk **nama Authorizer**, masukkan nama untuk otorisasi.
1. Untuk **jenis Authorizer**, pilih **Lambda**.
1. Untuk **Fungsi Lambda**, masukkan ARN lengkap untuk fungsi otorisasi Lambda yang Anda miliki di akun kedua Anda.
**catatan**
Di konsol Lambda, Anda dapat menemukan ARN untuk fungsi Anda di sudut kanan atas jendela konsol.
1. Peringatan dengan string `aws lambda add-permission` perintah akan muncul. Kebijakan ini memberikan izin API Gateway untuk menjalankan fungsi Lambda otorisasi. Salin perintah dan simpan untuk nanti. Anda menjalankan perintah setelah Anda membuat authorizer.
1. Untuk **muatan acara Lambda**, pilih **Token** untuk otorisasi atau **Permintaan `TOKEN`** otorisasi. `REQUEST`
1. Bergantung pada pilihan langkah sebelumnya, lakukan salah satu hal berikut:
1. Untuk opsi **Token**, lakukan hal berikut:
+ Untuk **sumber Token**, masukkan nama header yang berisi token otorisasi. Klien API harus menyertakan header dari nama ini untuk mengirim token otorisasi ke otorisasi Lambda.
+ Secara opsional, untuk **validasi Token**, masukkan pernyataan RegEx . API Gateway melakukan validasi awal token input terhadap ekspresi ini dan memanggil authorizer setelah validasi berhasil. Ini membantu mengurangi panggilan ke API Anda.
+ Untuk men-cache kebijakan otorisasi yang dihasilkan oleh otorisasi, biarkan **caching Otorisasi** tetap aktif. Saat caching kebijakan diaktifkan, Anda dapat memilih untuk mengubah nilai **TTL**. Menyetel **TTL** ke nol menonaktifkan caching kebijakan. Saat caching kebijakan diaktifkan, nama header yang ditentukan dalam **sumber Token** menjadi kunci cache. Jika beberapa nilai diteruskan ke header ini dalam permintaan, semua nilai akan menjadi kunci cache, dengan urutan dipertahankan.
**catatan**
Nilai **TTL** default adalah 300 detik. Nilai maksimum adalah 3600 detik, batas ini tidak dapat ditingkatkan.
1. Untuk opsi **Permintaan**, lakukan hal berikut:
+ Untuk **tipe sumber Identity**, pilih tipe parameter. Jenis parameter yang didukung adalah`Header`,`Query string`,`Stage variable`, dan`Context`. Untuk menambahkan lebih banyak sumber identitas, pilih **Tambah parameter**.
+ Untuk men-cache kebijakan otorisasi yang dihasilkan oleh otorisasi, biarkan **caching Otorisasi** tetap aktif. Saat caching kebijakan diaktifkan, Anda dapat memilih untuk mengubah nilai **TTL**. Menyetel **TTL** ke nol menonaktifkan caching kebijakan.
API Gateway menggunakan sumber identitas yang ditentukan sebagai kunci caching otorisasi permintaan. Saat caching diaktifkan, API Gateway memanggil fungsi Lambda otorisasi hanya setelah berhasil memverifikasi bahwa semua sumber identitas yang ditentukan ada saat runtime. Jika sumber identitas tertentu hilang, null, atau kosong, API Gateway mengembalikan `401 Unauthorized` respons tanpa memanggil fungsi Lambda otorisasi.
Ketika beberapa sumber identitas didefinisikan, mereka semua digunakan untuk mendapatkan kunci cache otorisasi. Mengubah salah satu bagian kunci cache menyebabkan otorisasi membuang dokumen kebijakan yang di-cache dan menghasilkan yang baru. Jika header dengan beberapa nilai diteruskan dalam permintaan, maka semua nilai akan menjadi bagian dari kunci cache, dengan urutan dipertahankan.
+ Ketika caching dimatikan, tidak perlu menentukan sumber identitas.
**catatan**
Untuk mengaktifkan caching, otorisasi Anda harus mengembalikan kebijakan yang berlaku untuk semua metode di seluruh API. **Untuk menerapkan kebijakan khusus metode, Anda dapat menonaktifkan caching Otorisasi.**
1. Pilih **Buat Authorizer**.
1. Tempel string `aws lambda add-permission` perintah yang Anda salin pada langkah sebelumnya ke AWS CLI jendela yang dikonfigurasi untuk akun kedua Anda. Ganti `AUTHORIZER_ID` dengan ID otorisasi Anda. Ini akan memberikan akses akun pertama Anda ke fungsi otorisasi Lambda akun kedua Anda.
# Kontrol akses berdasarkan atribut identitas dengan Izin Terverifikasi
Gunakan Izin Terverifikasi Amazon untuk mengontrol akses ke API Gateway API Anda. Saat Anda menggunakan API Gateway dengan Izin Terverifikasi, Izin Terverifikasi akan membuat otorisasi Lambda yang menggunakan keputusan otorisasi berbutir halus untuk mengontrol akses ke API Anda. Izin Terverifikasi mengotorisasi pemanggil berdasarkan skema penyimpanan kebijakan dan kebijakan menggunakan bahasa kebijakan Cedar untuk menentukan izin berbutir halus bagi pengguna aplikasi. Untuk informasi selengkapnya, lihat [Membuat penyimpanan kebijakan dengan API dan penyedia identitas yang terhubung](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/getting-started-api-policy-store.html) di *Panduan Pengguna Izin Terverifikasi Amazon*.
Izin Terverifikasi mendukung kumpulan pengguna Amazon Cognito atau penyedia identitas OpenID Connect (OIDC) sebagai sumber identitas. Izin Terverifikasi menganggap bahwa prinsipal telah diidentifikasi dan diautentikasi sebelumnya. Izin Terverifikasi hanya didukung untuk REST Regional dan yang dioptimalkan di tepi. APIs
## Buat otorisasi Lambda menggunakan Izin Terverifikasi
Izin Terverifikasi membuat otorisasi Lambda untuk menentukan apakah prinsipal diizinkan melakukan tindakan pada API Anda. Anda membuat kebijakan Cedar yang digunakan Izin Terverifikasi untuk melakukan tugas otorisasi.
Berikut ini adalah contoh kebijakan Cedar yang memungkinkan akses untuk menjalankan API berdasarkan kumpulan pengguna Amazon Cognito`us-east-1_ABC1234`, untuk grup `developer` pada `GET /users` sumber daya API. Izin Terverifikasi menentukan keanggotaan grup dengan mengurai token pembawa untuk identitas pemanggil.
```
permit(
principal in MyAPI::UserGroup::"us-east-1_ABC1234|developer",
action in [ MyAPI::Action::"get /users" ],
resource
);
```
Secara opsional, Izin Terverifikasi dapat melampirkan otorisasi ke metode API Anda. Pada tahap produksi untuk API Anda, kami menyarankan agar Anda tidak mengizinkan Izin Terverifikasi untuk melampirkan otorisasi untuk Anda.
Daftar berikut menunjukkan cara mengonfigurasi Izin Terverifikasi untuk melampirkan atau tidak melampirkan otorisasi Lambda ke permintaan metode metode API Anda.
**Lampirkan otorisasi untuk Anda ()Konsol Manajemen AWS**
**Saat Anda memilih **Buat penyimpanan kebijakan** di konsol Izin Terverifikasi, pada halaman **integrasi aplikasi Deploy**, pilih Sekarang.**
**Jangan lampirkan otorisasi untuk Anda ()Konsol Manajemen AWS**
**Saat Anda memilih **Buat penyimpanan kebijakan** di konsol Izin Terverifikasi, pada halaman **Integrasi aplikasi Terapkan**, pilih Nanti.**
Izin Terverifikasi masih membuat otorisasi Lambda untuk Anda. Otorisasi Lambda dimulai dengan. `AVPAuthorizerLambda-` Untuk petunjuk selengkapnya tentang cara melampirkan otorisasi Anda pada suatu metode, lihat[Konfigurasikan metode untuk menggunakan otorisasi Lambda (konsol)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-console).
**Lampirkan otorisasi untuk Anda ()CloudFormation**
Di CloudFormation template yang dihasilkan Izin Terverifikasi, di `Conditions` bagian, atur ke. `"Ref": "shouldAttachAuthorizer"` `true`
**Jangan lampirkan otorisasi untuk Anda ()CloudFormation**
Di CloudFormation template yang dihasilkan Izin Terverifikasi, di `Conditions` bagian, atur ke. `"Ref": "shouldAttachAuthorizer"` `false`
Izin Terverifikasi masih membuat otorisasi Lambda untuk Anda. Otorisasi Lambda dimulai dengan. `AVPAuthorizerLambda-` Untuk petunjuk selengkapnya tentang cara melampirkan otorisasi Anda pada suatu metode, lihat[Konfigurasikan metode untuk menggunakan otorisasi Lambda ()AWS CLI](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-cli).
## Panggil otorisasi Lambda menggunakan Izin Terverifikasi
Anda dapat menghubungi otorisasi Lambda Anda dengan memberikan identitas atau token akses di header. `Authorization` Untuk informasi selengkapnya, lihat [Panggil API dengan otorisasi API Gateway Lambda](call-api-with-api-gateway-lambda-authorization.md).
API Gateway menyimpan kebijakan yang dikembalikan oleh otorisasi Lambda Anda selama 120 detik. Anda dapat memodifikasi TTL di konsol API Gateway atau dengan menggunakan. AWS CLI
# Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi
Sebagai alternatif untuk menggunakan [peran dan kebijakan IAM](permissions.md) atau otorisasi [Lambda](apigateway-use-lambda-authorizer.md) (sebelumnya dikenal sebagai otorisasi khusus), Anda dapat menggunakan kumpulan [pengguna Amazon Cognito untuk mengontrol siapa yang dapat mengakses API Anda di Amazon](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) API Gateway.
Untuk menggunakan kumpulan pengguna Amazon Cognito dengan API Anda, Anda harus terlebih dahulu membuat otorisasi `COGNITO_USER_POOLS` jenis tersebut dan kemudian mengonfigurasi metode API untuk menggunakan otorisasi tersebut. Setelah API diterapkan, klien harus terlebih dahulu memasukkan pengguna ke kumpulan pengguna, mendapatkan [identitas atau token akses](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) untuk pengguna, dan kemudian memanggil metode API dengan salah satu token, yang biasanya diatur ke `Authorization` header permintaan. Panggilan API hanya berhasil jika token yang diperlukan disediakan dan token yang disediakan valid, jika tidak, klien tidak berwenang untuk melakukan panggilan karena klien tidak memiliki kredensi yang dapat diotorisasi.
Token identitas digunakan untuk mengotorisasi panggilan API berdasarkan klaim identitas pengguna yang masuk. Token akses digunakan untuk mengotorisasi panggilan API berdasarkan cakupan kustom sumber daya yang dilindungi akses tertentu. Untuk informasi selengkapnya, lihat [Menggunakan Token dengan Kumpulan Pengguna](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) dan [Server Sumber Daya dan Cakupan Khusus](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html).
Untuk membuat dan mengonfigurasi kumpulan pengguna Amazon Cognito untuk API, Anda melakukan tugas berikut:
+ Gunakan konsol Amazon Cognito, CLI/SDK, atau API untuk membuat kumpulan pengguna—atau gunakan yang dimiliki oleh akun lain. AWS
+ Gunakan konsol API Gateway, CLI/SDK, atau API untuk membuat otorisasi API Gateway dengan kumpulan pengguna yang dipilih.
+ Gunakan konsol API Gateway, CLI/SDK, atau API untuk mengaktifkan otorisasi pada metode API yang dipilih.
Untuk memanggil metode API apa pun dengan kumpulan pengguna diaktifkan, klien API Anda melakukan tugas berikut:
+ Gunakan Amazon Cognito CLI/SDK atau API untuk menandatangani pengguna ke kumpulan pengguna yang dipilih, dan mendapatkan token identitas atau token akses. Untuk mempelajari lebih lanjut tentang menggunakan SDKs, lihat [Contoh kode untuk Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html) menggunakan. AWS SDKs
+ Gunakan kerangka kerja khusus klien untuk memanggil API Gateway API yang diterapkan dan menyediakan token yang sesuai di header. `Authorization`
Sebagai pengembang API, Anda harus memberikan ID kumpulan pengguna, ID klien, dan mungkin rahasia klien terkait yang didefinisikan sebagai bagian dari kumpulan pengguna.
**catatan**
[Untuk mengizinkan pengguna masuk menggunakan kredensi Amazon Cognito dan juga mendapatkan kredensi sementara untuk digunakan dengan izin peran IAM, gunakan Identitas Federasi Amazon Cognito.](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) Untuk setiap metode HTTP titik akhir sumber daya API, tetapkan jenis otorisasi, kategori`Method Execution`, ke. `AWS_IAM`
Di bagian ini, kami menjelaskan cara membuat kumpulan pengguna, cara mengintegrasikan API Gateway API dengan kumpulan pengguna, dan cara menjalankan API yang terintegrasi dengan kumpulan pengguna.
**Topics**
+ [Buat kumpulan pengguna Amazon Cognito untuk REST API](apigateway-create-cognito-user-pool.md)
+ [Integrasikan REST API dengan kumpulan pengguna Amazon Cognito](apigateway-enable-cognito-user-pool.md)
+ [Panggil REST API yang terintegrasi dengan kumpulan pengguna Amazon Cognito](apigateway-invoke-api-integrated-with-cognito-user-pool.md)
+ [Konfigurasikan otorisasi Amazon Cognito lintas akun untuk REST API menggunakan konsol API Gateway](apigateway-cross-account-cognito-authorizer.md)
+ [Buat otorisasi Amazon Cognito untuk REST API menggunakan CloudFormation](apigateway-cognito-authorizer-cfn.md)
# Buat kumpulan pengguna Amazon Cognito untuk REST API
Sebelum mengintegrasikan API Anda dengan kumpulan pengguna, Anda harus membuat kumpulan pengguna di Amazon Cognito. Konfigurasi kumpulan pengguna Anda harus mengikuti semua [kuota sumber daya untuk Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Semua variabel Amazon Cognito yang ditentukan pengguna seperti grup, pengguna, dan peran hanya boleh menggunakan karakter alfanumerik. Untuk petunjuk tentang cara membuat kumpulan pengguna, lihat [Tutorial: Membuat kumpulan pengguna](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) di Panduan *Pengembang Amazon Cognito*.
Perhatikan ID kumpulan pengguna, ID klien, dan rahasia klien apa pun. Klien harus menyediakannya ke Amazon Cognito agar pengguna dapat mendaftar dengan kumpulan pengguna, masuk ke kumpulan pengguna, dan untuk mendapatkan identitas atau token akses untuk disertakan dalam permintaan memanggil metode API yang dikonfigurasi dengan kumpulan pengguna. Selain itu, Anda harus menentukan nama kumpulan pengguna saat mengonfigurasi kumpulan pengguna sebagai otorisasi di API Gateway, seperti yang dijelaskan selanjutnya.
Jika Anda menggunakan token akses untuk mengotorisasi panggilan metode API, pastikan untuk mengonfigurasi integrasi aplikasi dengan kumpulan pengguna untuk menyiapkan cakupan kustom yang Anda inginkan di server sumber daya tertentu. Untuk informasi selengkapnya tentang penggunaan token dengan kumpulan pengguna Amazon Cognito, lihat [Menggunakan Token dengan Kumpulan Pengguna](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Untuk informasi selengkapnya tentang server sumber daya, lihat [Mendefinisikan Server Sumber Daya untuk Kumpulan Pengguna Anda](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html).
Perhatikan pengidentifikasi server sumber daya yang dikonfigurasi dan nama cakupan kustom. Anda membutuhkannya untuk membangun nama lengkap cakupan akses untuk **OAuth Scopes**, yang digunakan oleh otorisasi. `COGNITO_USER_POOLS`
![\[Server dan cakupan sumber daya kumpulan pengguna Amazon Cognito\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png)
# Integrasikan REST API dengan kumpulan pengguna Amazon Cognito
Setelah membuat kumpulan pengguna Amazon Cognito, di API Gateway, Anda harus membuat `COGNITO_USER_POOLS` otorisasi yang menggunakan kumpulan pengguna. Prosedur berikut menunjukkan cara melakukannya menggunakan konsol API Gateway.
**catatan**
Anda dapat menggunakan [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html)tindakan untuk membuat `COGNITO_USER_POOLS` otorisasi yang menggunakan beberapa kumpulan pengguna. Anda dapat menggunakan hingga 1.000 kumpulan pengguna untuk satu `COGNITO_USER_POOLS` otorisasi. Batas ini tidak dapat dinaikkan.
**penting**
Setelah melakukan salah satu prosedur di bawah ini, Anda harus menerapkan atau menerapkan ulang API Anda untuk menyebarkan perubahan. Untuk informasi selengkapnya tentang penerapan API Anda, lihat[Menerapkan REST APIs di API Gateway](how-to-deploy-api.md).
**Untuk membuat `COGNITO_USER_POOLS` otorisasi menggunakan konsol API Gateway**
1. Buat API baru, atau pilih API yang ada di API Gateway.
1. Di panel navigasi utama, pilih **Authorizers**.
1. Pilih **Buat Authorizer**.
1. Untuk mengonfigurasi otorisasi baru untuk menggunakan kumpulan pengguna, lakukan hal berikut:
1. Untuk **nama Authorizer**, masukkan nama.
1. Untuk **jenis Authorizer**, pilih **Cognito**.
1. Untuk **kumpulan pengguna Cognito**, pilih Wilayah AWS tempat Anda membuat Amazon Cognito dan pilih kumpulan pengguna yang tersedia.
Anda dapat menggunakan variabel tahap untuk menentukan kumpulan pengguna Anda. Gunakan format berikut untuk kumpulan pengguna Anda:`arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`.
1. Untuk **sumber Token**, masukkan **Authorization** sebagai nama header untuk meneruskan identitas atau token akses yang dikembalikan oleh Amazon Cognito saat pengguna berhasil masuk.
1. (Opsional) Masukkan ekspresi reguler di bidang **validasi Token** untuk memvalidasi bidang `aud` (audiens) token identitas sebelum permintaan diotorisasi dengan Amazon Cognito. Perhatikan bahwa saat menggunakan token akses validasi ini menolak permintaan karena token akses tidak berisi bidang. `aud`
1. Pilih **Buat Authorizer**.
1. Setelah membuat `COGNITO_USER_POOLS` otorisasi, Anda dapat menguji panggilannya dengan menyediakan token identitas yang disediakan dari kumpulan pengguna. Anda tidak dapat menggunakan token akses untuk menguji pemanggilan otorisasi Anda.
Anda dapat memperoleh token identitas ini dengan memanggil [Amazon Cognito Identity SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) untuk melakukan login pengguna. Anda juga dapat menggunakan [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)aksinya. Jika Anda tidak mengonfigurasi **cakupan Otorisasi** apa pun, API Gateway memperlakukan token yang disediakan sebagai token identitas.
Prosedur sebelumnya membuat `COGNITO_USER_POOLS` otorisasi yang menggunakan kumpulan pengguna Amazon Cognito yang baru dibuat. Bergantung pada cara Anda mengaktifkan otorisasi pada metode API, Anda dapat menggunakan token identitas atau token akses yang disediakan dari kumpulan pengguna terintegrasi.
**Untuk mengkonfigurasi `COGNITO_USER_POOLS` otorisasi pada metode**
1. Pilih **Sumber daya**. Pilih metode baru atau pilih metode yang ada. Jika perlu, buat sumber daya.
1. Pada tab **Permintaan metode**, di bawah **Pengaturan permintaan metode**, pilih **Edit**.
1. Untuk **Authorizer, dari menu tarik-turun, pilih otorisasi** **kumpulan pengguna Amazon Cognito yang baru saja** Anda buat.
1. Untuk menggunakan token identitas, lakukan hal berikut:
1. Jaga **Cakupan Otorisasi kosong**.
1. Jika diperlukan, dalam **permintaan Integrasi**, tambahkan `$context.authorizer.claims.property-name` ekspresi `$context.authorizer.claims['property-name']` atau dalam templat pemetaan tubuh untuk meneruskan properti klaim identitas yang ditentukan dari kumpulan pengguna ke backend. Untuk nama properti sederhana, seperti `sub` atau`custom-sub`, dua notasi identik. Untuk nama properti kompleks, seperti`custom:role`, Anda tidak dapat menggunakan notasi titik. Misalnya, ekspresi pemetaan berikut meneruskan [bidang standar](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) klaim `sub` dan `email` ke backend:
```
{
"context" : {
"sub" : "$context.authorizer.claims.sub",
"email" : "$context.authorizer.claims.email"
}
}
```
Jika Anda mendeklarasikan bidang klaim kustom saat mengonfigurasi kumpulan pengguna, Anda dapat mengikuti pola yang sama untuk mengakses bidang kustom. Contoh berikut mendapatkan `role` bidang khusus klaim:
```
{
"context" : {
"role" : "$context.authorizer.claims.role"
}
}
```
Jika bidang klaim kustom dideklarasikan sebagai`custom:role`, gunakan contoh berikut untuk mendapatkan properti klaim:
```
{
"context" : {
"role" : "$context.authorizer.claims['custom:role']"
}
}
```
1. Untuk menggunakan token akses, lakukan hal berikut:
1. Untuk **Cakupan Otorisasi**, masukkan satu atau beberapa nama lengkap cakupan yang telah dikonfigurasi saat kumpulan pengguna Amazon Cognito dibuat. Misalnya, mengikuti contoh yang diberikan[Buat kumpulan pengguna Amazon Cognito untuk REST API](apigateway-create-cognito-user-pool.md), salah satu cakupannya adalah`https://my-petstore-api.example.com/cats.read`.
Saat runtime, pemanggilan metode berhasil jika cakupan apa pun yang ditentukan pada metode dalam langkah ini cocok dengan cakupan yang diklaim dalam token yang masuk. Jika tidak, panggilan gagal dengan `401 Unauthorized` respons.
1. Pilih **Simpan**.
1. Ulangi langkah-langkah ini untuk metode lain yang Anda pilih.
Dengan `COGNITO_USER_POOLS` otorisasi, jika opsi **OAuthScopes** tidak ditentukan, API Gateway memperlakukan token yang disediakan sebagai token identitas dan memverifikasi identitas yang diklaim terhadap yang dari kumpulan pengguna. Jika tidak, API Gateway memperlakukan token yang disediakan sebagai token akses dan memverifikasi cakupan akses yang diklaim dalam token terhadap cakupan otorisasi yang dideklarasikan pada metode.
Alih-alih menggunakan konsol API Gateway, Anda juga dapat mengaktifkan kumpulan pengguna Amazon Cognito pada metode dengan menentukan file definisi OpenAPI dan mengimpor definisi API ke API Gateway.
**Untuk mengimpor otorisasi COGNITO\$1USER\$1POOLS dengan file definisi OpenAPI**
1. Buat (atau ekspor) file definisi OpenAPI untuk API Anda.
1. Tentukan definisi JSON `COGNITO_USER_POOLS` authorizer (`MyUserPool`) sebagai bagian dari `securitySchemes` bagian di OpenAPI 3.0 atau `securityDefinitions` bagian di Open API 2.0 sebagai berikut:
------
#### [ OpenAPI 3.0 ]
```
"securitySchemes": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}
```
------
#### [ OpenAPI 2.0 ]
```
"securityDefinitions": {
"MyUserPool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}"
]
}
}
```
------
1. Untuk menggunakan token identitas untuk otorisasi metode, tambahkan `{ "MyUserPool": [] }` ke `security` definisi metode, seperti yang ditunjukkan dalam metode GET berikut pada sumber daya root.
```
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": []
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}
```
1. Untuk menggunakan token akses untuk otorisasi metode, ubah definisi keamanan di atas menjadi`{ "MyUserPool": [resource-server/scope, ...] }`:
```
"paths": {
"/": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"text/html"
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"security": [
{
"MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
}
],
"x-amazon-apigateway-integration": {
"type": "mock",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "'text/html'"
},
}
},
"requestTemplates": {
"application/json": "{\"statusCode\": 200}"
},
"passthroughBehavior": "when_no_match"
}
},
...
}
```
1. Jika diperlukan, Anda dapat mengatur pengaturan konfigurasi API lainnya dengan menggunakan definisi atau ekstensi OpenAPI yang sesuai. Untuk informasi selengkapnya, lihat [Ekstensi OpenAPI untuk API Gateway](api-gateway-swagger-extensions.md).
# Panggil REST API yang terintegrasi dengan kumpulan pengguna Amazon Cognito
Untuk memanggil metode dengan otorisasi kumpulan pengguna yang dikonfigurasi, klien harus melakukan hal berikut:
+ Aktifkan pengguna untuk mendaftar dengan kumpulan pengguna.
+ Aktifkan pengguna untuk masuk ke kumpulan pengguna.
+ Dapatkan [identitas atau token akses](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) pengguna yang masuk dari kumpulan pengguna.
+ Sertakan token di `Authorization` header (atau header lain yang Anda tentukan saat Anda membuat otorisasi).
Anda dapat menggunakan [AWS Amplify]()untuk melakukan tugas-tugas ini. Lihat [Mengintegrasikan Amazon Cognito Dengan Web dan Aplikasi Seluler](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) untuk informasi selengkapnya.
+ Untuk Android, lihat [Memulai dengan Amplify untuk](https://docs.amplify.aws/android/build-a-backend/auth/) Android.
+ Untuk menggunakan iOS, lihat [Memulai dengan Amplify untuk iOS](https://docs.amplify.aws/swift/build-a-backend/auth/).
+ Untuk menggunakannya JavaScript, lihat [Memulai dengan Amplify for Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/).
# Konfigurasikan otorisasi Amazon Cognito lintas akun untuk REST API menggunakan konsol API Gateway
Anda sekarang juga dapat menggunakan kumpulan pengguna Amazon Cognito dari AWS akun lain sebagai otorisasi API Anda. Kumpulan pengguna Amazon Cognito dapat menggunakan strategi otentikasi token pembawa seperti atau SALL. OAuth Hal ini memudahkan untuk mengelola dan berbagi otorisasi kumpulan pengguna Amazon Cognito pusat di beberapa API Gateway. APIs
Di bagian ini, kami menunjukkan cara mengonfigurasi kumpulan pengguna Amazon Cognito lintas akun menggunakan konsol Amazon API Gateway.
Petunjuk ini mengasumsikan bahwa Anda sudah memiliki API Gateway API di satu AWS akun dan kumpulan pengguna Amazon Cognito di akun lain.
## Buat otorisasi Amazon Cognito lintas akun untuk REST API
Masuk ke konsol Amazon API Gateway di akun yang memiliki API Anda di dalamnya, lalu lakukan hal berikut:
1. Buat API baru, atau pilih API yang ada di API Gateway.
1. Di panel navigasi utama, pilih **Authorizers**.
1. Pilih **Buat Authorizer**.
1. Untuk mengonfigurasi otorisasi baru untuk menggunakan kumpulan pengguna, lakukan hal berikut:
1. Untuk **nama Authorizer**, masukkan nama.
1. Untuk **jenis Authorizer**, pilih **Cognito**.
1. Untuk **kumpulan pengguna Cognito**, masukkan ARN lengkap untuk kumpulan pengguna yang Anda miliki di akun kedua Anda.
**catatan**
**Di konsol Amazon Cognito, Anda dapat menemukan ARN untuk kumpulan pengguna Anda di bidang **ARN** Kolam pada panel Pengaturan Umum.**
1. Untuk **sumber Token**, masukkan **Authorization** sebagai nama header untuk meneruskan identitas atau token akses yang dikembalikan oleh Amazon Cognito saat pengguna berhasil masuk.
1. (Opsional) Masukkan ekspresi reguler di bidang **validasi Token** untuk memvalidasi bidang `aud` (audiens) token identitas sebelum permintaan diotorisasi dengan Amazon Cognito. Perhatikan bahwa saat menggunakan token akses validasi ini menolak permintaan karena token akses tidak berisi bidang. `aud`
1. Pilih **Buat Authorizer**.
# Buat otorisasi Amazon Cognito untuk REST API menggunakan CloudFormation
Anda dapat menggunakannya CloudFormation untuk membuat kumpulan pengguna Amazon Cognito dan otorisasi Amazon Cognito. Contoh CloudFormation template melakukan hal berikut:
+ Buat kumpulan pengguna Amazon Cognito. Klien harus terlebih dahulu menandatangani pengguna ke kumpulan pengguna dan mendapatkan [identitas atau token akses](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Jika Anda menggunakan token akses untuk mengotorisasi panggilan metode API, pastikan untuk mengonfigurasi integrasi aplikasi dengan kumpulan pengguna untuk menyiapkan cakupan kustom yang Anda inginkan di server sumber daya tertentu.
+ Membuat API Gateway API dengan `GET` metode.
+ Membuat otorisasi Amazon Cognito yang menggunakan `Authorization` header sebagai sumber token.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
UserPool:
Type: AWS::Cognito::UserPool
Properties:
AccountRecoverySetting:
RecoveryMechanisms:
- Name: verified_phone_number
Priority: 1
- Name: verified_email
Priority: 2
AdminCreateUserConfig:
AllowAdminCreateUserOnly: true
EmailVerificationMessage: The verification code to your new account is {####}
EmailVerificationSubject: Verify your new account
SmsVerificationMessage: The verification code to your new account is {####}
VerificationMessageTemplate:
DefaultEmailOption: CONFIRM_WITH_CODE
EmailMessage: The verification code to your new account is {####}
EmailSubject: Verify your new account
SmsMessage: The verification code to your new account is {####}
UpdateReplacePolicy: Retain
DeletionPolicy: Retain
CogAuthorizer:
Type: AWS::ApiGateway::Authorizer
Properties:
Name: CognitoAuthorizer
RestApiId:
Ref: Api
Type: COGNITO_USER_POOLS
IdentitySource: method.request.header.Authorization
ProviderARNs:
- Fn::GetAtt:
- UserPool
- Arn
Api:
Type: AWS::ApiGateway::RestApi
Properties:
Name: MyCogAuthApi
ApiDeployment:
Type: AWS::ApiGateway::Deployment
Properties:
RestApiId:
Ref: Api
DependsOn:
- CogAuthorizer
- ApiGET
ApiDeploymentStageprod:
Type: AWS::ApiGateway::Stage
Properties:
RestApiId:
Ref: Api
DeploymentId:
Ref: ApiDeployment
StageName: prod
ApiGET:
Type: AWS::ApiGateway::Method
Properties:
HttpMethod: GET
ResourceId:
Fn::GetAtt:
- Api
- RootResourceId
RestApiId:
Ref: Api
AuthorizationType: COGNITO_USER_POOLS
AuthorizerId:
Ref: CogAuthorizer
Integration:
IntegrationHttpMethod: GET
Type: HTTP_PROXY
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Outputs:
ApiEndpoint:
Value:
Fn::Join:
- ""
- - https://
- Ref: Api
- .execute-api.
- Ref: AWS::Region
- "."
- Ref: AWS::URLSuffix
- /
- Ref: ApiDeploymentStageprod
- /
```
# Integrasi untuk REST APIs di API Gateway
Setelah menyiapkan metode API, Anda harus mengintegrasikannya dengan titik akhir di backend. Endpoint backend juga disebut sebagai titik akhir integrasi dan dapat berupa fungsi Lambda, halaman web HTTP, atau tindakan layanan. AWS
Seperti halnya metode API, integrasi API memiliki permintaan integrasi dan respons integrasi. Permintaan integrasi merangkum permintaan HTTP yang diterima oleh backend. Ini mungkin atau mungkin tidak berbeda dari permintaan metode yang diajukan oleh klien. Respons integrasi adalah respons HTTP yang merangkum output yang dikembalikan oleh backend.
Menyiapkan permintaan integrasi melibatkan hal-hal berikut: mengonfigurasi cara meneruskan permintaan metode yang dikirimkan klien ke backend; mengonfigurasi cara mengubah data permintaan, jika perlu, ke data permintaan integrasi; dan menentukan fungsi Lambda mana yang akan dipanggil, menentukan server HTTP mana yang akan meneruskan permintaan masuk, atau menentukan tindakan layanan yang akan dipanggil. AWS
Menyiapkan respons integrasi (hanya berlaku untuk integrasi non-proxy) melibatkan hal berikut: mengonfigurasi cara meneruskan hasil yang dikembalikan ke respons metode dari kode status tertentu, mengonfigurasi cara mengubah parameter respons integrasi yang ditentukan ke parameter respons metode yang telah dikonfigurasi sebelumnya, dan mengonfigurasi cara memetakan badan respons integrasi ke badan respons metode sesuai dengan templat pemetaan tubuh yang ditentukan.
Secara terprogram, permintaan integrasi dienkapsulasi oleh [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)sumber daya dan respons integrasi oleh sumber daya API Gateway. [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)
Untuk menyiapkan permintaan integrasi, Anda membuat [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)sumber daya dan menggunakannya untuk mengonfigurasi URL titik akhir integrasi. Anda kemudian mengatur izin IAM untuk mengakses backend, dan menentukan pemetaan untuk mengubah data permintaan yang masuk sebelum meneruskannya ke backend. Untuk menyiapkan respons integrasi untuk integrasi non-proxy, Anda membuat [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)sumber daya dan menggunakannya untuk menetapkan respons metode targetnya. Anda kemudian mengonfigurasi cara memetakan output backend ke respons metode.
**Topics**
+ [Menyiapkan permintaan integrasi di API Gateway](api-gateway-integration-settings-integration-request.md)
+ [Siapkan respons integrasi di API Gateway](api-gateway-integration-settings-integration-response.md)
+ [Integrasi Lambda untuk REST APIs di API Gateway](set-up-lambda-integrations.md)
+ [Integrasi HTTP untuk REST APIs di API Gateway](setup-http-integrations.md)
+ [Streaming respons integrasi untuk integrasi proxy Anda di API Gateway](response-transfer-mode.md)
+ [Integrasi pribadi untuk REST APIs di API Gateway](private-integration.md)
+ [Integrasi tiruan untuk REST APIs di API Gateway](how-to-mock-integration.md)
# Menyiapkan permintaan integrasi di API Gateway
Untuk menyiapkan permintaan integrasi, Anda melakukan tugas wajib dan opsional berikut:
1. Pilih jenis integrasi yang menentukan bagaimana data permintaan metode diteruskan ke backend.
1. Untuk integrasi non-tiruan, tentukan metode HTTP dan URI dari titik akhir integrasi yang ditargetkan, kecuali untuk integrasi. `MOCK`
1. Untuk integrasi dengan fungsi Lambda dan tindakan layanan AWS lainnya, tetapkan peran IAM dengan izin yang diperlukan untuk API Gateway untuk memanggil backend atas nama Anda.
1. Untuk integrasi non-proxy, atur pemetaan parameter yang diperlukan untuk memetakan parameter permintaan metode yang telah ditentukan sebelumnya ke parameter permintaan integrasi yang sesuai.
1. Untuk integrasi non-proxy, setel pemetaan badan yang diperlukan untuk memetakan badan permintaan metode masuk dari jenis konten tertentu sesuai dengan templat pemetaan yang ditentukan.
1. Untuk integrasi non-proxy, tentukan kondisi di mana data permintaan metode masuk diteruskan ke backend apa adanya.
1. Secara opsional, tentukan cara menangani konversi tipe untuk muatan biner.
1. Secara opsional, deklarasikan nama namespace cache dan parameter kunci cache untuk mengaktifkan caching API.
Melakukan tugas ini melibatkan pembuatan sumber daya [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) API Gateway dan menetapkan nilai properti yang sesuai. Anda dapat melakukannya menggunakan konsol API Gateway, AWS CLI perintah, AWS SDK, atau API Gateway REST API.
**Topics**
+ [Tugas dasar permintaan integrasi API](integration-request-basic-setup.md)
+ [Pilih jenis integrasi API Gateway API](api-gateway-api-integration-types.md)
+ [Siapkan integrasi proxy dengan sumber daya proxy](api-gateway-set-up-simple-proxy.md)
+ [Menyiapkan permintaan integrasi API menggunakan konsol API Gateway](how-to-method-settings-console.md)
# Tugas dasar permintaan integrasi API
Permintaan integrasi adalah permintaan HTTP yang API Gateway kirimkan ke backend, meneruskan data permintaan yang dikirimkan klien, dan mengubah data, jika perlu. Metode HTTP (atau kata kerja) dan URI dari permintaan integrasi ditentukan oleh backend (yaitu, titik akhir integrasi). Mereka dapat sama dengan atau berbeda dari metode HTTP permintaan metode dan URI, masing-masing.
Misalnya, ketika fungsi Lambda mengembalikan file yang diambil dari Amazon S3, Anda dapat mengekspos operasi ini secara intuitif sebagai permintaan `GET` metode ke klien meskipun permintaan integrasi yang sesuai mengharuskan permintaan `POST` digunakan untuk menjalankan fungsi Lambda. Untuk titik akhir HTTP, kemungkinan permintaan metode dan permintaan integrasi yang sesuai keduanya menggunakan kata kerja HTTP yang sama. Namun, ini tidak diperlukan. Anda dapat mengintegrasikan permintaan metode berikut:
```
GET /{var}?query=value
Host: api.domain.net
```
Dengan permintaan integrasi berikut:
```
POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...
{
path: "{var}'s value",
type: "value"
}
```
Sebagai pengembang API, Anda dapat menggunakan kata kerja HTTP dan URI apa pun untuk permintaan metode yang sesuai dengan kebutuhan Anda. Tetapi Anda harus mengikuti persyaratan titik akhir integrasi. Ketika data permintaan metode berbeda dari data permintaan integrasi, Anda dapat merekonsiliasi perbedaan dengan menyediakan pemetaan dari data permintaan metode ke data permintaan integrasi.
Dalam contoh sebelumnya, pemetaan menerjemahkan nilai variabel jalur (`{var}`) dan parameter kueri (`query`) dari permintaan `GET` metode ke nilai properti payload permintaan integrasi dan. `path` `type` Data permintaan lain yang dapat dipetakan mencakup header dan badan permintaan. Ini dijelaskan dalam[Pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping.md).
Saat menyiapkan permintaan integrasi proxy HTTP atau HTTP, Anda menetapkan URL endpoint HTTP backend sebagai nilai URI permintaan integrasi. Misalnya, di PetStore API, permintaan metode untuk mendapatkan halaman hewan peliharaan memiliki URI permintaan integrasi berikut:
```
http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
Saat menyiapkan integrasi proxy Lambda atau Lambda, Anda menetapkan Nama Sumber Daya Amazon (ARN) untuk menjalankan fungsi Lambda sebagai nilai URI permintaan integrasi. ARN ini memiliki format sebagai berikut:
```
arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations
```
Bagian setelahnya`arn:aws:apigateway:api-region:lambda:path/`, yaitu`/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`, adalah jalur REST API URI dari tindakan Lambda [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html). Jika Anda menggunakan konsol API Gateway untuk menyiapkan integrasi Lambda, API Gateway akan membuat ARN dan menetapkannya ke URI integrasi setelah meminta Anda untuk memilih dari suatu wilayah. `lambda-function-name`
Saat menyiapkan permintaan integrasi dengan tindakan AWS layanan lain, URI permintaan integrasi juga merupakan ARN, mirip dengan integrasi dengan tindakan Lambda. `Invoke` Misalnya, untuk integrasi dengan [GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)aksi Amazon S3, URI permintaan integrasi adalah ARN dengan format berikut:
```
arn:aws:apigateway:api-region:s3:path/{bucket}
```
URI permintaan integrasi adalah konvensi jalur untuk menentukan tindakan, di `{bucket}` mana placeholder nama bucket. Atau, tindakan AWS layanan dapat direferensikan dengan namanya. Menggunakan nama tindakan, URI permintaan integrasi untuk `GetBucket` tindakan Amazon S3 menjadi sebagai berikut:
```
arn:aws:apigateway:api-region:s3:action/GetBucket
```
Dengan URI permintaan integrasi berbasis tindakan, nama bucket (`{bucket}`) harus ditentukan dalam isi permintaan integrasi (`{ Bucket: "{bucket}" }`), mengikuti format input tindakan`GetBucket`.
Untuk AWS integrasi, Anda juga harus mengonfigurasi [kredensional](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials) agar API Gateway dapat memanggil tindakan terintegrasi. Anda dapat membuat peran IAM baru atau memilih peran IAM yang sudah ada untuk API Gateway untuk memanggil tindakan dan kemudian menentukan peran menggunakan ARN-nya. Berikut ini menunjukkan contoh ARN ini:
```
arn:aws:iam::account-id:role/iam-role-name
```
Peran IAM ini harus berisi kebijakan untuk memungkinkan tindakan dieksekusi. Itu juga harus memiliki API Gateway yang dideklarasikan (dalam hubungan kepercayaan peran) sebagai entitas tepercaya untuk mengambil peran. Izin tersebut dapat diberikan pada tindakan itu sendiri. Mereka dikenal sebagai izin berbasis sumber daya. Untuk integrasi Lambda, Anda dapat memanggil tindakan [AddPermission Lambda untuk menyetel izin](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) berbasis sumber daya dan kemudian menyetel ke null dalam permintaan integrasi API Gateway. `credentials`
Kami membahas pengaturan integrasi dasar. Pengaturan lanjutan melibatkan pemetaan data permintaan metode ke data permintaan integrasi. Untuk informasi selengkapnya, lihat [Transformasi data untuk REST APIs di API Gateway](rest-api-data-transformations.md).
# Pilih jenis integrasi API Gateway API
Anda memilih jenis integrasi API sesuai dengan jenis titik akhir integrasi yang bekerja dengan Anda dan bagaimana Anda ingin data diteruskan ke dan dari titik akhir integrasi. Untuk fungsi Lambda, Anda dapat memiliki integrasi proxy Lambda, atau integrasi kustom Lambda. Untuk titik akhir HTTP, Anda dapat memiliki integrasi proxy HTTP atau integrasi kustom HTTP. Untuk tindakan AWS layanan, Anda memiliki AWS integrasi tipe non-proxy saja. API Gateway juga mendukung integrasi tiruan, di mana API Gateway berfungsi sebagai titik akhir integrasi untuk menanggapi permintaan metode.
Integrasi kustom Lambda adalah kasus khusus AWS integrasi, di mana titik akhir integrasi sesuai dengan tindakan [pemanggilan fungsi layanan Lambda.](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)
Secara terprogram, Anda memilih jenis integrasi dengan mengatur [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type)properti pada sumber daya. [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) Untuk integrasi proxy Lambda, nilainya adalah. `AWS_PROXY` Untuk integrasi kustom Lambda dan semua AWS integrasi lainnya, memang demikian. `AWS` Untuk integrasi proxy HTTP dan integrasi HTTP, nilainya adalah `HTTP_PROXY` dan`HTTP`, masing-masing. Untuk integrasi tiruan, `type` nilainya adalah`MOCK`.
Integrasi proxy Lambda mendukung pengaturan integrasi yang efisien dengan satu fungsi Lambda. Pengaturannya sederhana dan dapat berkembang dengan backend tanpa harus meruntuhkan pengaturan yang ada. Untuk alasan ini, sangat disarankan untuk integrasi dengan fungsi Lambda.
Sebaliknya, integrasi kustom Lambda memungkinkan penggunaan kembali template pemetaan yang dikonfigurasi untuk berbagai titik akhir integrasi yang memiliki persyaratan serupa dari format data input dan output. Pengaturan lebih terlibat dan direkomendasikan untuk skenario aplikasi yang lebih maju.
Demikian pula, integrasi proxy HTTP memiliki pengaturan integrasi yang efisien dan dapat berkembang dengan backend tanpa harus meruntuhkan pengaturan yang ada. Integrasi kustom HTTP lebih terlibat untuk disiapkan, tetapi memungkinkan penggunaan kembali template pemetaan yang dikonfigurasi untuk titik akhir integrasi lainnya.
Daftar berikut merangkum jenis integrasi yang didukung:
+ `AWS`: Jenis integrasi ini memungkinkan API mengekspos tindakan AWS layanan. Dalam `AWS` integrasi, Anda harus mengonfigurasi permintaan integrasi dan respons integrasi dan menyiapkan pemetaan data yang diperlukan dari permintaan metode ke permintaan integrasi, dan dari respons integrasi ke respons metode.
+ `AWS_PROXY`: Jenis integrasi ini memungkinkan metode API diintegrasikan dengan tindakan pemanggilan fungsi Lambda dengan pengaturan integrasi yang fleksibel, serbaguna, dan efisien. Integrasi ini bergantung pada interaksi langsung antara klien dan fungsi Lambda terintegrasi.
Dengan jenis integrasi ini, juga dikenal sebagai integrasi proxy Lambda, Anda tidak mengatur permintaan integrasi atau respons integrasi. API Gateway meneruskan permintaan masuk dari klien sebagai input ke fungsi Lambda backend. Fungsi Lambda terintegrasi mengambil [input format ini dan mem-parsing](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) input dari semua sumber yang tersedia, termasuk header permintaan, variabel jalur URL, parameter string kueri, dan isi yang berlaku. Fungsi mengembalikan hasil mengikuti [format output](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) ini.
Ini adalah jenis integrasi yang disukai untuk memanggil fungsi Lambda melalui API Gateway dan tidak berlaku untuk tindakan AWS layanan lainnya, termasuk tindakan Lambda selain tindakan pemanggilan fungsi.
+ `HTTP`: Jenis integrasi ini memungkinkan API mengekspos titik akhir HTTP di backend. Dengan `HTTP` integrasi, juga dikenal sebagai integrasi kustom HTTP, Anda harus mengonfigurasi permintaan integrasi dan respons integrasi. Anda harus menyiapkan pemetaan data yang diperlukan dari permintaan metode ke permintaan integrasi, dan dari respons integrasi ke respons metode.
+ `HTTP_PROXY`: Integrasi proxy HTTP memungkinkan klien untuk mengakses titik akhir HTTP backend dengan pengaturan integrasi yang efisien pada metode API tunggal. Anda tidak mengatur permintaan integrasi atau respons integrasi. API Gateway meneruskan permintaan masuk dari klien ke titik akhir HTTP dan meneruskan respons keluar dari titik akhir HTTP ke klien.
+ `MOCK`: Jenis integrasi ini memungkinkan API Gateway mengembalikan respons tanpa mengirim permintaan lebih lanjut ke backend. Ini berguna untuk pengujian API karena dapat digunakan untuk menguji pengaturan integrasi tanpa menimbulkan biaya untuk menggunakan backend dan untuk mengaktifkan pengembangan kolaboratif API.
Dalam pengembangan kolaboratif, tim dapat mengisolasi upaya pengembangan mereka dengan menyiapkan simulasi komponen API yang dimiliki oleh tim lain dengan menggunakan integrasi. `MOCK` Ini juga digunakan untuk mengembalikan header terkait CORS untuk memastikan bahwa metode API mengizinkan akses CORS. Faktanya, konsol API Gateway mengintegrasikan `OPTIONS` metode untuk mendukung CORS dengan integrasi tiruan. [Respons gateway](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) adalah contoh lain dari integrasi tiruan.
# Siapkan integrasi proxy dengan sumber daya proxy
Untuk menyiapkan integrasi proxy di API Gateway API dengan [sumber daya proxy](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource), Anda melakukan tugas berikut:
+ Buat sumber daya proxy dengan variabel jalur serakah dari. `{proxy+}`
+ Tetapkan `ANY` metode pada sumber daya proxy.
+ Integrasikan sumber daya dan metode dengan backend menggunakan tipe integrasi HTTP atau Lambda.
**catatan**
Variabel jalur serakah, `ANY` metode, dan jenis integrasi proxy adalah fitur independen, meskipun umumnya digunakan bersama. Anda dapat mengonfigurasi metode HTTP tertentu pada sumber daya serakah atau menerapkan jenis integrasi non-proxy ke sumber daya proxy.
API Gateway memberlakukan batasan dan batasan tertentu saat menangani metode dengan integrasi proxy Lambda atau integrasi proxy HTTP. Lihat perinciannya di [Catatan penting Amazon API Gateway](api-gateway-known-issues.md).
**catatan**
Saat menggunakan integrasi proxy dengan passthrough, API Gateway mengembalikan `Content-Type:application/json` header default jika jenis konten payload tidak ditentukan.
[Sumber daya proxy paling kuat ketika terintegrasi dengan backend menggunakan integrasi proxy HTTP atau integrasi proxy Lambda.](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)
## Integrasi proxy HTTP dengan sumber daya proxy
Integrasi proxy HTTP, yang ditunjuk oleh `HTTP_PROXY` API Gateway REST API, adalah untuk mengintegrasikan permintaan metode dengan titik akhir HTTP backend. Dengan tipe integrasi ini, API Gateway hanya meneruskan seluruh permintaan dan respons antara frontend dan backend, tunduk pada batasan dan [batasan](api-gateway-known-issues.md) tertentu.
**catatan**
Integrasi proxy HTTP mendukung header multi-nilai dan string kueri.
Saat menerapkan integrasi proxy HTTP ke sumber daya proxy, Anda dapat menyiapkan API untuk mengekspos sebagian atau seluruh hierarki titik akhir backend HTTP dengan satu pengaturan integrasi. Misalnya, backend situs web diatur ke dalam beberapa cabang simpul pohon dari simpul akar (`/site`) sebagai:`/site/a0/a1/.../aN`,`/site/b0/b1/.../bM`, dll. Jika Anda mengintegrasikan `ANY` metode pada sumber daya proxy `/api/{proxy+}` dengan titik akhir backend dengan jalur URL`/site/{proxy}`, permintaan integrasi tunggal dapat mendukung operasi HTTP apa pun (GET, POST, dll.) di salah satu dari. `[a0, a1, ..., aN, b0, b1, ...bM, ...]` Jika Anda menerapkan integrasi proxy ke metode HTTP tertentu, misalnya`GET`, permintaan integrasi yang dihasilkan bekerja dengan operasi yang ditentukan (yaitu,`GET`) pada salah satu node backend tersebut.
## Integrasi proxy Lambda dengan sumber daya proxy
Integrasi proxy Lambda, yang ditunjuk oleh `AWS_PROXY` API Gateway REST API, adalah untuk mengintegrasikan permintaan metode dengan fungsi Lambda di backend. Dengan tipe integrasi ini, API Gateway menerapkan template pemetaan default untuk mengirim seluruh permintaan ke fungsi Lambda dan mengubah output dari fungsi Lambda menjadi respons HTTP.
Demikian pula, Anda dapat menerapkan integrasi proxy Lambda ke sumber daya proxy `/api/{proxy+}` untuk menyiapkan integrasi tunggal agar fungsi Lambda backend bereaksi satu per satu terhadap perubahan di salah satu sumber daya API di bawah. `/api`
# Menyiapkan permintaan integrasi API menggunakan konsol API Gateway
Penyiapan metode API mendefinisikan metode dan menjelaskan perilakunya. Untuk mengatur metode, Anda harus menentukan sumber daya, termasuk root (“/”), di mana metode diekspos, metode HTTP (,, dll.) `GET``POST`, Dan bagaimana itu akan diintegrasikan dengan backend yang ditargetkan. Permintaan dan respons metode menentukan kontrak dengan aplikasi panggilan, menetapkan parameter mana yang dapat diterima API dan seperti apa responsnya.
Prosedur berikut menjelaskan cara menggunakan konsol API Gateway untuk membuat permintaan integrasi.
**Topics**
+ [Siapkan integrasi Lambda](#how-to-method-settings-console-lambda)
+ [Siapkan integrasi HTTP](#how-to-method-settings-console-http)
+ [Siapkan integrasi AWS layanan](#how-to-method-settings-console-aws)
+ [Siapkan integrasi tiruan](#how-to-method-settings-console-mock)
## Siapkan integrasi Lambda
Gunakan integrasi fungsi Lambda untuk mengintegrasikan API Anda dengan fungsi Lambda. Pada API level, ini adalah tipe `AWS` integrasi jika Anda membuat integrasi non-proxy, atau tipe `AWS_PROXY` integrasi jika Anda membuat integrasi proxy.
**Untuk mengatur integrasi Lambda**
1. Di panel **Resources**, pilih **Create method**.
1. Untuk **jenis Metode**, pilih metode HTTP.
1. Untuk **jenis Integrasi**, pilih fungsi **Lambda**.
1. Untuk menggunakan integrasi proxy Lambda, aktifkan integrasi proxy **Lambda**. Untuk mempelajari lebih lanjut tentang integrasi proxy Lambda, lihat. [Memahami integrasi proxy API Gateway Lambda](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy)
1. Untuk **fungsi Lambda**, masukkan nama fungsi Lambda.
Jika Anda menggunakan fungsi Lambda di Wilayah yang berbeda dari API Anda, pilih Wilayah dari menu tarik-turun dan masukkan nama fungsi Lambda. Jika Anda menggunakan fungsi Lambda lintas akun, masukkan fungsi ARN.
1. Untuk menggunakan nilai batas waktu default 29 detik, tetap aktifkan **batas waktu default**. Untuk menetapkan batas waktu kustom, pilih Batas **waktu default** dan masukkan nilai batas waktu antara `50` dan milidetik. `29000`
1. (Opsional) Anda dapat mengonfigurasi pengaturan permintaan metode menggunakan menu tarik-turun berikut. Pilih **Pengaturan permintaan metode** dan konfigurasikan permintaan metode Anda. Untuk informasi lebih lanjut, lihat langkah 3 dari[Mengedit permintaan metode API Gateway di konsol API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Anda juga dapat mengonfigurasi pengaturan permintaan metode Anda setelah Anda membuat metode Anda.
1. Pilih **metode Buat**.
## Siapkan integrasi HTTP
Gunakan integrasi HTTP untuk mengintegrasikan API Anda dengan titik akhir HTTP. Pada level API, ini adalah tipe `HTTP` integrasi.
**Untuk mengatur integrasi HTTP**
1. Di panel **Resources**, pilih **Create method**.
1. Untuk **jenis Metode**, pilih metode HTTP.
1. Untuk **jenis Integrasi**, pilih **HTTP**.
1. Untuk menggunakan integrasi proxy HTTP, aktifkan **integrasi proxy HTTP**. Untuk mempelajari lebih lanjut tentang integrasi proxy HTTP, lihat[Siapkan integrasi proxy HTTP di API Gateway](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource).
1. Untuk **metode HTTP**, pilih jenis metode HTTP yang paling cocok dengan metode di backend HTTP.
1. Untuk **URL Endpoint**, masukkan URL backend HTTP yang ingin digunakan metode ini.
1. Untuk **penanganan Konten**, pilih perilaku penanganan konten.
1. Untuk menggunakan nilai batas waktu default 29 detik, tetap aktifkan **batas waktu default**. Untuk menetapkan batas waktu kustom, pilih Batas **waktu default** dan masukkan nilai batas waktu antara `50` dan milidetik. `29000`
1. (Opsional) Anda dapat mengonfigurasi pengaturan permintaan metode menggunakan menu tarik-turun berikut. Pilih **Pengaturan permintaan metode** dan konfigurasikan permintaan metode Anda. Untuk informasi lebih lanjut, lihat langkah 3 dari[Mengedit permintaan metode API Gateway di konsol API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Anda juga dapat mengonfigurasi pengaturan permintaan metode Anda setelah Anda membuat metode Anda.
1. Pilih **metode Buat**.
## Siapkan integrasi AWS layanan
Gunakan integrasi AWS layanan untuk mengintegrasikan API Anda secara langsung dengan AWS layanan. Pada level API, ini adalah tipe `AWS` integrasi.
Untuk menyiapkan API Gateway API untuk melakukan salah satu hal berikut:
+ Buat fungsi Lambda baru.
+ Tetapkan izin sumber daya pada fungsi Lambda.
+ Lakukan tindakan layanan Lambda lainnya.
Anda harus memilih **AWS layanan**.
**Untuk mengatur integrasi AWS layanan**
1. Di panel **Resources**, pilih **Create method**.
1. Untuk **jenis Metode**, pilih metode HTTP.
1. Untuk **jenis Integrasi**, pilih **AWS layanan**.
1. Untuk **AWS Wilayah**, pilih AWS Wilayah yang ingin digunakan metode ini untuk memanggil tindakan.
1. Untuk **AWS layanan**, pilih AWS layanan yang Anda inginkan untuk memanggil metode ini.
1. Untuk **AWS subdomain**, masukkan subdomain yang digunakan oleh layanan. AWS Biasanya, Anda akan membiarkan ini kosong. Beberapa AWS layanan dapat mendukung subdomain sebagai bagian dari host. Konsultasikan dokumentasi layanan untuk ketersediaan dan, jika tersedia, detailnya.
1. Untuk **metode HTTP**, pilih jenis metode HTTP yang sesuai dengan tindakan. Untuk jenis metode HTTP, lihat dokumentasi referensi API untuk AWS layanan yang Anda pilih untuk **AWS layanan**.
1. Untuk **tipe Tindakan**, pilih **Gunakan nama tindakan** untuk menggunakan tindakan API atau **Use path override** untuk menggunakan jalur sumber daya kustom. Untuk tindakan yang tersedia dan jalur sumber daya khusus, lihat dokumentasi referensi API untuk AWS layanan yang Anda pilih untuk **AWS layanan**.
1. Masukkan **nama Action** atau **Path override**.
1. Untuk **peran Eksekusi**, masukkan ARN dari peran IAM yang akan digunakan metode untuk memanggil tindakan.
Untuk membuat peran IAM, Anda dapat menyesuaikan instruksi di[Langkah 1: Buat peran eksekusi proxy AWS layanan](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles). Tentukan kebijakan akses dengan jumlah tindakan dan pernyataan sumber daya yang diinginkan. Untuk informasi selengkapnya, lihat [Cara kerja Amazon API Gateway dengan IAM](security_iam_service-with-iam.md).
Untuk sintaks pernyataan tindakan dan sumber daya, lihat dokumentasi untuk AWS layanan yang Anda pilih untuk **AWS layanan**.
Untuk hubungan kepercayaan peran IAM, tentukan hal berikut, yang memungkinkan API Gateway mengambil tindakan atas nama AWS akun Anda:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Untuk menggunakan nilai batas waktu default 29 detik, tetap aktifkan **batas waktu default**. Untuk menetapkan batas waktu kustom, pilih Batas **waktu default** dan masukkan nilai batas waktu antara `50` dan milidetik. `29000`
1. (Opsional) Anda dapat mengonfigurasi pengaturan permintaan metode menggunakan menu tarik-turun berikut. Pilih **Pengaturan permintaan metode** dan konfigurasikan permintaan metode Anda. Untuk informasi lebih lanjut, lihat langkah 3 dari[Mengedit permintaan metode API Gateway di konsol API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Anda juga dapat mengonfigurasi pengaturan permintaan metode Anda setelah Anda membuat metode Anda.
1. Pilih **metode Buat**.
## Siapkan integrasi tiruan
Gunakan integrasi tiruan jika Anda ingin API Gateway bertindak sebagai backend Anda untuk mengembalikan respons statis. Pada level API, ini adalah tipe `MOCK` integrasi. Biasanya, Anda dapat menggunakan `MOCK` integrasi saat API Anda belum final, tetapi Anda ingin menghasilkan respons API untuk membuka blokir tim dependen untuk pengujian. Untuk `OPTION` metode ini, API Gateway menetapkan `MOCK` integrasi sebagai default untuk mengembalikan header yang mengaktifkan CORS untuk sumber daya API yang diterapkan.
**Untuk mengatur integrasi tiruan**
1. Di panel **Resources**, pilih **Create method**.
1. Untuk **jenis Metode**, pilih metode HTTP.
1. Untuk **tipe Integrasi**, pilih **Mock**.
1. (Opsional) Anda dapat mengonfigurasi pengaturan permintaan metode menggunakan menu tarik-turun berikut. Pilih **Pengaturan permintaan metode** dan konfigurasikan permintaan metode Anda. Untuk informasi lebih lanjut, lihat langkah 3 dari[Mengedit permintaan metode API Gateway di konsol API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
Anda juga dapat mengonfigurasi pengaturan permintaan metode Anda setelah Anda membuat metode Anda.
1. Pilih **metode Buat**.
# Siapkan respons integrasi di API Gateway
Untuk integrasi non-proxy, Anda harus menyiapkan setidaknya satu respons integrasi, dan menjadikannya respons default, untuk meneruskan hasil yang dikembalikan dari backend ke klien. Anda dapat memilih untuk melewati hasil apa adanya atau mengubah data respons integrasi ke data respons metode jika keduanya memiliki format yang berbeda.
Untuk integrasi proxy, API Gateway secara otomatis meneruskan output backend ke klien sebagai respons HTTP. Anda tidak menetapkan respons integrasi atau respons metode.
Untuk menyiapkan respons integrasi, Anda melakukan tugas wajib dan opsional berikut:
1. Tentukan kode status HTTP dari respons metode yang data respons integrasi dipetakan. Ini wajib diisi.
1. Tentukan ekspresi reguler untuk memilih output backend yang akan diwakili oleh respons integrasi ini. Jika Anda membiarkan ini kosong, responsnya adalah respons default yang digunakan untuk menangkap respons apa pun yang belum dikonfigurasi.
1. Jika diperlukan, deklarasikan pemetaan yang terdiri dari pasangan nilai kunci untuk memetakan parameter respons integrasi yang ditentukan ke parameter respons metode yang diberikan.
1. Jika perlu, tambahkan templat pemetaan tubuh untuk mengubah muatan respons integrasi yang diberikan menjadi muatan respons metode yang ditentukan.
1. Jika diperlukan, tentukan cara menangani konversi tipe untuk muatan biner.
Respons integrasi adalah respons HTTP yang merangkum respons backend. Untuk titik akhir HTTP, respons backend adalah respons HTTP. Kode status respons integrasi dapat mengambil kode status yang dikembalikan ke backend, dan badan respons integrasi adalah payload yang dikembalikan ke backend. Untuk titik akhir Lambda, respons backend adalah output yang dikembalikan dari fungsi Lambda. Dengan integrasi Lambda, output fungsi Lambda dikembalikan sebagai respons. `200 OK` Payload dapat berisi hasil sebagai data JSON, termasuk string JSON atau objek JSON, atau pesan kesalahan sebagai objek JSON. Anda dapat menetapkan ekspresi reguler ke properti [SelectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) untuk memetakan respons kesalahan terhadap respons kesalahan HTTP yang sesuai. Untuk informasi selengkapnya tentang respons kesalahan fungsi Lambda, lihat. [Menangani kesalahan Lambda di API Gateway](handle-errors-in-lambda-integration.md) Dengan integrasi proxy Lambda, fungsi Lambda harus mengembalikan output dari format berikut:
```
{
statusCode: "...", // a valid HTTP status code
headers: {
custom-header: "..." // any API-specific custom header
},
body: "...", // a JSON string.
isBase64Encoded: true|false // for binary support
}
```
Tidak perlu memetakan respons fungsi Lambda ke respons HTTP yang tepat.
Untuk mengembalikan hasil ke klien, atur respons integrasi untuk meneruskan respons titik akhir melalui apa adanya ke respons metode yang sesuai. Atau Anda dapat memetakan data respons titik akhir ke data respons metode. Data respons yang dapat dipetakan mencakup kode status respons, parameter header respons, dan badan respons. Jika tidak ada respons metode yang ditentukan untuk kode status yang dikembalikan, API Gateway mengembalikan kesalahan 500. Lihat informasi yang lebih lengkap di [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md).
# Integrasi Lambda untuk REST APIs di API Gateway
Anda dapat mengintegrasikan metode API dengan fungsi Lambda menggunakan integrasi proxy Lambda atau integrasi Lambda non-proxy (kustom).
Dalam integrasi proxy Lambda, pengaturan yang diperlukan sederhana. Setel metode HTTP integrasi ke POST, URI endpoint integrasi ke ARN dari tindakan pemanggilan fungsi Lambda dari fungsi Lambda tertentu, dan berikan izin API Gateway untuk memanggil fungsi Lambda atas nama Anda.
Di integrasi non-proxy Lambda, selain langkah penyiapan integrasi proxy, Anda juga menentukan cara data permintaan masuk dipetakan ke permintaan integrasi dan bagaimana data respons integrasi yang dihasilkan dipetakan ke respons metode.
**Topics**
+ [Integrasi proxy Lambda di API Gateway](set-up-lambda-proxy-integrations.md)
+ [Siapkan integrasi kustom Lambda di API Gateway](set-up-lambda-custom-integrations.md)
+ [Siapkan pemanggilan asinkron dari fungsi Lambda backend](set-up-lambda-integration-async.md)
+ [Menangani kesalahan Lambda di API Gateway](handle-errors-in-lambda-integration.md)
# Integrasi proxy Lambda di API Gateway
Bagian berikut menunjukkan cara menggunakan integrasi proxy Lambda.
**Topics**
+ [Memahami integrasi proxy API Gateway Lambda](#api-gateway-create-api-as-simple-proxy)
+ [Support untuk header multi-nilai dan parameter string kueri](#apigateway-multivalue-headers-and-parameters)
+ [Format input fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-input-format)
+ [Format output dari fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-output-format)
+ [Siapkan integrasi proxy Lambda untuk API Gateway menggunakan AWS CLI](set-up-lambda-proxy-integration-using-cli.md)
+ [Siapkan sumber daya proxy dengan integrasi proxy Lambda dengan definisi OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## Memahami integrasi proxy API Gateway Lambda
Integrasi proxy Amazon API Gateway Lambda adalah mekanisme yang sederhana, kuat, dan gesit untuk membangun API dengan penyiapan metode API tunggal. Integrasi proxy Lambda memungkinkan klien untuk memanggil satu fungsi Lambda di backend. Fungsi ini mengakses banyak sumber daya atau fitur AWS layanan lain, termasuk memanggil fungsi Lambda lainnya.
Dalam integrasi proxy Lambda, ketika klien mengirimkan permintaan API, API Gateway meneruskan ke fungsi Lambda terintegrasi [objek peristiwa](#api-gateway-simple-proxy-for-lambda-input-format), kecuali urutan parameter permintaan tidak dipertahankan. [Data permintaan](#api-gateway-simple-proxy-for-lambda-input-format) ini mencakup header permintaan, parameter string kueri, variabel jalur URL, payload, dan data konfigurasi API. Data konfigurasi dapat mencakup nama tahap penyebaran saat ini, variabel tahap, identitas pengguna, atau konteks otorisasi (jika ada). Fungsi backend Lambda mem-parsing data permintaan yang masuk untuk menentukan respons yang dikembalikan. [Agar API Gateway meneruskan output Lambda sebagai respons API ke klien, fungsi Lambda harus mengembalikan hasilnya dalam format ini.](#api-gateway-simple-proxy-for-lambda-output-format)
Karena API Gateway tidak terlalu banyak campur tangan antara klien dan fungsi Lambda backend untuk integrasi proxy Lambda, klien dan fungsi Lambda terintegrasi dapat beradaptasi dengan perubahan satu sama lain tanpa merusak pengaturan integrasi API yang ada. Untuk mengaktifkan ini, klien harus mengikuti protokol aplikasi yang diberlakukan oleh fungsi Lambda backend.
Anda dapat menyiapkan integrasi proxy Lambda untuk metode API apa pun. Tetapi integrasi proxy Lambda lebih kuat ketika dikonfigurasi untuk metode API yang melibatkan sumber daya proxy generik. Sumber daya proxy generik dapat dilambangkan dengan variabel jalur template khusus, placeholder metode catch-all `{proxy+}``ANY`, atau keduanya. Klien dapat meneruskan input ke fungsi Lambda backend dalam permintaan masuk sebagai parameter permintaan atau muatan yang berlaku. Parameter permintaan termasuk header, variabel jalur URL, parameter string kueri, dan payload yang berlaku. Fungsi Lambda terintegrasi memverifikasi semua sumber input sebelum memproses permintaan dan menanggapi klien dengan pesan kesalahan yang berarti jika ada input yang diperlukan yang hilang.
Saat memanggil metode API yang terintegrasi dengan metode HTTP generik `ANY` dan sumber daya generik`{proxy+}`, klien mengirimkan permintaan dengan metode HTTP tertentu sebagai pengganti. `ANY` Klien juga menentukan jalur URL tertentu, bukan`{proxy+}`, dan menyertakan header yang diperlukan, parameter string kueri, atau payload yang berlaku.
Daftar berikut merangkum perilaku runtime dari berbagai metode API dengan integrasi proxy Lambda:
+ `ANY /{proxy+}`: Klien harus memilih metode HTTP tertentu, harus menetapkan hierarki jalur sumber daya tertentu, dan dapat mengatur header, parameter string kueri, dan muatan yang berlaku untuk meneruskan data sebagai input ke fungsi Lambda terintegrasi.
+ `ANY /res`: Klien harus memilih metode HTTP tertentu dan dapat mengatur header, parameter string kueri, dan payload yang berlaku untuk meneruskan data sebagai input ke fungsi Lambda terintegrasi.
+ `GET|POST|PUT|... /{proxy+}`: Klien dapat mengatur hierarki jalur sumber daya tertentu, header apa pun, parameter string kueri, dan muatan yang berlaku untuk meneruskan data sebagai input ke fungsi Lambda terintegrasi.
+ `GET|POST|PUT|... /res/{path}/...`: Klien harus memilih segmen jalur tertentu (untuk `{path}` variabel) dan dapat mengatur header permintaan, parameter string kueri, dan payload yang berlaku untuk meneruskan data input ke fungsi Lambda terintegrasi.
+ `GET|POST|PUT|... /res`: Klien dapat memilih header permintaan, parameter string kueri, dan payload yang berlaku untuk meneruskan data input ke fungsi Lambda terintegrasi.
Baik sumber daya proxy `{proxy+}` dan sumber daya kustom `{custom}` dinyatakan sebagai variabel jalur templat. Namun `{proxy+}` dapat merujuk ke sumber daya apa pun di sepanjang hierarki jalur, sementara `{custom}` mengacu pada segmen jalur tertentu saja. Misalnya, toko kelontong mungkin mengatur inventaris produk online-nya berdasarkan nama departemen, kategori produksi, dan jenis produk. Situs web toko kelontong kemudian dapat mewakili produk yang tersedia dengan variabel jalur template berikut dari sumber daya khusus:. `/{department}/{produce-category}/{product-type}` Misalnya, apel diwakili oleh `/produce/fruit/apple` dan wortel oleh`/produce/vegetables/carrot`. Ini juga dapat digunakan `/{proxy+}` untuk mewakili departemen apa pun, kategori produk apa pun, atau jenis produk apa pun yang dapat dicari pelanggan saat berbelanja di toko online. Misalnya, `/{proxy+}` dapat merujuk ke salah satu item berikut:
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
Untuk memungkinkan pelanggan mencari produk apa pun yang tersedia, kategori produksinya, dan departemen toko terkait, Anda dapat mengekspos satu metode `GET /{proxy+}` dengan izin hanya-baca. Demikian pula, untuk memungkinkan supervisor memperbarui inventaris `produce` departemen, Anda dapat menyiapkan metode tunggal lain `PUT /produce/{proxy+}` dengan read/write izin. Untuk memungkinkan kasir memperbarui total sayuran yang sedang berjalan, Anda dapat mengatur `POST /produce/vegetables/{proxy+}` metode dengan read/write izin. Untuk membiarkan manajer toko melakukan tindakan apa pun yang mungkin pada produk apa pun yang tersedia, pengembang toko online dapat mengekspos `ANY /{proxy+}` metode dengan read/write izin. Dalam kasus apa pun, pada waktu berjalan, pelanggan atau karyawan harus memilih produk tertentu dari jenis tertentu di departemen yang dipilih, kategori produk tertentu di departemen yang dipilih, atau departemen tertentu.
Untuk informasi selengkapnya tentang menyiapkan integrasi proxy API Gateway, lihat[Siapkan integrasi proxy dengan sumber daya proxy](api-gateway-set-up-simple-proxy.md).
Integrasi proxy mengharuskan klien memiliki pengetahuan yang lebih rinci tentang persyaratan backend. Oleh karena itu, untuk memastikan kinerja aplikasi dan pengalaman pengguna yang optimal, pengembang backend harus berkomunikasi dengan jelas kepada pengembang klien persyaratan backend, dan memberikan mekanisme umpan balik kesalahan yang kuat ketika persyaratan tidak terpenuhi.
## Support untuk header multi-nilai dan parameter string kueri
API Gateway mendukung beberapa header dan parameter string kueri yang memiliki nama yang sama. Header multi-nilai serta header dan parameter nilai tunggal dapat digabungkan dalam permintaan dan tanggapan yang sama. Untuk informasi selengkapnya, lihat [Format input fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-input-format) dan [Format output dari fungsi Lambda untuk integrasi proxy](#api-gateway-simple-proxy-for-lambda-output-format).
## Format input fungsi Lambda untuk integrasi proxy
Dalam integrasi proxy Lambda, API Gateway memetakan seluruh permintaan klien ke `event` parameter input fungsi Lambda backend. Contoh berikut menunjukkan struktur peristiwa yang dikirimkan API Gateway ke integrasi proxy Lambda.
Dalam contoh ini, kami berasumsi bahwa pemanggilan ke API Gateway adalah sebagai berikut:
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
Outputnya terlihat seperti berikut:
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "IP",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
**catatan**
Dalam masukan:
`headers`Kuncinya hanya dapat berisi header nilai tunggal.
`multiValueHeaders`Kuncinya dapat berisi header multi-nilai serta header nilai tunggal.
Jika Anda menentukan nilai untuk keduanya `headers` dan`multiValueHeaders`, API Gateway menggabungkannya ke dalam satu daftar. Jika pasangan kunci-nilai yang sama ditentukan di keduanya, hanya nilai dari yang `multiValueHeaders` akan muncul dalam daftar gabungan.
Dalam input ke fungsi Lambda backend, `requestContext` objek adalah peta pasangan kunci-nilai. Di setiap pasangan, kuncinya adalah nama properti variabel [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference), dan nilainya adalah nilai properti itu. API Gateway mungkin menambahkan kunci baru ke peta.
Bergantung pada fitur yang diaktifkan, `requestContext` peta dapat bervariasi dari API ke API. Misalnya, dalam contoh sebelumnya, tidak ada jenis otorisasi yang ditentukan, jadi tidak ada `$context.authorizer.*` atau `$context.identity.*` properti yang ada. Ketika jenis otorisasi ditentukan, ini menyebabkan API Gateway meneruskan informasi pengguna yang diotorisasi ke titik akhir integrasi dalam `requestContext.identity` objek sebagai berikut:
+ Ketika jenis otorisasi`AWS_IAM`, informasi pengguna yang berwenang mencakup `$context.identity.*` properti.
+ Ketika jenis otorisasi adalah `COGNITO_USER_POOLS` (Amazon Cognito Authorizer), informasi `$context.identity.cognito*` pengguna yang berwenang termasuk dan properti. `$context.authorizer.claims.*`
+ Ketika jenis otorisasi adalah `CUSTOM` (Lambda Authorizer), informasi pengguna yang berwenang `$context.authorizer.principalId` termasuk dan properti lain yang berlaku. `$context.authorizer.*`
## Format output dari fungsi Lambda untuk integrasi proxy
Dalam integrasi proxy Lambda, API Gateway memerlukan fungsi Lambda backend untuk mengembalikan output sesuai dengan format JSON berikut:
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
```
Dalam output:
+ `multiValueHeaders`Tombol `headers` dan dapat tidak ditentukan jika tidak ada header respons tambahan yang akan dikembalikan.
+ `headers`Kuncinya hanya dapat berisi header nilai tunggal.
+ `multiValueHeaders`Kuncinya dapat berisi header multi-nilai serta header nilai tunggal. Anda dapat menggunakan `multiValueHeaders` kunci untuk menentukan semua header tambahan Anda, termasuk yang bernilai tunggal.
+ Jika Anda menentukan nilai untuk keduanya `headers` dan`multiValueHeaders`, API Gateway menggabungkannya ke dalam satu daftar. Jika pasangan kunci-nilai yang sama ditentukan di keduanya, hanya nilai dari yang `multiValueHeaders` akan muncul dalam daftar gabungan.
Untuk mengaktifkan CORS untuk integrasi proxy Lambda, Anda harus `Access-Control-Allow-Origin:domain-name` menambahkan ke output. `headers` `domain-name`bisa `*` untuk nama domain apa pun. Output `body` disusun ke frontend sebagai payload respons metode. **Jika `body` adalah gumpalan biner, Anda dapat menyandikannya sebagai string yang dikodekan Base64 dengan mengatur `true` dan `isBase64Encoded` mengonfigurasi `*/*` sebagai Tipe Media Biner.** Jika tidak, Anda dapat mengaturnya ke `false` atau membiarkannya tidak ditentukan.
**catatan**
Untuk informasi selengkapnya tentang mengaktifkan dukungan biner, lihat[Mengaktifkan dukungan biner menggunakan konsol API Gateway](api-gateway-payload-encodings-configure-with-console.md). Untuk contoh fungsi Lambda, lihat. [Kembalikan media biner dari integrasi proxy Lambda di API Gateway](lambda-proxy-binary-media.md)
Jika output fungsi dari format yang berbeda, API Gateway mengembalikan respon `502 Bad Gateway` kesalahan.
Untuk mengembalikan respons dalam fungsi Lambda di Node.js, Anda dapat menggunakan perintah seperti berikut:
+ Untuk mengembalikan hasil yang sukses, hubungi`callback(null, {"statusCode": 200, "body": "results"})`.
+ Untuk melempar pengecualian, panggil`callback(new Error('internal server error'))`.
+ Untuk kesalahan sisi klien (jika, misalnya, parameter yang diperlukan tidak ada), Anda dapat memanggil `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` untuk mengembalikan kesalahan tanpa melempar pengecualian.
Dalam `async` fungsi Lambda di Node.js, sintaks yang setara adalah:
+ Untuk mengembalikan hasil yang sukses, hubungi`return {"statusCode": 200, "body": "results"}`.
+ Untuk melempar pengecualian, panggil`throw new Error("internal server error")`.
+ Untuk kesalahan sisi klien (jika, misalnya, parameter yang diperlukan tidak ada), Anda dapat memanggil `return {"statusCode": 400, "body": "Missing parameters of ..."}` untuk mengembalikan kesalahan tanpa melempar pengecualian.
# Siapkan integrasi proxy Lambda untuk API Gateway menggunakan AWS CLI
Di bagian ini, kami menunjukkan cara menyiapkan API dengan integrasi proxy Lambda menggunakan. AWS CLI Untuk petunjuk mendetail tentang penggunaan konsol API Gateway guna mengonfigurasi sumber daya proxy dengan integrasi proxy Lambda, lihat. [Tutorial: Buat REST API dengan integrasi proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md)
Sebagai contoh, kami menggunakan contoh fungsi Lambda berikut sebagai backend API:
```
export const handler = async(event, context) => {
console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}
res.body = "Hello, " + greeter + "!";
return res
};
```
Membandingkan ini dengan pengaturan integrasi kustom Lambda di[Siapkan integrasi kustom Lambda di API Gateway](set-up-lambda-custom-integrations.md), input ke fungsi Lambda ini dapat dinyatakan dalam parameter permintaan dan isi. Anda memiliki lebih banyak garis lintang untuk memungkinkan klien meneruskan data input yang sama. Di sini, klien dapat meneruskan nama penyambut sebagai parameter string kueri, header, atau properti tubuh. Fungsi ini juga dapat mendukung integrasi kustom Lambda. Penyiapan API lebih sederhana. Anda tidak mengonfigurasi respons metode atau respons integrasi sama sekali.
**Untuk mengatur integrasi proxy Lambda menggunakan AWS CLI**
1. Gunakan [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)perintah berikut untuk membuat API:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Outputnya akan terlihat seperti berikut:
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
Anda menggunakan API `id` (`te6si5ach7`) dan `rootResourceId` (`krznpq9xpg`) di seluruh contoh ini.
1. [Gunakan perintah [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) berikut untuk membuat API Gateway Resource dari:](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting`
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
Outputnya akan terlihat seperti berikut:
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Anda menggunakan `id` nilai `{proxy+}` sumber daya (`2jf6xt`) untuk membuat metode pada `/{proxy+}` sumber daya di langkah berikutnya.
1. Gunakan [put-metode](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut untuk membuat permintaan `ANY` metode: `ANY /{proxy+}`
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
Outputnya akan terlihat seperti berikut:
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
Metode API ini memungkinkan klien untuk menerima atau mengirim salam dari fungsi Lambda di backend.
1. Gunakan perintah [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) berikut untuk mengatur integrasi `ANY /{proxy+}` metode dengan fungsi Lambda, bernama. `HelloWorld` Fungsi ini menanggapi permintaan dengan pesan`"Hello, {name}!"`, jika `greeter` parameter disediakan, atau`"Hello, World!"`, jika parameter string query tidak diatur.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
**penting**
Untuk integrasi Lambda, Anda harus menggunakan metode HTTP `POST` untuk permintaan integrasi, sesuai dengan [spesifikasi tindakan layanan Lambda untuk pemanggilan](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) fungsi. Peran IAM `apigAwsProxyRole` harus memiliki kebijakan yang memungkinkan `apigateway` layanan untuk menjalankan fungsi Lambda. Untuk informasi selengkapnya tentang izin IAM, lihat. [Model izin API Gateway untuk menjalankan API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api)
Outputnya akan terlihat seperti berikut:
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations",
"httpMethod": "POST",
"cacheNamespace": "vvom7n",
"credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole",
"type": "AWS_PROXY"
}
```
Alih-alih menyediakan peran IAM`credentials`, Anda dapat menggunakan perintah [add-permission untuk menambahkan izin berbasis](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) sumber daya. Inilah yang dilakukan konsol API Gateway.
1. Gunakan perintah [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) berikut untuk menyebarkan API ke sebuah panggung: `test`
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Uji API menggunakan perintah cURL berikut di terminal.
Memanggil API dengan parameter string kueri`?greeter=jane`:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane'
```
Memanggil API dengan parameter header`greeter:jane`:
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-H 'greeter: jane'
```
Memanggil API dengan badan`{"greeter":"jane"}`:
```
curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
Dalam semua kasus, outputnya adalah respons 200 dengan badan respons berikut:
```
Hello, jane!
```
# Siapkan sumber daya proxy dengan integrasi proxy Lambda dengan definisi OpenAPI
Untuk menyiapkan sumber daya proxy dengan tipe integrasi proxy Lambda, buat sumber daya API dengan parameter jalur serakah (misalnya,`/parent/{proxy+}`) dan integrasikan sumber daya ini dengan backend fungsi Lambda (misalnya,) pada metode. `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource` `ANY` Parameter jalur serakah harus berada di akhir jalur sumber daya API. Seperti sumber daya non-proxy, Anda dapat mengatur sumber daya proxy dengan menggunakan konsol API Gateway, mengimpor file definisi OpenAPI, atau memanggil API REST API Gateway API secara langsung.
File definisi API OpenAPI berikut menunjukkan contoh API dengan sumber daya proxy yang terintegrasi dengan fungsi Lambda bernama. `SimpleLambda4ProxyResource`
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"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"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/testStage"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"basePath": "/testStage",
"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"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
}
}
```
------
Dalam integrasi proxy Lambda, pada waktu berjalan, API Gateway memetakan permintaan masuk ke `event` parameter input fungsi Lambda. Input mencakup metode permintaan, jalur, header, parameter string kueri apa pun, payload apa pun, konteks terkait, dan variabel tahap yang ditentukan. Format input dijelaskan dalam[Format input fungsi Lambda untuk integrasi proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Agar API Gateway berhasil memetakan output Lambda ke respons HTTP, fungsi Lambda harus menampilkan hasil dalam format yang dijelaskan dalam. [Format output dari fungsi Lambda untuk integrasi proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format)
Dalam integrasi proxy Lambda dari sumber daya proxy melalui `ANY` metode, fungsi Lambda backend tunggal berfungsi sebagai event handler untuk semua permintaan melalui sumber daya proxy. Misalnya, untuk mencatat pola lalu lintas, Anda dapat meminta perangkat seluler mengirim informasi lokasi negara bagian, kota, jalan, dan bangunannya dengan mengirimkan permintaan `/state/city/street/house` di jalur URL untuk sumber daya proxy. Fungsi backend Lambda kemudian dapat mengurai jalur URL dan menyisipkan tupel lokasi ke dalam tabel DynamoDB.
# Siapkan integrasi kustom Lambda di API Gateway
Untuk menunjukkan cara mengatur integrasi kustom Lambda, atau non-proxy, kami membuat API Gateway API untuk mengekspos `GET /greeting?greeter={name}` metode untuk menjalankan fungsi Lambda. Gunakan salah satu contoh fungsi Lambda berikut untuk API Anda.
Gunakan salah satu contoh fungsi Lambda berikut:
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;
// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';
// Log the greeting to CloudWatch
console.log('Hello: ', greeting);
// Return a greeting to the caller
return greeting;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
}
if event['greeter'] == "":
res['body'] = "Hello, World"
elif (event['greeter']):
res['body'] = "Hello, " + event['greeter'] + "!"
else:
raise Exception('Missing the required greeter parameter.')
return res
```
------
Fungsi merespons dengan pesan `"Hello, {name}!"` jika nilai `greeter` parameter adalah string yang tidak kosong. Ia mengembalikan pesan `"Hello, World!"` jika `greeter` nilai adalah string kosong. Fungsi mengembalikan pesan kesalahan `"Missing the required greeter parameter."` jika parameter penyambut tidak diatur dalam permintaan masuk. Kami menamai fungsinya`HelloWorld`.
Anda dapat membuatnya di konsol Lambda atau dengan menggunakan. AWS CLI Pada bagian ini, kami mereferensikan fungsi ini menggunakan ARN berikut:
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
Dengan fungsi Lambda diatur di backend, lanjutkan untuk mengatur API.
**Untuk mengatur integrasi kustom Lambda menggunakan AWS CLI**
1. Gunakan [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)perintah berikut untuk membuat API:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Outputnya akan terlihat seperti berikut:
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
Anda menggunakan API `id` (`te6si5ach7`) dan `rootResourceId` (`krznpq9xpg`) di seluruh contoh ini.
1. [Gunakan perintah [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) berikut untuk membuat API Gateway Resource dari:](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting`
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
Outputnya akan terlihat seperti berikut:
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Anda menggunakan `id` nilai `greeting` sumber daya (`2jf6xt`) untuk membuat metode pada `/greeting` sumber daya di langkah berikutnya.
1. Gunakan perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut untuk membuat permintaan metode API dari: `GET /greeting?greeter={name}`
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false
```
Outputnya akan terlihat seperti berikut:
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
Metode API ini memungkinkan klien untuk menerima salam dari fungsi Lambda di backend. `greeter`Parameternya opsional karena backend harus menangani penelepon anonim atau penelepon yang diidentifikasi sendiri.
1. Gunakan [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)perintah berikut untuk mengatur `200 OK` respons terhadap permintaan metode`GET /greeting?greeter={name}`:
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. Gunakan perintah [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) berikut untuk mengatur integrasi `GET /greeting?greeter={name}` metode dengan fungsi Lambda, bernama. `HelloWorld` Fungsi menanggapi permintaan dengan pesan`"Hello, {name}!"`, jika `greeter` parameter disediakan, atau`"Hello, World!"`, jika parameter string query tidak diatur.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
Template pemetaan yang disediakan di sini menerjemahkan parameter string `greeter` kueri ke `greeter` properti payload JSON. Ini diperlukan karena input ke fungsi Lambda harus diekspresikan dalam tubuh.
**penting**
Untuk integrasi Lambda, Anda harus menggunakan metode HTTP `POST` untuk permintaan integrasi, sesuai dengan [spesifikasi tindakan layanan Lambda untuk pemanggilan](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) fungsi. `uri`Parameternya adalah ARN dari tindakan pemanggilan fungsi.
Outputnya akan terlihat seperti berikut:
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"
},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}
```
Peran IAM `apigAwsProxyRole` harus memiliki kebijakan yang memungkinkan `apigateway` layanan untuk menjalankan fungsi Lambda. Alih-alih menyediakan peran IAM`credentials`, Anda dapat memanggil perintah [add-permission untuk menambahkan izin berbasis](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) sumber daya. Beginilah cara konsol API Gateway menambahkan izin ini.
1. Gunakan [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)perintah berikut untuk mengatur respons integrasi untuk meneruskan output fungsi Lambda ke klien sebagai respons `200 OK` metode:
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
Dengan mengatur pola pilihan ke string kosong, `200 OK` responsnya adalah default.
Outputnya akan terlihat seperti berikut:
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. Gunakan perintah [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) berikut untuk menyebarkan API ke sebuah panggung: `test`
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Uji API menggunakan perintah cURL berikut di terminal:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'
```
# Siapkan pemanggilan asinkron dari fungsi Lambda backend
Dalam integrasi Lambda non-proxy (kustom), fungsi Lambda backend dipanggil secara sinkron secara default. Ini adalah perilaku yang diinginkan untuk sebagian besar operasi REST API. Beberapa aplikasi, bagaimanapun, memerlukan pekerjaan yang harus dilakukan secara asinkron (sebagai operasi batch atau operasi latensi panjang), biasanya oleh komponen backend terpisah. Dalam hal ini, fungsi Lambda backend dipanggil secara asinkron, dan metode REST API front-end tidak mengembalikan hasilnya.
[Anda dapat mengonfigurasi fungsi Lambda agar integrasi non-proxy Lambda dipanggil secara asinkron dengan menentukan sebagai jenis pemanggilan Lambda. `'Event'`](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html) Ini dilakukan sebagai berikut:
## Konfigurasikan pemanggilan asinkron Lambda di konsol API Gateway
Agar semua pemanggilan menjadi asinkron:
+ Dalam **permintaan Integrasi**, tambahkan `X-Amz-Invocation-Type` header dengan nilai statis`'Event'`.
Bagi klien untuk memutuskan apakah pemanggilan asinkron atau sinkron:
1. Dalam **permintaan Metode**, tambahkan `InvocationType` header.
1. Dalam **permintaan Integrasi** tambahkan `X-Amz-Invocation-Type` header dengan ekspresi pemetaan. `method.request.header.InvocationType`
1. Klien dapat menyertakan `InvocationType: Event` header dalam permintaan API untuk pemanggilan asinkron atau untuk pemanggilan sinkron. `InvocationType: RequestResponse`
## Konfigurasikan pemanggilan asinkron Lambda menggunakan OpenAPI
Agar semua pemanggilan menjadi asinkron:
+ Tambahkan `X-Amz-Invocation-Type` header ke **x-amazon-apigateway-integration**bagian.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "'Event'"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
Bagi klien untuk memutuskan apakah pemanggilan asinkron atau sinkron:
1. Tambahkan header berikut pada [OpenAPI Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) Object.
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. Tambahkan `X-Amz-Invocation-Type` header ke **x-amazon-apigateway-integration**bagian.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
1. Klien dapat menyertakan `InvocationType: Event` header dalam permintaan API untuk pemanggilan asinkron atau untuk pemanggilan sinkron. `InvocationType: RequestResponse`
## Konfigurasikan pemanggilan asinkron Lambda menggunakan CloudFormation
CloudFormation Template berikut menunjukkan cara mengkonfigurasi `AWS::ApiGateway::Method` untuk pemanggilan asinkron.
Agar semua pemanggilan menjadi asinkron:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: "'Event'"
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Bagi klien untuk memutuskan apakah pemanggilan asinkron atau sinkron:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
RequestParameters:
method.request.header.InvocationType: false
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Klien dapat menyertakan `InvocationType: Event` header dalam permintaan API untuk pemanggilan asinkron atau untuk pemanggilan sinkron. `InvocationType: RequestResponse`
# Menangani kesalahan Lambda di API Gateway
Untuk integrasi kustom Lambda, Anda harus memetakan kesalahan yang dikembalikan oleh Lambda dalam respons integrasi terhadap respons kesalahan HTTP standar untuk klien Anda. Jika tidak, kesalahan Lambda dikembalikan sebagai `200 OK` respons secara default dan hasilnya tidak intuitif untuk pengguna API Anda.
Ada dua jenis kesalahan yang dapat dikembalikan Lambda: kesalahan standar dan kesalahan khusus. Di API Anda, Anda harus menangani ini secara berbeda.
Dengan integrasi proxy Lambda, Lambda diperlukan untuk mengembalikan output dari format berikut:
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
Dalam output ini, `statusCode` biasanya `4XX` untuk kesalahan klien dan `5XX` untuk kesalahan server. API Gateway menangani kesalahan ini dengan memetakan kesalahan Lambda ke respons kesalahan HTTP, sesuai dengan yang ditentukan. `statusCode` Agar API Gateway dapat meneruskan jenis kesalahan (misalnya,`InvalidParameterException`), sebagai bagian dari respons terhadap klien, fungsi Lambda harus menyertakan header (misalnya,`"X-Amzn-ErrorType":"InvalidParameterException"`) di `headers` properti.
**Topics**
+ [Menangani kesalahan Lambda standar di API Gateway](#handle-standard-errors-in-lambda-integration)
+ [Menangani kesalahan Lambda khusus di API Gateway](#handle-custom-errors-in-lambda-integration)
## Menangani kesalahan Lambda standar di API Gateway
AWS Lambda Kesalahan standar memiliki format berikut:
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
Di sini, `errorMessage` adalah ekspresi string dari kesalahan. `errorType`Ini adalah kesalahan atau tipe pengecualian yang bergantung pada bahasa. `stackTrace`Ini adalah daftar ekspresi string yang menunjukkan jejak tumpukan yang mengarah ke terjadinya kesalahan.
Misalnya, perhatikan fungsi Lambda berikut JavaScript (Node.js).
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
Fungsi ini mengembalikan kesalahan Lambda standar berikut, yang berisi `Malformed input ...` sebagai pesan kesalahan:
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
Demikian pula, pertimbangkan fungsi Lambda Python berikut, yang memunculkan pesan kesalahan `Exception` yang sama. `Malformed input ...`
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
Fungsi ini mengembalikan kesalahan Lambda standar berikut:
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
Perhatikan bahwa nilai `errorType` dan `stackTrace` properti bergantung pada bahasa. Kesalahan standar juga berlaku untuk objek kesalahan apa pun yang merupakan perpanjangan dari `Error` objek atau subkelas `Exception` kelas.
Untuk memetakan kesalahan Lambda standar ke respons metode, Anda harus terlebih dahulu memutuskan kode status HTTP untuk kesalahan Lambda yang diberikan. Anda kemudian menetapkan pola ekspresi reguler pada `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` properti yang [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)terkait dengan kode status HTTP yang diberikan. Di konsol API Gateway, ini `selectionPattern` dilambangkan sebagai **regex kesalahan Lambda** di bagian **Respons Integrasi, di bawah setiap respons integrasi**.
**catatan**
API Gateway menggunakan regex gaya pola Java untuk pemetaan respons. Untuk informasi selengkapnya, lihat [Pola](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) dalam Oracle dokumentasi.
Misalnya, gunakan yang berikut ini [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)untuk menyiapkan `selectionPattern` ekspresi baru:
```
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
```
Pastikan bahwa Anda juga mengatur kode kesalahan yang sesuai (`400`) pada [respon metode](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Jika tidak, API Gateway akan menampilkan respons kesalahan konfigurasi yang tidak valid saat runtime.
**catatan**
Saat runtime, API Gateway mencocokkan kesalahan `errorMessage` Lambda dengan pola ekspresi reguler pada `selectionPattern` properti. Jika ada kecocokan, API Gateway mengembalikan kesalahan Lambda sebagai respons HTTP dari kode status HTTP yang sesuai. Jika tidak ada kecocokan, API Gateway mengembalikan kesalahan sebagai respons default atau melempar pengecualian konfigurasi yang tidak valid jika tidak ada respons default yang dikonfigurasi.
Menyetel `selectionPattern` nilai `.*` untuk respons yang diberikan berarti mengatur ulang respons ini sebagai respons default. Ini karena pola pemilihan seperti itu akan cocok dengan semua pesan kesalahan, termasuk null, yaitu, pesan kesalahan yang tidak ditentukan. Pemetaan yang dihasilkan mengesampingkan pemetaan default. Jika Anda menggunakan `.+` sebagai pola pemilihan untuk memfilter respons, itu mungkin tidak cocok dengan respons yang mengandung ketahuilah bahwa itu mungkin tidak cocok dengan respons yang berisi karakter baris baru ('`\n`).
Untuk memperbarui `selectionPattern` nilai yang ada menggunakan AWS CLI, panggil [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)operasi untuk mengganti nilai `/selectionPattern` jalur dengan ekspresi regex yang ditentukan dari pola. `Malformed*`
Untuk mengatur `selectionPattern` ekspresi menggunakan konsol API Gateway, masukkan ekspresi di kotak teks **regex kesalahan Lambda** saat menyiapkan atau memperbarui respons integrasi kode status HTTP tertentu.
## Menangani kesalahan Lambda khusus di API Gateway
Alih-alih kesalahan standar yang dijelaskan di bagian sebelumnya, AWS Lambda memungkinkan Anda mengembalikan objek kesalahan kustom sebagai string JSON. Kesalahan dapat berupa objek JSON yang valid. Misalnya, fungsi Lambda berikut JavaScript (Node.js) mengembalikan kesalahan kustom:
```
export const handler = (event, context, callback) => {
...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};
```
Anda harus mengubah `myErrorObj` objek menjadi string JSON sebelum memanggil `callback` untuk keluar dari fungsi. Jika tidak, `myErrorObj` dikembalikan sebagai string dari`"[object Object]"`. Saat metode API Anda terintegrasi dengan fungsi Lambda sebelumnya, API Gateway menerima respons integrasi dengan muatan berikut:
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
Seperti halnya respons integrasi apa pun, Anda dapat melewati respons kesalahan ini apa adanya terhadap respons metode. Atau Anda dapat memiliki template pemetaan untuk mengubah payload menjadi format yang berbeda. Misalnya, pertimbangkan template pemetaan tubuh berikut untuk respons metode kode status`500`:
```
{
errorMessage: $input.path('$.errorMessage');
}
```
Template ini menerjemahkan badan respons integrasi yang berisi string JSON kesalahan kustom ke badan respons metode berikut. Badan respons metode ini berisi objek JSON kesalahan kustom:
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
Bergantung pada persyaratan API Anda, Anda mungkin perlu meneruskan beberapa atau semua properti kesalahan kustom sebagai parameter header respons metode. Anda dapat mencapai ini dengan menerapkan pemetaan kesalahan kustom dari badan respons integrasi ke header respons metode.
Misalnya, ekstensi OpenAPI berikut mendefinisikan pemetaan dari`errorMessage.errorType`,,, dan `errorMessage.trace` properti ke `errorMessage.httpStatus``errorMessage.trace.function`,,, dan `error_type` header `error_status``error_trace_function`, masing-masing. `error_trace`
```
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
"method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type": "integration.response.body.errorMessage.errorType",
"method.response.header.error_trace": "integration.response.body.errorMessage.trace"
},
...
}
}
}
```
Saat runtime, API Gateway melakukan deserialisasi `integration.response.body` parameter saat melakukan pemetaan header. Namun, deserialisasi ini hanya berlaku untuk body-to-header pemetaan untuk respons kesalahan khusus Lambda dan tidak berlaku untuk pemetaan yang menggunakan. body-to-body `$input.body` Dengan pemetaan custom-error-body-to -header ini, klien menerima header berikut sebagai bagian dari respons metode, asalkan,, `error_status` `error_trace``error_trace_function`, dan `error_type` header dideklarasikan dalam permintaan metode.
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
`errorMessage.trace`Properti badan respons integrasi adalah properti yang kompleks. Hal ini dipetakan ke `error_trace` header sebagai string JSON.
# Integrasi HTTP untuk REST APIs 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.
**Topics**
+ [Siapkan integrasi proxy HTTP di API Gateway](#api-gateway-set-up-http-proxy-integration-on-proxy-resource)
+ [Siapkan integrasi kustom HTTP di API Gateway](#set-up-http-custom-integrations)
## 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, lihat[Tutorial: Membuat REST API dengan integrasi proxy HTTP](api-gateway-create-api-as-simple-proxy-for-http.md).
File definisi OpenAPI berikut menunjukkan contoh API dengan sumber daya proxy yang terintegrasi dengan situs web. [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)
------
#### [ 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-all`ANY`. 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, juga dikenal sebagai integrasi non-proxy, Anda memiliki kontrol lebih besar atas data mana yang harus dilewatkan 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters) pada sumber daya Metode.](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) pada sumber daya Integrasi [yang sesuai](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) untuk menentukan pemetaan. parameter-to-parameter Anda juga mengatur properti [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#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](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) pada sumber daya. [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 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. Anda kemudian mengatur [SelectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) untuk memilih respons integrasi berdasarkan respons dari backend. Untuk integrasi HTTP non-proxy, ini adalah ekspresi reguler. Misalnya, untuk memetakan semua kode status respons HTTP 2xx dari titik akhir HTTP ke pemetaan keluaran ini, gunakan. `2\d{2}`
**catatan**
API Gateway menggunakan regex gaya pola Java untuk pemetaan respons. Untuk informasi selengkapnya, lihat [Pola](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) dalam Oracle dokumentasi.
Kemudian, sebagai bagian dari pengaturan respons integrasi, Anda mengatur properti [ResponseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) pada sumber daya yang [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)sesuai untuk menentukan pemetaan. parameter-to-parameter Anda juga mengatur peta [ResponseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#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, lihat[Transformasi data untuk REST APIs di API Gateway](rest-api-data-transformations.md).
# Streaming respons integrasi untuk integrasi proxy Anda di API Gateway
Anda dapat mengonfigurasi integrasi proksi untuk mengontrol cara API Gateway menghasilkan respons integrasi Anda. Secara default, API Gateway menunggu untuk menerima respons lengkap sebelum memulai transmisi. Namun, jika Anda menyetel mode transfer respons integrasi ke`STREAM`, API Gateway tidak menunggu respons dihitung sepenuhnya sebelum mengirimkannya ke klien. Aliran respons berfungsi untuk semua jenis titik akhir API REST.
Gunakan streaming respons untuk kasus penggunaan berikut:
+ Turunkan time-to-first-byte (TTFB) untuk aplikasi AI generatif seperti chatbots.
+ Streaming file gambar, video, atau musik besar tanpa menggunakan URL S3 yang telah ditandatangani sebelumnya.
+ Lakukan operasi yang berjalan lama sambil melaporkan kemajuan tambahan seperti peristiwa terkirim server (SSE).
+ Melebihi batas muatan respons 10 MB API Gateway.
+ Melebihi batas waktu tunggu 29 detik API Gateway tanpa meminta peningkatan batas batas waktu integrasi.
+ Menerima payload biner tanpa mengkonfigurasi jenis media biner.
## Pertimbangan untuk streaming payload respons
Pertimbangan berikut dapat memengaruhi penggunaan streaming payload respons Anda:
+ Anda hanya dapat menggunakan streaming payload respons untuk `HTTP_PROXY` atau jenis `AWS_PROXY` integrasi. Ini termasuk integrasi proxy Lambda dan integrasi pribadi yang menggunakan integrasi. `HTTP_PROXY`
+ Pengaturan mode transfer default adalah`BUFFERED`. Untuk menggunakan streaming respons, Anda harus mengubah mode transfer respons ke`STREAM`.
+ Streaming respons hanya didukung untuk REST APIs.
+ Permintaan streaming tidak didukung.
+ Anda dapat melakukan streaming respons Anda hingga 15 menit.
+ Streaming Anda tunduk pada batas waktu idle. Untuk titik akhir Regional atau pribadi, batas waktu adalah 5 menit. Untuk titik akhir yang dioptimalkan tepi, batas waktu adalah 30 detik.
+ Jika Anda menggunakan streaming respons untuk REST API Regional dengan CloudFront distribusi Anda sendiri, Anda dapat mencapai waktu idle lebih dari 30 detik dengan meningkatkan batas waktu respons distribusi Anda CloudFront. Untuk informasi selengkapnya, lihat [Batas waktu respons.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout)
+ Saat mode transfer respons disetel ke`STREAM`, API Gateway tidak dapat mendukung fitur yang memerlukan buffering seluruh respons integrasi. Karena itu, fitur berikut tidak didukung dengan streaming respons:
+ Caching titik akhir
+ Pengkodean konten. Jika Anda ingin mengompres respons integrasi Anda, lakukan ini dalam integrasi Anda.
+ Transformasi respons dengan VTL
+ Dalam setiap respons streaming, muatan respons 10MB pertama tidak tunduk pada batasan bandwidth apa pun. Data payload respons melebihi 10MB dibatasi hingga 2MB/s.
+ Ketika koneksi antara klien dan API Gateway atau antara API Gateway dan Lambda ditutup karena batas waktu, fungsi Lambda mungkin terus dijalankan. Untuk informasi selengkapnya, lihat [Mengonfigurasi batas waktu fungsi Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html).
+ Streaming respons menimbulkan biaya. Untuk informasi selengkapnya, lihat [Harga API Gateway](https://aws.amazon.com/api-gateway/pricing/).
# Siapkan integrasi proxy HTTP dengan streaming respons payload di API Gateway
Saat mengatur streaming payload respons, Anda menentukan mode transfer respons dalam permintaan integrasi metode Anda. Anda mengonfigurasi setelan ini dalam permintaan integrasi untuk mengontrol perilaku API Gateway sebelum dan selama respons integrasi. Saat Anda menggunakan streaming respons, Anda dapat mengonfigurasi batas waktu integrasi hingga 15 menit.
Saat Anda menggunakan streaming respons payload dengan `HTTP_PROXY` integrasi, API Gateway tidak akan mengirim kode status respons HTTP atau header respons HTTP apa pun hingga sepenuhnya menerima semua header.
## Buat integrasi proxy HTTP dengan streaming respons payload
Prosedur berikut menunjukkan cara mengimpor API baru dengan `responseTransferMode` set ke`STREAM`. Jika Anda memiliki API integrasi yang ada dan ingin memodifikasinya`responseTransferMode`, lihat[Perbarui mode transfer respons untuk integrasi proxy HTTP](#response-streaming-http-update).
------
#### [ Konsol Manajemen AWS ]
**Untuk membuat integrasi proxy HTTP dengan streaming respons payload**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih **Buat sumber daya**.
1. Untuk **Nama sumber daya**, masukkan **streaming**.
1. Pilih **Buat sumber daya**.
1. Dengan sumber daya **/streaming** yang dipilih, pilih **Create method**.
1. Untuk **jenis Metode**, pilih **APAPUN**.
1. Untuk **jenis Integrasi**, pilih **HTTP**.
1. Pilih **integrasi proxy HTTP**.
1. Untuk **mode transfer Respons**, pilih **Streaming**.
1. Untuk **metode HTTP**, pilih metode.
1. Untuk **URL Endpoint**, masukkan titik akhir integrasi. Pastikan Anda memilih titik akhir yang menghasilkan muatan besar untuk dialirkan kembali kepada Anda.
1. Pilih **metode Buat**.
Setelah Anda membuat metode, terapkan API Anda.
**Untuk men-deploy API Anda**
1. Pilih **Deploy API**.
1. Untuk **Stage**, pilih **New stage**.
1. Untuk **nama Panggung**, masukkan**prod**.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Pilih **Deploy**.
------
#### [ AWS CLI ]
**Untuk membuat API baru dengan streaming respons payload**
1. Salin file Open API berikut, lalu simpan sebagai`ResponseStreamDemoSwagger.yaml`. Dalam file ini, `responseTransferMode` diatur ke`STREAM`. Titik akhir integrasi diatur ke`https://example.com`, tetapi kami menyarankan Anda memodifikasinya ke titik akhir yang menghasilkan muatan besar untuk dialirkan kembali kepada Anda.
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/streaming:
get:
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "https://example.com"
type: "http_proxy"
timeoutInMillis: 900000
responseTransferMode: "STREAM"
```
1. Gunakan `import-rest-api` perintah berikut untuk mengimpor definisi OpenAPI Anda:
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. Gunakan `create-deployment` perintah berikut untuk menerapkan API baru Anda ke panggung:
```
aws apigateway create-deployment \
--rest-api-id a1b2c3 \
--stage-name prod \
--region us-west-1
```
------
## Perbarui mode transfer respons untuk integrasi proxy HTTP
Prosedur berikut menunjukkan cara memperbarui mode transfer respons untuk integrasi proxy HTTP.
------
#### [ Konsol Manajemen AWS ]
**Untuk memperbarui mode transfer respons untuk integrasi proxy HTTP**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
1. Pada tab **Permintaan integrasi**, di bawah **Pengaturan permintaan integrasi**, pilih **Edit**.
1. Untuk **mode transfer Respons**, pilih **Streaming**.
1. Pilih **Simpan**.
Setelah memperbarui metode, terapkan API Anda.
**Untuk men-deploy API Anda**
1. Pilih **Deploy API**.
1. Untuk **Stage**, pilih **New stage**.
1. Untuk **nama Panggung**, masukkan**prod**.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Pilih **Deploy**.
------
#### [ AWS CLI ]
`update-integration`Perintah berikut memperbarui mode transfer integrasi dari `BUFFERED` ke`STREAM`. Untuk yang ada APIs, mode transfer respons untuk semua integrasi diatur ke`BUFFERED`.
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method GET \
--patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \
--region us-west-1
```
Anda perlu menerapkan ulang API agar perubahan diterapkan. Jika Anda menyesuaikan batas waktu integrasi, nilai batas waktu ini akan dihapus, karena API Gateway mengalirkan respons Anda hingga 5 menit.
`update-integration`Perintah berikut memperbarui mode transfer integrasi dari `STREAM` ke`BUFFERED`:
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method GET \
--patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \
--region us-west-1
```
Anda perlu menerapkan ulang API agar perubahan diterapkan.
------
# Siapkan integrasi proxy Lambda dengan streaming respons payload di API Gateway
Anda dapat melakukan streaming respons fungsi Lambda untuk meningkatkan kinerja time to first byte (TTFB) dan mengirim sebagian tanggapan kembali ke klien saat tersedia. API Gateway mengharuskan Anda menggunakan API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)Lambda untuk menjalankan fungsi Lambda Anda. API Gateway meneruskan objek peristiwa ke fungsi Lambda. Fungsi backend Lambda mem-parsing data permintaan yang masuk untuk menentukan respons yang dikembalikan. Agar API Gateway dapat melakukan streaming output Lambda, fungsi Lambda harus menampilkan [format](#response-transfer-mode-lambda-format) yang diperlukan oleh API Gateway.
## Perbedaan integrasi proxy Lambda antara mode transfer respons streaming dan buffer
Daftar berikut menjelaskan perbedaan antara integrasi proxy Lambda dan integrasi proxy Lambda untuk streaming respons:
+ API Gateway menggunakan [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)API untuk menjalankan integrasi proxy Lambda untuk streaming respons. Ini menghasilkan URI yang berbeda, yaitu sebagai berikut:
```
arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations
```
ARN ini menggunakan tanggal yang berbeda untuk versi API dan tindakan layanan yang berbeda dibandingkan dengan integrasi proxy Lambda.
Jika Anda menggunakan konsol API Gateway untuk streaming respons, konsol menggunakan URI yang benar untuk Anda.
+ Dalam integrasi proxy Lambda, API Gateway mengirimkan respons ke klien hanya setelah menerima respons penuh dari Lambda. Dalam integrasi proxy Lambda untuk streaming respons, API Gateway memulai aliran muatan setelah menerima metadata dan pembatas yang valid dari Lambda.
+ Integrasi proxy Lambda untuk streaming respons menggunakan format input yang sama dengan integrasi proxy, tetapi memerlukan format output yang berbeda.
## Format integrasi proxy Lambda untuk streaming respons
Saat API Gateway memanggil fungsi Lambda dengan streaming respons, format input sama dengan format input fungsi Lambda untuk integrasi proxy. Untuk informasi selengkapnya, lihat [Format input fungsi Lambda untuk integrasi proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format).
Saat Lambda mengalirkan respons ke API Gateway, respons harus mematuhi format berikut. Format ini menggunakan pembatas untuk memisahkan metadata JSON dan muatan mentah. Dalam hal ini, data payload dialirkan saat ditransmisikan oleh fungsi Lambda streaming Anda:
```
{
"headers": {"headerName": "headerValue", ...},
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"cookies" : ["cookie1", "cookie2"],
"statusCode": httpStatusCode
}PAYLOAD1 | PAYLOAD2 | PAYLOAD3
```
Dalam output:
+ `statusCode`Tombol `headers``multiValueHeaders`,`cookies`, dan dapat tidak ditentukan jika tidak ada header respons tambahan yang akan dikembalikan.
+ `headers`Kuncinya hanya dapat berisi header nilai tunggal.
+ Output mengharapkan header berisi salah satu atau`Transfer-Encoding: chunked`. `Content-length: number` Jika fungsi Anda tidak mengembalikan salah satu header ini, API Gateway akan ditambahkan `Transfer-Encoding: chunked` ke header respons.
+ `multiValueHeaders`Kuncinya dapat berisi header multi-nilai serta header nilai tunggal. Anda dapat menggunakan `multiValueHeaders` kunci untuk menentukan semua header tambahan Anda, termasuk yang bernilai tunggal.
+ Jika Anda menentukan nilai untuk keduanya `headers` dan`multiValueHeaders`, API Gateway menggabungkannya ke dalam satu daftar. Jika pasangan kunci-nilai yang sama ditentukan di keduanya, hanya nilai dari yang `multiValueHeaders` akan muncul dalam daftar gabungan.
+ Metadata harus JSON yang valid. Hanya`headers`,`multiValueHeaders`, `cookies` dan `statusCode` kuncinya didukung.
+ Anda harus memberikan pembatas setelah metadata JSON. Pembatas harus 8 byte nol dan harus muncul dalam 16KB pertama data aliran.
+ API Gateway tidak memerlukan format khusus untuk payload respons metode.
Jika Anda menggunakan URL fungsi untuk melakukan streaming fungsi Lambda Anda, Anda harus memodifikasi input dan output fungsi Lambda Anda untuk memenuhi persyaratan ini.
Jika output fungsi Lambda Anda tidak mematuhi persyaratan format ini, API Gateway mungkin masih menjalankan fungsi Lambda Anda. Tabel berikut menunjukkan kombinasi setelan permintaan integrasi API dan kode fungsi Lambda yang didukung oleh API Gateway. Ini termasuk kombinasi yang didukung untuk mode transfer respons buffer.
| Mode transfer respons | Kode fungsi mematuhi format yang diperlukan | Lambda memanggil API | Didukung oleh API Gateway |
| --- | --- | --- | --- |
| Streaming | Ya | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Ya. API Gateway mengalirkan respons Anda. |
| Streaming | Tidak | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Tidak. API Gateway memanggil fungsi Lambda Anda dan mengembalikan respons kesalahan 500. |
| Streaming | Ya | [Memohon](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Tidak. API Gateway tidak mendukung konfigurasi integrasi ini. |
| Streaming | Tidak | [Memohon](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Tidak. API Gateway tidak mendukung konfigurasi integrasi ini. |
| Buffer | Ya | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Tidak. API Gateway tidak mendukung konfigurasi integrasi ini. |
| Buffer | Tidak | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Tidak. API Gateway tidak mendukung konfigurasi integrasi ini. |
| Buffer | Ya | [Memohon](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway mengembalikan header HTTP dan kode status tetapi bukan badan respons. |
| Buffer | Tidak | [Memohon](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Ya. Ini adalah integrasi proxy Lambda. Untuk informasi selengkapnya, lihat Integrasi [proxy Lambda](set-up-lambda-proxy-integrations.md). |
# Konfigurasikan integrasi proxy Lambda dengan streaming respons payload di API Gateway
Saat mengatur streaming payload respons, Anda menentukan mode transfer dalam permintaan integrasi sumber daya Anda. Anda mengonfigurasi setelan ini dalam permintaan integrasi untuk mengontrol perilaku API Gateway sebelum dan selama respons integrasi.
## Contoh fungsi Lambda untuk streaming respons
Fungsi Lambda Anda harus mematuhi. [Format integrasi proxy Lambda untuk streaming respons](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format) Kami menyarankan Anda menggunakan salah satu dari tiga contoh fungsi Lambda untuk menguji streaming respons. Saat Anda membuat fungsi Lambda, pastikan untuk melakukan hal berikut:
+ Berikan batas waktu yang memadai untuk fungsi Anda. Kami menyarankan Anda mengonfigurasi batas waktu minimal 1 menit untuk mempelajari tentang streaming respons. Saat Anda membuat sumber daya produksi, pastikan batas waktu fungsi Lambda Anda mencakup siklus permintaan penuh. Untuk informasi selengkapnya, lihat [Mengonfigurasi batas waktu fungsi Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html).
+ Gunakan runtime Node.js terbaru.
+ Gunakan Wilayah tempat streaming respons Lambda tersedia.
------
#### [ Using HttpResponseStream.from ]
Contoh kode berikut mengalirkan objek metadata JSON dan muatan kembali ke klien menggunakan `awslambda.HttpResponseStream()` metode tanpa menggunakan metode pipeline. Anda tidak perlu membuat pembatas. Untuk informasi selengkapnya, lihat [Menulis fungsi Lambda yang mendukung streaming respons](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html).
```
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
"statusCode": 200,
"headers": {
"x-foo": "bar"
},
"multiValueHeaders": {
"x-mv1": ["hello", "world"],
"Set-Cookie": ["c1=blue", "c2=red"]
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("First payload ");
await new Promise(r => setTimeout(r, 1000)); // synthetic delay
responseStream.write("Final payload");
responseStream.end();
});
```
------
#### [ Using the pipeline method ]
Lambda merekomendasikan bahwa ketika Anda menulis fungsi yang mendukung streaming respons, Anda menggunakan `awslambda.streamifyResponse()` dekorator yang disediakan runtime Node.js asli, dan metodenya. `pipeline()` Saat Anda menggunakan metode pipeline, Anda tidak perlu membuat pembatas, Lambda melakukan ini untuk Anda. Untuk informasi selengkapnya, lihat [Menulis fungsi Lambda yang mendukung streaming respons](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html).
Contoh kode berikut mengalirkan objek metadata JSON dan tiga muatan kembali ke klien.
```
import { pipeline } from 'node:stream/promises';
import { Readable } from 'node:stream';
export const handler = awslambda.streamifyResponse(
async (event, responseStream, context) => {
const httpResponseMetadata = {
statusCode: 200,
headers: {
"Content-Type": "text/plain",
"X-Custom-Header": "Example-Custom-Header"
}
};
responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata);
const dataStream = Readable.from(async function* () {
yield "FIRST payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "SECOND payload\n";
await new Promise(r => setTimeout(r, 1000));
yield "THIRD payload\n";
await new Promise(r => setTimeout(r, 1000));
}());
await pipeline(dataStream, responseStream);
}
);
```
------
#### [ Without using the pipeline method ]
Contoh kode berikut mengalirkan objek metadata JSON dan tiga muatan kembali ke klien tanpa menggunakan metode ini. `awslambda.HttpResponseStream()` Tanpa `awslambda.HttpResponseStream()` metode ini, Anda harus menyertakan pembatas 8 byte nol antara metadata dan muatan.
```
export const handler = awslambda.streamifyResponse(async (event, response, ctx) => {
response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}');
response.write("\x00".repeat(8)); // DELIMITER
await new Promise(r => setTimeout(r, 1000));
response.write("FIRST payload");
await new Promise(r => setTimeout(r, 1000));
response.write("SECOND payload");
await new Promise(r => setTimeout(r, 1000));
response.write("FINAL payload");
response.end();
});
```
------
## Buat integrasi proxy Lambda dengan streaming respons payload
Prosedur berikut menunjukkan cara membuat integrasi proxy Lambda dengan streaming respons payload. Gunakan contoh fungsi Lambda atau buat sendiri.
------
#### [ Konsol Manajemen AWS ]
**Untuk membuat integrasi proxy Lambda dengan streaming respons payload**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih **Buat sumber daya**.
1. Untuk **Nama sumber daya**, masukkan **streaming**.
1. Pilih **Buat sumber daya**.
1. Dengan sumber daya **/streaming** yang dipilih, pilih **Create method**.
1. Untuk **jenis Metode**, pilih **APAPUN**.
1. Untuk **jenis Integrasi**, pilih **Lambda**.
1. Pilih integrasi **proxy Lambda**.
1. Untuk **mode transfer Respons**, pilih **Streaming**.
1. Untuk fungsi **Lambda, pilih nama fungsi** Lambda Anda.
Konsol API Gateway secara otomatis menggunakan [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)API untuk menjalankan fungsi Lambda. Anda bertanggung jawab untuk menulis fungsi Lambda yang mendukung streaming respons. Sebagai contoh, lihat [Contoh fungsi Lambda untuk streaming respons](#response-streaming-lambda-example).
1. Pilih **metode Buat**.
Setelah Anda membuat metode, terapkan API Anda.
**Untuk men-deploy API Anda**
1. Pilih **Deploy API**.
1. Untuk **Stage**, pilih **New stage**.
1. Untuk **nama Panggung**, masukkan**prod**.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Pilih **Deploy**.
------
#### [ AWS CLI ]
Prosedur berikut menunjukkan cara mengimpor API baru dengan `responseTransferMode` set ke`STREAM`. Jika Anda memiliki API integrasi yang ada dan ingin memodifikasinya`responseTransferMode`, lihat[Perbarui mode transfer respons untuk integrasi proxy Lambda](#response-streaming-lambda-update).
**Untuk membuat API baru dengan streaming respons payload**
1. Salin file Open API berikut, lalu simpan sebagai file`ResponseStreamDemoSwagger.yaml`. Dalam file ini, `responseTransferMode` diatur ke`STREAM`, dan URI integrasi diatur ke`arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`.
Ganti nama fungsi dari `my-function` dengan fungsi berkemampuan streaming dan ganti kredensialnya dengan peran IAM yang memiliki kebijakan yang memungkinkan layanan `apigateway` memanggil fungsi Lambda.
```
openapi: "3.0.1"
info:
title: "ResponseStreamingDemo"
version: "2025-04-28T17:28:25Z"
servers:
- url: "{basePath}"
variables:
basePath:
default: "prod"
paths:
/lambda:
get:
x-amazon-apigateway-integration:
httpMethod: "POST"
uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations"
type: "aws_proxy"
timeoutInMillis: 90000
responseTransferMode: "STREAM"
credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role"
```
Alih-alih menyediakan peran IAM untuk kredensyal, Anda dapat menggunakan perintah untuk Lambda `add-permission` untuk menambahkan izin berbasis sumber daya.
1. Gunakan `import-rest-api` perintah berikut untuk mengimpor definisi OpenAPI Anda:
```
aws apigateway import-rest-api \
--body 'fileb://~/ResponseStreamDemoSwagger.yaml' \
--parameters endpointConfigurationTypes=REGIONAL \
--region us-west-1
```
1. Gunakan `create-deployment` perintah berikut untuk menerapkan API baru Anda ke panggung:
```
aws apigateway create-deployment \
--rest-api-id a1b2c2 \
--stage-name prod \
--region us-west-1
```
------
### Perbarui mode transfer respons untuk integrasi proxy Lambda
Prosedur berikut menunjukkan cara memperbarui mode transfer respons untuk integrasi proxy Lambda. Saat Anda mengubah mode transfer respons ke streaming, perbarui fungsi Lambda Anda sehingga mematuhi persyaratan untuk streaming respons. Gunakan contoh fungsi Lambda atau buat sendiri.
------
#### [ Konsol Manajemen AWS ]
**Untuk memperbarui mode transfer respons untuk integrasi proxy Lambda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
1. Pada tab **Permintaan integrasi**, di bawah **Pengaturan permintaan integrasi**, pilih **Edit**.
1. Untuk **mode transfer Respons**, pilih **Streaming**.
1. Untuk fungsi **Lambda, pilih nama fungsi** Lambda Anda.
1. Pilih **Simpan**.
Setelah memperbarui metode, terapkan API Anda.
**Untuk men-deploy API Anda**
1. Pilih **Deploy API**.
1. Untuk **Stage**, pilih **New stage**.
1. Untuk **nama Panggung**, masukkan**prod**.
1. (Opsional) Untuk **Deskripsi**, masukkan deskripsi.
1. Pilih **Deploy**.
------
#### [ AWS CLI ]
1. Perbarui fungsi Lambda Anda agar diaktifkan streaming.
1. Gunakan AWS CLI perintah berikut untuk memperbarui URI integrasi dan mode transfer respons integrasi Anda:
```
aws apigateway update-integration \
--rest-api-id a1b2c3 \
--resource-id aaa111 \
--http-method ANY \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \
--region us-west-1
```
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
# Memecahkan masalah dengan streaming respons di API Gateway
Panduan pemecahan masalah berikut dapat membantu menyelesaikan masalah dengan Anda APIs yang menggunakan streaming respons.
## Pemecahan masalah umum
Anda dapat menggunakan tab pengujian [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html)atau konsol untuk menguji respons streaming Anda. Pertimbangan berikut dapat memengaruhi penggunaan pemanggilan pengujian Anda untuk streaming respons:
+ Saat Anda menguji metode Anda, API Gateway menyangga payload respons yang dialirkan. Setelah salah satu kondisi berikut terpenuhi, API Gateway mengembalikan respons satu kali yang berisi muatan buffer:
+ Permintaan selesai
+ 35 detik telah berlalu
+ Lebih dari 1 MB payload respons telah di-buffer
+ Jika lebih dari 35 detik berlalu sebelum metode Anda mengembalikan status respons HTTP dan semua header, maka status respons yang dikembalikan adalah 0. TestInvokeMethod
+ API Gateway tidak menghasilkan log eksekusi apa pun.
Setelah menerapkan API, Anda dapat menguji respons streaming dengan menggunakan perintah curl. Kami menyarankan Anda menggunakan `-i` opsi untuk menyertakan header respons protokol dalam output. Untuk melihat data respons saat tiba, gunakan opsi curl `--no-buffer`
## Memecahkan masalah kesalahan cURL
Jika Anda menguji integrasi dan Anda menerima kesalahan`curl: (18) transfer closed with outstanding read data remaining`, pastikan batas waktu integrasi Anda cukup lama. Jika Anda menggunakan fungsi Lambda, Anda perlu memperbarui batas waktu respons fungsi Lambda. Untuk informasi selengkapnya, lihat [Mengonfigurasi batas waktu fungsi Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html).
## Memecahkan masalah menggunakan pencatatan akses
Anda dapat menggunakan log akses untuk tahap REST API untuk mencatat dan memecahkan masalah aliran respons Anda. Selain variabel yang ada, Anda dapat menggunakan variabel log akses berikut:
`$context.integration.responseTransferMode`
Mode transfer respons integrasi Anda. Ini bisa salah satu `BUFFERED` atau`STREAMED`.
`$context.integration.timeToAllHeaders`
Waktu antara saat API Gateway menetapkan koneksi integrasi saat menerima semua header respons integrasi dari klien.
`$context.integration.timeToFirstContent`
Waktu antara saat API Gateway menetapkan koneksi integrasi saat menerima byte konten pertama.
`$context.integration.latency` atau `$context.integrationLatency`
Waktu ketika API Gateway menetapkan koneksi integrasi saat aliran respons integrasi selesai.
Gambar berikut menunjukkan bagaimana variabel log akses ini mewakili komponen yang berbeda dari aliran respons.
![\[Akses variabel log untuk streaming respons di API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/response-streaming-figure.png)
Untuk informasi selengkapnya tentang log akses, lihat [Siapkan CloudWatch logging untuk REST APIs di API Gateway](set-up-logging.md). Anda juga dapat menggunakan X-Ray untuk memantau aliran respons Anda. Lihat informasi yang lebih lengkap di [Lacak permintaan pengguna ke REST APIs menggunakan X-Ray di API Gateway](apigateway-xray.md).
# Integrasi pribadi untuk REST APIs di API Gateway
Gunakan integrasi pribadi untuk mengekspos HTTP/HTTPS sumber daya Anda dalam VPC Amazon untuk akses oleh klien di luar VPC. Ini memperluas akses ke sumber daya VPC pribadi Anda di luar batas VPC. Anda dapat mengontrol akses ke API Anda dengan menggunakan salah satu [metode otorisasi](apigateway-control-access-to-api.md) yang didukung API Gateway.
Untuk membuat integrasi pribadi, Anda harus terlebih dahulu membuat tautan VPC. API Gateway mendukung tautan VPC V2 untuk REST. APIs VPC link V2 memungkinkan Anda membuat integrasi pribadi yang menghubungkan REST API Anda ke Application Load Balancers tanpa menggunakan Network Load Balancer. Menggunakan Application Load Balancer memungkinkan Anda terhubung ke aplikasi ECSs berbasis container Amazon dan banyak backend lainnya. Tautan VPC V1 dianggap sebagai jenis integrasi lama. Meskipun didukung oleh API Gateway, kami menyarankan Anda untuk tidak membuat tautan VPC baru V1.
## Pertimbangan-pertimbangan
Pertimbangan berikut dapat memengaruhi penggunaan integrasi pribadi Anda:
+ Semua sumber daya harus dimiliki oleh yang sama Akun AWS. Ini termasuk penyeimbang beban, tautan VPC, dan REST API.
+ Secara default, lalu lintas integrasi pribadi menggunakan protokol HTTP. Untuk menggunakan HTTPS, tentukan [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)yang berisi nama server yang aman, seperti`https://example.com:443/test`.
+ Dalam integrasi pribadi, API Gateway menyertakan bagian [tahap](set-up-stages.md) titik akhir API dalam permintaan ke sumber daya backend Anda. Misalnya, jika Anda meminta `test` tahap API, API Gateway menyertakan `test/path` permintaan integrasi pribadi Anda. Untuk menghapus nama panggung dari permintaan ke sumber daya backend Anda, gunakan [pemetaan parameter](rest-api-parameter-mapping.md) untuk membuat penggantian variabel. `$context.requestOverride.path`
+ Integrasi pribadi dengan AWS Cloud Map tidak didukung.
**Topics**
+ [Pertimbangan-pertimbangan](#private-integrations-considerations)
+ [Siapkan tautan VPC V2 di API Gateway](apigateway-vpc-links-v2.md)
+ [Siapkan integrasi pribadi](set-up-private-integration.md)
+ [Integrasi pribadi menggunakan tautan VPC V1 (warisan)](vpc-links-v1.md)
# Siapkan tautan VPC V2 di API Gateway
Tautan VPC memungkinkan Anda membuat integrasi pribadi yang menghubungkan rute API Anda ke sumber daya pribadi di VPC, seperti Application Load Balancers atau aplikasi berbasis container Amazon ECS. Integrasi pribadi menggunakan tautan VPC V2 untuk merangkum koneksi antara API Gateway dan sumber daya VPC yang ditargetkan. Anda dapat menggunakan kembali tautan VPC di berbagai sumber daya dan. APIs
Saat Anda membuat tautan VPC, API Gateway membuat dan mengelola [antarmuka jaringan elastis](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) untuk tautan VPC V2 di akun Anda. Proses ini dapat menghabiskan waktu beberapa menit. Ketika tautan VPC V2 siap digunakan, statusnya bertransisi dari ke. `PENDING` `AVAILABLE`
**catatan**
Jika tidak ada lalu lintas yang dikirim melalui tautan VPC selama 60 hari, itu menjadi. `INACTIVE` Saat tautan VPC dalam `INACTIVE` status, API Gateway menghapus semua antarmuka jaringan tautan VPC. Hal ini menyebabkan permintaan API yang bergantung pada tautan VPC gagal. Jika permintaan API dilanjutkan, API Gateway menyediakan ulang antarmuka jaringan. Diperlukan beberapa menit untuk membuat antarmuka jaringan dan mengaktifkan kembali tautan VPC. Anda dapat menggunakan status tautan VPC untuk memantau status tautan VPC Anda.
## Buat tautan VPC V2 dengan menggunakan AWS CLI
Untuk membuat tautan VPC V2, semua sumber daya yang terlibat harus dimiliki oleh akun yang sama AWS . [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html)Perintah berikut membuat link VPC:
```
aws apigatewayv2 create-vpc-link --name MyVpcLink \
--subnet-ids subnet-aaaa subnet-bbbb \
--security-group-ids sg1234 sg5678
```
**catatan**
Tautan VPC V2 tidak dapat diubah. Setelah membuat tautan VPC V2, Anda tidak dapat mengubah subnet atau grup keamanannya.
## Hapus tautan VPC V2 dengan menggunakan AWS CLI
[delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html)Perintah berikut menghapus tautan VPC.
```
aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123
```
## Ketersediaan berdasarkan Wilayah
Tautan VPC V2 didukung di Wilayah dan Zona Ketersediaan berikut:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/apigateway-vpc-links-v2.html)
# Siapkan integrasi pribadi
Untuk membuat integrasi pribadi dengan Application Load Balancer atau Network Load Balancer, Anda membuat integrasi proxy HTTP, menentukan [tautan VPC V2](apigateway-vpc-links-v2.md) yang akan digunakan, dan menyediakan ARN Network Load Balancer atau Application Load Balancer. Secara default, lalu lintas integrasi pribadi menggunakan protokol HTTP. Untuk menggunakan HTTPS, tentukan [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)yang berisi nama server yang aman, seperti`https://example.com:443/test`. Untuk tutorial lengkap tentang cara membuat REST API dengan integrasi pribadi, lihat[Tutorial: Buat REST API dengan integrasi pribadi](getting-started-with-private-integration.md).
## Buat integrasi pribadi
Prosedur berikut menunjukkan cara membuat integrasi pribadi yang terhubung ke penyeimbang beban dengan menggunakan tautan VPC V2.
------
#### [ Konsol Manajemen AWS ]
Untuk tutorial tentang cara membuat integrasi pribadi lihat,[Tutorial: Buat REST API dengan integrasi pribadi](getting-started-with-private-integration.md).
------
#### [ AWS CLI ]
Perintah [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) berikut membuat integrasi pribadi yang terhubung ke penyeimbang beban dengan menggunakan tautan VPC V2:
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id bbb111
```
Alih-alih langsung memberikan ID koneksi, Anda dapat menggunakan variabel panggung sebagai gantinya. Saat menerapkan API ke sebuah panggung, Anda menyetel ID VPC link V2. Perintah [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) berikut membuat integrasi pribadi menggunakan variabel stage untuk VPC link V2 ID:
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id aaa000 \
--integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \
--uri 'https://example.com:443/path' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkV2Id}"
```
Pastikan untuk mengutip dua kali ekspresi variabel panggung (\$1 \$1stageVariables.vpClinkv2id\$1) dan keluar dari karakter \$1.
------
#### [ OpenAPI ]
Anda dapat menyiapkan API dengan integrasi pribadi dengan mengimpor file OpenAPI API. Pengaturannya mirip dengan definisi OpenAPI API dengan integrasi HTTP, dengan pengecualian berikut:
+ Anda harus secara eksplisit mengatur `connectionType` ke. `VPC_LINK`
+ Anda harus secara eksplisit mengatur `connectionId` ke ID dari `VpcLinkV2` atau ke variabel tahap yang merujuk ID dari sebuah. `VpcLinkV2`
+ `uri`Parameter dalam integrasi pribadi menunjuk ke HTTP/HTTPS titik akhir di VPC, tetapi digunakan sebagai gantinya untuk mengatur header permintaan `Host` integrasi.
+ `uri`Parameter dalam integrasi pribadi dengan titik akhir HTTPS di VPC digunakan untuk memverifikasi nama domain yang dinyatakan terhadap yang ada di sertifikat yang diinstal pada titik akhir VPC.
Anda dapat menggunakan variabel tahap untuk mereferensikan `VpcLinkV2` ID. Atau Anda dapat menetapkan nilai ID langsung ke`connectionId`.
File OpenAPI berformat JSON berikut menunjukkan contoh API dengan tautan VPC seperti yang direferensikan oleh variabel tahap (): `${stageVariables.vpcLinkIdV2}`
```
{
"swagger": "2.0",
"info": {
"version": "2017-11-17T04:40:23Z",
"title": "MyApiWithVpcLinkV2"
},
"host": "abcdef123.execute-api.us-west-2.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "https://example.com:443/path",
"passthroughBehavior": "when_no_match",
"connectionType": "VPC_LINK",
"connectionId": "${stageVariables.vpcLinkV2Id}",
"integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011",
"httpMethod": "GET",
"type": "http_proxy"
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Perbarui integrasi pribadi
Contoh berikut memperbarui tautan VPC V2 untuk integrasi pribadi.
------
#### [ Konsol Manajemen AWS ]
**Untuk memperbarui integrasi pribadi**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API dengan integrasi pribadi.
1. Pilih sumber daya dan metode yang menggunakan integrasi pribadi.
1. Pada **tab Permintaan integrasi**, di bawah **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Anda dapat mengedit pengaturan integrasi pribadi Anda. Jika saat ini Anda menggunakan tautan VPC V1, Anda dapat mengubah tautan VPC Anda ke tautan VPC V2.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ AWS CLI ]
Perintah [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) berikut memperbarui integrasi pribadi untuk menggunakan tautan VPC V2:
```
aws apigateway update-integration \
--rest-api-id a1b2c3d4e5 \
--resource-id a1b2c3 \
--http-method GET \
--patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]"
```
------
# Integrasi pribadi menggunakan tautan VPC V1 (warisan)
**catatan**
Implementasi integrasi pribadi berikut menggunakan tautan VPC V1. Tautan VPC V1 adalah sumber daya lama. Kami menyarankan Anda menggunakan [tautan VPC V2 untuk](apigateway-vpc-links-v2.md) REST. APIs
Untuk membuat integrasi pribadi, Anda harus terlebih dahulu membuat Network Load Balancer. Network Load Balancer Anda harus memiliki [listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) yang merutekan permintaan ke sumber daya di VPC Anda. Untuk meningkatkan ketersediaan API Anda, pastikan Network Load Balancer merutekan lalu lintas ke sumber daya di lebih dari satu Availability Zone di. Wilayah AWS Kemudian, Anda membuat tautan VPC yang Anda gunakan untuk menghubungkan API dan Network Load Balancer Anda. Setelah membuat tautan VPC, Anda membuat integrasi pribadi untuk merutekan lalu lintas dari API ke sumber daya di VPC melalui tautan VPC dan Network Load Balancer. Network Load Balancer dan API harus dimiliki oleh yang sama. Akun AWS
**Topics**
+ [Menyiapkan Network Load Balancer untuk integrasi pribadi API Gateway (lama)](set-up-nlb-for-vpclink-using-console.md)
+ [Berikan izin untuk API Gateway untuk membuat tautan VPC (lama)](grant-permissions-to-create-vpclink.md)
+ [Siapkan API Gateway API dengan integrasi pribadi menggunakan AWS CLI (legacy)](set-up-api-with-vpclink-cli.md)
+ [Akun API Gateway yang digunakan untuk integrasi pribadi (lama)](set-up-api-with-vpclink-accounts.md)
# Menyiapkan Network Load Balancer untuk integrasi pribadi API Gateway (lama)
**catatan**
Implementasi integrasi pribadi berikut menggunakan tautan VPC V1. Tautan VPC V1 adalah sumber daya lama. Kami menyarankan Anda menggunakan [tautan VPC V2 untuk](apigateway-vpc-links-v2.md) REST. APIs
Prosedur berikut menguraikan langkah-langkah untuk menyiapkan Network Load Balancer (NLB) untuk integrasi pribadi API Gateway menggunakan konsol Amazon EC2 dan memberikan referensi untuk petunjuk terperinci untuk setiap langkah.
Untuk setiap VPC tempat Anda memiliki sumber daya, Anda hanya perlu mengkonfigurasi satu NLB dan satu. VPCLink NLB mendukung beberapa [pendengar](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) dan grup [target](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html) per NLB. Anda dapat mengonfigurasi setiap layanan sebagai pendengar tertentu di NLB dan menggunakan satu layanan VPCLink untuk terhubung ke NLB. Saat membuat integrasi pribadi di API Gateway, Anda kemudian menentukan setiap layanan menggunakan port spesifik yang ditetapkan untuk setiap layanan. Untuk informasi selengkapnya, lihat [Tutorial: Buat REST API dengan integrasi pribadi](getting-started-with-private-integration.md). Network Load Balancer dan API harus dimiliki oleh yang sama. Akun AWS
**Untuk membuat Network Load Balancer untuk integrasi pribadi menggunakan konsol API Gateway**
1. Masuk ke Konsol Manajemen AWS dan buka konsol Amazon EC2 di. [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)
1. Siapkan server web pada instans Amazon EC2. Untuk contoh penyiapan, lihat [Menginstal Server Web LAMP di Amazon Linux 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html).
1. Buat Network Load Balancer, daftarkan instans EC2 dengan grup target, dan tambahkan grup target ke pendengar Network Load Balancer. Untuk detailnya, ikuti petunjuk di [Memulai dengan Network Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html).
1. Setelah Network Load Balancer dibuat, lakukan hal berikut:
1. Perhatikan ARN dari Network Load Balancer. Anda akan memerlukannya untuk membuat tautan VPC di API Gateway untuk mengintegrasikan API dengan sumber daya VPC di belakang Network Load Balancer.
1. Matikan evaluasi grup keamanan untuk PrivateLink.
+ Untuk menonaktifkan evaluasi grup keamanan untuk PrivateLink lalu lintas menggunakan konsol, Anda dapat memilih tab **Keamanan**, lalu **Edit**. Dalam **pengaturan Keamanan**, hapus **Menegakkan aturan masuk pada PrivateLink ** lalu lintas.
+ Gunakan [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html)perintah berikut untuk mematikan evaluasi grup keamanan untuk PrivateLink lalu lintas:
```
aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \
--security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off
```
**catatan**
Jangan menambahkan dependensi apa pun ke API Gateway CIDRs karena mereka pasti akan berubah tanpa pemberitahuan.
# Berikan izin untuk API Gateway untuk membuat tautan VPC (lama)
**catatan**
Implementasi integrasi pribadi berikut menggunakan tautan VPC V1. Tautan VPC V1 adalah sumber daya lama. Kami menyarankan Anda menggunakan [tautan VPC V2 untuk](apigateway-vpc-links-v2.md) REST. APIs
Agar Anda atau pengguna di akun Anda dapat membuat dan memelihara tautan VPC, Anda atau pengguna harus memiliki izin untuk membuat, menghapus, dan melihat konfigurasi layanan titik akhir VPC, mengubah izin layanan titik akhir VPC, dan memeriksa penyeimbang beban. Untuk memberikan izin tersebut, gunakan langkah-langkah berikut.
**Untuk memberikan izin untuk membuat, memperbarui, dan menghapus tautan VPC**
1. Buat kebijakan IAM yang mirip dengan berikut ini:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"apigateway:POST",
"apigateway:GET",
"apigateway:PATCH",
"apigateway:DELETE"
],
"Resource": [
"arn:aws:apigateway:us-east-1::/vpclinks",
"arn:aws:apigateway:us-east-1::/vpclinks/*"
]
},
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeLoadBalancers"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpointServiceConfiguration",
"ec2:DeleteVpcEndpointServiceConfigurations",
"ec2:DescribeVpcEndpointServiceConfigurations",
"ec2:ModifyVpcEndpointServicePermissions"
],
"Resource": "*"
}
]
}
```
------
Jika Anda ingin mengaktifkan penandaan untuk tautan VPC Anda, pastikan untuk mengizinkan operasi penandaan. Untuk informasi selengkapnya, lihat [Izinkan operasi penandaan](apigateway-tagging-iam-policy.md#allow-tagging).
1. Buat atau pilih peran IAM dan lampirkan kebijakan sebelumnya ke peran tersebut.
1. Tetapkan peran IAM kepada Anda atau pengguna di akun Anda yang membuat tautan VPC.
# Siapkan API Gateway API dengan integrasi pribadi menggunakan AWS CLI (legacy)
**catatan**
Implementasi integrasi pribadi berikut menggunakan tautan VPC V1. Tautan VPC V1 adalah sumber daya lama. Kami menyarankan Anda menggunakan [tautan VPC V2 untuk](apigateway-vpc-links-v2.md) REST. APIs
Tutorial berikut menunjukkan cara menggunakan AWS CLI untuk membuat link VPC dan integrasi pribadi. Prasyarat berikut diperlukan:
+ Anda memerlukan Network Load Balancer yang dibuat dan dikonfigurasi dengan sumber VPC Anda sebagai target. Untuk informasi selengkapnya, lihat [Menyiapkan Network Load Balancer untuk integrasi pribadi API Gateway (lama)](set-up-nlb-for-vpclink-using-console.md). Ini harus Akun AWS sama dengan API Anda. Anda memerlukan Network Load Balancer ARN untuk membuat tautan VPC Anda.
+ Untuk membuat dan mengelola`VpcLink`, Anda memerlukan izin untuk membuat `VpcLink` di API Anda. Anda tidak memerlukan izin untuk menggunakan file. `VpcLink` Untuk informasi selengkapnya, lihat [Berikan izin untuk API Gateway untuk membuat tautan VPC (lama)](grant-permissions-to-create-vpclink.md).
**Untuk menyiapkan API dengan integrasi pribadi menggunakan AWS CLI**
1. Gunakan [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html)perintah berikut untuk membuat `VpcLink` penargetan Network Load Balancer yang ditentukan:
```
aws apigateway create-vpc-link \
--name my-test-vpc-link \
--target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef
```
Output dari perintah ini mengakui penerimaan permintaan dan menunjukkan `PENDING` status untuk yang `VpcLink` sedang dibuat.
```
{
"status": "PENDING",
"targetArns": [
"arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
],
"id": "gim7c3",
"name": "my-test-vpc-link"
}
```
Dibutuhkan 2-4 menit bagi API Gateway untuk menyelesaikan pembuatan`VpcLink`. Ketika operasi selesai dengan sukses, `status` adalah`AVAILABLE`. Anda dapat memverifikasi ini dengan menggunakan [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html)perintah berikut:
```
aws apigateway get-vpc-link --vpc-link-id gim7c3
```
Jika operasi gagal, Anda mendapatkan `FAILED` status, dengan `statusMessage` berisi pesan kesalahan. Misalnya, jika Anda mencoba membuat `VpcLink` dengan Network Load Balancer yang sudah dikaitkan dengan titik akhir VPC, Anda mendapatkan hal berikut di properti: `statusMessage`
```
"NLB is already associated with another VPC Endpoint Service"
```
Setelah berhasil `VpcLink` dibuat, Anda dapat membuat API dan mengintegrasikannya dengan sumber daya VPC melalui file. `VpcLink`
Perhatikan `id` nilai yang baru dibuat`VpcLink`. Dalam contoh output ini, itu`gim7c3`. Anda membutuhkannya untuk mengatur integrasi pribadi.
1. Gunakan [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)perintah berikut untuk membuat [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)resource API Gateway:
```
aws apigateway create-rest-api --name 'My VPC Link Test'
```
Perhatikan nilai dan `id` `rootResourceId` nilai `RestApi` `RestApi`'s dalam hasil yang dikembalikan. Anda memerlukan nilai ini untuk melakukan operasi lebih lanjut pada API.
Selanjutnya, Anda membuat API dengan hanya `GET` metode pada sumber daya root (`/`) dan mengintegrasikan metode dengan`VpcLink`.
1. Gunakan perintah [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) berikut untuk membuat metode: `GET /`
```
aws apigateway put-method \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--authorization-type "NONE"
```
Jika Anda tidak menggunakan integrasi proxy dengan`VpcLink`, Anda juga harus menyiapkan setidaknya respons metode kode `200` status. Anda menggunakan integrasi proxy di sini.
1. Setelah Anda membuat `GET /` metode, Anda mengatur integrasi. Untuk integrasi pribadi, Anda menggunakan `connection-id` parameter untuk memberikan `VpcLink` ID. Anda dapat menggunakan variabel tahap atau langsung memasukkan `VpcLink` ID. `uri`Parameter ini tidak digunakan untuk merutekan permintaan ke titik akhir Anda, tetapi digunakan untuk mengatur `Host` header dan untuk validasi sertifikat.
------
#### [ Use the VPC link ID ]
Gunakan perintah [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) berikut untuk menggunakan `VpcLink` ID secara langsung dalam integrasi:
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id gim7c3
```
------
#### [ Use a stage variable ]
Gunakan perintah [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) berikut untuk menggunakan variabel stage untuk mereferensikan ID tautan VPC. Saat menerapkan API ke suatu panggung, Anda menyetel ID tautan VPC.
```
aws apigateway put-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \
--http-method GET \
--type HTTP_PROXY \
--integration-http-method GET \
--connection-type VPC_LINK \
--connection-id "\${stageVariables.vpcLinkId}"
```
Pastikan untuk mengutip dua kali ekspresi variabel tahap (`${stageVariables.vpcLinkId}`) dan melarikan diri dari `$` karakter.
------
Kapan pun, Anda juga dapat memperbarui integrasi untuk mengubah`connection-id`. Gunakan perintah [update-integration berikut untuk memperbarui integrasi](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) Anda:
```
aws apigateway update-integration \
--rest-api-id abcdef123 \
--resource-id skpp60rab7 \
--http-method GET \
--patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'
```
Pastikan untuk menggunakan daftar JSON stringified sebagai nilai parameter. `patch-operations`
Karena Anda menggunakan integrasi proxy pribadi, API Anda sekarang siap untuk penerapan dan untuk uji coba.
1. Jika Anda menggunakan variabel stage untuk menentukan`connection-id`, Anda perlu menerapkan API untuk mengujinya. Gunakan perintah [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) berikut untuk menerapkan API Anda dengan variabel stage:
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name test \
--variables vpcLinkId=gim7c3
```
Untuk memperbarui variabel stage dengan `VpcLink` ID yang berbeda, seperti`asf9d7`, gunakan perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) berikut:
```
aws apigateway update-stage \
--rest-api-id abcdef123 \
--stage-name test \
--patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'
```
Saat Anda membuat hardcode `connection-id` properti dengan `VpcLink` ID literal, Anda tidak perlu menerapkan API untuk mengujinya. Gunakan [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html)perintah untuk menguji API Anda sebelum diterapkan.
1. Gunakan perintah berikut untuk menjalankan API Anda:
```
curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test
```
Atau, Anda dapat memasukkan URL Invoke-API Anda di browser web untuk melihat hasilnya.
# Akun API Gateway yang digunakan untuk integrasi pribadi (lama)
Akun API Gateway khusus wilayah berikut secara otomatis IDs ditambahkan ke layanan titik akhir VPC Anda seperti `AllowedPrincipals` saat Anda membuat file. `VpcLink`
| **Wilayah** | **ID Akun** |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
# Integrasi tiruan untuk REST APIs di API Gateway
Amazon API Gateway mendukung integrasi tiruan untuk metode API. Fitur ini memungkinkan pengembang API untuk menghasilkan respons API dari API Gateway secara langsung, tanpa perlu backend integrasi. Sebagai pengembang API, Anda dapat menggunakan fitur ini untuk membuka blokir tim dependen yang perlu bekerja dengan API sebelum pengembangan proyek selesai. Anda juga dapat menggunakan fitur ini untuk menyediakan halaman landing untuk API Anda, yang dapat memberikan ikhtisar dan navigasi ke API Anda. Untuk contoh halaman arahan seperti itu, lihat permintaan integrasi dan respons metode GET pada sumber daya root dari contoh API yang dibahas[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md).
Sebagai pengembang API, Anda memutuskan bagaimana API Gateway merespons permintaan integrasi tiruan. Untuk ini, Anda mengonfigurasi permintaan integrasi metode dan respons integrasi untuk mengaitkan respons dengan kode status tertentu. Untuk metode dengan integrasi tiruan untuk mengembalikan `200` respons, konfigurasikan template pemetaan badan permintaan integrasi untuk mengembalikan yang berikut ini.
```
{"statusCode": 200}
```
Konfigurasikan respons `200` integrasi untuk memiliki template pemetaan tubuh berikut, misalnya:
```
{
"statusCode": 200,
"message": "Go ahead without me."
}
```
Demikian pula, agar metode mengembalikan, misalnya, respons `500` kesalahan, siapkan templat pemetaan badan permintaan integrasi untuk mengembalikan yang berikut ini.
```
{"statusCode": 500}
```
Siapkan respons `500` integrasi dengan, misalnya, templat pemetaan berikut:
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
Atau, Anda dapat meminta metode integrasi tiruan mengembalikan respons integrasi default tanpa menentukan templat pemetaan permintaan integrasi. Respons integrasi default adalah respons dengan **regex status HTTP** yang tidak ditentukan. Pastikan perilaku passthrough yang sesuai ditetapkan.
**catatan**
Integrasi tiruan tidak dimaksudkan untuk mendukung template respons besar. Jika Anda membutuhkannya untuk kasus penggunaan Anda, Anda harus mempertimbangkan untuk menggunakan integrasi Lambda sebagai gantinya.
Dengan menggunakan templat pemetaan permintaan integrasi, Anda dapat menyuntikkan logika aplikasi untuk memutuskan respons integrasi tiruan mana yang akan dikembalikan berdasarkan kondisi tertentu. Misalnya, Anda dapat menggunakan parameter `scope` kueri pada permintaan yang masuk untuk menentukan apakah akan mengembalikan respons yang berhasil atau respons kesalahan:
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
Dengan cara ini, metode integrasi tiruan memungkinkan panggilan internal dilakukan sambil menolak jenis panggilan lain dengan respons kesalahan.
Di bagian ini, kami menjelaskan cara menggunakan konsol API Gateway untuk mengaktifkan integrasi tiruan untuk metode API.
**Topics**
+ [Aktifkan integrasi tiruan menggunakan konsol API Gateway](how-to-mock-integration-console.md)
# Aktifkan integrasi tiruan menggunakan konsol API Gateway
Anda harus memiliki metode yang tersedia di API Gateway. Ikuti petunjuk dalam [Tutorial: Membuat REST API dengan integrasi non-proxy HTTP](api-gateway-create-api-step-by-step.md).
1. Pilih sumber daya API dan pilih **metode Buat**.
Untuk membuat metode, lakukan hal berikut:
1. Untuk **jenis Metode**, pilih metode.
1. Untuk **jenis Integrasi**, pilih **Mock**.
1. Pilih **metode Buat**.
1. Pada tab **Permintaan metode**, untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **parameter string kueri URL**. Pilih **Tambahkan string kueri** dan untuk **Nama**, masukkan**scope**. Parameter kueri ini menentukan apakah pemanggil internal atau sebaliknya.
1. Pilih **Simpan**.
1. Pada tab **respons Metode**, pilih **Buat respons**, lalu lakukan hal berikut:
1. Untuk **Status HTTP**, masukkan**500**.
1. Pilih **Simpan**.
1. Pada tab **Permintaan integrasi**, untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Pilih **template Pemetaan**, lalu lakukan hal berikut:
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
{
#if( $input.params('scope') == "internal" )
"statusCode": 200
#else
"statusCode": 500
#end
}
```
1. Pilih **Simpan**.
1. Pada tab **Respons Integrasi**, untuk **Default - Respons** pilih **Edit**.
1. Pilih **template Pemetaan**, lalu lakukan hal berikut:
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
{
"statusCode": 200,
"message": "Go ahead without me"
}
```
1. Pilih **Simpan**.
1. Pilih **Buat respons**.
Untuk membuat respons 500, lakukan hal berikut:
1. Untuk **regex status HTTP, masukkan**. **5\$1d\$12\$1**
1. Untuk **status respons Metode**, pilih**500**.
1. Pilih **Simpan**.
1. Untuk **5\$1 d \$12\$1 - Respons**, pilih **Edit**.
1. Pilih **Templat pemetaan**, lalu pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
```
1. Pilih **Simpan**.
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab. Untuk menguji integrasi tiruan Anda, lakukan hal berikut:
1. Masukkan `scope=internal` di bawah **String kueri**. Pilih **Uji**. Hasil tes menunjukkan:
```
Request: /?scope=internal
Status: 200
Latency: 26 ms
Response Body
{
"statusCode": 200,
"message": "Go ahead without me"
}
Response Headers
{"Content-Type":"application/json"}
```
1. Masukkan `scope=public` di bawah `Query strings` atau biarkan kosong. Pilih **Uji**. Hasil tes menunjukkan:
```
Request: /
Status: 500
Latency: 16 ms
Response Body
{
"statusCode": 500,
"message": "The invoked method is not supported on the API resource."
}
Response Headers
{"Content-Type":"application/json"}
```
Anda juga dapat mengembalikan header dalam respons integrasi tiruan dengan terlebih dahulu menambahkan header ke respons metode dan kemudian menyiapkan pemetaan header dalam respons integrasi. Faktanya, beginilah cara konsol API Gateway mengaktifkan dukungan CORS dengan mengembalikan header yang diperlukan CORS.
# Minta validasi untuk REST APIs di API Gateway
Anda dapat mengonfigurasi API Gateway untuk melakukan validasi dasar permintaan API sebelum melanjutkan dengan permintaan integrasi. Ketika validasi gagal, API Gateway segera gagal permintaan, mengembalikan respons kesalahan 400 ke pemanggil, dan menerbitkan hasil validasi di Log. CloudWatch Ini mengurangi panggilan yang tidak perlu ke backend. Lebih penting lagi, ini memungkinkan Anda fokus pada upaya validasi khusus untuk aplikasi Anda. Anda dapat memvalidasi badan permintaan dengan memverifikasi bahwa parameter permintaan yang diperlukan valid dan non-null atau dengan menentukan skema model untuk validasi data yang lebih rumit.
**Topics**
+ [Ikhtisar validasi permintaan dasar di API Gateway](#api-gateway-request-validation-basic-definitions)
+ [Model data untuk REST APIs](models-mappings-models.md)
+ [Siapkan validasi permintaan dasar di API Gateway](api-gateway-request-validation-set-up.md)
+ [AWS CloudFormation template API sampel dengan validasi permintaan dasar](api-gateway-request-validation-sample-cloudformation.md)
## Ikhtisar validasi permintaan dasar di API Gateway
API Gateway dapat melakukan validasi permintaan dasar, sehingga Anda dapat fokus pada validasi khusus aplikasi di backend. Untuk validasi, API Gateway memverifikasi salah satu atau kedua kondisi berikut:
+ Parameter permintaan yang diperlukan dalam URI, string kueri, dan header permintaan masuk disertakan dan tidak kosong. API Gateway hanya memeriksa keberadaan parameter dan tidak memeriksa jenis atau formatnya.
+ Payload permintaan yang berlaku mematuhi permintaan [skema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) yang dikonfigurasi dari metode untuk jenis konten tertentu. Jika tidak ada jenis konten yang cocok ditemukan, validasi permintaan tidak dilakukan. Untuk menggunakan model yang sama terlepas dari jenis konten, setel tipe konten untuk model data Anda`$default`.
Untuk mengaktifkan validasi, Anda menentukan aturan validasi dalam validator [permintaan, menambahkan validator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) ke [peta API validator permintaan, dan menetapkan validator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) ke metode API individual.
**catatan**
Minta validasi badan dan [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md) merupakan dua topik terpisah. Jika payload permintaan tidak memiliki skema model yang cocok, Anda dapat memilih untuk melewati atau memblokir muatan asli. Untuk informasi selengkapnya, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
# Model data untuk REST APIs
Di API Gateway, model mendefinisikan struktur data payload. Di API Gateway, model didefinisikan menggunakan [draf skema JSON](https://tools.ietf.org/html/draft-zyp-json-schema-04) 4. Objek JSON berikut adalah data sampel dalam contoh Pet Store.
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
Data berisi`id`,`type`, dan `price` hewan peliharaan. Model data ini memungkinkan Anda untuk:
+ Gunakan validasi permintaan dasar.
+ Buat template pemetaan untuk transformasi data.
+ Buat tipe data yang ditentukan pengguna (UDT) saat Anda membuat SDK.
![\[Contoh model data JSON untuk PetStore API.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/how-to-validate-requests.png)
Dalam model ini:
1. `$schema`Objek mewakili pengidentifikasi versi Skema JSON yang valid. Skema ini adalah draf Skema JSON v4.
1. `title`Objek adalah pengidentifikasi yang dapat dibaca manusia untuk model tersebut. Judul ini adalah`PetStoreModel`.
1. Kata kunci `required` validasi membutuhkan`type`, dan `price` untuk validasi permintaan dasar.
1. Model `properties` tersebut adalah`id`,`type`, dan`price`. Setiap objek memiliki properti yang dijelaskan dalam model.
1. Objek hanya `type` dapat memiliki nilai`dog`,`cat`, atau`fish`.
1. Objek `price` adalah angka dan dibatasi dengan `minimum` 25 dan 500`maximum`.
## PetStore model
```
1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3 "title": "PetStoreModel",
4 "type" : "object",
5 "required" : [ "price", "type" ],
6 "properties" : {
7 "id" : {
8 "type" : "integer"
9 },
10 "type" : {
11 "type" : "string",
12 "enum" : [ "dog", "cat", "fish" ]
13 },
14 "price" : {
15 "type" : "number",
16 "minimum" : 25.0,
17 "maximum" : 500.0
18 }
19 }
20 }
```
Dalam model ini:
1. Pada baris 2, `$schema` objek mewakili pengenal versi Skema JSON yang valid. Skema ini adalah draf Skema JSON v4.
1. Pada baris 3, `title` objek adalah pengidentifikasi yang dapat dibaca manusia untuk model tersebut. Judul ini adalah`PetStoreModel`.
1. Pada baris 5, kata kunci `required` validasi membutuhkan`type`, dan `price` untuk validasi permintaan dasar.
1. Pada baris 6 - 17, modelnya adalah`id`,`type`, dan`price`. `properties` Setiap objek memiliki properti yang dijelaskan dalam model.
1. Pada baris 12, objek hanya `type` dapat memiliki nilai`dog`,`cat`, atau`fish`.
1. Pada baris 14 - 17, objek `price` adalah angka dan dibatasi dengan `minimum` 25 dan 500`maximum`.
## Membuat model yang lebih kompleks
Anda dapat menggunakan `$ref` primitif untuk membuat definisi yang dapat digunakan kembali untuk model yang lebih panjang. Misalnya, Anda dapat membuat definisi yang disebut `Price` di `definitions` bagian yang menjelaskan `price` objek. Nilai `$ref` adalah `Price` definisi.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReUsableRef",
"required" : ["price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "#/definitions/Price"
}
},
"definitions" : {
"Price": {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
Anda juga dapat mereferensikan skema model lain yang ditentukan dalam file model eksternal. Tetapkan nilai `$ref` properti ke lokasi model. Dalam contoh berikut, `Price` model didefinisikan dalam `PetStorePrice` model di API`a1234`.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStorePrice",
"type": "number",
"minimum": 25,
"maximum": 500
}
```
Model yang lebih panjang dapat merujuk `PetStorePrice` model.
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "PetStoreModelReusableRefAPI",
"required" : [ "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"price" : {
"$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
}
}
}
```
## Menggunakan model data keluaran
Jika Anda mengubah data, Anda dapat menentukan model payload dalam respons integrasi. Model payload dapat digunakan saat Anda membuat SDK. Untuk bahasa yang diketik dengan kuat, seperti Java, Objective-C, atau Swift, objek sesuai dengan tipe data yang ditentukan pengguna (UDT). API Gateway membuat UDT jika Anda menyediakannya dengan model data saat Anda membuat SDK. Untuk informasi selengkapnya tentang transformasi data, lihat[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
Contoh berikut adalah data keluaran dari respons integrasi.
```
{
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
}
```
Contoh berikut adalah model payload yang menggambarkan data output.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PetStoreOutputModel",
"type" : "object",
"required" : [ "description", "askingPrice" ],
"properties" : {
"description" : {
"type" : "string"
},
"askingPrice" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
Dengan model ini, Anda dapat memanggil SDK untuk mengambil nilai `description` dan `askingPrice` properti dengan membaca properti `PetStoreOutputModel[i].description` dan`PetStoreOutputModel[i].askingPrice`. Jika tidak ada model yang disediakan, API Gateway menggunakan model kosong untuk membuat UDT default.
## Langkah selanjutnya
+ Bagian ini menyediakan sumber daya yang dapat Anda gunakan untuk mendapatkan lebih banyak pengetahuan tentang konsep yang disajikan dalam topik ini.
Anda dapat mengikuti tutorial validasi permintaan:
+ [Siapkan validasi permintaan menggunakan konsol API Gateway](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console)
+ [Siapkan validasi permintaan dasar menggunakan AWS CLI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli)
+ [Siapkan validasi permintaan dasar menggunakan definisi OpenAPI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger)
+ Untuk informasi selengkapnya tentang templat transformasi dan pemetaan data, [Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md)
# Siapkan validasi permintaan dasar di API Gateway
Bagian ini menunjukkan cara menyiapkan validasi permintaan untuk API Gateway menggunakan konsol AWS CLI, dan definisi OpenAPI.
**Topics**
+ [Siapkan validasi permintaan menggunakan konsol API Gateway](#api-gateway-request-validation-setup-in-console)
+ [Siapkan validasi permintaan dasar menggunakan AWS CLI](#api-gateway-request-validation-setup-cli)
+ [Siapkan validasi permintaan dasar menggunakan definisi OpenAPI](#api-gateway-request-validation-setup-importing-swagger)
## Siapkan validasi permintaan menggunakan konsol API Gateway
Anda dapat menggunakan konsol API Gateway untuk memvalidasi permintaan dengan memilih salah satu dari tiga validator untuk permintaan API:
+ **Validasi tubuh**.
+ **Validasi parameter string kueri dan header**.
+ **Validasi isi, parameter string kueri, dan header**.
Saat Anda menerapkan salah satu validator pada metode API, konsol API Gateway menambahkan validator ke peta API. [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)
Untuk mengikuti tutorial ini, Anda akan menggunakan CloudFormation template untuk membuat API Gateway API yang tidak lengkap. API ini memiliki `/validator` sumber daya dengan `GET` dan `POST` metode. Kedua metode terintegrasi dengan titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Anda akan mengkonfigurasi dua jenis validasi permintaan:
+ Dalam `GET` metode ini, Anda akan mengkonfigurasi validasi permintaan untuk parameter string kueri URL.
+ Dalam `POST` metode ini, Anda akan mengonfigurasi validasi permintaan untuk badan permintaan.
Ini akan memungkinkan hanya panggilan API tertentu untuk melewati API.
Unduh dan unzip [template pembuatan aplikasi untuk CloudFormation](samples/request-validation-tutorial-console.zip). Anda akan menggunakan template ini untuk membuat API yang tidak lengkap. Anda akan menyelesaikan langkah-langkah lainnya di konsol API Gateway.
**Untuk membuat CloudFormation tumpukan**
1. Buka CloudFormation konsol di [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Pilih **Buat tumpukan** kemudian pilih **Dengan sumber daya baru (standar)**.
1. Untuk **Tentukan templat**, pilih **Unggah file templat**.
1. Pilih template yang Anda unduh.
1. Pilih **Berikutnya**.
1. Untuk **nama Stack**, masukkan **request-validation-tutorial-console** dan kemudian pilih **Berikutnya**.
1. Untuk **opsi Konfigurasi tumpukan**, pilih **Berikutnya**.
1. Untuk **Kemampuan**, akui bahwa CloudFormation dapat membuat sumber daya IAM di akun Anda.
1. Pilih **Berikutnya**, lalu pilih **Kirim**.
CloudFormation ketentuan sumber daya yang ditentukan dalam template. Diperlukan beberapa menit untuk menyelesaikan penyediaan sumber daya Anda. Ketika status CloudFormation tumpukan Anda adalah **CREATE\$1COMPLETE**, Anda siap untuk melanjutkan ke langkah berikutnya.
**Untuk memilih API yang baru dibuat**
1. Pilih **request-validation-tutorial-console** tumpukan yang baru dibuat.
1. Pilih **Sumber daya**.
1. Di bawah **Physical ID**, pilih API Anda. Tautan ini akan mengarahkan Anda ke konsol API Gateway.
Sebelum Anda memodifikasi `GET` dan `POST` metode, Anda harus membuat model.
**Untuk membuat model**
1. Model diperlukan untuk menggunakan validasi permintaan pada badan permintaan yang masuk. Untuk membuat model, di panel navigasi utama, pilih **Model**.
1. Pilih **Buat model**.
1. Untuk **Nama**, masukkan **PetStoreModel**.
1. Untuk **Jenis Konten**, masukkan**application/json**. Jika tidak ada jenis konten yang cocok ditemukan, validasi permintaan tidak dilakukan. Untuk menggunakan model yang sama terlepas dari jenis konten, masukkan**\$1default**.
1. Untuk **Deskripsi**, masukkan **My PetStore Model** sebagai deskripsi model.
1. Untuk **skema Model**, tempelkan model berikut ke editor kode, dan pilih **Buat**.
```
{
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
}
```
Untuk informasi lebih lanjut tentang model, lihat[Model data untuk REST APIs](models-mappings-models.md).
**Untuk mengkonfigurasi validasi permintaan untuk metode `GET`**
1. Di panel navigasi utama, pilih **Resources**, lalu pilih metode **GET**.
1. Pada tab **Permintaan metode**, di bawah **Pengaturan permintaan metode**, pilih **Edit**.
1. Untuk **validator Permintaan**, pilih **Validasi parameter string kueri** dan header.
1. Di bawah **parameter string kueri URL**, lakukan hal berikut:
1. Pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan **petType**.
1. Aktifkan **Diperlukan**.
1. Tetap **caching** dimatikan.
1. Pilih **Simpan**.
1. Pada tab **Permintaan integrasi**, di bawah **Pengaturan permintaan integrasi**, pilih **Edit**.
1. Di bawah **parameter string kueri URL**, lakukan hal berikut:
1. Pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan **petType**.
1. Untuk **Dipetakan dari**, masukkan**method.request.querystring.petType**. Ini memetakan **petType** ke jenis hewan peliharaan.
Untuk informasi selengkapnya tentang pemetaan data, lihat tutorial [pemetaan data](set-up-data-transformations-in-api-gateway.md#mapping-example-console).
1. Tetap **caching** dimatikan.
1. Pilih **Simpan**.
**Untuk menguji validasi permintaan untuk metode ini `GET`**
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Untuk **string Kueri**, masukkan**petType=dog**, lalu pilih **Uji**.
1. Tes metode akan kembali `200 OK` dan daftar anjing-anjingnya.
Untuk informasi tentang cara mengubah data keluaran ini, lihat [tutorial pemetaan data](set-up-data-transformations-in-api-gateway.md#mapping-example-console).
1. Hapus **petType=dog** dan pilih **Uji**.
1. Tes metode akan mengembalikan `400` kesalahan dengan pesan kesalahan berikut:
```
{
"message": "Missing required request parameters: [petType]"
}
```
**Untuk mengkonfigurasi validasi permintaan untuk metode `POST`**
1. Di panel navigasi utama, pilih **Resources**, lalu pilih metode **POST**.
1. Pada tab **Permintaan metode**, di bawah **Pengaturan permintaan metode**, pilih **Edit**.
1. Untuk **validator Permintaan**, pilih **Validasi** isi.
1. Di bawah **badan Permintaan**, pilih **Tambah model**.
1. Untuk **jenis Konten**, masukkan**application/json**. Jika tidak ada jenis konten yang cocok ditemukan, validasi permintaan tidak dilakukan. Untuk menggunakan model yang sama terlepas dari jenis konten, masukkan`$default`.
Untuk **Model**, pilih **PetStoreModel**.
1. Pilih **Simpan**.
**Untuk menguji validasi permintaan untuk metode `POST`**
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Untuk **Request body** paste berikut ini ke editor kode:
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 400
}
```
Pilih **Uji**.
1. Tes metode akan kembali `200 OK` dan pesan sukses.
1. Untuk **Request body** paste berikut ini ke editor kode:
```
{
"id": 2,
"name": "Bella",
"type": "dog",
"price": 4000
}
```
Pilih **Uji**.
1. Tes metode akan mengembalikan `400` kesalahan dengan pesan kesalahan berikut:
```
{
"message": "Invalid request body"
}
```
Di bagian bawah log pengujian, alasan untuk badan permintaan yang tidak valid dikembalikan. Dalam hal ini, harga hewan peliharaan berada di luar maksimum yang ditentukan dalam model.
**Untuk menghapus CloudFormation tumpukan**
1. Buka CloudFormation konsol di [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Pilih CloudFormation tumpukan Anda.
1. Pilih **Hapus** dan kemudian konfirmasikan pilihan Anda.
### Langkah selanjutnya
+ Untuk informasi tentang cara mengubah data keluaran dan melakukan lebih banyak pemetaan data, lihat tutorial [pemetaan data](set-up-data-transformations-in-api-gateway.md#mapping-example-console).
+ Ikuti [Mengatur validasi permintaan dasar menggunakan AWS CLI](#api-gateway-request-validation-setup-cli) tutorial, untuk melakukan langkah-langkah serupa menggunakan. AWS CLI
## Siapkan validasi permintaan dasar menggunakan AWS CLI
Anda dapat membuat validator untuk menyiapkan validasi permintaan menggunakan. AWS CLI Untuk mengikuti tutorial ini, Anda akan menggunakan CloudFormation template untuk membuat API Gateway API yang tidak lengkap.
**catatan**
Ini bukan CloudFormation template yang sama dengan tutorial konsol.
Menggunakan `/validator` sumber daya pra-ekspos, Anda akan membuat `GET` dan `POST` metode. Kedua metode akan terintegrasi dengan titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Anda akan mengkonfigurasi dua validasi permintaan berikut:
+ Pada `GET` metode ini, Anda akan membuat `params-only` validator untuk memvalidasi parameter string kueri URL.
+ Pada `POST` metode ini, Anda akan membuat `body-only` validator untuk memvalidasi badan permintaan.
Ini akan memungkinkan hanya panggilan API tertentu untuk melewati API.
**Untuk membuat CloudFormation tumpukan**
Unduh dan unzip [template pembuatan aplikasi untuk CloudFormation](samples/request-validation-tutorial-cli.zip).
Untuk menyelesaikan tutorial berikut, Anda memerlukan [AWS Command Line Interface (AWS CLI) versi 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Untuk perintah panjang, karakter escape (`\`) digunakan untuk memisahkan perintah menjadi beberapa baris.
**catatan**
Di Windows, beberapa perintah Bash CLI yang biasa Anda gunakan (`zip`seperti) tidak didukung oleh terminal bawaan sistem operasi. Untuk mendapatkan versi terintegrasi Windows dari Ubuntu dan Bash, [instal Windows Subsystem untuk](https://learn.microsoft.com/en-us/windows/wsl/install) Linux. Contoh perintah CLI dalam panduan ini menggunakan pemformatan Linux. Perintah yang menyertakan dokumen JSON sebaris harus diformat ulang jika Anda menggunakan CLI Windows.
1. Gunakan perintah berikut untuk membuat CloudFormation tumpukan.
```
aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation ketentuan sumber daya yang ditentukan dalam template. Diperlukan beberapa menit untuk menyelesaikan penyediaan sumber daya Anda. Gunakan perintah berikut untuk melihat status CloudFormation tumpukan Anda.
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
```
1. Ketika status CloudFormation tumpukan Anda`StackStatus: "CREATE_COMPLETE"`, gunakan perintah berikut untuk mengambil nilai output yang relevan untuk langkah-langkah masa depan.
```
aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Nilai output adalah sebagai berikut:
+ ApiId, yang merupakan ID untuk API. Untuk tutorial ini, ID API adalah`abc123`.
+ ResourceId, yang merupakan ID untuk sumber daya validator tempat `GET` dan `POST` metode diekspos. Untuk tutorial ini, ID Sumber Daya adalah `efg456`
**Untuk membuat validator permintaan dan mengimpor model**
1. Validator diperlukan untuk menggunakan validasi permintaan dengan file. AWS CLI Gunakan perintah berikut untuk membuat validator yang hanya memvalidasi parameter permintaan.
```
aws apigateway create-request-validator --rest-api-id abc123 \
--no-validate-request-body \
--validate-request-parameters \
--name params-only
```
Perhatikan ID `params-only` validator.
1. Gunakan perintah berikut untuk membuat validator yang hanya memvalidasi badan permintaan.
```
aws apigateway create-request-validator --rest-api-id abc123 \
--validate-request-body \
--no-validate-request-parameters \
--name body-only
```
Perhatikan ID `body-only` validator.
1. Model diperlukan untuk menggunakan validasi permintaan pada badan permintaan yang masuk. Gunakan perintah berikut untuk mengimpor model.
```
aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'
```
Jika tidak ada jenis konten yang cocok ditemukan, validasi permintaan tidak dilakukan. Untuk menggunakan model yang sama terlepas dari jenis konten, tentukan `$default` sebagai kunci.
**Untuk membuat `GET` dan `POST` metode**
1. Gunakan perintah berikut untuk menambahkan metode `GET` HTTP pada `/validate` sumber daya. Perintah ini menciptakan `GET` metode, menambahkan `params-only` validator, dan menetapkan string query `petType` sesuai kebutuhan.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--authorization-type "NONE" \
--request-validator-id aaa111 \
--request-parameters "method.request.querystring.petType=true"
```
Gunakan perintah berikut untuk menambahkan metode `POST` HTTP pada `/validate` sumber daya. Perintah ini membuat `POST` metode, menambahkan `body-only` validator, dan melampirkan model ke validator body-only.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
--request-validator-id bbb222 \
--request-models 'application/json'=PetStoreModel
```
1. Gunakan perintah berikut untuk mengatur `200 OK` respons `GET /validate` metode.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200
```
Gunakan perintah berikut untuk mengatur `200 OK` respons `POST /validate` metode.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Gunakan perintah berikut untuk mengatur `Integration` dengan titik akhir HTTP tertentu untuk `GET /validation` metode ini.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--type HTTP \
--integration-http-method GET \
--request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
Gunakan perintah berikut untuk mengatur `Integration` dengan titik akhir HTTP tertentu untuk `POST /validation` metode ini.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
```
1. Gunakan perintah berikut untuk menyiapkan respons integrasi untuk `GET /validation` metode ini.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456\
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
Gunakan perintah berikut untuk menyiapkan respons integrasi untuk `POST /validation` metode ini.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern ""
```
**Untuk menguji API**
1. Untuk menguji `GET` metode, yang akan melakukan validasi permintaan untuk string query, gunakan perintah berikut:
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--path-with-query-string '/validate?petType=dog'
```
Hasilnya akan mengembalikan daftar `200 OK` dan anjing-anjingnya.
1. Gunakan perintah berikut untuk menguji tanpa menyertakan string kueri `petType`
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
Hasilnya akan mengembalikan `400` kesalahan.
1. Untuk menguji `POST` metode, yang akan melakukan validasi permintaan untuk badan permintaan, gunakan perintah berikut:
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'
```
Hasilnya akan mengembalikan pesan `200 OK` dan sukses.
1. Gunakan perintah berikut untuk menguji menggunakan badan yang tidak valid.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'
```
Hasilnya akan mengembalikan `400` kesalahan, karena harga anjingnya melebihi harga maksimum yang ditentukan oleh model.
**Untuk menghapus CloudFormation tumpukan**
+ Gunakan perintah berikut untuk menghapus CloudFormation sumber daya Anda.
```
aws cloudformation delete-stack --stack-name request-validation-tutorial-cli
```
## Siapkan validasi permintaan dasar menggunakan definisi OpenAPI
Anda dapat mendeklarasikan validator permintaan di API level dengan menentukan satu set [x-amazon-apigateway-request-Validators.requestValidator objek](api-gateway-swagger-extensions-request-validators.requestValidator.md) objek di [x-amazon-apigateway-request-validator objek](api-gateway-swagger-extensions-request-validators.md) peta untuk memilih bagian permintaan mana yang akan divalidasi. Dalam definisi OpenAPI contoh, ada dua validator:
+ `all`validator yang memvalidasi tubuh, menggunakan model `RequestBodyModel` data, dan parameter.
Model `RequestBodyModel` data mengharuskan objek input JSON berisi`name`,`type`, dan `price` properti. `name`Properti dapat berupa string apa pun, `type` harus menjadi salah satu bidang enumerasi yang ditentukan (`["dog", "cat", "fish"]`), dan `price` harus berkisar antara 25 dan 500. `id`Parameter tidak diperlukan.
+ `param-only`yang hanya memvalidasi parameter.
Untuk mengaktifkan validator permintaan pada semua metode API, tentukan [x-amazon-apigateway-requestproperti -validator](api-gateway-swagger-extensions-request-validator.md) properti di tingkat API definisi OpenAPI. Dalam definisi OpenAPI contoh, `all` validator digunakan pada semua metode API, kecuali jika diganti. Saat menggunakan model untuk memvalidasi isi, jika tidak ada jenis konten yang cocok ditemukan, validasi permintaan tidak dilakukan. Untuk menggunakan model yang sama terlepas dari jenis konten, tentukan `$default` sebagai kunci.
Untuk mengaktifkan validator permintaan pada metode individual, tentukan `x-amazon-apigateway-request-validator` properti di tingkat metode. Dalam contoh, definisi OpenAPI, `param-only` validator menimpa validator pada metode. `all` `GET`
Untuk mengimpor contoh OpenAPI ke API Gateway, lihat petunjuk berikut ke [Impor API Regional ke API Gateway](import-export-api-endpoints.md) atau ke. [Impor API yang dioptimalkan tepi ke API Gateway](import-edge-optimized-api.md)
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ReqValidators Sample",
"version" : "1.0.0"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "/v1"
}
}
} ],
"paths" : {
"/validation" : {
"get" : {
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RequestBodyModel"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"test-method-response-header" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ArrayOfError"
}
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"RequestBodyModel" : {
"required" : [ "name", "price", "type" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"maximum" : 500.0,
"minimum" : 25.0,
"type" : "number"
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Error"
}
},
"Error" : {
"type" : "object"
}
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"version" : "1.0.0",
"title" : "ReqValidators Sample"
},
"basePath" : "/v1",
"schemes" : [ "https" ],
"paths" : {
"/validation" : {
"get" : {
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "q1",
"in" : "query",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "params-only",
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.type" : "method.request.querystring.q1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
},
"post" : {
"consumes" : [ "application/json" ],
"produces" : [ "application/json", "application/xml" ],
"parameters" : [ {
"name" : "h1",
"in" : "header",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "RequestBodyModel",
"required" : true,
"schema" : {
"$ref" : "#/definitions/RequestBodyModel"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/ArrayOfError"
},
"headers" : {
"test-method-response-header" : {
"type" : "string"
}
}
}
},
"x-amazon-apigateway-request-validator" : "all",
"x-amazon-apigateway-integration" : {
"httpMethod" : "POST",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
},
"responseTemplates" : {
"application/xml" : "xml 400 response template",
"application/json" : "json 400 response template"
}
},
"2\\d{2}" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.custom_h1" : "method.request.header.h1"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"definitions" : {
"RequestBodyModel" : {
"type" : "object",
"required" : [ "name", "price", "type" ],
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string",
"enum" : [ "dog", "cat", "fish" ]
},
"name" : {
"type" : "string"
},
"price" : {
"type" : "number",
"minimum" : 25.0,
"maximum" : 500.0
}
}
},
"ArrayOfError" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Error"
}
},
"Error" : {
"type" : "object"
}
},
"x-amazon-apigateway-request-validators" : {
"all" : {
"validateRequestParameters" : true,
"validateRequestBody" : true
},
"params-only" : {
"validateRequestParameters" : true,
"validateRequestBody" : false
}
}
}
```
------
# AWS CloudFormation template API sampel dengan validasi permintaan dasar
CloudFormation Contoh definisi template berikut mendefinisikan API sampel dengan validasi permintaan diaktifkan. API adalah bagian dari [PetStoreAPI](http://petstore-demo-endpoint.execute-api.com/petstore/pets). Ini mengekspos `POST` metode untuk menambahkan hewan peliharaan ke `pets` koleksi dan `GET` metode untuk menanyakan hewan peliharaan dengan jenis tertentu.
Ada dua validator permintaan yang dideklarasikan:
**`GETValidator`**
Validator ini diaktifkan pada metode. `GET` Ini memungkinkan API Gateway untuk memverifikasi bahwa parameter kueri yang diperlukan (`q1`) disertakan dan tidak kosong dalam permintaan yang masuk.
**`POSTValidator`**
Validator ini diaktifkan pada metode. `POST` Ini memungkinkan API Gateway untuk memverifikasi bahwa format permintaan payload mematuhi yang ditentukan `RequestBodyModel` ketika jenis konten `application/json` jika tidak ada jenis konten yang cocok ditemukan, validasi permintaan tidak dilakukan. Untuk menggunakan model yang sama terlepas dari jenis konten, tentukan`$default`. `RequestBodyModel`berisi model tambahan,`RequestBodyModelId`, untuk menentukan ID hewan peliharaan.
```
AWSTemplateFormatVersion: 2010-09-09
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: ReqValidatorsSample
RequestBodyModelId:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModelId
properties:
id:
type: integer
RequestBodyModel:
Type: 'AWS::ApiGateway::Model'
Properties:
RestApiId: !Ref Api
ContentType: application/json
Description: Request body model for Pet type, name, price, and ID.
Schema:
$schema: 'http://json-schema.org/draft-04/schema#'
title: RequestBodyModel
required:
- price
- name
- type
type: object
properties:
id:
"$ref": !Sub
- 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}'
- Api: !Ref Api
RequestBodyModelId: !Ref RequestBodyModelId
price:
type: number
minimum: 25
maximum: 500
name:
type: string
type:
type: string
enum:
- "dog"
- "cat"
- "fish"
GETValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: params-only
RestApiId: !Ref Api
ValidateRequestBody: False
ValidateRequestParameters: True
POSTValidator:
Type: AWS::ApiGateway::RequestValidator
Properties:
Name: body-only
RestApiId: !Ref Api
ValidateRequestBody: True
ValidateRequestParameters: False
ValidationResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'validation'
ValidationMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: GET
AuthorizationType: NONE
RequestValidatorId: !Ref GETValidator
RequestParameters:
method.request.querystring.q1: true
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ValidationMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref ValidationResource
HttpMethod: POST
AuthorizationType: NONE
RequestValidatorId: !Ref POSTValidator
RequestModels:
application/json : !Ref RequestBodyModel
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: POST
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- ValidationMethodGet
- RequestBodyModel
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}'
```
# Transformasi data untuk REST APIs di API Gateway
**catatan**
Bagian ini menjelaskan fitur yang Anda gunakan dengan integrasi non-proxy. Namun, kami menyarankan jika memungkinkan, Anda menggunakan integrasi proxy untuk REST API Anda. Integrasi proxy memiliki pengaturan integrasi yang efisien dan dapat berkembang dengan backend tanpa harus meruntuhkan pengaturan yang ada. Untuk informasi selengkapnya, lihat [Pilih jenis integrasi API Gateway API](api-gateway-api-integration-types.md).
Jika Anda menggunakan integrasi non-proxy, Anda dapat menggunakan dua fitur API Gateway untuk mengubah permintaan metode dan respons integrasi Anda. Anda dapat mengubah permintaan metode jika membutuhkan format payload yang berbeda dari payload permintaan integrasi. Anda dapat mengubah respons integrasi Anda jika mengembalikan format payload yang berbeda dari format yang perlu Anda kembalikan dalam respons metode. Untuk informasi selengkapnya tentang siklus hidup permintaan, lihat. [Contoh sumber daya untuk REST API](rest-api-develop.md#rest-api-develop-example)
Contoh berikut menunjukkan transformasi data di mana untuk header`"x-version:beta"`, parameter `x-version` header diubah menjadi parameter `app-version` header. Transformasi data dari `x-version` ke `app-version` terjadi dalam permintaan integrasi. Dengan begitu, titik akhir integrasi menerima nilai parameter header yang diubah. Ketika titik akhir integrasi mengembalikan kode status, kode status diubah dari `200` ke `204` sebelum respons metode.
![\[Diagram transformasi data API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/develop-non-proxy.png)
Untuk membuat transformasi data, Anda dapat menggunakan fitur berikut:
**Pemetaan parameter**
Dalam pemetaan parameter, Anda dapat mengubah parameter jalur URL permintaan integrasi, parameter string kueri URL, atau nilai header HTTP, tetapi Anda tidak dapat mengubah payload permintaan integrasi. Anda juga dapat memodifikasi nilai header respons HTTP. Gunakan pemetaan parameter untuk membuat nilai header statis untuk berbagi sumber daya lintas asal (CORS).
Anda dapat menggunakan pemetaan parameter dalam permintaan integrasi untuk integrasi proxy dan non-proxy, tetapi untuk menggunakan pemetaan parameter untuk respons integrasi, Anda memerlukan integrasi non-proxy. Pemetaan parameter tidak memerlukan skrip apa pun di [Velocity Template Language (](https://velocity.apache.org/engine/devel/vtl-reference.html)VTL). Untuk informasi selengkapnya, lihat [Pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping.md).
**Pemetaan transformasi template**
Dalam transformasi template pemetaan, Anda menggunakan template pemetaan untuk memetakan parameter jalur URL, parameter string kueri URL, header HTTP, dan permintaan integrasi atau badan respons integrasi. *Template pemetaan* adalah skrip yang dinyatakan dalam [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) menggunakan [JSONPath ekspresi](https://goessner.net/articles/JsonPath/) dan diterapkan pada payload berdasarkan header. `Content-type`
Dengan template pemetaan, Anda dapat melakukan hal berikut:
+ Pilih data mana yang akan dikirim menggunakan integrasi Layanan AWS, seperti fungsi Amazon DynamoDB atau Lambda, atau titik akhir HTTP. Untuk informasi selengkapnya, lihat [Tutorial: Memodifikasi permintaan integrasi dan respon untuk integrasi ke layanan AWS](set-up-data-transformations-in-api-gateway.md).
+ Ganti permintaan integrasi API dan parameter respons integrasi secara kondisional, buat nilai header baru, dan ganti kode status. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md).
Anda juga dapat menentukan perilaku API Anda ketika badan permintaan integrasi memiliki `Content-type` header tanpa templat pemetaan yang cocok. Ini disebut perilaku passthrough integrasi. Untuk informasi selengkapnya, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
## Pilih antara pemetaan parameter dan transformasi template pemetaan
Kami menyarankan Anda menggunakan pemetaan parameter untuk mengubah data Anda bila memungkinkan. Jika API Anda mengharuskan Anda mengubah isi, atau mengharuskan Anda melakukan penggantian dan modifikasi bersyarat berdasarkan permintaan integrasi atau respons integrasi yang masuk, dan Anda tidak dapat menggunakan integrasi proxy, gunakan transformasi templat pemetaan.
# Pemetaan parameter untuk REST APIs di API Gateway
**catatan**
Jika Anda menggunakan API HTTP, lihat[Mengubah permintaan dan tanggapan API untuk HTTP APIs di API Gateway](http-api-parameter-mapping.md).
Dalam pemetaan parameter, Anda memetakan parameter permintaan atau respons. Anda dapat memetakan parameter menggunakan ekspresi pemetaan parameter atau nilai statis. Untuk daftar ekspresi pemetaan, lihat[Referensi sumber pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping-sources.md). Anda dapat menggunakan pemetaan parameter dalam permintaan integrasi untuk integrasi proxy dan non-proxy, tetapi untuk menggunakan pemetaan parameter untuk respons integrasi, Anda memerlukan integrasi non-proxy.
Misalnya, Anda dapat memetakan parameter header permintaan metode `puppies` ke parameter header permintaan integrasi`DogsAge0`. Kemudian, jika klien mengirim header `puppies:true` ke API Anda, permintaan integrasi mengirimkan header permintaan `DogsAge0:true` ke titik akhir integrasi. Diagram berikut menunjukkan siklus hidup permintaan dari contoh ini.
![\[Diagram contoh pemetaan parameter API Gateway untuk permintaan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Untuk membuat contoh ini menggunakan API Gateway, lihat[Contoh 1: Petakan parameter permintaan metode ke parameter permintaan integrasi](request-response-data-mappings.md#request-response-data-mappings-example-1).
Sebagai contoh lain, Anda juga dapat memetakan parameter header respons integrasi `kittens` ke parameter header respons metode`CatsAge0`. Kemudian, jika titik akhir integrasi kembali`kittens:false`, klien menerima header`CatsAge0:false`. Diagram berikut menunjukkan siklus hidup permintaan dari contoh ini.
![\[Diagram contoh pemetaan parameter API Gateway untuk respons\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [Contoh pemetaan parameter untuk REST APIs di API Gateway](request-response-data-mappings.md)
+ [Referensi sumber pemetaan parameter untuk REST APIs di API Gateway](rest-api-parameter-mapping-sources.md)
# Contoh pemetaan parameter untuk REST APIs di API Gateway
Contoh berikut menunjukkan cara membuat ekspresi pemetaan parameter menggunakan konsol API Gateway, OpenAPI, CloudFormation dan template. Untuk contoh cara menggunakan pemetaan parameter untuk membuat header CORS yang diperlukan, lihat. [CORS untuk REST APIs di API Gateway](how-to-cors.md)
## Contoh 1: Petakan parameter permintaan metode ke parameter permintaan integrasi
Contoh berikut memetakan parameter header permintaan metode `puppies` ke parameter header permintaan integrasi`DogsAge0`.
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan parameter permintaan metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **header permintaan HTTP**.
1. Pilih **Tambahkan header**.
1. Untuk **Nama**, masukkan **puppies**.
1. Pilih **Simpan**.
1. Pilih tab **Permintaan integrasi**, dan kemudian untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
Konsol Manajemen AWS Secara otomatis menambahkan pemetaan parameter dari `method.request.header.puppies ` ke `puppies` untuk Anda, tetapi Anda perlu mengubah **Nama** agar sesuai dengan parameter header permintaan yang diharapkan oleh titik akhir integrasi Anda.
1. Untuk **Nama**, masukkan **DogsAge0**.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
Langkah-langkah berikut menunjukkan cara memverifikasi bahwa pemetaan parameter Anda berhasil.
**(Opsional) Uji pemetaan parameter Anda**
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Untuk header, masukkan**puppies:true**.
1. Pilih **Uji**.
1. Dalam **Log**, hasilnya akan terlihat seperti berikut:
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
Parameter header permintaan telah berubah dari `puppies` menjadi`DogsAge0`.
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Contoh 2: Petakan beberapa parameter permintaan metode ke parameter permintaan integrasi yang berbeda
Contoh berikut memetakan parameter string permintaan metode multi-nilai `methodRequestQueryParam` ke parameter string kueri permintaan integrasi `integrationQueryParam` dan memetakan parameter header permintaan metode `methodRequestHeaderParam` ke parameter `integrationPathParam` jalur permintaan integrasi.
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan parameter permintaan metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **parameter string kueri URL**.
1. Pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan **methodRequestQueryParam**.
1. Pilih **header permintaan HTTP**.
1. Pilih **Tambahkan header**.
1. Untuk **Nama**, masukkan **methodRequestHeaderParam**.
1. Pilih **Simpan**.
1. Pilih tab **Permintaan integrasi**, dan kemudian untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Pilih **parameter jalur URL**.
1. Pilih **Tambahkan parameter jalur**.
1. Untuk **Nama**, masukkan **integrationPathParam**.
1. Untuk **Dipetakan dari**, masukkan**method.request.header.methodRequestHeaderParam**.
Ini memetakan header permintaan metode yang Anda tentukan dalam permintaan metode ke parameter jalur permintaan integrasi baru.
1. Pilih **parameter string kueri URL**.
1. Pilih **Tambahkan string kueri**.
1. Untuk **Nama**, masukkan **integrationQueryParam**.
1. Untuk **Dipetakan dari**, masukkan**method.request.multivaluequerystring.methodRequestQueryParam**.
Ini memetakan parameter string kueri multivalue ke parameter string kueri permintaan integrasi bernilai tunggal baru.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
Definisi OpenAPI berikut membuat pemetaan parameter berikut untuk integrasi HTTP:
+ Header permintaan metode, bernama`methodRequestHeaderParam`, ke dalam parameter jalur permintaan integrasi, bernama `integrationPathParam`
+ Metode multi-nilai meminta string kueri, bernama`methodRequestQueryParam`, ke dalam string permintaan permintaan integrasi, bernama `integrationQueryParam`
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Definisi OpenAPI berikut membuat pemetaan parameter berikut untuk integrasi HTTP:
+ Header permintaan metode, bernama`methodRequestHeaderParam`, ke dalam parameter jalur permintaan integrasi, bernama `integrationPathParam`
+ Metode multi-nilai meminta string kueri, bernama`methodRequestQueryParam`, ke dalam string permintaan permintaan integrasi, bernama `integrationQueryParam`
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Contoh 3: Memetakan bidang dari badan permintaan JSON ke parameter permintaan integrasi
Anda juga dapat memetakan parameter permintaan integrasi dari bidang di badan permintaan JSON menggunakan [JSONPath ekspresi](http://goessner.net/articles/JsonPath/index.html#e2). Contoh berikut memetakan badan permintaan metode ke header permintaan integrasi bernama `body-header` dan memetakan bagian dari badan permintaan, seperti yang dinyatakan oleh ekspresi JSON ke header permintaan integrasi bernama`pet-price`.
Untuk menguji contoh ini, berikan masukan yang berisi kategori harga, seperti berikut ini:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan parameter permintaan metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih`POST`,, `PUT``PATCH`, atau `ANY` metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Pilih **parameter header permintaan URL**.
1. Pilih **Tambahkan parameter header permintaan**.
1. Untuk **Nama**, masukkan **body-header**.
1. Untuk **Dipetakan dari**, masukkan**method.request.body**.
Ini memetakan badan permintaan metode ke parameter header permintaan integrasi baru.
1. Pilih **Tambahkan parameter header permintaan**.
1. Untuk **Nama**, masukkan **pet-price**.
1. Untuk **Dipetakan dari**, masukkan** method.request.body[0].price**.
Ini memetakan bagian dari badan permintaan metode ke parameter header permintaan integrasi baru.
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Parameter permintaan integrasi peta definisi OpenAPI berikut dari bidang di badan permintaan JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Contoh 4: Petakan respons integrasi terhadap respons metode
Anda juga dapat memetakan respons integrasi ke respons metode. Contoh berikut memetakan badan respons integrasi ke header respons metode bernama`location`, memetakan header respons integrasi `x-app-id` ke header respons metode`id`, dan memetakan header respons integrasi multi-nilai `item` ke header `items` respons metode.
------
#### [ Konsol Manajemen AWS ]
**Untuk memetakan respon integrasi**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Pilih metode.
Metode Anda harus memiliki integrasi non-proxy.
1. Pilih tab **respons Metode**, dan kemudian untuk **Respons 200**, pilih **Edit**.
1. Untuk **nama Header**, pilih **Tambahkan header**.
1. Buat tiga header bernama**id**,**item**, dan**location**.
1. Pilih **Simpan**.
1. Pilih tab **Integrasi respon**, dan kemudian untuk **Default - Respons**, pilih **Edit**.
1. Di bawah **pemetaan Header**, masukkan yang berikut ini.
1. Untuk **id**, masukkan **integration.response.header.x-app-id**
1. Untuk **item**, masukkan **integration.response.multivalueheader.item**
1. Untuk **lokasi**, masukkan **integration.response.body.redirect.url**
1. Pilih **Simpan**.
1. Menerapkan ulang API Anda agar perubahan diterapkan.
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Definisi OpenAPI berikut memetakan respons integrasi terhadap respons metode.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# Referensi sumber pemetaan parameter untuk REST APIs di API Gateway
Saat Anda membuat pemetaan parameter, Anda menentukan permintaan metode atau parameter respons integrasi untuk dimodifikasi dan Anda menentukan cara memodifikasi parameter tersebut.
Tabel berikut menunjukkan parameter permintaan metode yang dapat Anda petakan, dan ekspresi untuk membuat pemetaan. Dalam ekspresi ini, *name* adalah nama parameter permintaan metode. Misalnya, untuk memetakan parameter header permintaan`puppies`, gunakan ekspresi`method.request.header.puppies`. Ekspresi Anda harus sesuai dengan ekspresi reguler`'^[a-zA-Z0-9._$-]+$]'`. Anda dapat menggunakan pemetaan parameter dalam permintaan integrasi untuk integrasi proxy dan non-proxy.
| **Sumber data yang dipetakan** | **Ekspresi pemetaan** |
| --- | --- |
| Jalur permintaan metode | method.request.path.name |
| String kueri permintaan metode | method.request.querystring.name |
| String kueri permintaan metode multi-nilai | method.request.multivaluequerystring.name |
| Header permintaan metode | method.request.header.name |
| Header permintaan metode multi-nilai | method.request.multivalueheader.name |
| Badan permintaan metode | method.request.body |
| Metode permintaan badan (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*adalah JSONPath ekspresi untuk bidang JSON dari badan permintaan. Untuk informasi lebih lanjut, lihat [JSONPath ekspresi](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variabel tahap | stageVariables.name |
| Variabel konteks | `context.name` Nama harus menjadi salah satu [variabel konteks yang didukung](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Nilai statis | `'static_value'`. *static\$1value*Ini adalah string literal dan harus diapit dalam sepasang tanda kutip tunggal. Misalnya, `'https://www.example.com'`. |
Tabel berikut menunjukkan parameter respons integrasi yang dapat Anda petakan dan ekspresi untuk membuat pemetaan. Dalam ekspresi ini, *name* adalah nama parameter respons integrasi. Anda dapat memetakan header respons metode dari header respons integrasi atau badan respons integrasi, variabel \$1context, atau nilai statis. Untuk menggunakan pemetaan parameter untuk respons integrasi, Anda memerlukan integrasi non-proxy.
| Sumber data yang dipetakan | Ekspresi pemetaan |
| --- | --- |
| Header respon integrasi | integration.response.header.name |
| Header respon integrasi | integration.response.multivalueheader.name |
| Badan respons integrasi | integration.response.body |
| Integrasi respon body (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*adalah JSONPath ekspresi untuk bidang JSON dari tubuh respons. Untuk informasi lebih lanjut, lihat [JSONPath ekspresi](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variabel tahap | stageVariables.name |
| Variabel konteks | `context.name` Nama harus menjadi salah satu [variabel konteks yang didukung](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Nilai statis | ` 'static_value'` *static\$1value*Ini adalah string literal dan harus diapit dalam sepasang tanda kutip tunggal. Misalnya, `'https://www.example.com'`. |
# Memetakan transformasi template untuk REST APIs di API Gateway
Transformasi template pemetaan menggunakan template pemetaan untuk memodifikasi permintaan integrasi atau respons integrasi Anda. *Template pemetaan* adalah skrip yang dinyatakan dalam [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) dan diterapkan ke payload menggunakan [JSONPath ](https://goessner.net/articles/JsonPath/)berdasarkan header. `Content-type` Anda menggunakan templat pemetaan saat menggunakan transformasi templat pemetaan. Bagian ini menjelaskan informasi konseptual yang terkait dengan templat pemetaan.
Diagram berikut menunjukkan siklus hidup permintaan untuk `POST /pets` sumber daya yang memiliki integrasi dengan titik akhir PetStore integrasi. Di API ini, pengguna mengirim data tentang hewan peliharaan dan titik akhir integrasi mengembalikan biaya adopsi yang terkait dengan hewan peliharaan. Dalam siklus hidup permintaan ini, transformasi templat pemetaan memfilter badan permintaan ke titik akhir integrasi dan memfilter badan respons dari titik akhir integrasi.
![\[Contoh siklus hidup permintaan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/mapping-template-transforms.png)
Bagian berikut menjelaskan siklus hidup permintaan dan respons.
## Permintaan metode dan permintaan integrasi
Pada contoh sebelumnya, jika ini adalah badan permintaan yang dikirim ke permintaan metode:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Badan permintaan ini tidak dalam format yang benar untuk digunakan oleh titik akhir integrasi, sehingga API Gateway melakukan transformasi template pemetaan. API Gateway hanya melakukan transformasi template pemetaan karena ada template pemetaan yang ditentukan untuk Content-Type. `application/json` Jika Anda tidak mendefinisikan template pemetaan untuk Content-Type, secara default, API Gateway meneruskan isi melalui permintaan integrasi ke titik akhir integrasi. Untuk mengubah perilaku ini, lihat[Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
Template pemetaan berikut mengubah data permintaan metode dalam permintaan integrasi sebelum dikirim ke titik akhir integrasi:
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. `$inputRoot`Variabel mewakili objek root dalam data JSON asli dari bagian sebelumnya. Arahan dimulai dengan `#` simbol.
1. `dog`Ini adalah gabungan dari pengguna `id` dan nilai string.
1. `Age`berasal dari badan permintaan metode.
Kemudian, output berikut diteruskan ke titik akhir integrasi:
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Respon integrasi dan respons metode
Setelah permintaan berhasil ke titik akhir integrasi, titik akhir mengirimkan respons ke respons integrasi API Gateway. Berikut ini adalah contoh data output dari endpoint integrasi:
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
Respons metode mengharapkan muatan yang berbeda dari apa yang dikembalikan oleh respons integrasi. API Gateway melakukan transformasi template pemetaan. API Gateway hanya melakukan transformasi template pemetaan karena ada template pemetaan yang ditentukan untuk Content-Type. `application/json` Jika Anda tidak mendefinisikan template pemetaan untuk Content-Type, secara default, API Gateway meneruskan isi melalui respons integrasi ke respons metode. Untuk mengubah perilaku ini, lihat[Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
Output berikut dikirim ke respon metode:
```
{"adoptionFee": 19.95}
```
Ini melengkapi contoh transformasi template pemetaan. Sebaiknya jika memungkinkan, alih-alih menggunakan transformasi templat pemetaan, Anda menggunakan integrasi proxy untuk mengubah data Anda. Untuk informasi selengkapnya, lihat [Pilih jenis integrasi API Gateway API](api-gateway-api-integration-types.md).
# Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway
Jika permintaan metode Anda memiliki payload dan Anda tidak memiliki template pemetaan yang ditentukan untuk `Content-Type` header, Anda dapat memilih untuk meneruskan payload permintaan yang disediakan klien melalui permintaan integrasi ke backend tanpa transformasi. Proses ini dikenal sebagai integrasi passthrough.
Perilaku passthrough aktual dari permintaan yang masuk ditentukan oleh pengaturan ini. Ada tiga opsi:
**Bila tidak ada template yang cocok dengan header Content-Type permintaan**
Pilih opsi ini jika Anda ingin badan permintaan metode melewati permintaan integrasi ke backend tanpa transformasi ketika jenis konten permintaan metode tidak cocok dengan jenis konten apa pun yang terkait dengan templat pemetaan.
Saat memanggil API Gateway API, Anda memilih opsi ini dengan menetapkan `WHEN_NO_MATCH` sebagai nilai `passthroughBehavior` properti pada [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Ketika tidak ada templat yang ditentukan (disarankan)**
Pilih opsi ini jika Anda ingin badan permintaan metode melewati permintaan integrasi ke backend tanpa transformasi ketika tidak ada templat pemetaan yang ditentukan dalam permintaan integrasi. Jika templat ditentukan saat opsi ini dipilih, permintaan metode dengan jenis muatan dan konten yang tidak cocok dengan templat pemetaan yang ditentukan akan ditolak dengan respons Jenis Media Tidak Didukung HTTP 415.
Saat memanggil API Gateway API, Anda memilih opsi ini dengan menetapkan `WHEN_NO_TEMPLATES` sebagai nilai `passthroughBehavior` properti pada [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Tidak pernah**
Pilih opsi ini jika Anda tidak ingin badan permintaan metode melewati permintaan integrasi ke backend tanpa transformasi ketika tidak ada templat pemetaan yang ditentukan dalam permintaan integrasi. Jika templat ditentukan saat opsi ini dipilih, permintaan metode dari jenis konten yang tidak dipetakan akan ditolak dengan respons Jenis Media Tidak Didukung HTTP 415.
Saat memanggil API Gateway API, Anda memilih opsi ini dengan menetapkan `NEVER` sebagai nilai `passthroughBehavior` properti pada [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Contoh berikut menunjukkan kemungkinan perilaku passthrough.
Contoh 1: Satu template pemetaan didefinisikan dalam permintaan integrasi untuk jenis `application/json` konten.
| Tipe konten | Opsi passthrough | Perilaku |
| --- | --- | --- |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1MATCH | Muatan permintaan diubah menggunakan templat. |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1TEMPLATES | Muatan permintaan diubah menggunakan templat. |
| Tidak ada API Gateway default ke `application/json` | NEVER | Muatan permintaan diubah menggunakan templat. |
| application/json | WHEN\$1NO\$1MATCH | Muatan permintaan diubah menggunakan templat. |
| application/json | WHEN\$1NO\$1TEMPLATES | Muatan permintaan diubah menggunakan templat. |
| application/json | NEVER | Muatan permintaan diubah menggunakan templat. |
| application/xml | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/xml | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
Contoh 2: Satu template pemetaan didefinisikan dalam permintaan integrasi untuk jenis `application/xml` konten.
| Tipe konten | Opsi passthrough | Perilaku |
| --- | --- | --- |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1TEMPLATES | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| Tidak ada API Gateway default ke `application/json` | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/json | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/json | WHEN\$1NO\$1TEMPLATES | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/json | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/xml | WHEN\$1NO\$1MATCH | Muatan permintaan diubah menggunakan templat. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Muatan permintaan diubah menggunakan templat. |
| application/xml | NEVER | Muatan permintaan diubah menggunakan templat. |
Contoh 3: Tidak ada templat pemetaan yang ditentukan dalam permintaan integrasi.
| Tipe konten | Opsi passthrough | Perilaku |
| --- | --- | --- |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| Tidak ada API Gateway default ke `application/json` | WHEN\$1NO\$1TEMPLATES | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| Tidak ada API Gateway default ke `application/json` | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/json | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/json | WHEN\$1NO\$1TEMPLATES | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/json | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
| application/xml | WHEN\$1NO\$1MATCH | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/xml | WHEN\$1NO\$1TEMPLATES | Payload permintaan tidak diubah dan dikirim ke backend apa adanya. |
| application/xml | NEVER | Permintaan ditolak dengan 415 Unsupported Media Type respons HTTP. |
# Contoh template pemetaan tambahan untuk REST APIs di API Gateway
Contoh berikut menunjukkan API album foto di API Gateway yang menggunakan templat pemetaan untuk mengubah permintaan integrasi dan data respons integrasi. Ini juga menggunakan model data untuk menentukan permintaan metode dan muatan respons integrasi. Untuk informasi selengkapnya tentang model data, lihat[Model data untuk REST APIs](models-mappings-models.md).
## Permintaan metode dan permintaan integrasi
Berikut ini adalah model yang mendefinisikan badan permintaan metode. Model input ini mengharuskan penelepon mengunggah satu halaman foto, dan membutuhkan minimal 10 foto untuk setiap halaman. Anda dapat menggunakan model input ini untuk menghasilkan SDK atau menggunakan validasi permintaan untuk API Anda. Saat menggunakan validasi permintaan, jika badan permintaan metode tidak mematuhi struktur data model, API Gateway gagal permintaan.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
Berikut ini adalah contoh badan permintaan metode yang mematuhi struktur data dari model data sebelumnya.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
Dalam contoh ini, jika badan permintaan metode sebelumnya dikirimkan oleh klien, maka template pemetaan ini mengubah payload agar sesuai dengan format yang diperlukan oleh titik akhir integrasi.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
Contoh berikut adalah data output dari transformasi:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Data ini dikirim ke permintaan integrasi, dan kemudian ke titik akhir integrasi.
## Respon integrasi dan respons metode
Berikut ini adalah contoh model keluaran untuk data foto dari titik akhir integrasi. Anda dapat menggunakan model ini untuk model respons metode, yang diperlukan saat Anda membuat SDK yang diketik kuat untuk API. Hal ini menyebabkan output dilemparkan ke kelas yang sesuai di Java atau Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
Titik akhir integrasi mungkin tidak merespons dengan respons yang mematuhi struktur data model ini. Misalnya, respons integrasi mungkin terlihat seperti berikut:
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
Contoh template pemetaan berikut mengubah data respons integrasi ke dalam format yang diharapkan oleh respons metode:
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
Contoh berikut adalah data output dari transformasi:
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Data ini dikirim ke respons metode dan kemudian kembali ke klien.
# Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway
Anda dapat menggunakan transformasi templat pemetaan untuk mengganti semua jenis parameter permintaan, header respons, atau kode status respons. Anda menggunakan template pemetaan untuk melakukan hal berikut:
+ Lakukan pemetaan many-to-one parameter
+ Ganti parameter setelah pemetaan API Gateway standar diterapkan
+ Parameter peta kondisional berdasarkan konten tubuh atau nilai parameter lainnya
+ Buat parameter baru secara terprogram
+ Ganti kode status yang dikembalikan oleh titik akhir integrasi Anda
Override adalah final. Override hanya dapat diterapkan ke setiap parameter satu kali. Jika Anda mencoba mengganti parameter yang sama beberapa kali, API Gateway mengembalikan `5XX` respons. Jika Anda harus mengganti parameter yang sama beberapa kali di seluruh template, kami sarankan membuat variabel dan menerapkan override di akhir template. Template diterapkan hanya setelah seluruh template diurai.
## Contoh 1: Ganti kode status berdasarkan badan integrasi
Contoh berikut menggunakan [API contoh](api-gateway-create-api-from-example.md) untuk mengganti kode status berdasarkan badan respons integrasi.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengganti kode status berdasarkan badan respons integrasi**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Buat API**.
1. Untuk **REST API**, pilih **Build**.
1. Untuk **detail API**, pilih **API Contoh**.
1. Pilih **Buat API**.
API Gateway membuat contoh API toko hewan peliharaan. Untuk mengambil informasi tentang hewan peliharaan, Anda menggunakan permintaan metode API`GET /pets/{petId}`, di mana `{petId}` parameter jalur yang sesuai dengan nomor ID untuk hewan peliharaan.
Dalam contoh ini, Anda mengganti kode respons `GET` metode `400` saat kondisi kesalahan terdeteksi.
1. Di pohon **Resources**, pilih `GET` metode di bawah`/{petId}`.
1. Pertama, Anda menguji implementasi API saat ini.
Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. **Untuk **PeTiD**, masukkan**-1**, lalu pilih Test.**
**Badan Respons** menunjukkan out-of-range kesalahan:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Selain itu, baris terakhir di bawah **Log** diakhiri dengan:`Method completed with status: 200`.
Integrasi berhasil diselesaikan, tetapi ada kesalahan. Sekarang Anda akan mengganti kode status berdasarkan respons integrasi.
1. Pada tab **Respons Integrasi**, untuk **Default - Respons**, pilih **Edit**.
1. Pilih **template Pemetaan**.
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Template pemetaan ini menggunakan `$context.responseOverride.status` variabel untuk mengganti kode status `400` jika respons integrasi berisi string. `error`
1. Pilih **Simpan**.
1. Pilih tab **Uji**.
1. Untuk **PeTiD, masukkan**. **-1**
1. 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 **Log** sekarang berakhir dengan:`Method completed with status: 400`.
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Definisi OpenAPI berikut membuat `GET pets/{petId}` sumber daya dan mengganti kode status berdasarkan badan integrasi.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Contoh 2: Ganti header permintaan dan buat header baru
Contoh berikut menggunakan [API contoh](api-gateway-create-api-from-example.md) untuk mengganti header permintaan dan membuat header baru.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengganti header permintaan metode dengan membuat header baru**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih contoh API yang Anda buat di tutorial sebelumnya. Nama API seharusnya **PetStore**.
1. Di pohon **Resources**, pilih `GET` metode di bawah`/pet`.
1. Pada tab **Permintaan metode**, untuk **pengaturan permintaan Metode**, pilih **Edit**.
1. Pilih **header permintaan HTTP**, lalu pilih **Tambah header**.
1. Untuk **Nama**, masukkan **header1**.
1. Pilih **Tambahkan header**, lalu buat header kedua yang disebut**header2**.
1. Pilih **Simpan**.
Sekarang, Anda menggabungkan header ini menjadi satu nilai header menggunakan template pemetaan.
1. Pada tab **Permintaan integrasi**, untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
1. Untuk **Request body passthrough**, pilih **Bila tidak ada templat yang ditentukan (disarankan)**.
1. Pilih **template Pemetaan**, lalu lakukan hal berikut:
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
#set($header1Override = "pets")
#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])
```
Template pemetaan ini diganti `header1` dengan string `pets` dan membuat header multi-nilai yang disebut `$header3Value` yang menggabungkan dan. `header1` `header2`
1. Pilih **Simpan**.
1. Pilih tab **Uji**.
1. Di bawah **Header**, salin kode berikut:
```
header1:header1Val
header2:header2Val
```
1. Pilih **Uji**.
Di **Log**, Anda akan melihat entri yang menyertakan teks ini:
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
Dalam contoh ini, Anda menggunakan properti [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) untuk mengimpor file definisi OpenAPI ke API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#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])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
Definisi OpenAPI berikut membuat `GET pets` sumber daya dan mengganti header permintaan dan membuat header baru.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Untuk menggunakan penggantian template pemetaan, tambahkan satu atau beberapa variabel berikut`$context`. Untuk daftar `$context` variabel, lihat[Variabel konteks untuk transformasi data](api-gateway-mapping-template-reference.md#context-variable-reference).
# Tutorial: Memodifikasi permintaan integrasi dan respon untuk integrasi ke layanan AWS
Tutorial berikut menunjukkan cara menggunakan transformasi template pemetaan untuk mengatur template pemetaan untuk mengubah permintaan integrasi dan tanggapan menggunakan konsol dan CLI. AWS
**Topics**
+ [Mengatur transformasi data menggunakan konsol API Gateway](#mapping-example-console)
+ [Mengatur transformasi data menggunakan AWS CLI](#mapping-example-cli)
+ [CloudFormation Templat transformasi data yang lengkap](#api-gateway-data-transformations-full-cfn-stack)
## Mengatur transformasi data menggunakan konsol API Gateway
[Dalam tutorial ini, Anda akan membuat tabel API dan DynamoDB yang tidak lengkap menggunakan file.zip berikut.zip. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) API yang tidak lengkap ini memiliki `/pets` sumber daya dengan `GET` dan `POST` metode.
+ `GET`Metode ini akan mendapatkan data dari titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Data keluaran akan diubah sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
+ `POST`Metode ini akan memungkinkan pengguna untuk menyimpan informasi `POST` ke tabel Amazon DynamoDB menggunakan template pemetaan.
Unduh dan unzip [template pembuatan aplikasi untuk CloudFormation](samples/data-transformation-tutorial-console.zip). Anda akan menggunakan template ini untuk membuat tabel DynamoDB untuk memposting informasi hewan peliharaan dan API yang tidak lengkap. Anda akan menyelesaikan langkah-langkah lainnya di konsol API Gateway.
**Untuk membuat CloudFormation tumpukan**
1. Buka CloudFormation konsol di [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Pilih **Buat tumpukan** kemudian pilih **Dengan sumber daya baru (standar)**.
1. Untuk **Tentukan templat**, pilih **Unggah file templat**.
1. Pilih template yang Anda unduh.
1. Pilih **Berikutnya**.
1. Untuk **nama Stack**, masukkan **data-transformation-tutorial-console** dan kemudian pilih **Berikutnya**.
1. Untuk **opsi Konfigurasi tumpukan**, pilih **Berikutnya**.
1. Untuk **Kemampuan**, akui bahwa CloudFormation dapat membuat sumber daya IAM di akun Anda.
1. Pilih **Berikutnya**, lalu pilih **Kirim**.
CloudFormation ketentuan sumber daya yang ditentukan dalam template. Diperlukan beberapa menit untuk menyelesaikan penyediaan sumber daya Anda. Ketika status CloudFormation tumpukan Anda adalah **CREATE\$1COMPLETE**, Anda siap untuk melanjutkan ke langkah berikutnya.
**Untuk menguji respon `GET` integrasi**
1. Pada tab **Sumber Daya** CloudFormation tumpukan untuk**data-transformation-tutorial-console**, pilih ID fisik API Anda.
1. Di panel navigasi utama, pilih **Resources**, lalu pilih metode **GET**.
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
Output dari tes akan menunjukkan yang berikut:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Anda akan mengubah output ini sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
**Untuk mengubah respon `GET` integrasi**
1. Pilih tab **Respons Integrasi**.
Saat ini, tidak ada template pemetaan yang ditentukan, sehingga respons integrasi tidak akan diubah.
1. Untuk **Default - Respons**, pilih **Edit**.
1. Pilih **template Pemetaan**, lalu lakukan hal berikut:
1. Pilih **Tambahkan templat pemetaan**.
1. Untuk **jenis Konten**, masukkan**application/json**.
1. Untuk **badan Template**, masukkan yang berikut ini:
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Pilih **Simpan**.
**Untuk menguji respon `GET` integrasi**
+ Pilih tab **Test**, lalu pilih **Test**.
Output dari tes akan menunjukkan respons yang diubah.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Untuk mengubah data masukan dari `POST` metode**
1. Pilih metode **POST**.
1. Pilih tab **Permintaan integrasi**, dan kemudian untuk **pengaturan permintaan Integrasi**, pilih **Edit**.
CloudFormation Template telah mengisi beberapa bidang permintaan integrasi.
+ Jenis integrasi adalah Layanan AWS.
+ Layanan AWS Ini adalah DynamoDB.
+ Metode HTTP adalah`POST`.
+ Tindakan adalah`PutItem`.
+ Peran Eksekusi yang memungkinkan API Gateway untuk menempatkan item ke dalam tabel DynamoDB adalah. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation membuat peran ini untuk memungkinkan API Gateway memiliki izin minimal untuk berinteraksi dengan DynamoDB.
Nama tabel DynamoDB belum ditentukan. Anda akan menentukan nama dalam langkah-langkah berikut.
1. Untuk **Request body passthrough**, pilih **Never**.
Ini berarti bahwa API akan menolak data dengan Content-Types yang tidak memiliki template pemetaan.
1. Pilih **template Pemetaan**.
1. **Jenis Konten** diatur ke`application/json`. Ini berarti jenis konten yang tidak application/json akan ditolak oleh API. Untuk informasi selengkapnya tentang perilaku passthrough integrasi, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md)
1. Masukkan kode berikut ke dalam editor teks.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Template ini menentukan tabel sebagai `data-transformation-tutorial-console-ddb` dan menetapkan item sebagai`id`,`type`, dan`price`. Item akan berasal dari tubuh `POST` metode. Anda juga dapat menggunakan model data untuk membantu membuat template pemetaan. Untuk informasi selengkapnya, lihat [Minta validasi untuk REST APIs di API Gateway](api-gateway-method-request-validation.md).
1. Pilih **Simpan** untuk menyimpan template pemetaan Anda.
**Untuk menambahkan metode dan respons integrasi dari `POST` metode**
CloudFormation Membuat metode kosong dan respons integrasi. Anda akan mengedit tanggapan ini untuk memberikan informasi lebih lanjut. Untuk informasi selengkapnya tentang cara mengedit tanggapan, lihat[Contoh pemetaan parameter untuk REST APIs di API Gateway](request-response-data-mappings.md).
1. Pada tab **Respons Integrasi**, untuk **Default - Respons**, pilih **Edit**.
1. Pilih **Templat pemetaan**, lalu pilih **Tambahkan templat pemetaan**.
1. Untuk **tipe Konten, masukkan**. **application/json**
1. Di editor kode, masukkan template pemetaan keluaran berikut untuk mengirim pesan output:
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Untuk informasi lebih lanjut tentang variabel konteks, lihat[Variabel konteks untuk transformasi data](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Pilih **Simpan** untuk menyimpan template pemetaan Anda.
**Uji `POST` metodenya**
Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
1. Di badan permintaan, masukkan contoh berikut.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Pilih **Uji**.
Output harus menunjukkan pesan sukses Anda.
Anda dapat membuka konsol DynamoDB [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)di untuk memverifikasi bahwa item contoh ada di tabel Anda.
**Untuk menghapus CloudFormation tumpukan**
1. Buka CloudFormation konsol di [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Pilih CloudFormation tumpukan Anda.
1. Pilih **Hapus** dan kemudian konfirmasikan pilihan Anda.
## Mengatur transformasi data menggunakan AWS CLI
[Dalam tutorial ini, Anda akan membuat tabel API dan DynamoDB yang tidak lengkap menggunakan file.zip berikut.zip. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) API yang tidak lengkap ini memiliki `/pets` sumber daya dengan `GET` metode yang terintegrasi dengan titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Anda akan membuat `POST` metode untuk terhubung ke tabel DynamoDB dan menggunakan template pemetaan untuk memasukkan data ke dalam tabel DynamoDB.
+ Anda akan mengubah data keluaran sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
+ Anda akan membuat `POST` metode untuk memungkinkan pengguna untuk menyimpan informasi ke `POST` tabel Amazon DynamoDB menggunakan template pemetaan.
**Untuk membuat CloudFormation tumpukan**
Unduh dan unzip [template pembuatan aplikasi untuk CloudFormation](samples/data-transformation-tutorial-cli.zip).
Untuk menyelesaikan tutorial berikut, Anda memerlukan [AWS Command Line Interface (AWS CLI) versi 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Untuk perintah panjang, karakter escape (`\`) digunakan untuk memisahkan perintah menjadi beberapa baris.
**catatan**
Di Windows, beberapa perintah Bash CLI yang biasa Anda gunakan (`zip`seperti) tidak didukung oleh terminal bawaan sistem operasi. Untuk mendapatkan versi terintegrasi Windows dari Ubuntu dan Bash, [instal Windows Subsystem untuk](https://learn.microsoft.com/en-us/windows/wsl/install) Linux. Contoh perintah CLI dalam panduan ini menggunakan pemformatan Linux. Perintah yang menyertakan dokumen JSON sebaris harus diformat ulang jika Anda menggunakan CLI Windows.
1. Gunakan perintah berikut untuk membuat CloudFormation tumpukan.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation ketentuan sumber daya yang ditentukan dalam template. Diperlukan beberapa menit untuk menyelesaikan penyediaan sumber daya Anda. Gunakan perintah berikut untuk melihat status CloudFormation tumpukan Anda.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Ketika status CloudFormation tumpukan Anda`StackStatus: "CREATE_COMPLETE"`, gunakan perintah berikut untuk mengambil nilai output yang relevan untuk langkah-langkah masa depan.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Nilai output adalah sebagai berikut:
+ ApiRole, yang merupakan nama peran yang memungkinkan API Gateway untuk menempatkan item dalam tabel DynamoDB. Untuk tutorial ini, nama perannya adalah`data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableNama, yang merupakan nama tabel DynamoDB. Untuk tutorial ini, nama tabelnya adalah `data-transformation-tutorial-cli-ddb`
+ ResourceId, yang merupakan ID untuk sumber daya hewan peliharaan tempat `POST` metode `GET` dan diekspos. Untuk tutorial ini, Resource ID adalah `efg456`
+ ApiId, yang merupakan ID untuk API. Untuk tutorial ini, ID API adalah`abc123`.
**Untuk menguji `GET` metode sebelum transformasi data**
+ Gunakan perintah berikut untuk menguji `GET` metode.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
Output dari tes akan menunjukkan yang berikut ini.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Anda akan mengubah output ini sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
**Untuk mengubah respon `GET` integrasi**
+ Gunakan perintah berikut untuk memperbarui respons integrasi untuk `GET` metode ini. Ganti *rest-api-id* dan *resource-id* dengan nilai-nilai Anda.
Gunakan perintah berikut untuk membuat respons integrasi.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Untuk menguji `GET` metode**
+ Gunakan perintah berikut untuk menguji `GET` metode.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
Output dari tes akan menunjukkan respons yang diubah.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Untuk membuat `POST` metode**
1. Gunakan perintah berikut untuk membuat metode baru pada `/pets` sumber daya.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Metode ini akan memungkinkan Anda untuk mengirim informasi hewan peliharaan ke tabel DynamoDB yang Anda buat di tumpukan. CloudFormation
1. Gunakan perintah berikut untuk membuat Layanan AWS integrasi pada `POST` metode.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Gunakan perintah berikut untuk membuat respons metode untuk panggilan `POST` metode yang berhasil.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Gunakan perintah berikut untuk membuat respons integrasi untuk panggilan `POST` metode yang berhasil.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Untuk menguji `POST` metode**
+ Gunakan perintah berikut untuk menguji `POST` metode.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
Output akan menampilkan pesan yang berhasil.
**Untuk menghapus CloudFormation tumpukan**
+ Gunakan perintah berikut untuk menghapus CloudFormation sumber daya Anda.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## CloudFormation Templat transformasi data yang lengkap
Contoh berikut adalah CloudFormation template lengkap, yang membuat API dan tabel DynamoDB dengan sumber daya `/pets` `GET` dengan dan metode. `POST`
+ `GET`Metode ini akan mendapatkan data dari titik akhir `http://petstore-demo-endpoint.execute-api.com/petstore/pets` HTTP. Data keluaran akan diubah sesuai dengan template pemetaan di[Memetakan transformasi template untuk REST APIs di API Gateway](models-mappings.md).
+ `POST`Metode ini akan memungkinkan pengguna untuk menyimpan informasi `POST` ke tabel DynamoDB menggunakan template pemetaan.
### Contoh CloudFormation template
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Contoh menggunakan variabel untuk memetakan transformasi template untuk API Gateway
Contoh berikut menunjukkan cara menggunakan`$context`,`input`, dan `util` variabel dalam template pemetaan. Anda dapat menggunakan integrasi tiruan atau integrasi non-proxy Lambda yang mengembalikan peristiwa input kembali ke API Gateway. Untuk daftar semua variabel yang didukung untuk transformasi data, lihat[Variabel untuk transformasi data untuk API Gateway](api-gateway-mapping-template-reference.md).
## Contoh 1: Berikan beberapa `$context` variabel ke titik akhir integrasi
Contoh berikut menunjukkan template pemetaan yang memetakan `$context` variabel masuk ke variabel backend dengan nama yang sedikit berbeda dalam payload permintaan integrasi:
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
Salah satu variabelnya adalah kunci API. Contoh ini mengasumsikan bahwa metode tersebut memerlukan kunci API.
## Contoh 2: Teruskan semua parameter permintaan ke titik akhir integrasi melalui payload JSON
Contoh berikut meneruskan semua parameter permintaan, termasuk`path`,`querystring`, dan `header` parameter, ke titik akhir integrasi melalui payload JSON:
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
Jika permintaan memiliki parameter input berikut:
+ Parameter jalur bernama `myparam`
+ Parameter string kueri `querystring1=value1,value2`
+ Header. `"header1" : "value1"`
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Contoh 3: Lulus subbagian dari permintaan metode ke titik akhir integrasi
Contoh berikut menggunakan parameter input `name` untuk mengambil hanya `name` parameter dan parameter input `input.json('$')` untuk mengambil seluruh isi permintaan metode:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
Untuk permintaan yang menyertakan parameter string kueri `name=Bella&type=dog` dan isi berikut:
```
{
"Price" : "249.99",
"Age": "6"
}
```
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
Template pemetaan ini menghapus parameter `type=dog` string kueri.
Jika input JSON berisi karakter unescaped yang tidak dapat diuraikan, API JavaScript Gateway mungkin menampilkan respons 400. Terapkan `$util.escapeJavaScript($input.json('$'))` untuk memastikan input JSON dapat diurai dengan benar.
Contoh sebelumnya dengan `$util.escapeJavaScript($input.json('$'))` diterapkan adalah sebagai berikut:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
Dalam hal ini, output dari template pemetaan ini akan terlihat seperti berikut:
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## Contoh 4: Gunakan JSONPath ekspresi untuk meneruskan subbagian dari permintaan metode ke titik akhir integrasi
Contoh berikut menggunakan JSONPath ekspresi untuk mengambil hanya parameter input `name` dan `Age` dari badan permintaan:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
Untuk permintaan yang menyertakan parameter string kueri `name=Bella&type=dog` dan isi berikut:
```
{
"Price" : "249.99",
"Age": "6"
}
```
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{
"name" : "Bella",
"body" : "6"
}
```
Template pemetaan ini menghapus parameter string kueri `type=dog` dan `Price` bidang dari badan.
Jika payload permintaan metode berisi karakter unescaped yang tidak dapat diuraikan, API JavaScript Gateway mungkin menampilkan respons. `400` Terapkan `$util.escapeJavaScript()` untuk memastikan input JSON dapat diurai dengan benar.
Contoh sebelumnya dengan `$util.escapeJavaScript($input.json('$.Age'))` diterapkan adalah sebagai berikut:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
Dalam hal ini, output dari template pemetaan ini akan terlihat seperti berikut:
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## Contoh 5: Gunakan JSONPath ekspresi untuk meneruskan informasi tentang permintaan metode ke titik akhir integrasi
Contoh berikut menggunakan`$input.params()`,`$input.path()`, dan `$input.json()` untuk mengirim informasi tentang permintaan metode ke titik akhir integrasi. Template pemetaan ini menggunakan `size()` metode untuk memberikan jumlah elemen dalam daftar.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
Untuk permintaan yang menyertakan parameter jalur `123` dan isi berikut:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
Jika payload permintaan metode berisi karakter unescaped yang tidak dapat diuraikan, API JavaScript Gateway mungkin menampilkan respons. `400` Terapkan `$util.escapeJavaScript()` untuk memastikan input JSON dapat diurai dengan benar.
Contoh sebelumnya dengan `$util.escapeJavaScript($input.json('$.things'))` diterapkan adalah sebagai berikut:
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
Output dari template pemetaan ini akan terlihat seperti berikut:
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# Variabel untuk transformasi data untuk API Gateway
Saat Anda membuat pemetaan parameter, Anda dapat menggunakan variabel konteks sebagai sumber data Anda. Saat Anda membuat transformasi template pemetaan, Anda dapat menggunakan variabel konteks, input, dan variabel util dalam skrip yang Anda tulis di [Velocity Template](https://velocity.apache.org/engine/devel/vtl-reference.html) Language (VTL). Misalnya template pemetaan yang menggunakan variabel referensi ini, lihat[Contoh menggunakan variabel untuk memetakan transformasi template untuk API Gateway](api-gateway-mapping-variable-examples.md).
Untuk daftar variabel referensi untuk pencatatan akses, lihat[Variabel untuk pencatatan akses untuk API Gateway](api-gateway-variables-for-access-logging.md).
## Variabel konteks untuk transformasi data
Anda dapat menggunakan `$context` variabel case-sensitive berikut untuk transformasi data.
| Parameter | Deskripsi |
| --- | --- |
| \$1context.accountId | ID AWS akun pemilik API. |
| \$1context.apiId | API Gateway identifier ditetapkan ke API Anda. |
| \$1context.authorizer.claims.property | Properti klaim yang dikembalikan dari kumpulan pengguna Amazon Cognito setelah pemanggil metode berhasil diautentikasi. Untuk informasi selengkapnya, lihat [Kontrol akses ke REST APIs menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi](apigateway-integrate-with-cognito.md). Memanggil `$context.authorizer.claims` mengembalikan null. |
| \$1context.authorizer.principalId | Identifikasi pengguna utama yang terkait dengan token yang dikirim oleh klien dan dikembalikan dari otorisasi API Gateway Lambda (sebelumnya dikenal sebagai otorisasi khusus). Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | Nilai stringifikasi dari pasangan nilai kunci yang ditentukan dari `context` peta dikembalikan dari fungsi otorisasi API Gateway Lambda. Misalnya, jika otorisasi mengembalikan `context` peta berikut:
Memanggil `$context.authorizer.key` mengembalikan `"value"` string, memanggil `$context.authorizer.numKey` mengembalikan `"1"` string, dan memanggil `$context.authorizer.boolKey` mengembalikan `"true"` string. Sebab*property*, satu-satunya karakter khusus yang didukung adalah `(_)` karakter garis bawah. Untuk informasi selengkapnya, lihat [Gunakan otorisasi API Gateway Lambda](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | ID permintaan AWS titik akhir. |
| \$1context.deploymentId | ID penerapan API. |
| \$1context.domainName | Nama domain lengkap yang digunakan untuk memanggil API. Ini harus sama dengan `Host` header yang masuk. |
| \$1context.domainPrefix | Label pertama dari`$context.domainName`. |
| \$1context.error.message | String yang berisi pesan kesalahan API Gateway. Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)pemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, lihat [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md) dan [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | Nilai yang dikutip dari\$1context.error.message, yaitu"\$1context.error.message". |
| \$1context.error.responseType | Sebuah [jenis [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType). Variabel ini hanya dapat digunakan untuk substitusi variabel sederhana dalam template [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)pemetaan tubuh, yang tidak diproses oleh mesin Velocity Template Language, dan dalam logging akses. Untuk informasi selengkapnya, lihat [Pantau eksekusi WebSocket API dengan CloudWatch metrik](apigateway-websocket-api-logging.md) dan [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Sebuah string yang berisi pesan kesalahan validasi rinci. |
| \$1context.extendedRequestId | ID tambahan yang dibuat dan ditetapkan API Gateway ke permintaan API. ID permintaan yang diperluas berisi informasi yang berguna untuk debugging dan pemecahan masalah. |
| \$1context.httpMethod | Metode HTTP yang digunakan. Nilai yang valid meliputi: `DELETE``GET`,,`HEAD`,`OPTIONS`,`PATCH`,`POST`, dan`PUT`. |
| \$1context.identity.accountId | ID AWS akun yang terkait dengan permintaan. |
| \$1context.identity.apiKey | Untuk metode API yang memerlukan kunci API, variabel ini adalah kunci API yang terkait dengan permintaan metode. Untuk metode yang tidak memerlukan kunci API, variabel ini adalah null. Untuk informasi selengkapnya, lihat [Paket penggunaan dan kunci API untuk REST APIs di API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | ID kunci API yang terkait dengan permintaan API yang memerlukan kunci API. |
| \$1context.identity.caller | Pengidentifikasi utama penelepon yang menandatangani permintaan. Didukung untuk sumber daya yang menggunakan otorisasi IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Daftar dipisahkan koma dari semua penyedia otentikasi Amazon Cognito yang digunakan oleh penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Misalnya, untuk identitas dari kumpulan pengguna Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` *Untuk informasi tentang penyedia autentikasi Amazon Cognito yang tersedia, lihat [Menggunakan Identitas Federasi di Panduan Pengembang](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) Amazon Cognito.* |
| \$1context.identity.cognitoAuthenticationType | Jenis otentikasi Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. Nilai yang mungkin termasuk `authenticated` untuk identitas yang diautentikasi dan `unauthenticated` untuk identitas yang tidak diautentikasi. |
| \$1context.identity.cognitoIdentityId | ID identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID kumpulan identitas Amazon Cognito dari penelepon yang membuat permintaan. Hanya tersedia jika permintaan ditandatangani dengan kredenal Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID AWS organisasi](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | Alamat IP sumber dari koneksi TCP langsung membuat permintaan ke titik akhir API Gateway. |
| \$1context.identity.clientCert.clientCertPem | Sertifikat klien yang dikodekan PEM yang disajikan klien selama otentikasi TLS timbal balik. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.subjectDN | Nama yang dibedakan dari subjek sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.issuerDN | Nama terhormat dari penerbit sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.serialNumber | Nomor seri sertifikat. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.validity.notBefore | Tanggal sebelum sertifikat tidak valid. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.clientCert.validity.notAfter | Tanggal setelah sertifikat tidak valid. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. Hadir hanya di log akses jika otentikasi TLS timbal balik gagal. |
| \$1context.identity.vpcId | ID VPC VPC membuat permintaan ke titik akhir API Gateway. |
| \$1context.identity.vpceId | ID titik akhir VPC dari titik akhir VPC membuat permintaan ke titik akhir API Gateway. Hadir hanya ketika Anda memiliki API pribadi. |
| \$1context.identity.user | Pengidentifikasi utama pengguna yang akan diotorisasi terhadap akses sumber daya. Didukung untuk sumber daya yang menggunakan otorisasi IAM. |
| \$1context.identity.userAgent | [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)Header pemanggil API. |
| \$1context.identity.userArn | Nama Sumber Daya Amazon (ARN) dari pengguna efektif yang diidentifikasi setelah otentikasi. Untuk informasi selengkapnya, lihat [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Mengembalikan `true` jika permintaan diarahkan ke kenari dan `false` jika permintaan tidak diarahkan ke kenari. Hadir hanya ketika Anda mengaktifkan kenari. |
| \$1context.path | Jalur permintaan. Misalnya, untuk URL permintaan non-proxy darihttps://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, \$1context.path nilainya adalah/\$1stage\$1/root/child. |
| \$1context.protocol | Protokol permintaan, misalnya,HTTP/1.1. API Gateway APIs dapat menerima permintaan HTTP/2, tetapi API Gateway mengirimkan permintaan ke integrasi backend menggunakan HTTP/1.1. Akibatnya, protokol permintaan dicatat sebagai HTTP/1.1 bahkan jika klien mengirim permintaan yang menggunakan HTTP/2. |
| \$1context.requestId | ID untuk permintaan. Klien dapat mengganti ID permintaan ini. Gunakan `$context.extendedRequestId` untuk ID permintaan unik yang dihasilkan API Gateway. |
| \$1context.requestOverride.header.header\$1name | Header permintaan menimpa. Jika parameter ini didefinisikan, ini berisi header yang akan digunakan alih-alih **Header HTTP** yang didefinisikan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Jalur permintaan menimpa. Jika parameter ini ditentukan, parameter ini berisi jalur permintaan yang akan digunakan, bukan **Parameter Jalur URL** yang ditentukan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Permintaan query string override. Jika parameter ini didefinisikan, parameter ini berisi string permintaan permintaan yang akan digunakan, bukan **Parameter String Kueri URL** yang didefinisikan di panel **Permintaan Integrasi**. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | Header respon menimpa. Jika parameter ini didefinisikan, ini berisi header yang akan dikembalikan, bukan header Response yang didefinisikan sebagai pemetaan Default di panel Integration Response. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Kode status respons menimpa. Jika parameter ini didefinisikan, ini berisi kode status yang akan dikembalikan, bukan status respons Metode yang didefinisikan sebagai pemetaan Default di panel Respons Integrasi. Untuk informasi selengkapnya, lihat [Ganti parameter permintaan dan respons API Anda serta kode status untuk REST APIs di API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Waktu permintaan yang diformat [CLF](https://httpd.apache.org/docs/current/logs.html#common) (). dd/MMM/yyyy:HH:mm:ss \$1-hhmm |
| \$1context.requestTimeEpoch | Waktu permintaan yang diformat [Epoch](https://en.wikipedia.org/wiki/Unix_time), dalam milidetik. |
| \$1context.resourceId | Pengidentifikasi yang ditetapkan API Gateway ke sumber daya Anda. |
| \$1context.resourcePath | Jalan menuju sumber daya Anda. Misalnya, untuk URI permintaan non-proxy dari`https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, `$context.resourcePath` Nilainya adalah`/root/child`. Untuk informasi selengkapnya, lihat [Tutorial: Membuat REST API dengan integrasi non-proxy HTTP](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | Tahap penerapan permintaan API (misalnya, `Beta` atau`Prod`). |
| \$1context.wafResponseCode | Tanggapan yang diterima dari [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` atau`WAF_BLOCK`. Tidak akan diatur jika tahap tidak terkait dengan ACL web. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | ARN lengkap dari ACL web yang digunakan untuk memutuskan apakah akan mengizinkan atau memblokir permintaan. Tidak akan diatur jika tahap tidak terkait dengan ACL web. Untuk informasi selengkapnya, lihat [Gunakan AWS WAF untuk melindungi REST Anda APIs di API Gateway](apigateway-control-access-aws-waf.md). |
## Variabel masukan
Anda dapat menggunakan `$input` variabel case-sensitive berikut untuk merujuk ke metode permintaan payload dan parameter permintaan metode. Fungsi-fungsi berikut tersedia:
| Variabel dan fungsi | Deskripsi |
| --- | --- |
| \$1input.body | Mengembalikan payload permintaan mentah sebagai string. Anda dapat menggunakan `$input.body` untuk mempertahankan seluruh nomor floating point, seperti`10.00`. |
| \$1input.json(x) | Fungsi ini mengevaluasi JSONPath ekspresi dan mengembalikan hasil sebagai string JSON. Misalnya, `$input.json('$.pets')` mengembalikan string JSON yang mewakili `pets` struktur. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). |
| \$1input.params() | Mengembalikan peta dari semua parameter permintaan. Kami menyarankan Anda menggunakan `$util.escapeJavaScript` untuk membersihkan hasilnya untuk menghindari potensi serangan injeksi. Untuk kontrol penuh sanitasi permintaan, gunakan integrasi proxy tanpa templat dan tangani sanitasi permintaan dalam integrasi Anda. |
| \$1input.params(x) | Mengembalikan nilai parameter permintaan metode dari path, query string, atau nilai header (dicari dalam urutan itu), diberikan string `x` nama parameter. Kami menyarankan Anda menggunakan `$util.escapeJavaScript` untuk membersihkan parameter untuk menghindari potensi serangan injeksi. Untuk kontrol penuh sanitasi parameter, gunakan integrasi proxy tanpa templat dan tangani sanitasi permintaan dalam integrasi Anda. |
| \$1input.path(x) | Mengambil JSONPath ekspresi string (`x`) dan mengembalikan representasi objek JSON dari hasil. Ini memungkinkan Anda untuk mengakses dan memanipulasi elemen payload secara native di [Apache Velocity Template](https://velocity.apache.org/engine/devel/vtl-reference.html) Language (VTL). Misalnya, jika ekspresi `$input.path('$.pets')` mengembalikan objek seperti ini:
`$input.path('$.pets').size()`akan kembali`"3"`. Untuk informasi selengkapnya tentang JSONPath, lihat [JSONPath](https://goessner.net/articles/JsonPath/)atau [JSONPath untuk Java](https://github.com/json-path/JsonPath). |
## Variabel tahap
Anda dapat menggunakan variabel tahap berikut sebagai placeholder untuk ARNs dan URLs dalam integrasi metode. Untuk informasi selengkapnya, lihat [Menggunakan variabel stage untuk REST API di API Gateway](stage-variables.md).
| Sintaksis | Deskripsi |
| --- | --- |
| \$1stageVariables.variable\$1name,\$1stageVariables['variable\$1name'], atau \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*merupakan nama variabel tahap. |
## Variabel Util
Anda dapat menggunakan `$util` variabel case-sensitive berikut untuk menggunakan fungsi utilitas untuk memetakan template. Kecuali ditentukan lain, set karakter default adalah UTF-8.
| Fungsi | Deskripsi |
| --- | --- |
| \$1util.escapeJavaScript() | Melarikan diri dari karakter dalam string menggunakan aturan JavaScript string. Fungsi ini akan mengubah tanda kutip tunggal biasa (`'`) menjadi yang keluar (`\'`). Namun, tanda kutip tunggal yang lolos tidak valid di JSON. Jadi, ketika output dari fungsi ini digunakan dalam properti JSON, Anda harus mengubah tanda kutip tunggal yang diloloskan (`\'`) kembali ke tanda kutip tunggal biasa (`'`). Ini ditunjukkan dalam contoh berikut:
|
| \$1util.parseJson() | Mengambil “stringified” JSON dan mengembalikan representasi objek dari hasilnya. Anda dapat menggunakan hasil dari fungsi ini untuk mengakses dan memanipulasi elemen payload secara native di Apache Velocity Template Language (VTL). Misalnya, jika Anda memiliki muatan berikut:
|
| \$1util.urlEncode() | Mengkonversi string ke dalam format “aplikasi/x-www-form-urlencoded”. |
| \$1util.urlDecode() | Mendekode string “aplikasi/x-www-form-urlencoded”. |
| \$1util.base64Encode() | Mengkodekan data ke dalam string yang dikodekan base64. |
| \$1util.base64Decode() | Mendekode data dari string yang dikodekan base64. |
# Tanggapan gateway untuk REST APIs di API Gateway
Respons gateway diidentifikasi oleh tipe respons yang ditentukan oleh API Gateway. [Respons terdiri dari kode status HTTP, satu set header tambahan yang ditentukan oleh pemetaan parameter, dan payload yang dihasilkan oleh template pemetaan non-VTL.](https://velocity.apache.org/engine/devel/vtl-reference.html)
Di API Gateway REST API, respons gateway diwakili oleh [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Di OpenAPI, `GatewayResponse` instance dijelaskan oleh ekstensi [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md).
Untuk mengaktifkan respons gateway, Anda menyiapkan respons gateway untuk [jenis respons yang didukung](supported-gateway-response-types.md) di API level. Setiap kali API Gateway menampilkan respons jenis ini, templat pemetaan header dan pemetaan muatan yang ditentukan dalam respons gateway diterapkan untuk mengembalikan hasil yang dipetakan ke pemanggil API.
Di bagian berikut, kami menunjukkan cara mengatur respons gateway dengan menggunakan konsol API Gateway dan API Gateway REST API.
## Menyiapkan respons gateway untuk menyesuaikan respons kesalahan
Jika API Gateway gagal memproses permintaan yang masuk, ia mengembalikan respons kesalahan ke klien tanpa meneruskan permintaan ke backend integrasi. Secara default, respons kesalahan berisi pesan kesalahan deskriptif singkat. Misalnya, jika Anda mencoba memanggil operasi pada sumber daya API yang tidak ditentukan, Anda menerima respons kesalahan dengan `{ "message": "Missing Authentication Token" }` pesan tersebut. Jika Anda baru mengenal API Gateway, Anda mungkin merasa sulit untuk memahami apa yang sebenarnya salah.
Untuk beberapa respons kesalahan, API Gateway memungkinkan penyesuaian oleh pengembang API untuk mengembalikan respons dalam format yang berbeda. `Missing Authentication Token`Misalnya, Anda dapat menambahkan petunjuk ke payload respons asli dengan kemungkinan penyebabnya, seperti dalam contoh ini:. `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`
Saat API Anda memediasi antara pertukaran eksternal dan AWS Cloud, Anda menggunakan templat pemetaan VTL untuk permintaan integrasi atau respons integrasi untuk memetakan payload dari satu format ke format lainnya. Namun, template pemetaan VTL hanya berfungsi untuk permintaan yang valid dengan tanggapan yang berhasil.
Untuk permintaan yang tidak valid, API Gateway melewati integrasi sama sekali dan mengembalikan respons kesalahan. Anda harus menggunakan kustomisasi untuk membuat respons kesalahan dalam format yang sesuai dengan pertukaran. Di sini, kustomisasi diberikan dalam template pemetaan non-VTL yang hanya mendukung substitusi variabel sederhana.
*Menggeneralisasi respons kesalahan yang dihasilkan API Gateway terhadap respons apa pun yang dihasilkan oleh API Gateway, kami menyebutnya sebagai respons gateway.* Ini membedakan respons yang dihasilkan API Gateway dari respons integrasi. Template pemetaan respons gateway dapat mengakses nilai `$context` variabel dan nilai `$stageVariables` properti, serta parameter permintaan metode, dalam bentuk. `method.request.param-position.param-name`
Untuk informasi lebih lanjut tentang `$context` variabel, lihat[Variabel konteks untuk transformasi data](api-gateway-mapping-template-reference.md#context-variable-reference). Untuk informasi selengkapnya tentang `$stageVariables`, lihat [Variabel tahap](api-gateway-mapping-template-reference.md#stagevariables-template-reference). Untuk informasi selengkapnya tentang parameter permintaan metode, lihat[Variabel masukan](api-gateway-mapping-template-reference.md#input-variable-reference).
**Topics**
+ [Menyiapkan respons gateway untuk menyesuaikan respons kesalahan](#customize-gateway-responses)
+ [Menyiapkan respons gateway untuk REST API menggunakan konsol API Gateway](set-up-gateway-response-using-the-console.md)
+ [Siapkan respons gateway menggunakan API Gateway REST API](set-up-gateway-response-using-the-api.md)
+ [Siapkan kustomisasi respons gateway di OpenAPI](set-up-gateway-responses-in-swagger.md)
+ [Jenis respons gateway untuk API Gateway](supported-gateway-response-types.md)
# Menyiapkan respons gateway untuk REST API menggunakan konsol API Gateway
Contoh berikut menunjukkan cara menyiapkan respons gateway untuk REST API menggunakan konsol API Gateway
**Untuk menyesuaikan respons gateway menggunakan konsol API Gateway**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Di panel navigasi utama, pilih **Respons Gateway**.
1. Pilih jenis respons, lalu pilih **Edit**. Dalam panduan ini, kami menggunakan **token otentikasi Hilang sebagai contoh**.
1. Anda dapat mengubah kode Status yang dihasilkan API Gateway untuk **menampilkan kode status** berbeda yang memenuhi persyaratan API Anda. Dalam contoh ini, kustomisasi mengubah kode status dari default (`403`) menjadi `404` karena pesan kesalahan ini terjadi ketika klien memanggil sumber daya yang tidak didukung atau tidak valid yang dapat dianggap sebagai tidak ditemukan.
1. Untuk mengembalikan header khusus, pilih **Tambahkan header respons di bawah Header** **respons**. Untuk tujuan ilustrasi, kami menambahkan header khusus berikut:
```
Access-Control-Allow-Origin:'a.b.c'
x-request-id:method.request.header.x-amzn-RequestId
x-request-path:method.request.path.petId
x-request-query:method.request.querystring.q
```
Dalam pemetaan header sebelumnya, nama domain statis (`'a.b.c'`) dipetakan ke `Allow-Control-Allow-Origin` header untuk memungkinkan akses CORS ke API; header permintaan input `x-amzn-RequestId` dipetakan ke `request-id` dalam respons; variabel `petId` jalur permintaan yang masuk dipetakan ke `request-path` header dalam respons; dan parameter `q` kueri dari permintaan asli dipetakan ke header respons. `request-query`
1. Di bawah **Template Response**, simpan `application/json` untuk **Jenis Konten** dan masukkan template pemetaan tubuh berikut di editor **badan Template**:
```
{
"message":"$context.error.messageString",
"type": "$context.error.responseType",
"statusCode": "'404'",
"stage": "$context.stage",
"resourcePath": "$context.resourcePath",
"stageVariables.a": "$stageVariables.a"
}
```
Contoh ini menunjukkan cara memetakan `$context` dan `$stageVariables` properti ke properti badan respons gateway.
1. Pilih **Simpan perubahan**.
1. Menerapkan API ke tahap baru atau yang sudah ada.
Uji respons gateway Anda dengan memanggil perintah CURL berikut, dengan asumsi URL pemanggilan metode API yang sesuai adalah: `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`
```
curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1
```
Karena parameter string kueri tambahan `q=1` tidak kompatibel dengan API, kesalahan dikembalikan dari respons gateway yang ditentukan. Anda harus mendapatkan respons gateway yang mirip dengan yang berikut ini:
```
> GET /custErr/pets/5?q=1 HTTP/1.1
Host: o81lxisefl.execute-api.us-east-1.amazonaws.com
User-Agent: curl/7.51.0
Accept: */*
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 334
Connection: keep-alive
Date: Tue, 02 May 2017 03:15:47 GMT
x-amzn-RequestId: 123344566
Access-Control-Allow-Origin: a.b.c
x-amzn-ErrorType: MissingAuthenticationTokenException
header-1: static
x-request-query: 1
x-request-path: 5
X-Cache: Error from cloudfront
Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront)
X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA==
{
"message":"Missing Authentication Token",
"type": MISSING_AUTHENTICATION_TOKEN,
"statusCode": '404',
"stage": custErr,
"resourcePath": /pets/{petId},
"stageVariables.a": a
}
```
Contoh sebelumnya mengasumsikan bahwa backend API adalah [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets) dan API memiliki variabel stage,, didefinisikan. `a`
# Siapkan respons gateway menggunakan API Gateway REST API
Sebelum menyesuaikan respons gateway menggunakan API Gateway REST API, Anda harus sudah membuat API dan telah memperoleh pengenalnya. Untuk mengambil pengenal API, Anda dapat mengikuti relasi tautan [restapi:gateway-response](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) dan memeriksa hasilnya.
**Untuk menyesuaikan respons gateway menggunakan API Gateway REST API**
1. Untuk menimpa seluruh [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)instance, panggil tindakan [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html). [https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters)
1. Untuk memperbarui bagian dari `GatewayResponse` instance, panggil tindakan [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html). Tentukan parameter jalur URL yang diinginkan`responseType`, dan berikan dalam permintaan payload `GatewayResponse` properti individual yang Anda inginkan—misalnya, atau `responseParameters` pemetaan. `responseTemplates`
# Siapkan kustomisasi respons gateway di OpenAPI
Anda dapat menggunakan `x-amazon-apigateway-gateway-responses` ekstensi di tingkat root API untuk menyesuaikan respons gateway di OpenAPI. Definisi OpenAPI berikut menunjukkan contoh untuk menyesuaikan [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)tipe. `MISSING_AUTHENTICATION_TOKEN`
```
"x-amazon-apigateway-gateway-responses": {
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.x-request-path": "method.input.params.petId",
"gatewayresponse.header.x-request-query": "method.input.params.q",
"gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'",
"gatewayresponse.header.x-request-header": "method.input.params.Accept"
},
"responseTemplates": {
"application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}"
}
}
```
Dalam contoh ini, kustomisasi mengubah kode status dari default (`403`) menjadi`404`. Ini juga menambah respons gateway empat parameter header dan satu template pemetaan tubuh untuk jenis `application/json` media.
# Jenis respons gateway untuk API Gateway
API Gateway memaparkan respons gateway berikut untuk penyesuaian oleh pengembang API.
| Jenis respons gateway | Kode status default | Deskripsi |
| --- | --- | --- |
| ACCESS\$1DENIED | 403 | Respons gateway untuk kegagalan otorisasi—misalnya, saat akses ditolak oleh otorisasi khusus atau Amazon Cognito. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| API\$1CONFIGURATION\$1ERROR | 500 | Respons gateway untuk konfigurasi API yang tidak valid—termasuk saat alamat titik akhir yang tidak valid dikirimkan, saat decoding base64 gagal pada data biner saat dukungan biner diberlakukan, atau saat pemetaan respons integrasi tidak dapat cocok dengan templat apa pun dan tidak ada templat default yang dikonfigurasi. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_5XX` |
| AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | Respons gateway karena gagal terhubung ke otorisasi khusus atau Amazon Cognito. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_5XX` |
| AUTHORIZER\$1FAILURE | 500 | Respons gateway saat otorisasi khusus atau Amazon Cognito gagal mengautentikasi pemanggil. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_5XX` |
| BAD\$1REQUEST\$1PARAMETERS | 400 | Respons gateway ketika parameter permintaan tidak dapat divalidasi sesuai dengan validator permintaan yang diaktifkan. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| BAD\$1REQUEST\$1BODY | 400 | Respons gateway saat badan permintaan tidak dapat divalidasi sesuai dengan validator permintaan yang diaktifkan. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| DEFAULT\$14XX | Null | Respons gateway default untuk jenis respons yang tidak ditentukan dengan kode status. `4XX` Mengubah kode status respons gateway fallback ini mengubah kode status semua `4XX` respons lain ke nilai baru. Menyetel ulang kode status ini ke null mengembalikan kode status dari semua `4XX` respons lain ke nilai aslinya. [AWS WAF tanggapan khusus](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) lebih diutamakan daripada respons gateway khusus. |
| DEFAULT\$15XX | Null | Respons gateway default untuk jenis respons yang tidak ditentukan dengan kode status. `5XX` Mengubah kode status respons gateway fallback ini mengubah kode status semua `5XX` respons lain ke nilai baru. Menyetel ulang kode status ini ke null mengembalikan kode status dari semua `5XX` respons lain ke nilai aslinya. |
| EXPIRED\$1TOKEN | 403 | Respons gateway untuk kesalahan kedaluwarsa token AWS otentikasi. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| INTEGRATION\$1FAILURE | 504 | Respons gateway untuk kesalahan integrasi gagal. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_5XX` |
| INTEGRATION\$1TIMEOUT | 504 | Respons gateway untuk kesalahan waktu integrasi habis. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_5XX` |
| INVALID\$1API\$1KEY | 403 | Respons gateway untuk kunci API tidak valid yang dikirimkan untuk metode yang memerlukan kunci API. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| INVALID\$1SIGNATURE | 403 | Respons gateway untuk kesalahan AWS tanda tangan yang tidak valid. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| MISSING\$1AUTHENTICATION\$1TOKEN | 403 | Respons gateway untuk kesalahan token otentikasi yang hilang, termasuk kasus ketika klien mencoba memanggil metode atau sumber daya API yang tidak didukung. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| QUOTA\$1EXCEEDED | 429 | Respons gateway untuk kuota paket penggunaan melebihi kesalahan. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| REQUEST\$1TOO\$1LARGE | 413 | Respons gateway untuk permintaan kesalahan terlalu besar. Jika jenis respons tidak ditentukan, respons ini default ke:. `HTTP content length exceeded 10485760 bytes` |
| RESOURCE\$1NOT\$1FOUND | 404 | Respons gateway ketika API Gateway tidak dapat menemukan sumber daya yang ditentukan setelah permintaan API melewati otentikasi dan otorisasi, kecuali untuk autentikasi dan otorisasi kunci API. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| THROTTLED | 429 | Respons gateway saat batas pelambatan tingkat rencana, metode, tahap, atau akun terlampaui. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| UNAUTHORIZED | 401 | Respons gateway saat otorisasi khusus atau Amazon Cognito gagal mengautentikasi pemanggil. |
| UNSUPPORTED\$1MEDIA\$1TYPE | 415 | Respons gateway ketika payload adalah tipe media yang tidak didukung, jika perilaku passthrough yang ketat diaktifkan. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` |
| WAF\$1FILTERED | 403 | Respons gateway saat permintaan diblokir oleh AWS WAF. Jika tipe respons tidak ditentukan, respons ini default ke tipe. `DEFAULT_4XX` [AWS WAF tanggapan khusus](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) lebih diutamakan daripada respons gateway khusus. |
# CORS untuk REST APIs di API Gateway
[Cross-origin resource sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) adalah fitur keamanan browser yang membatasi permintaan HTTP lintas asal yang dimulai dari skrip yang berjalan di browser. Untuk informasi lebih lanjut, lihat [Apa itu CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/) .
## Menentukan apakah akan mengaktifkan dukungan CORS
Permintaan HTTP *lintas asal* adalah permintaan yang dibuat untuk:
+ *Domain* yang berbeda (misalnya, dari `example.com` ke`amazondomains.com`)
+ *Subdomain* yang berbeda (misalnya, dari `example.com` ke`petstore.example.com`)
+ *Port* yang berbeda (misalnya, dari `example.com` ke`example.com:10777`)
+ *Protokol* yang berbeda (misalnya, dari `https://example.com` ke`http://example.com`)
Jika Anda tidak dapat mengakses API dan menerima pesan kesalahan yang berisi`Cross-Origin Request Blocked`, Anda mungkin perlu mengaktifkan CORS.
Permintaan HTTP cross-origin dapat dibagi menjadi dua jenis: permintaan *sederhana* dan permintaan *non-sederhana*.
## Mengaktifkan CORS untuk permintaan sederhana
Permintaan HTTP *sederhana* jika semua kondisi berikut benar:
+ Ini dikeluarkan terhadap sumber daya API yang hanya mengizinkan`GET`,`HEAD`, dan `POST` permintaan.
+ Jika itu adalah permintaan `POST` metode, itu harus menyertakan `Origin` header.
+ Jenis konten payload permintaan adalah`text/plain`,`multipart/form-data`, atau`application/x-www-form-urlencoded`.
+ Permintaan tidak berisi header khusus.
+ Persyaratan tambahan apa pun yang tercantum dalam [dokumentasi Mozilla CORS untuk permintaan sederhana](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests).
Untuk permintaan `POST` metode lintas asal sederhana, respons dari sumber daya Anda harus menyertakan header `Access-Control-Allow-Origin: '*'` atau`Access-Control-Allow-Origin:'origin'`.
Semua permintaan HTTP lintas asal lainnya adalah permintaan *non-sederhana*.
## Mengaktifkan CORS untuk permintaan yang tidak sederhana
Jika sumber daya API Anda menerima permintaan yang tidak sederhana, Anda harus mengaktifkan dukungan CORS tambahan tergantung pada jenis integrasi Anda.
### Mengaktifkan CORS untuk integrasi non-proxy
Untuk integrasi ini, [protokol CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) mengharuskan browser untuk mengirim permintaan preflight ke server dan menunggu persetujuan (atau permintaan kredensional) dari server sebelum mengirim permintaan yang sebenarnya. Anda harus mengonfigurasi API Anda untuk mengirim respons yang sesuai ke permintaan preflight.
Untuk membuat respons preflight:
1. Buat `OPTIONS` metode dengan integrasi tiruan.
1. Tambahkan header respons berikut ke respons metode 200:
+ `Access-Control-Allow-Headers`
+ `Access-Control-Allow-Methods`
+ `Access-Control-Allow-Origin`
1. Atur perilaku passthrough integrasi ke`NEVER`. Dalam hal ini, permintaan metode dari jenis konten yang tidak dipetakan akan ditolak dengan respons Jenis Media Tidak Didukung HTTP 415. Untuk informasi selengkapnya, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md).
1. Masukkan nilai untuk header respons. Untuk mengizinkan semua asal, semua metode, dan header umum, gunakan nilai header berikut:
+ `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'`
+ `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'`
+ `Access-Control-Allow-Origin: '*'`
Setelah membuat permintaan preflight, Anda harus mengembalikan `Access-Control-Allow-Origin:'origin'` header `Access-Control-Allow-Origin: '*'` or untuk semua metode yang mendukung CORS untuk setidaknya semua 200 tanggapan.
### Mengaktifkan CORS untuk integrasi non-proxy menggunakan Konsol Manajemen AWS
Anda dapat menggunakan Konsol Manajemen AWS untuk mengaktifkan CORS. API Gateway membuat `OPTIONS` metode dan menambahkan `Access-Control-Allow-Origin` header ke respons integrasi metode yang ada. Ini tidak selalu berhasil, dan terkadang Anda perlu memodifikasi respons integrasi secara manual untuk mengembalikan `Access-Control-Allow-Origin` header untuk semua metode berkemampuan CORS untuk setidaknya semua 200 respons.
Jika Anda memiliki tipe media biner yang disetel ke `*/*` API Anda, saat API Gateway membuat `OPTIONS` metode, ubah `contentHandling` ke`CONVERT_TO_TEXT`.
Perintah [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) berikut mengubah ke `contentHandling` `CONVERT_TO_TEXT` untuk permintaan integrasi:
```
aws apigateway update-integration \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
[update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)Perintah berikut mengubah `contentHandling` to `CONVERT_TO_TEXT` untuk respons integrasi:
```
aws apigateway update-integration-response \
--rest-api-id abc123 \
--resource-id aaa111 \
--http-method OPTIONS \
--status-code 200 \
--patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
```
## Mengaktifkan dukungan CORS untuk integrasi proxy
Untuk integrasi proxy Lambda atau integrasi proxy HTTP, backend Anda bertanggung jawab untuk mengembalikan`Access-Control-Allow-Origin`,`Access-Control-Allow-Methods`, dan `Access-Control-Allow-Headers` header, karena integrasi proxy tidak mengembalikan respons integrasi.
Contoh berikut fungsi Lambda mengembalikan header CORS yang diperlukan:
------
#### [ Node.js ]
```
export const handler = async (event) => {
const response = {
statusCode: 200,
headers: {
"Access-Control-Allow-Headers" : "Content-Type",
"Access-Control-Allow-Origin": "https://www.example.com",
"Access-Control-Allow-Methods": "OPTIONS,POST,GET"
},
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};
```
------
#### [ Python 3 ]
```
import json
def lambda_handler(event, context):
return {
'statusCode': 200,
'headers': {
'Access-Control-Allow-Headers': 'Content-Type',
'Access-Control-Allow-Origin': 'https://www.example.com',
'Access-Control-Allow-Methods': 'OPTIONS,POST,GET'
},
'body': json.dumps('Hello from Lambda!')
}
```
------
**Topics**
+ [Menentukan apakah akan mengaktifkan dukungan CORS](#apigateway-cors-request-types)
+ [Mengaktifkan CORS untuk permintaan sederhana](#apigateway-cors-simple-request)
+ [Mengaktifkan CORS untuk permintaan yang tidak sederhana](#apigateway-enable-cors-non-simple)
+ [Mengaktifkan dukungan CORS untuk integrasi proxy](#apigateway-enable-cors-proxy)
+ [Aktifkan CORS pada sumber daya menggunakan konsol API Gateway](how-to-cors-console.md)
+ [Aktifkan CORS pada sumber daya menggunakan API impor API Gateway](enable-cors-for-resource-using-swagger-importer-tool.md)
+ [Uji CORS untuk API Gateway API](apigateway-test-cors.md)
# Aktifkan CORS pada sumber daya menggunakan konsol API Gateway
Anda dapat menggunakan konsol API Gateway untuk mengaktifkan dukungan CORS untuk satu atau semua metode pada sumber daya REST API yang telah Anda buat. Setelah Anda mengaktifkan dukungan COR, atur perilaku passthrough integrasi ke. `NEVER` Dalam hal ini, permintaan metode dari jenis konten yang tidak dipetakan akan ditolak dengan respons Jenis Media Tidak Didukung HTTP 415. Untuk informasi selengkapnya, lihat [Perilaku permintaan metode untuk muatan tanpa memetakan template untuk REST APIs di API Gateway](integration-passthrough-behaviors.md)
**penting**
Sumber daya dapat berisi sumber daya anak. Mengaktifkan dukungan CORS untuk sumber daya dan metodenya tidak secara rekursif mengaktifkannya untuk sumber daya anak dan metodenya.
**Untuk mengaktifkan dukungan CORS pada sumber daya REST API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API.
1. Pilih sumber daya di bawah **Sumber Daya**.
1. Di bagian **Rincian sumber daya**, pilih **Aktifkan CORS.**
![\[Di panel Resources, pilih Aktifkan CORS.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png)
1. Di kotak **Aktifkan CORS**, lakukan hal berikut:
1. (Opsional) Jika Anda membuat respons gateway khusus dan ingin mengaktifkan dukungan CORS untuk respons, pilih respons gateway.
1. Pilih setiap metode untuk mengaktifkan dukungan CORS. `OPTION`Metode ini harus mengaktifkan CORS.
Jika Anda mengaktifkan dukungan CORS untuk suatu `ANY` metode, CORS diaktifkan untuk semua metode.
1. Di bidang input **Access-Control-Allow-Headers**, masukkan string statis dari daftar header yang dipisahkan koma yang harus dikirimkan klien dalam permintaan sumber daya yang sebenarnya. Gunakan daftar header yang disediakan konsol `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` atau tentukan header Anda sendiri.
1. Gunakan nilai yang disediakan konsol `'*'` sebagai nilai header **Access-Control-Allow-Origin untuk mengizinkan permintaan akses dari semua asal**, atau tentukan asal yang akan diizinkan mengakses sumber daya.
1. Pilih **Simpan**.
![\[Pilih header mana yang diizinkan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png)
**penting**
Saat menerapkan instruksi di atas ke `ANY` metode dalam integrasi proxy, header CORS apa pun yang berlaku tidak akan disetel. Sebagai gantinya, backend Anda harus mengembalikan header CORS yang berlaku, seperti. `Access-Control-Allow-Origin`
Setelah CORS diaktifkan pada `GET` metode, `OPTIONS` metode ditambahkan ke sumber daya, jika belum ada. `200`Respons `OPTIONS` metode ini secara otomatis dikonfigurasi untuk mengembalikan tiga `Access-Control-Allow-*` header untuk memenuhi jabat tangan preflight. Selain itu, metode aktual (`GET`) juga dikonfigurasi secara default untuk mengembalikan `Access-Control-Allow-Origin` header dalam respons 200 juga. Untuk jenis tanggapan lain, Anda perlu mengonfigurasinya secara manual untuk mengembalikan `Access-Control-Allow-Origin'` header dengan '\$1' atau asal tertentu, jika Anda tidak ingin mengembalikan `Cross-origin access` kesalahan.
Setelah Anda mengaktifkan dukungan CORS pada sumber daya Anda, Anda harus menerapkan atau menerapkan ulang API agar pengaturan baru diterapkan. Untuk informasi selengkapnya, lihat [Buat deployment](set-up-deployments.md#create-deployment).
**catatan**
Jika Anda tidak dapat mengaktifkan dukungan CORS pada sumber daya Anda setelah mengikuti prosedur, kami sarankan Anda membandingkan konfigurasi CORS Anda dengan sumber daya API `/pets` contoh. Untuk mempelajari cara membuat contoh API, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md).
# Aktifkan CORS pada sumber daya menggunakan API impor API Gateway
Jika Anda menggunakan [API Gateway Import API](api-gateway-import-api.md), Anda dapat mengatur dukungan CORS menggunakan file OpenAPI. Anda harus terlebih dahulu menentukan `OPTIONS` metode dalam sumber daya Anda yang mengembalikan header yang diperlukan.
**catatan**
Browser web mengharapkan Access-Control-Allow-Headers, dan Access-Control-Allow-Origin header akan diatur di setiap metode API yang menerima permintaan CORS. Selain itu, beberapa browser pertama-tama membuat permintaan HTTP ke `OPTIONS` metode di sumber daya yang sama, dan kemudian berharap untuk menerima header yang sama.
## `Options`Metode contoh
Contoh berikut menciptakan `OPTIONS` metode untuk integrasi tiruan.
------
#### [ OpenAPI 3.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
tags:
- CORS
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
type: mock
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
```
------
#### [ OpenAPI 2.0 ]
```
/users:
options:
summary: CORS support
description: |
Enable CORS by returning correct headers
consumes:
- "application/json"
produces:
- "application/json"
tags:
- CORS
x-amazon-apigateway-integration:
type: mock
requestTemplates: "{\"statusCode\": 200}"
passthroughBehavior: "never"
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
Setelah Anda mengonfigurasi `OPTIONS` metode untuk sumber daya Anda, Anda dapat menambahkan header yang diperlukan ke metode lain di sumber daya yang sama yang perlu menerima permintaan CORS.
1. **Deklarasikan **Access-Control-Allow-Origin dan Header ke tipe** respons.**
------
#### [ OpenAPI 3.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content: {}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
200:
description: Default response for CORS method
headers:
Access-Control-Allow-Headers:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Origin:
type: "string"
```
------
1. Di `x-amazon-apigateway-integration` tag, atur pemetaan untuk header tersebut ke nilai statis Anda:
------
#### [ OpenAPI 3.0 ]
```
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods: "'*'"
method.response.header.Access-Control-Allow-Origin: "'*'"
responseTemplates:
application/json: |
{}
```
------
#### [ OpenAPI 2.0 ]
```
responses:
"default":
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Methods : "'*'"
method.response.header.Access-Control-Allow-Origin : "'*'"
```
------
## Contoh API
Contoh berikut membuat API lengkap dengan `OPTIONS` metode dan `GET` metode dengan `HTTP` integrasi.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "cors-api"
description: "cors-api"
version: "2024-01-16T18:36:01Z"
servers:
- url: "/{basePath}"
variables:
basePath:
default: "/test"
paths:
/:
get:
operationId: "GetPet"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
content: {}
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
schema:
type: "string"
Access-Control-Allow-Methods:
schema:
type: "string"
Access-Control-Allow-Headers:
schema:
type: "string"
content:
application/json:
schema:
$ref: "#/components/schemas/Empty"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
components:
schemas:
Empty:
type: "object"
```
------
#### [ OpenAPI 2.0 ]
```
swagger: "2.0"
info:
description: "cors-api"
version: "2024-01-16T18:36:01Z"
title: "cors-api"
basePath: "/test"
schemes:
- "https"
paths:
/:
get:
operationId: "GetPet"
produces:
- "application/json"
responses:
"200":
description: "200 response"
headers:
Access-Control-Allow-Origin:
type: "string"
x-amazon-apigateway-integration:
httpMethod: "GET"
uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets"
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Origin: "'*'"
passthroughBehavior: "never"
type: "http"
options:
consumes:
- "application/json"
produces:
- "application/json"
responses:
"200":
description: "200 response"
schema:
$ref: "#/definitions/Empty"
headers:
Access-Control-Allow-Origin:
type: "string"
Access-Control-Allow-Methods:
type: "string"
Access-Control-Allow-Headers:
type: "string"
x-amazon-apigateway-integration:
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'"
method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
method.response.header.Access-Control-Allow-Origin: "'*'"
requestTemplates:
application/json: "{\"statusCode\": 200}"
passthroughBehavior: "never"
type: "mock"
definitions:
Empty:
type: "object"
```
------
# Uji CORS untuk API Gateway API
Anda dapat menguji konfigurasi CORS API Anda dengan menjalankan API Anda, dan memeriksa header CORS dalam respons. `curl`Perintah berikut mengirimkan permintaan OPTIONS ke API yang diterapkan.
```
curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}
```
```
< HTTP/1.1 200 OK
< Date: Tue, 19 May 2020 00:55:22 GMT
< Content-Type: application/json
< Content-Length: 0
< Connection: keep-alive
< x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token
< x-amz-apigw-id: Abcd=
< Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT
```
`Access-Control-Allow-Methods`Header `Access-Control-Allow-Origin``Access-Control-Allow-Headers`,, dan dalam respons menunjukkan bahwa API mendukung CORS. Lihat informasi yang lebih lengkap di [CORS untuk REST APIs di API Gateway](how-to-cors.md).
# Jenis media biner untuk REST APIs di API Gateway
Di API Gateway, permintaan dan respons API memiliki muatan teks atau biner. Payload teks adalah string JSON `UTF-8` -encoded. Payload biner adalah apa pun selain payload teks. Payload biner dapat berupa, misalnya, file JPEG, file, atau GZip file XHTML. Konfigurasi API yang diperlukan untuk mendukung media biner bergantung pada apakah API Anda menggunakan integrasi proxy atau non-proxy.
Jika Anda menggunakan integrasi proxy dengan streaming respons payload, Anda tidak perlu mengonfigurasi jenis media biner Anda. Untuk informasi selengkapnya, lihat [Streaming respons integrasi untuk integrasi proxy Anda di API Gateway](response-transfer-mode.md).
## AWS Lambda integrasi proxy
Untuk menangani payload biner untuk integrasi AWS Lambda proxy, Anda harus base64-menyandikan respons fungsi Anda. Anda juga harus mengonfigurasi [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)untuk API Anda. `binaryMediaTypes`Konfigurasi API Anda adalah daftar tipe konten yang API Anda perlakukan sebagai data biner. Contoh jenis media biner termasuk `image/png` atau`application/octet-stream`. Anda dapat menggunakan karakter wildcard (`*`) untuk mencakup beberapa jenis media.
API Gateway menggunakan `Accept` header pertama dari klien untuk menentukan apakah respons harus mengembalikan media biner. Untuk mengembalikan media biner saat Anda tidak dapat mengontrol urutan nilai `Accept` header, seperti permintaan dari browser, setel tipe media biner API Anda`*/*`.
Untuk kode sampel, lihat [Kembalikan media biner dari integrasi proxy Lambda di API Gateway](lambda-proxy-binary-media.md).
Jika Anda menggunakan integrasi proxy Lambda dengan streaming respons payload, Anda tidak perlu mengonfigurasi jenis media biner Anda. Untuk informasi selengkapnya, lihat [Siapkan integrasi proxy Lambda dengan streaming respons payload di API Gateway](response-transfer-mode-lambda.md).
## Integrasi non-proxy
Untuk menangani muatan biner untuk integrasi non-proxy, Anda menambahkan jenis media ke [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)daftar sumber daya. `RestApi` `binaryMediaTypes`Konfigurasi API Anda adalah daftar tipe konten yang API Anda perlakukan sebagai data biner. [Atau, Anda dapat mengatur properti [ContentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) pada Integrasi dan sumber daya. [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) `contentHandling`Nilainya bisa`CONVERT_TO_BINARY`,`CONVERT_TO_TEXT`, atau tidak terdefinisi.
**catatan**
Integrasi untuk `MOCK` atau pribadi, pengaturan `contentHandling` properti tidak didukung di. Konsol Manajemen AWS Anda harus menggunakan AWS CLI, CloudFormation, atau SDK untuk mengatur `contentHandling` properti.
Bergantung pada `contentHandling` nilainya, dan apakah header respons atau `Content-Type` header permintaan yang masuk cocok dengan entri dalam `binaryMediaTypes` daftar, API Gateway dapat menyandikan byte biner mentah sebagai string yang disandikan base64, memecahkan kode string yang dikodekan base64 kembali ke byte mentahnya, atau meneruskan isi tanpa modifikasi. `Accept`
Anda harus mengonfigurasi API sebagai berikut untuk mendukung payload biner untuk API Anda di API Gateway:
+ Tambahkan jenis media biner yang diinginkan ke `binaryMediaTypes` daftar pada [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)sumber daya. Jika properti ini dan properti tidak ditentukan, muatan ditangani sebagai string JSON yang dikodekan UTF-8. `contentHandling`
+ Alamat `contentHandling` properti sumber daya [Integrasi](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
+ Agar payload permintaan dikonversi dari string yang dikodekan base64 ke gumpalan binernya, setel properti ke. `CONVERT_TO_BINARY`
+ Agar payload permintaan dikonversi dari gumpalan biner ke string yang dikodekan base64, setel properti ke. `CONVERT_TO_TEXT`
+ Untuk meneruskan muatan tanpa modifikasi, biarkan properti tidak terdefinisi. Untuk meneruskan payload biner tanpa modifikasi, Anda juga harus memastikan bahwa entri tersebut `Content-Type` cocok dengan salah satu `binaryMediaTypes` entri, dan [perilaku passthrough](integration-passthrough-behaviors.md) diaktifkan untuk API.
+ Atur `contentHandling` properti sumber [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)daya. `contentHandling`Properti, `Accept` header dalam permintaan klien, dan `binaryMediaTypes` gabungan API Anda menentukan cara API Gateway menangani konversi tipe konten. Lihat perinciannya di [Konversi jenis konten di API Gateway](api-gateway-payload-encodings-workflow.md).
**penting**
Jika permintaan berisi beberapa jenis media di `Accept` header, API Gateway hanya menghormati jenis `Accept` media pertama. Jika Anda tidak dapat mengontrol urutan jenis `Accept` media dan jenis media konten biner Anda bukan yang pertama dalam daftar, tambahkan jenis `Accept` media pertama dalam `binaryMediaTypes` daftar API Anda. API Gateway menangani semua jenis konten dalam daftar ini sebagai biner.
Misalnya, untuk mengirim file JPEG menggunakan `` elemen di browser, browser mungkin mengirim `Accept:image/webp,image/*,*/*;q=0.8` permintaan. Dengan menambahkan `image/webp` ke `binaryMediaTypes` daftar, titik akhir menerima file JPEG sebagai biner.
Untuk informasi mendetail tentang cara API Gateway menangani muatan teks dan biner, lihat[Konversi jenis konten di API Gateway](api-gateway-payload-encodings-workflow.md).
# Konversi jenis konten di API Gateway
Kombinasi API Anda`binaryMediaTypes`, header dalam permintaan klien, dan `contentHandling` properti integrasi menentukan cara API Gateway menyandikan payload.
[Tabel berikut menunjukkan cara API Gateway mengonversi payload permintaan untuk konfigurasi spesifik `Content-Type` header permintaan, `binaryMediaTypes` daftar [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)sumber daya, dan nilai `contentHandling` properti sumber daya Integrasi.](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html)
| Metode permintaan payload | Permintaan `Content-Type` header | `binaryMediaTypes` | `contentHandling` | Muatan permintaan integrasi |
| --- | --- | --- | --- | --- |
| Data teks | Tipe data apa pun | Tidak terdefinisi | Tidak terdefinisi | UTF8-string yang dikodekan |
| Data teks | Tipe data apa pun | Tidak terdefinisi | CONVERT\$1TO\$1BINARY | Gumpalan biner yang didekode Base64 |
| Data teks | Tipe data apa pun | Tidak terdefinisi | CONVERT\$1TO\$1TEXT | UTF8-string yang dikodekan |
| Data teks | Tipe data teks | Atur dengan jenis media yang cocok | Tidak terdefinisi | Data teks |
| Data teks | Tipe data teks | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1BINARY | Gumpalan biner yang didekode Base64 |
| Data teks | Tipe data teks | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1TEXT | Data teks |
| Data biner | Tipe data biner | Atur dengan jenis media yang cocok | Tidak terdefinisi | Data biner |
| Data biner | Tipe data biner | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1BINARY | Data biner |
| Data biner | Tipe data biner | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1TEXT | String yang dikodekan Base64 |
Tabel berikut menunjukkan cara API Gateway mengonversi payload respons untuk konfigurasi spesifik `Accept` header permintaan, `binaryMediaTypes` daftar [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)sumber daya, dan nilai `contentHandling` properti sumber daya. [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)
**penting**
Jika permintaan berisi beberapa jenis media di `Accept` header, API Gateway hanya menghormati jenis `Accept` media pertama. Jika Anda tidak dapat mengontrol urutan jenis `Accept` media dan jenis media konten biner Anda bukan yang pertama dalam daftar, tambahkan jenis `Accept` media pertama dalam `binaryMediaTypes` daftar API Anda. API Gateway menangani semua jenis konten dalam daftar ini sebagai biner.
Misalnya, untuk mengirim file JPEG menggunakan `` elemen di browser, browser mungkin mengirim `Accept:image/webp,image/*,*/*;q=0.8` permintaan. Dengan menambahkan `image/webp` ke `binaryMediaTypes` daftar, titik akhir menerima file JPEG sebagai biner.
| Payload respons integrasi | Permintaan `Accept` header | `binaryMediaTypes` | `contentHandling` | Metode respon payload |
| --- | --- | --- | --- | --- |
| Teks atau data biner | Jenis teks | Tidak terdefinisi | Tidak terdefinisi | UTF8-string yang dikodekan |
| Teks atau data biner | Jenis teks | Tidak terdefinisi | CONVERT\$1TO\$1BINARY | Gumpalan yang didekode Base64 |
| Teks atau data biner | Jenis teks | Tidak terdefinisi | CONVERT\$1TO\$1TEXT | UTF8-string yang dikodekan |
| Data teks | Jenis teks | Atur dengan jenis media yang cocok | Tidak terdefinisi | Data teks |
| Data teks | Jenis teks | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1BINARY | Gumpalan yang didekode Base64 |
| Data teks | Jenis teks | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1TEXT | UTF8-string yang dikodekan |
| Data teks | Tipe biner | Atur dengan jenis media yang cocok | Tidak terdefinisi | Gumpalan yang didekode Base64 |
| Data teks | Tipe biner | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1BINARY | Gumpalan yang didekode Base64 |
| Data teks | Tipe biner | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1TEXT | UTF8-string yang dikodekan |
| Data biner | Jenis teks | Atur dengan jenis media yang cocok | Tidak terdefinisi | String yang dikodekan Base64 |
| Data biner | Jenis teks | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1BINARY | Data biner |
| Data biner | Jenis teks | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1TEXT | String yang dikodekan Base64 |
| Data biner | Tipe biner | Atur dengan jenis media yang cocok | Tidak terdefinisi | Data biner |
| Data biner | Tipe biner | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1BINARY | Data biner |
| Data biner | Tipe biner | Atur dengan jenis media yang cocok | CONVERT\$1TO\$1TEXT | String yang dikodekan Base64 |
Saat mengonversi payload teks menjadi gumpalan biner, API Gateway mengasumsikan bahwa data teks adalah string yang dikodekan base64 dan mengeluarkan data biner sebagai gumpalan yang diterjemahkan base64. Jika konversi gagal, ia mengembalikan `500` respons, yang menunjukkan kesalahan konfigurasi API. Anda tidak menyediakan template pemetaan untuk konversi semacam itu, meskipun Anda harus mengaktifkan [perilaku passthrough](integration-passthrough-behaviors.md) di API.
Saat mengonversi payload biner menjadi string teks, API Gateway selalu menerapkan pengkodean base64 pada data biner. Anda dapat menentukan templat pemetaan untuk muatan semacam itu, tetapi hanya dapat mengakses string yang dikodekan base64 dalam templat pemetaan`$input.body`, seperti yang ditunjukkan dalam kutipan contoh templat pemetaan berikut.
```
{
"data": "$input.body"
}
```
Agar payload biner melewati tanpa modifikasi, Anda harus mengaktifkan [perilaku passthrough](integration-passthrough-behaviors.md) di API.
# Mengaktifkan dukungan biner menggunakan konsol API Gateway
Bagian ini menjelaskan cara mengaktifkan dukungan biner menggunakan konsol API Gateway. Sebagai contoh, kami menggunakan API yang terintegrasi dengan Amazon S3. Kami fokus pada tugas untuk mengatur jenis media yang didukung dan untuk menentukan bagaimana payload harus ditangani. Untuk informasi terperinci tentang cara membuat API yang terintegrasi dengan Amazon S3, lihat. [Tutorial: Buat REST API sebagai proxy Amazon S3](integrating-api-with-aws-services-s3.md)
**Untuk mengaktifkan dukungan biner dengan menggunakan konsol API Gateway**
1. Tetapkan tipe media biner untuk API:
1. Buat API baru atau pilih API yang sudah ada. Untuk contoh ini, kami memberi nama API`FileMan`.
1. Di bawah API yang dipilih di panel navigasi utama, pilih **pengaturan API**.
1. Di panel **pengaturan API**, pilih **Kelola jenis media** di bagian **Jenis Media Biner**.
1. Pilih **Tambahkan tipe media biner**.
1. Masukkan jenis media yang diperlukan, misalnya**image/png**, di bidang teks input. Jika perlu, ulangi langkah ini untuk menambahkan lebih banyak jenis media. Untuk mendukung semua jenis media biner, tentukan`*/*`.
1. Pilih **Simpan perubahan**.
1. Mengatur cara payload pesan ditangani untuk metode API:
1. Buat yang baru atau pilih sumber daya yang ada di API. Untuk contoh ini, kami menggunakan `/{folder}/{item}` sumber daya.
1. Buat yang baru atau pilih metode yang ada pada sumber daya. Sebagai contoh, kami menggunakan `GET /{folder}/{item}` metode yang terintegrasi dengan `Object GET` tindakan di Amazon S3.
1. Untuk **penanganan Konten**, pilih opsi.
![\[Siapkan GET metode di konsol API Gateway.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png)
Pilih **Passthrough** jika Anda tidak ingin mengonversi isi ketika klien dan backend menerima format biner yang sama. Pilih **Konversi ke teks** untuk mengonversi badan biner menjadi string yang dikodekan base64 ketika, misalnya, backend mengharuskan payload permintaan biner diteruskan sebagai properti JSON. Dan pilih **Konversi ke biner** ketika klien mengirimkan string yang dikodekan base64 dan backend memerlukan format biner asli, atau ketika titik akhir mengembalikan string yang dikodekan base64 dan klien hanya menerima output biner.
1. Untuk **Passthrough badan Permintaan**, pilih **Bila tidak ada templat yang ditentukan (disarankan)** untuk mengaktifkan perilaku passthrough pada badan permintaan.
Anda juga bisa memilih **Never**. Ini berarti bahwa API akan menolak data dengan tipe konten yang tidak memiliki template pemetaan.
1. Pertahankan `Accept` header permintaan masuk dalam permintaan integrasi. Anda harus melakukan ini jika Anda telah mengatur `passthrough` dan `contentHandling` ingin mengganti pengaturan itu saat runtime.
![\[Simpan Accept header dalam permintaan integrasi.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png)
1. Untuk konversi ke teks, tentukan template pemetaan untuk menempatkan data biner yang dikodekan base64 ke dalam format yang diperlukan.
Contoh template pemetaan untuk dikonversi ke teks adalah sebagai berikut:
```
{
"operation": "thumbnail",
"base64Image": "$input.body"
}
```
Format template pemetaan ini tergantung pada persyaratan titik akhir input.
1. Pilih **Simpan**.
# Mengaktifkan dukungan biner menggunakan API Gateway REST API
Tugas berikut menunjukkan cara mengaktifkan dukungan biner menggunakan panggilan API Gateway REST API.
**Topics**
+ [Menambahkan dan memperbarui tipe media biner yang didukung ke API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [Konfigurasikan konversi payload permintaan](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [Konfigurasikan konversi payload respons](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [Ubah data biner menjadi data teks](#api-gateway-payload-encodings-convert-binary-to-string)
+ [Mengkonversi data teks ke payload biner](#api-gateway-payload-encodings-convert-string-to-binary)
+ [Melewati muatan biner](#api-gateway-payload-encodings-pass-binary-as-is)
## Menambahkan dan memperbarui tipe media biner yang didukung ke API
Untuk mengaktifkan API Gateway untuk mendukung tipe media biner baru, Anda harus menambahkan jenis media biner ke `binaryMediaTypes` daftar `RestApi` sumber daya. Misalnya, agar API Gateway menangani gambar JPEG, kirimkan `PATCH` permintaan ke `RestApi` sumber daya:
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/image~1jpeg"
}
]
}
```
Spesifikasi tipe MIME `image/jpeg` yang merupakan bagian dari nilai `path` properti diloloskan sebagai. `image~1jpeg`
Untuk memperbarui jenis media biner yang didukung, ganti atau hapus jenis media dari `binaryMediaTypes` daftar `RestApi` sumber daya. Misalnya, untuk mengubah dukungan biner dari file JPEG ke byte mentah, kirimkan `PATCH` permintaan ke `RestApi` sumber daya, sebagai berikut:
```
PATCH /restapis/
{
"patchOperations" : [{
"op" : "replace",
"path" : "/binaryMediaTypes/image~1jpeg",
"value" : "application/octet-stream"
},
{
"op" : "remove",
"path" : "/binaryMediaTypes/image~1jpeg"
}]
}
```
## Konfigurasikan konversi payload permintaan
Jika titik akhir membutuhkan input biner, atur `contentHandling` properti `Integration` sumber daya ke`CONVERT_TO_BINARY`. Untuk melakukannya, kirimkan `PATCH` permintaan, sebagai berikut:
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## Konfigurasikan konversi payload respons
Jika klien menerima hasilnya sebagai gumpalan biner alih-alih muatan yang dikodekan base64 yang dikembalikan dari titik akhir, setel properti sumber daya ke. `contentHandling` `IntegrationResponse` `CONVERT_TO_BINARY` Untuk melakukan ini, kirimkan `PATCH` permintaan, sebagai berikut:
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}]
}
```
## Ubah data biner menjadi data teks
Untuk mengirim data biner sebagai properti JSON dari input ke AWS Lambda atau Kinesis melalui API Gateway, lakukan hal berikut:
1. Aktifkan dukungan payload biner API dengan menambahkan jenis media biner baru `application/octet-stream` ke `binaryMediaTypes` daftar API.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. Tetapkan `CONVERT_TO_TEXT` pada `contentHandling` properti `Integration` sumber daya dan sediakan template pemetaan untuk menetapkan string data biner yang dikodekan base64 ke properti JSON. Dalam contoh berikut, properti JSON adalah `body` dan `$input.body` memegang string yang dikodekan base64.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_TEXT"
},
{
"op" : "add",
"path" : "/requestTemplates/application~1octet-stream",
"value" : "{\"body\": \"$input.body\"}"
}
]
}
```
## Mengkonversi data teks ke payload biner
Misalkan fungsi Lambda mengembalikan file gambar sebagai string yang dikodekan base64. Untuk meneruskan output biner ini ke klien melalui API Gateway, lakukan hal berikut:
1. Perbarui `binaryMediaTypes` daftar API dengan menambahkan jenis media biner`application/octet-stream`, jika belum ada dalam daftar.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream",
}]
}
```
1. Setel `contentHandling` properti pada `Integration` sumber daya ke`CONVERT_TO_BINARY`. Jangan mendefinisikan template pemetaan. Jika Anda tidak mendefinisikan template pemetaan, API Gateway akan memanggil template passthrough untuk mengembalikan blob biner yang diterjemahkan base64 sebagai file gambar ke klien.
```
PATCH /restapis//resources//methods//integration/responses/
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
}
]
}
```
## Melewati muatan biner
Untuk menyimpan gambar di bucket Amazon S3 menggunakan API Gateway, lakukan hal berikut:
1. Perbarui `binaryMediaTypes` daftar API dengan menambahkan jenis media biner`application/octet-stream`, jika belum ada dalam daftar.
```
PATCH /restapis/
{
"patchOperations" : [ {
"op" : "add",
"path" : "/binaryMediaTypes/application~1octet-stream"
}
]
}
```
1. Pada `contentHandling` properti sumber `Integration` daya, atur`CONVERT_TO_BINARY`. Tetapkan `WHEN_NO_MATCH` sebagai nilai `passthroughBehavior` properti tanpa mendefinisikan template pemetaan. Hal ini memungkinkan API Gateway untuk memanggil template passthrough.
```
PATCH /restapis//resources//methods//integration
{
"patchOperations" : [
{
"op" : "replace",
"path" : "/contentHandling",
"value" : "CONVERT_TO_BINARY"
},
{
"op" : "replace",
"path" : "/passthroughBehaviors",
"value" : "WHEN_NO_MATCH"
}
]
}
```
# Impor dan ekspor pengkodean konten untuk API Gateway
Untuk mengimpor `binaryMediaTypes` daftar di a [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), gunakan ekstensi API Gateway berikut ke file definisi OpenAPI API. Ekstensi ini juga digunakan untuk mengekspor pengaturan API.
+ [x-amazon-apigateway-binaryproperti -media-tipe](api-gateway-swagger-extensions-binary-media-types.md)
Untuk mengimpor dan mengekspor nilai `contentHandling` properti pada `IntegrationResponse` sumber daya `Integration` atau, gunakan ekstensi API Gateway berikut ke definisi OpenAPI:
+ [x-amazon-apigateway-integration objek](api-gateway-swagger-extensions-integration.md)
+ [x-amazon-apigateway-integration.response objek](api-gateway-swagger-extensions-integration-response.md)
# Kembalikan media biner dari integrasi proxy Lambda di API Gateway
Untuk mengembalikan media biner dari [integrasi AWS Lambda proxy](set-up-lambda-proxy-integrations.md), base64 menyandikan respons dari fungsi Lambda Anda. Anda juga harus [mengonfigurasi tipe media biner API Anda](api-gateway-payload-encodings-configure-with-console.md). Saat Anda mengonfigurasi tipe media biner API Anda, API Anda memperlakukan tipe konten tersebut sebagai data biner. Batas ukuran muatan adalah 10 MB.
**catatan**
Untuk menggunakan browser web untuk menjalankan API dengan contoh integrasi ini, setel tipe media biner API Anda ke`*/*`. API Gateway menggunakan `Accept` header pertama dari klien untuk menentukan apakah respons harus mengembalikan media biner. Untuk mengembalikan media biner saat Anda tidak dapat mengontrol urutan nilai `Accept` header, seperti permintaan dari browser, setel tipe media biner API Anda ke `*/*` (untuk semua jenis konten).
Contoh berikut fungsi Lambda dapat mengembalikan gambar biner dari Amazon S3 atau teks ke klien. Respons fungsi mencakup `Content-Type` header untuk menunjukkan kepada klien jenis data yang dikembalikan. Fungsi secara kondisional menetapkan `isBase64Encoded` properti dalam responsnya, tergantung pada jenis data yang dikembalikan.
------
#### [ Node.js ]
```
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
const client = new S3Client({region: 'us-east-2'});
export const handler = async (event) => {
var randomint = function(max) {
return Math.floor(Math.random() * max);
}
var number = randomint(2);
if (number == 1){
const input = {
"Bucket" : "bucket-name",
"Key" : "image.png"
}
try {
const command = new GetObjectCommand(input)
const response = await client.send(command);
var str = await response.Body.transformToByteArray();
} catch (err) {
console.error(err);
}
const base64body = Buffer.from(str).toString('base64');
return {
'headers': { "Content-Type": "image/png" },
'statusCode': 200,
'body': base64body,
'isBase64Encoded': true
}
} else {
return {
'headers': { "Content-Type": "text/html" },
'statusCode': 200,
'body': "
",
}
```
------
Untuk mempelajari lebih lanjut tentang jenis media biner, lihat[Jenis media biner untuk REST APIs di API Gateway](api-gateway-payload-encodings.md).
# Akses file biner di Amazon S3 melalui API Gateway API
Contoh berikut menunjukkan file OpenAPI yang digunakan untuk mengakses gambar di Amazon S3, cara mengunduh gambar dari Amazon S3, dan cara mengunggah gambar ke Amazon S3.
**Topics**
+ [File OpenAPI dari API sampel untuk mengakses gambar di Amazon S3](#api-gateway-content-encodings-example-image-s3-swagger-file)
+ [Unduh gambar dari Amazon S3](#api-gateway-content-encodings-example-download-image-from-s3)
+ [Unggah gambar ke Amazon S3](#api-gateway-content-encodings-example-upload-image-to-s3)
## File OpenAPI dari API sampel untuk mengakses gambar di Amazon S3
File OpenAPI berikut menunjukkan contoh API yang menggambarkan mengunduh file gambar dari Amazon S3 dan mengunggah file gambar ke Amazon S3. API ini mengekspos `GET /s3?key={file-name}` dan `PUT /s3?key={file-name}` metode untuk mengunduh dan mengunggah file gambar tertentu. `GET`Metode mengembalikan file gambar sebagai string yang dikodekan base64 sebagai bagian dari output JSON, mengikuti template pemetaan yang disediakan, dalam respons 200 OK. `PUT`Metode ini mengambil gumpalan biner mentah sebagai input dan mengembalikan respons 200 OK dengan muatan kosong.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/s3": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling": "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/s3": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200" }
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.path.key": "method.request.querystring.key"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{key}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws",
"contentHandling" : "CONVERT_TO_BINARY"
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Unduh gambar dari Amazon S3
Untuk mengunduh file gambar (`image.jpg`) sebagai gumpalan biner dari Amazon S3:
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
Respons yang berhasil terlihat seperti ini:
```
200 OK HTTP/1.1
[raw bytes]
```
Byte mentah dikembalikan karena `Accept` header disetel ke jenis media biner `application/octet-stream` dan dukungan biner diaktifkan untuk API.
Atau, untuk mengunduh file gambar (`image.jpg`) sebagai string yang disandikan base64 (diformat sebagai properti JSON) dari Amazon S3, tambahkan template respons ke respons integrasi 200, seperti yang ditunjukkan pada blok definisi OpenAPI berwajah tebal berikut:
```
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/binarySupportRole",
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
},
```
Permintaan untuk mengunduh file gambar terlihat seperti berikut:
```
GET /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
Respons yang berhasil terlihat seperti berikut:
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Unggah gambar ke Amazon S3
Untuk mengunggah file gambar (`image.jpg`) sebagai gumpalan biner ke Amazon S3:
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
Respons yang berhasil terlihat seperti berikut:
```
200 OK HTTP/1.1
```
Untuk mengunggah file gambar (`image.jpg`) sebagai string yang dikodekan base64 ke Amazon S3:
```
PUT /v1/s3?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
Muatan input harus berupa string yang dikodekan base64 karena nilai `Content-Type` header diatur ke. `application/json` Respons yang berhasil terlihat seperti berikut:
```
200 OK HTTP/1.1
```
# Akses file biner di Lambda menggunakan API Gateway API
Contoh OpenAPI berikut menunjukkan cara mengakses file biner AWS Lambda melalui API Gateway API. API ini mengekspos `GET /lambda?key={file-name}` dan `PUT /lambda?key={file-name}` metode untuk mengunduh dan mengunggah file gambar tertentu. `GET`Metode mengembalikan file gambar sebagai string yang dikodekan base64 sebagai bagian dari output JSON, mengikuti template pemetaan yang disediakan, dalam respons 200 OK. `PUT`Metode ini mengambil gumpalan biner mentah sebagai input dan mengembalikan respons 200 OK dengan muatan kosong.
Anda membuat fungsi Lambda yang dipanggil API Anda, dan itu harus mengembalikan string yang dikodekan base64 dengan header. `Content-Type` `application/json`
**Topics**
+ [File OpenAPI dari API sampel untuk mengakses gambar di Lambda](#api-gateway-content-encodings-example-image-lambda-swagger-file)
+ [Unduh gambar dari Lambda](#api-gateway-content-encodings-example-download-image-from-lambda)
+ [Unggah gambar ke Lambda](#api-gateway-content-encodings-example-upload-image-to-lambda)
## File OpenAPI dari API sampel untuk mengakses gambar di Lambda
File OpenAPI berikut menunjukkan contoh API yang menggambarkan mengunduh file gambar dari Lambda dan mengunggah file gambar ke Lambda.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"paths": {
"/lambda": {
"get": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
},
"application/octet-stream": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types": [
"application/octet-stream",
"image/jpeg"
],
"servers": [
{
"url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/v1"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-21T17:26:28Z",
"title": "ApiName"
},
"host": "abcdefghi.execute-api.us-east-1.amazonaws.com",
"basePath": "/v1",
"schemes": [
"https"
],
"paths": {
"/lambda": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200",
"responseTemplates": {
"application/json": "{\n \"image\": \"$input.body\"\n}"
}
}
}
}
},
"put": {
"produces": [
"application/json", "application/octet-stream"
],
"parameters": [
{
"name": "key",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
},
"500": {
"description": "500 response"
}
},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations",
"type": "AWS",
"credentials": "arn:aws:iam::123456789012:role/Lambda",
"httpMethod": "POST",
"contentHandling" : "CONVERT_TO_TEXT",
"requestTemplates": {
"application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}"
},
"responses": {
"default": {
"statusCode": "500"
},
"2\\d{2}": {
"statusCode": "200"
}
}
}
}
}
},
"x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"],
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
## Unduh gambar dari Lambda
Untuk mengunduh file gambar (`image.jpg`) sebagai gumpalan biner dari Lambda:
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/octet-stream
```
Respons yang berhasil terlihat seperti berikut:
```
200 OK HTTP/1.1
[raw bytes]
```
Untuk mengunduh file gambar (`image.jpg`) sebagai string yang dikodekan base64 (diformat sebagai properti JSON) dari Lambda:
```
GET /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
```
Respons yang berhasil terlihat seperti berikut:
```
200 OK HTTP/1.1
{
"image": "W3JhdyBieXRlc10="
}
```
## Unggah gambar ke Lambda
Untuk mengunggah file gambar (`image.jpg`) sebagai gumpalan biner ke Lambda:
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/octet-stream
Accept: application/json
[raw bytes]
```
Respons yang berhasil terlihat seperti berikut:
```
200 OK
```
Untuk mengunggah file gambar (`image.jpg`) sebagai string yang dikodekan base64 ke Lambda:
```
PUT /v1/lambda?key=image.jpg HTTP/1.1
Host: abcdefghi.execute-api.us-east-1.amazonaws.com
Content-Type: application/json
Accept: application/json
W3JhdyBieXRlc10=
```
Respons yang berhasil terlihat seperti berikut:
```
200 OK
```
# Panggil REST APIs di API Gateway
Untuk memanggil API yang diterapkan, klien mengirimkan permintaan ke URL untuk layanan komponen API Gateway untuk eksekusi API, yang dikenal sebagai`execute-api`.
URL dasar untuk REST APIs adalah dalam format berikut:
```
https://api-id.execute-api.region.amazonaws.com/stage/
```
di *api-id* mana pengenal API, *region* adalah AWS Wilayah, dan *stage* merupakan nama panggung penerapan API.
**penting**
Sebelum Anda dapat menjalankan API, Anda harus menerapkannya di API Gateway. Untuk petunjuk tentang penerapan API, lihat[Menerapkan REST APIs di API Gateway](how-to-deploy-api.md).
**Topics**
+ [Mendapatkan URL pemanggilan API](#apigateway-how-to-call-rest-api)
+ [Memanggil API](#apigateway-call-api)
+ [Menggunakan konsol API Gateway untuk menguji metode REST API](how-to-test-method.md)
+ [Menggunakan Java SDK yang dihasilkan oleh API Gateway untuk REST API](how-to-call-apigateway-generated-java-sdk.md)
+ [Menggunakan Android SDK yang dihasilkan oleh API Gateway untuk REST API](how-to-generate-sdk-android.md)
+ [Menggunakan JavaScript SDK yang dihasilkan oleh API Gateway untuk REST API](how-to-generate-sdk-javascript.md)
+ [Menggunakan Ruby SDK yang dihasilkan oleh API Gateway untuk REST API](how-to-call-sdk-ruby.md)
+ [Menggunakan SDK iOS yang dihasilkan oleh API Gateway untuk REST API di Objective-C atau Swift](how-to-generate-sdk-ios.md)
## Mendapatkan URL pemanggilan API
Anda dapat menggunakan konsol, definisi OpenAPI AWS CLI, atau yang diekspor untuk mendapatkan URL pemanggilan API.
### Mendapatkan URL pemanggilan API menggunakan konsol
Prosedur berikut menunjukkan cara mendapatkan URL pemanggilan API di konsol REST API.
**Untuk mendapatkan URL pemanggilan API menggunakan konsol REST API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API yang diterapkan.
1. Dari panel navigasi utama, pilih **Stage**.
1. Di bawah **Detail tahap**, pilih ikon salin untuk menyalin URL pemanggilan API Anda.
URL ini untuk sumber daya root API Anda.
![\[Setelah Anda membuat REST API, konsol akan menampilkan URL pemanggilan API Anda.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. Untuk mendapatkan URL pemanggilan API untuk sumber daya lain di API Anda, perluas tahapan di bawah panel navigasi sekunder, lalu pilih metode.
1. Pilih ikon salin untuk menyalin URL pemanggilan tingkat sumber daya API Anda.
![\[URL tingkat sumber daya untuk REST API Anda berada di bawah panel navigasi sekunder panggung.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/resource-level-invoke-url.png)
#### Mendapatkan URL pemanggilan API menggunakan AWS CLI
Prosedur berikut menunjukkan cara mendapatkan URL pemanggilan API menggunakan. AWS CLI
**Untuk mendapatkan URL pemanggilan API menggunakan AWS CLI**
1. Gunakan perintah berikut untuk mendapatkan`rest-api-id`. Perintah ini mengembalikan semua `rest-api-id` nilai di Wilayah Anda. Untuk informasi selengkapnya, lihat [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html).
```
aws apigateway get-rest-apis
```
1. Ganti contoh `rest-api-id` dengan Anda`rest-api-id`, ganti contoh *\$1stage-name\$1* dengan Anda*\$1stage-name\$1*, dan ganti*\$1region\$1*, dengan Wilayah Anda.
```
https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/
```
##### Memperoleh URL pemanggilan API menggunakan file definisi OpenAPI yang diekspor dari API
Anda juga dapat membuat URL root dengan menggabungkan `host` dan `basePath` bidang file definisi OpenAPI yang diekspor dari API. Untuk petunjuk tentang cara mengekspor API Anda, lihat[Ekspor REST API dari API Gateway](api-gateway-export-api.md).
## Memanggil API
[Anda dapat memanggil API yang digunakan menggunakan browser, curl, atau aplikasi lain, seperti Postman.](https://www.postman.com/)
Selain itu, Anda dapat menggunakan konsol API Gateway untuk menguji panggilan API. Pengujian menggunakan `TestInvoke` fitur API Gateway, yang memungkinkan pengujian API sebelum API diterapkan. Untuk informasi selengkapnya, lihat [Menggunakan konsol API Gateway untuk menguji metode REST API](how-to-test-method.md).
**catatan**
Nilai parameter string kueri dalam URL pemanggilan tidak dapat berisi. `%%`
### Memanggil API menggunakan browser web
Jika API Anda mengizinkan akses anonim, Anda dapat menggunakan browser web apa pun untuk menjalankan metode apa pun`GET`. Masukkan URL pemanggilan lengkap di bilah alamat browser.
Untuk metode lain atau panggilan yang diperlukan otentikasi, Anda harus menentukan payload atau menandatangani permintaan. Anda dapat menangani ini dalam skrip di belakang halaman HTML atau dalam aplikasi klien menggunakan salah satu file AWS SDKs.
#### Memanggil API menggunakan curl
Anda dapat menggunakan alat seperti [curl](https://curl.se/) di terminal Anda untuk memanggil API Anda. Contoh perintah curl berikut memanggil metode GET pada `getUsers` sumber daya `prod` tahap API.
------
#### [ Linux or Macintosh ]
```
curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers'
```
------
#### [ Windows ]
```
curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers"
```
------
# Menggunakan konsol API Gateway untuk menguji metode REST API
Gunakan konsol API Gateway untuk menguji metode REST API.
**Topics**
+ [Prasyarat](#how-to-test-method-prerequisites)
+ [Uji metode dengan konsol API Gateway](#how-to-test-method-console)
## Prasyarat
+ Anda harus menentukan pengaturan untuk metode yang ingin Anda uji. Ikuti petunjuk dalam [Metode untuk REST APIs di API Gateway](how-to-method-settings.md).
## Uji metode dengan konsol API Gateway
**penting**
Metode pengujian dengan konsol API Gateway dapat mengakibatkan perubahan pada sumber daya yang tidak dapat dibatalkan. Menguji metode dengan konsol API Gateway sama dengan memanggil metode di luar konsol API Gateway. Misalnya, jika Anda menggunakan konsol API Gateway untuk memanggil metode yang menghapus sumber daya API, jika pemanggilan metode berhasil, sumber daya API akan dihapus.
**Untuk menguji suatu metode**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih REST API.
1. Di panel **Resources**, pilih metode yang ingin Anda uji.
1. Pilih tab **Uji**. Anda mungkin perlu memilih tombol panah kanan untuk menampilkan tab.
![\[Gunakan tab pengujian untuk menguji API Anda. Itu di sebelah tab respons metode.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/api-gateway-test-new-console.png)
Masukkan nilai di salah satu kotak yang ditampilkan (seperti **string Kueri**, **Header**, dan **badan Permintaan**). Konsol menyertakan nilai-nilai ini dalam permintaan metode dalam bentuk aplikasi/json default.
Untuk opsi tambahan yang mungkin perlu Anda tentukan, hubungi pemilik API.
1. Pilih **Uji**. Informasi berikut akan ditampilkan:
+ **Permintaan** adalah jalur sumber daya yang dipanggil untuk metode.
+ **Status** adalah kode status HTTP respon.
+ **Latensi (ms)** adalah waktu antara penerimaan permintaan dari penelepon dan respons yang dikembalikan.
+ **Response body** adalah badan respon HTTP.
+ **Response header** adalah header respon HTTP.
**Tip**
Bergantung pada pemetaan, kode status HTTP, badan respons, dan header respons mungkin berbeda dari yang dikirim dari fungsi Lambda, proxy HTTP, atau proxy layanan. AWS
+ **Log** adalah entri Amazon CloudWatch Log simulasi yang akan ditulis jika metode ini dipanggil di luar konsol API Gateway.
**catatan**
Meskipun entri CloudWatch Log disimulasikan, hasil pemanggilan metode adalah nyata.
Selain menggunakan konsol API Gateway, Anda dapat menggunakan AWS CLI atau AWS SDK untuk API Gateway untuk menguji pemanggilan metode. Untuk melakukannya dengan menggunakan AWS CLI, lihat [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html).
# Menggunakan Java SDK yang dihasilkan oleh API Gateway untuk REST API
Di bagian ini, kami menguraikan langkah-langkah untuk menggunakan Java SDK yang dihasilkan oleh API Gateway untuk REST API, dengan menggunakan [Simple Calculator](simple-calc-lambda-api-swagger-definition.md) API sebagai contoh. Sebelum melanjutkan, Anda harus menyelesaikan langkah-langkahnya. [Hasilkan SDKs untuk REST APIs di API Gateway](how-to-generate-sdk.md)
**Untuk menginstal dan menggunakan Java SDK yang dihasilkan oleh API Gateway**
1. Ekstrak konten file.zip yang dihasilkan API Gateway yang Anda unduh sebelumnya.
1. Unduh dan instal [Apache Maven](https://maven.apache.org/) (harus versi 3.5 atau lebih baru).
1. Unduh dan instal [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html).
1. Mengatur variabel `JAVA_HOME` lingkungan.
1. Buka folder SDK yang tidak di-zip tempat file pom.xml berada. Folder ini secara `generated-code` default. Jalankan **mvn install** perintah untuk menginstal file artefak yang dikompilasi ke repositori Maven lokal Anda. Ini membuat `target` folder yang berisi pustaka SDK yang dikompilasi.
1. Ketik perintah berikut di direktori kosong untuk membuat rintisan proyek klien untuk memanggil API menggunakan pustaka SDK yang diinstal.
```
mvn -B archetype:generate \
-DarchetypeGroupdId=org.apache.maven.archetypes \
-DgroupId=examples.aws.apig.simpleCalc.sdk.app \
-DartifactId=SimpleCalc-sdkClient
```
**catatan**
Pemisah `\` dalam perintah sebelumnya disertakan untuk keterbacaan. Seluruh perintah harus pada satu baris tanpa pemisah.
Perintah ini menciptakan sebuah rintisan aplikasi. Aplikasi rintisan berisi `pom.xml` file dan `src` folder di bawah direktori root proyek (*SimpleCalc-sdkClient*dalam perintah sebelumnya). Awalnya, ada dua file sumber: `src/main/java/{package-path}/App.java` dan`src/test/java/{package-path}/AppTest.java`. Dalam contoh ini, *\$1package-path\$1* adalah`examples/aws/apig/simpleCalc/sdk/app`. Jalur paket ini berasal dari `DarchetypeGroupdId` nilai. Anda dapat menggunakan `App.java` file sebagai template untuk aplikasi klien Anda, dan Anda dapat menambahkan yang lain di folder yang sama jika diperlukan. Anda dapat menggunakan `AppTest.java` file sebagai templat pengujian unit untuk aplikasi Anda, dan Anda dapat menambahkan file kode pengujian lainnya ke folder pengujian yang sama sesuai kebutuhan.
1. Perbarui dependensi paket dalam `pom.xml` file yang dihasilkan menjadi berikut, ganti `name` properti proyek`groupId`,, dan Anda `artifactId``version`, jika perlu:
```
4.0.0examples.aws.apig.simpleCalc.sdk.appSimpleCalc-sdkClientjar1.0-SNAPSHOTSimpleCalc-sdkClienthttp://maven.apache.orgcom.amazonawsaws-java-sdk-core1.11.94my-apig-api-examplessimple-calc-sdk1.0.0junitjunit4.12testcommons-iocommons-io2.5org.apache.maven.pluginsmaven-compiler-plugin3.5.11.81.8
```
**catatan**
Ketika versi artefak dependen yang lebih baru tidak `aws-java-sdk-core` kompatibel dengan versi yang ditentukan di atas (`1.11.94`), Anda harus memperbarui `` tag ke versi baru.
1. Selanjutnya, kami menunjukkan cara memanggil API menggunakan SDK dengan memanggil`getABOp(GetABOpRequest req)`,`getApiRoot(GetApiRootRequest req)`, dan `postApiRoot(PostApiRootRequest req)` metode SDK. Metode ini sesuai dengan`GET /{a}/{b}/{op}`,`GET /?a={x}&b={y}&op={operator}`, dan `POST /` metode, dengan muatan permintaan `{"a": x, "b": y, "op": "operator"}` API, masing-masing.
Perbarui `App.java` file sebagai berikut:
```
package examples.aws.apig.simpleCalc.sdk.app;
import java.io.IOException;
import com.amazonaws.opensdk.config.ConnectionConfiguration;
import com.amazonaws.opensdk.config.TimeoutConfiguration;
import examples.aws.apig.simpleCalc.sdk.*;
import examples.aws.apig.simpleCalc.sdk.model.*;
import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*;
public class App
{
SimpleCalcSdk sdkClient;
public App() {
initSdk();
}
// The configuration settings are for illustration purposes and may not be a recommended best practice.
private void initSdk() {
sdkClient = SimpleCalcSdk.builder()
.connectionConfiguration(
new ConnectionConfiguration()
.maxConnections(100)
.connectionMaxIdleMillis(1000))
.timeoutConfiguration(
new TimeoutConfiguration()
.httpRequestTimeout(3000)
.totalExecutionTimeout(10000)
.socketTimeout(2000))
.build();
}
// Calling shutdown is not necessary unless you want to exert explicit control of this resource.
public void shutdown() {
sdkClient.shutdown();
}
// GetABOpResult getABOp(GetABOpRequest getABOpRequest)
public Output getResultWithPathParameters(String x, String y, String operator) {
operator = operator.equals("+") ? "add" : operator;
operator = operator.equals("/") ? "div" : operator;
GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator));
return abopResult.getResult().getOutput();
}
public Output getResultWithQueryParameters(String a, String b, String op) {
GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op));
return rootResult.getResult().getOutput();
}
public Output getResultByPostInputBody(Double x, Double y, String o) {
PostApiRootResult postResult = sdkClient.postApiRoot(
new PostApiRootRequest().input(new Input().a(x).b(y).op(o)));
return postResult.getResult().getOutput();
}
public static void main( String[] args )
{
System.out.println( "Simple calc" );
// to begin
App calc = new App();
// call the SimpleCalc API
Output res = calc.getResultWithPathParameters("1", "2", "-");
System.out.printf("GET /1/2/-: %s\n", res.getC());
// Use the type query parameter
res = calc.getResultWithQueryParameters("1", "2", "+");
System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC());
// Call POST with an Input body.
res = calc.getResultByPostInputBody(1.0, 2.0, "*");
System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC());
}
}
```
Dalam contoh sebelumnya, pengaturan konfigurasi yang digunakan untuk membuat instance klien SDK adalah untuk tujuan ilustrasi dan belum tentu direkomendasikan praktik terbaik. Selain itu, menelepon `sdkClient.shutdown()` adalah opsional, terutama jika Anda memerlukan kontrol yang tepat kapan harus membebaskan sumber daya.
Kami telah menunjukkan pola penting untuk memanggil API menggunakan Java SDK. Anda dapat memperluas instruksi untuk memanggil metode API lainnya.
# Menggunakan Android SDK yang dihasilkan oleh API Gateway untuk REST API
Di bagian ini, kami akan menguraikan langkah-langkah untuk menggunakan SDK Android yang dihasilkan oleh API Gateway untuk REST API. Sebelum melangkah lebih jauh, Anda harus sudah menyelesaikan langkah-langkahnya. [Hasilkan SDKs untuk REST APIs di API Gateway](how-to-generate-sdk.md)
**catatan**
SDK yang dihasilkan tidak kompatibel dengan Android 4.4 dan yang lebih lama. Untuk informasi selengkapnya, lihat [Catatan penting Amazon API Gateway](api-gateway-known-issues.md).
**Untuk menginstal dan menggunakan Android SDK yang dihasilkan oleh API Gateway**
1. Ekstrak konten file.zip yang dihasilkan API Gateway yang Anda unduh sebelumnya.
1. Unduh dan instal [Apache Maven](https://maven.apache.org/) (lebih disukai versi 3.x).
1. Unduh dan instal [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html).
1. Mengatur variabel `JAVA_HOME` lingkungan.
1. Jalankan **mvn install** perintah untuk menginstal file artefak yang dikompilasi ke repositori Maven lokal Anda. Ini membuat `target` folder yang berisi pustaka SDK yang dikompilasi.
1. Salin file SDK (nama yang berasal dari Id **Artifact** dan Versi **Artifact** yang Anda tentukan saat membuat SDK, misalnya,) dari `target` folder`simple-calcsdk-1.0.0.jar`, bersama dengan semua pustaka lain dari `target/lib` folder, ke folder proyek Anda. `lib`
Jika Anda menggunakan Android Studio, buat `libs` folder di bawah modul aplikasi klien Anda dan salin file.jar yang diperlukan ke folder ini. Verifikasi bahwa bagian dependensi dalam file gradle modul berisi yang berikut ini.
```
compile fileTree(include: ['*.jar'], dir: 'libs')
compile fileTree(include: ['*.jar'], dir: 'app/libs')
```
Pastikan tidak ada file.jar duplikat yang dideklarasikan.
1. Gunakan `ApiClientFactory` class untuk menginisialisasi SDK yang dihasilkan API GateWay-generated. Sebagai contoh:
```
ApiClientFactory factory = new ApiClientFactory();
// Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway.
final SimpleCalcClient client = factory.build(SimpleCalcClient.class);
// Invoke a method:
// For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method:
Result output = client.rootGet("1", "2", "+");
// where the Result class of the SDK corresponds to the Result model of the API.
//
// For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request,
Result output = client.aBOpGet(a, b, c);
// where a, b, c can be "1", "2", "add", respectively.
// For the following API method:
// POST /
// host: ...
// Content-Type: application/json
//
// { "a": 1, "b": 2, "op": "+" }
// you can call invoke it by calling the rootPost method of the SDK as follows:
Input body = new Input();
input.a=1;
input.b=2;
input.op="+";
Result output = client.rootPost(body);
// where the Input class of the SDK corresponds to the Input model of the API.
// Parse the result:
// If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as
String result=output.c;
```
1. Untuk menggunakan penyedia kredensial Amazon Cognito untuk mengotorisasi panggilan ke API Anda, gunakan `ApiClientFactory` kelas untuk meneruskan sekumpulan AWS kredensional menggunakan SDK yang dihasilkan oleh API Gateway, seperti yang ditunjukkan pada contoh berikut.
```
// Use CognitoCachingCredentialsProvider to provide AWS credentials
// for the ApiClientFactory
AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider(
context, // activity context
"identityPoolId", // Cognito identity pool id
Regions.US_EAST_1 // region of Cognito identity pool
);
ApiClientFactory factory = new ApiClientFactory()
.credentialsProvider(credentialsProvider);
```
1. Untuk menyetel kunci API menggunakan SDK yang dihasilkan API Gateway, gunakan kode yang mirip dengan berikut ini.
```
ApiClientFactory factory = new ApiClientFactory()
.apiKey("YOUR_API_KEY");
```
# Menggunakan JavaScript SDK yang dihasilkan oleh API Gateway untuk REST API
Prosedur berikut menunjukkan cara menggunakan JavaScript SDK yang dihasilkan oleh API Gateway.
**catatan**
Instruksi ini menganggap Anda telah menyelesaikan instruksi di[Hasilkan SDKs untuk REST APIs di API Gateway](how-to-generate-sdk.md).
**penting**
Jika API Anda hanya memiliki metode APAPUN yang ditentukan, paket SDK yang dihasilkan tidak akan berisi `apigClient.js` file, dan Anda harus menentukan sendiri metode APAPUN.
**Untuk menginstal, memulai dan memanggil JavaScript SDK yang dihasilkan oleh API Gateway untuk REST API**
1. Ekstrak konten file.zip buatan API Gateway yang Anda unduh sebelumnya.
1. Aktifkan berbagi sumber daya lintas asal (CORS) untuk semua metode yang akan dipanggil oleh SDK yang dihasilkan oleh API Gateway. Untuk petunjuk, lihat [CORS untuk REST APIs di API Gateway](how-to-cors.md).
1. Di halaman web Anda, sertakan referensi ke skrip berikut.
```
```
1. Dalam kode Anda, inisialisasi SDK yang dihasilkan oleh API Gateway dengan menggunakan kode yang mirip dengan berikut ini.
```
var apigClient = apigClientFactory.newClient();
```
Untuk menginisialisasi SDK yang dihasilkan oleh API Gateway dengan AWS kredensional, gunakan kode yang mirip dengan berikut ini. Jika Anda menggunakan AWS kredensional, semua permintaan ke API akan ditandatangani.
```
var apigClient = apigClientFactory.newClient({
accessKey: 'ACCESS_KEY',
secretKey: 'SECRET_KEY',
});
```
Untuk menggunakan kunci API dengan SDK yang dihasilkan oleh API Gateway, teruskan kunci API sebagai parameter ke `Factory` objek dengan menggunakan kode yang mirip dengan berikut ini. Jika Anda menggunakan kunci API, kunci tersebut ditentukan sebagai bagian dari `x-api-key` header dan semua permintaan ke API akan ditandatangani. Ini berarti Anda harus mengatur header CORS Accept yang sesuai untuk setiap permintaan.
```
var apigClient = apigClientFactory.newClient({
apiKey: 'API_KEY'
});
```
1. Panggil metode API di API Gateway dengan menggunakan kode yang mirip dengan berikut ini. Setiap panggilan mengembalikan janji dengan callback sukses dan gagal.
```
var params = {
// This is where any modeled request parameters should be added.
// The key is the parameter name, as it is defined in the API in API Gateway.
param0: '',
param1: ''
};
var body = {
// This is where you define the body of the request,
};
var additionalParams = {
// If there are any unmodeled query parameters or headers that must be
// sent with the request, add them here.
headers: {
param0: '',
param1: ''
},
queryParams: {
param0: '',
param1: ''
}
};
apigClient.methodName(params, body, additionalParams)
.then(function(result){
// Add success callback code here.
}).catch( function(result){
// Add error callback code here.
});
```
Di sini, *methodName* dibangun dari jalur sumber daya permintaan metode dan kata kerja HTTP. Untuk SimpleCalc API, metode SDK untuk metode API
```
1. GET /?a=...&b=...&op=...
2. POST /
{ "a": ..., "b": ..., "op": ...}
3. GET /{a}/{b}/{op}
```
metode SDK yang sesuai adalah sebagai berikut:
```
1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters
2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...}
3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters
```
# Menggunakan Ruby SDK yang dihasilkan oleh API Gateway untuk REST API
Prosedur berikut menunjukkan cara menggunakan Ruby SDK yang dihasilkan oleh API Gateway.
**catatan**
Instruksi ini mengasumsikan Anda sudah menyelesaikan instruksi di[Hasilkan SDKs untuk REST APIs di API Gateway](how-to-generate-sdk.md).
**Untuk menginstal, membuat instance, dan memanggil Ruby SDK yang dihasilkan oleh API Gateway untuk REST API**
1. Buka zip file Ruby SDK yang diunduh. Sumber SDK yang dihasilkan ditampilkan sebagai berikut.
![\[Buka zip file Ruby SDK yang diunduh ke dalam modul Ruby\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png)
1. Buat Ruby Gem dari sumber SDK yang dihasilkan, menggunakan perintah shell berikut di jendela terminal:
```
# change to /simplecalc-sdk directory
cd simplecalc-sdk
# build the generated gem
gem build simplecalc-sdk.gemspec
```
Setelah ini, **simplecalc-sdk-1.0.0.gem** menjadi tersedia.
1. Instal permata:
```
gem install simplecalc-sdk-1.0.0.gem
```
1. Buat aplikasi klien. Buat instance dan inisialisasi klien Ruby SDK di aplikasi:
```
require 'simplecalc-sdk'
client = SimpleCalc::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50
)
```
Jika API memiliki otorisasi `AWS_IAM` jenis yang dikonfigurasi, Anda dapat menyertakan AWS kredensi pemanggil dengan menyediakan `accessKey` dan selama inisialisasi: `secretKey`
```
require 'pet-sdk'
client = Pet::Client.new(
http_wire_trace: true,
retry_limit: 5,
http_read_timeout: 50,
access_key_id: 'ACCESS_KEY',
secret_access_key: 'SECRET_KEY'
)
```
1. Lakukan panggilan API melalui SDK di aplikasi.
**Tip**
Jika Anda tidak terbiasa dengan konvensi panggilan metode SDK, Anda dapat meninjau `client.rb` file di folder SDK `lib` yang dihasilkan. Folder berisi dokumentasi setiap panggilan metode API yang didukung.
Untuk menemukan operasi yang didukung:
```
# to show supported operations:
puts client.operation_names
```
Ini menghasilkan tampilan berikut, sesuai dengan metode API `GET /?a={.}&b={.}&op={.}``GET /{a}/{b}/{op}`, dan`POST /`, ditambah muatan `{a:"…", b:"…", op:"…"}` format, masing-masing:
```
[:get_api_root, :get_ab_op, :post_api_root]
```
Untuk menjalankan metode `GET /?a=1&b=2&op=+` API, panggil metode Ruby SDK berikut ini:
```
resp = client.get_api_root({a:"1", b:"2", op:"+"})
```
Untuk menjalankan metode `POST /` API dengan payload sebesar`{a: "1", b: "2", "op": "+"}`, panggil metode Ruby SDK berikut:
```
resp = client.post_api_root(input: {a:"1", b:"2", op:"+"})
```
Untuk menjalankan metode `GET /1/2/+` API, panggil metode Ruby SDK berikut:
```
resp = client.get_ab_op({a:"1", b:"2", op:"+"})
```
Pemanggilan metode SDK yang berhasil mengembalikan respons berikut:
```
resp : {
result: {
input: {
a: 1,
b: 2,
op: "+"
},
output: {
c: 3
}
}
}
```
# Menggunakan SDK iOS yang dihasilkan oleh API Gateway untuk REST API di Objective-C atau Swift
Dalam tutorial ini, kami akan menunjukkan cara menggunakan SDK iOS yang dihasilkan oleh API Gateway untuk REST API di aplikasi Objective-C atau Swift untuk memanggil API yang mendasarinya. Kami akan menggunakan [SimpleCalc API](simple-calc-lambda-api.md) sebagai contoh untuk mengilustrasikan topik-topik berikut:
+ Cara menginstal komponen AWS Mobile SDK yang diperlukan ke dalam proyek Xcode Anda
+ Cara membuat objek klien API sebelum memanggil metode API
+ Cara memanggil metode API melalui metode SDK yang sesuai pada objek klien API
+ Cara menyiapkan input metode dan mengurai hasilnya menggunakan kelas model SDK yang sesuai
**Topics**
+ [Menggunakan SDK iOS (Objective-C) yang dihasilkan untuk memanggil API](#how-to-use-sdk-ios-objc)
+ [Menggunakan SDK iOS (Swift) yang dihasilkan untuk memanggil API](#how-to-generate-sdk-ios-swift)
## Menggunakan SDK iOS (Objective-C) yang dihasilkan untuk memanggil API
Sebelum memulai prosedur berikut, Anda harus menyelesaikan langkah-langkah [Hasilkan SDKs untuk REST APIs di API Gateway](how-to-generate-sdk.md) untuk iOS di Objective-C dan mengunduh file.zip dari SDK yang dihasilkan.
### Instal SDK AWS seluler dan SDK iOS yang dihasilkan oleh API Gateway dalam proyek Objective-C
Prosedur berikut menjelaskan cara menginstal SDK.
**Untuk menginstal dan menggunakan SDK iOS yang dihasilkan oleh API Gateway di Objective-C**
1. Ekstrak konten file.zip buatan API Gateway yang Anda unduh sebelumnya. Dengan menggunakan [SimpleCalc API](simple-calc-lambda-api.md), Anda mungkin ingin mengganti nama folder SDK yang tidak di-zip menjadi sesuatu seperti. **sdk\$1objc\$1simple\$1calc** Di folder SDK ini ada `README.md` file dan `Podfile` file. `README.md`File berisi instruksi untuk menginstal dan menggunakan SDK. Tutorial ini memberikan rincian tentang instruksi ini. Penginstalan memanfaatkan [CocoaPods](https://cocoapods.org)untuk mengimpor pustaka API Gateway yang diperlukan dan komponen AWS Mobile SDK dependen lainnya. Anda harus memperbarui `Podfile` untuk mengimpor SDKs ke proyek Xcode aplikasi Anda. Folder SDK yang tidak diarsipkan juga berisi `generated-src` folder yang berisi kode sumber SDK yang dihasilkan dari API Anda.
1. Luncurkan Xcode dan buat proyek iOS Objective-C baru. Catat target proyek. Anda harus mengaturnya di`Podfile`.
![\[Temukan target di Xcode.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png)
1. Untuk mengimpor AWS Mobile SDK for iOS ke dalam proyek Xcode dengan menggunakan CocoaPods, lakukan hal berikut:
1. Instal CocoaPods dengan menjalankan perintah berikut di jendela terminal:
```
sudo gem install cocoapods
pod setup
```
1. Salin `Podfile` file dari folder SDK yang diekstrak ke direktori yang sama yang berisi file proyek Xcode Anda. Ganti blok berikut:
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
dengan nama target proyek Anda:
```
target 'app_objc_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Jika proyek Xcode Anda sudah berisi file bernama`Podfile`, tambahkan baris kode berikut ke dalamnya:
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. Buka jendela terminal dan jalankan perintah berikut:
```
pod install
```
Ini menginstal komponen API Gateway dan komponen AWS Mobile SDK dependen lainnya.
1. Tutup proyek Xcode dan kemudian buka `.xcworkspace` file untuk meluncurkan kembali Xcode.
1. Tambahkan semua `.m` file `.h` dan file dari `generated-src` direktori SDK yang diekstrak ke proyek Xcode Anda.
![\[.h dan.m file ada di src yang dihasilkan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png)
*Untuk mengimpor AWS Mobile SDK for iOS Objective-C ke project Anda dengan mengunduh AWS Mobile SDK secara eksplisit atau menggunakan [Carthage](https://github.com/Carthage/Carthage#installing-carthage), ikuti petunjuk dalam file README.md.* Pastikan untuk hanya menggunakan salah satu opsi ini untuk mengimpor SDK AWS Seluler.
### Memanggil metode API menggunakan SDK iOS yang dihasilkan oleh API Gateway dalam proyek Objective-C
Saat Anda membuat SDK dengan awalan `SIMPLE_CALC` untuk [SimpleCalc API](simple-calc-lambda-api.md) ini dengan dua model untuk input (`Input`) dan output (`Result`) metode, di SDK, kelas klien API yang dihasilkan menjadi `SIMPLE_CALCSimpleCalcClient` dan kelas data yang sesuai adalah `SIMPLE_CALCInput` dan`SIMPLE_CALCResult`, masing-masing. Permintaan dan respons API dipetakan ke metode SDK sebagai berikut:
+ Permintaan API dari
```
GET /?a=...&b=...&op=...
```
menjadi metode SDK dari
```
(AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b
```
`AWSTask.result`Properti adalah `SIMPLE_CALCResult` tipe jika `Result` model ditambahkan ke respons metode. Jika tidak, properti adalah `NSDictionary` tipe.
+ Permintaan API ini dari
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
menjadi metode SDK dari
```
(AWSTask *)rootPost:(SIMPLE_CALCInput *)body
```
+ Permintaan API dari
```
GET /{a}/{b}/{op}
```
menjadi metode SDK dari
```
(AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op
```
Prosedur berikut menjelaskan cara memanggil metode API dalam kode sumber aplikasi Objective-C; misalnya, sebagai bagian dari `viewDidLoad` delegasi dalam file. `ViewController.m`
**Untuk memanggil API melalui SDK iOS yang dihasilkan oleh API Gateway**
1. Impor file header kelas klien API untuk membuat kelas klien API dapat dipanggil di aplikasi:
```
#import "SIMPLE_CALCSimpleCalc.h"
```
`#import`Pernyataan itu juga mengimpor `SIMPLE_CALCInput.h` dan `SIMPLE_CALCResult.h` untuk dua kelas model.
1. Buat instance class klien API:
```
SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient];
```
Untuk menggunakan Amazon Cognito dengan API, setel `defaultServiceConfiguration` properti pada `AWSServiceManager` objek default, seperti yang ditunjukkan di bawah ini, sebelum memanggil `defaultClient` metode untuk membuat objek klien API (ditunjukkan pada contoh sebelumnya):
```
AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id];
AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds];
AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration;
```
1. Panggil `GET /?a=1&b=2&op=+` metode untuk melakukan`1+2`:
```
[[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField1.text = [self handleApiResponse:task];
return nil;
}];
```
di mana fungsi pembantu `handleApiResponse:task` memformat hasilnya sebagai string yang akan ditampilkan dalam bidang teks (`_textField1`).
```
- (NSString *)handleApiResponse:(AWSTask *)task {
if (task.error != nil) {
return [NSString stringWithFormat: @"Error: %@", task.error.description];
} else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) {
return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c];
}
return nil;
}
```
Tampilan yang dihasilkan adalah`1 + 2 = 3`.
1. Panggil `POST /` dengan muatan untuk melakukan`1-2`:
```
SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init];
input.a = [NSNumber numberWithInt:1];
input.b = [NSNumber numberWithInt:2];
input.op = @"-";
[[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField2.text = [self handleApiResponse:task];
return nil;
}];
```
Tampilan yang dihasilkan adalah`1 - 2 = -1`.
1. Panggil `GET /{a}/{b}/{op}` untuk melakukan`1/2`:
```
[[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) {
_textField3.text = [self handleApiResponse:task];
return nil;
}];
```
Tampilan yang dihasilkan adalah`1 div 2 = 0.5`. Di sini, `div` digunakan sebagai pengganti `/` karena [fungsi Lambda sederhana](simple-calc-nodejs-lambda-function.md) di backend tidak menangani variabel jalur yang dikodekan URL.
## Menggunakan SDK iOS (Swift) yang dihasilkan untuk memanggil API
Sebelum memulai prosedur berikut, Anda harus menyelesaikan langkah-langkah [Hasilkan SDKs untuk REST APIs di API Gateway](how-to-generate-sdk.md) untuk iOS di Swift dan mengunduh file.zip dari SDK yang dihasilkan.
**Topics**
+ [Instal SDK AWS seluler dan SDK yang dihasilkan API Gateway dalam proyek Swift](#use-sdk-ios-swift-install-sdk)
+ [Memanggil metode API melalui SDK iOS yang dihasilkan oleh API Gateway dalam proyek Swift](#use-sdk-ios-swift-call-api)
### Instal SDK AWS seluler dan SDK yang dihasilkan API Gateway dalam proyek Swift
Prosedur berikut menjelaskan cara menginstal SDK.
**Untuk menginstal dan menggunakan SDK iOS yang dihasilkan oleh API Gateway di Swift**
1. Ekstrak konten file.zip buatan API Gateway yang Anda unduh sebelumnya. Dengan menggunakan [SimpleCalc API](simple-calc-lambda-api.md), Anda mungkin ingin mengganti nama folder SDK yang tidak di-zip menjadi sesuatu seperti. **sdk\$1swift\$1simple\$1calc** Di folder SDK ini ada `README.md` file dan `Podfile` file. `README.md`File berisi instruksi untuk menginstal dan menggunakan SDK. Tutorial ini memberikan rincian tentang instruksi ini. Penginstalan memanfaatkan [CocoaPods](https://cocoapods.org)untuk mengimpor komponen AWS Mobile SDK yang diperlukan. Anda harus memperbarui `Podfile` untuk mengimpor SDKs ke proyek Xcode aplikasi Swift Anda. Folder SDK yang tidak diarsipkan juga berisi `generated-src` folder yang berisi kode sumber SDK yang dihasilkan dari API Anda.
1. Luncurkan Xcode dan buat proyek iOS Swift baru. Catat target proyek. Anda harus mengaturnya di`Podfile`.
![\[Temukan target di Xcode.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png)
1. Untuk mengimpor komponen AWS Mobile SDK yang diperlukan ke dalam proyek Xcode dengan menggunakan CocoaPods, lakukan hal berikut:
1. Jika tidak diinstal, instal CocoaPods dengan menjalankan perintah berikut di jendela terminal:
```
sudo gem install cocoapods
pod setup
```
1. Salin `Podfile` file dari folder SDK yang diekstrak ke direktori yang sama yang berisi file proyek Xcode Anda. Ganti blok berikut:
```
target '' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
dengan nama target proyek Anda seperti yang ditunjukkan:
```
target 'app_swift_simple_calc' do
pod 'AWSAPIGateway', '~> 2.4.7'
end
```
Jika proyek Xcode Anda sudah berisi a `Podfile` dengan target yang benar, Anda cukup menambahkan baris kode berikut ke `do ... end` loop:
```
pod 'AWSAPIGateway', '~> 2.4.7'
```
1. Buka jendela terminal dan jalankan perintah berikut di direktori aplikasi:
```
pod install
```
Ini menginstal komponen API Gateway dan komponen AWS Mobile SDK dependen apa pun ke dalam proyek aplikasi.
1. Tutup proyek Xcode dan kemudian buka `*.xcworkspace` file untuk meluncurkan kembali Xcode.
1. Tambahkan semua file header SDK (`.h`) dan file kode sumber Swift (`.swift`) dari `generated-src` direktori yang diekstrak ke proyek Xcode Anda.
![\[.h dan.swift ada di src yang dihasilkan\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png)
1. **Untuk mengaktifkan pemanggilan pustaka Objective-C dari AWS Mobile SDK dari proyek kode Swift Anda, setel path `Bridging_Header.h` file pada properti **Objective-C Bridging Header** di bawah Swift Compiler - Pengaturan umum konfigurasi proyek Xcode Anda:**
![\[Atur jalur file Bridging_Header.h di bawah Swift Compiler - General.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png)
**Tip**
Anda dapat mengetik **bridging** di kotak pencarian Xcode untuk menemukan properti **Objective-C** Bridging Header.
1. Bangun proyek Xcode untuk memverifikasi bahwa itu dikonfigurasi dengan benar sebelum melanjutkan lebih jauh. Jika Xcode Anda menggunakan versi Swift yang lebih baru daripada yang didukung untuk AWS Mobile SDK, Anda akan mendapatkan kesalahan kompiler Swift. Dalam hal ini, setel properti **Use Legacy Swift Language Version** ke **Ya** di bawah pengaturan **Swift Compiler** - Version:
![\[Setel properti Legacy Swift Language Version ke Ya.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png)
Untuk mengimpor SDK AWS Seluler untuk iOS di Swift ke proyek Anda dengan mengunduh AWS SDK Seluler secara eksplisit atau [menggunakan](https://github.com/Carthage/Carthage#installing-carthage) Carthage, ikuti petunjuk dalam `README.md` file yang disertakan dengan paket SDK. Pastikan untuk hanya menggunakan salah satu opsi ini untuk mengimpor SDK AWS Seluler.
### Memanggil metode API melalui SDK iOS yang dihasilkan oleh API Gateway dalam proyek Swift
Saat Anda membuat SDK dengan awalan untuk [SimpleCalc API](simple-calc-lambda-api.md) ini dengan dua model `SIMPLE_CALC` untuk mendeskripsikan input (`Input`) dan output (`Result`) permintaan dan respons API, di SDK, kelas klien API yang dihasilkan menjadi `SIMPLE_CALCSimpleCalcClient` dan kelas data yang sesuai adalah `SIMPLE_CALCInput` dan`SIMPLE_CALCResult`, masing-masing. Permintaan dan respons API dipetakan ke metode SDK sebagai berikut:
+ Permintaan API dari
```
GET /?a=...&b=...&op=...
```
menjadi metode SDK dari
```
public func rootGet(op: String?, a: String?, b: String?) -> AWSTask
```
`AWSTask.result`Properti adalah `SIMPLE_CALCResult` tipe jika `Result` model ditambahkan ke respons metode. Kalau tidak, itu adalah `NSDictionary` tipe.
+ Permintaan API ini dari
```
POST /
{
"a": "Number",
"b": "Number",
"op": "String"
}
```
menjadi metode SDK dari
```
public func rootPost(body: SIMPLE_CALCInput) -> AWSTask
```
+ Permintaan API dari
```
GET /{a}/{b}/{op}
```
menjadi metode SDK dari
```
public func aBOpGet(a: String, b: String, op: String) -> AWSTask
```
Prosedur berikut menjelaskan cara memanggil metode API dalam kode sumber aplikasi Swift; misalnya, sebagai bagian dari `viewDidLoad()` delegasi dalam file. `ViewController.m`
**Untuk memanggil API melalui SDK iOS yang dihasilkan oleh API Gateway**
1. Buat instance class klien API:
```
let client = SIMPLE_CALCSimpleCalcClient.default()
```
Untuk menggunakan Amazon Cognito dengan API, tetapkan konfigurasi AWS layanan default (ditampilkan berikut) sebelum mendapatkan `default` metode (ditampilkan sebelumnya):
```
let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id")
let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider)
AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration
```
1. Panggil `GET /?a=1&b=2&op=+` metode untuk melakukan`1+2`:
```
client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
di mana fungsi pembantu `self.showResult(task)` mencetak hasil atau kesalahan ke konsol; misalnya:
```
func showResult(task: AWSTask) {
if let error = task.error {
print("Error: \(error)")
} else if let result = task.result {
if result is SIMPLE_CALCResult {
let res = result as! SIMPLE_CALCResult
print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!))
} else if result is NSDictionary {
let res = result as! NSDictionary
print("NSDictionary: \(res)")
}
}
}
```
Di aplikasi produksi, Anda dapat menampilkan hasil atau kesalahan di bidang teks. Tampilan yang dihasilkan adalah`1 + 2 = 3`.
1. Panggil `POST /` dengan muatan untuk melakukan`1-2`:
```
let body = SIMPLE_CALCInput()
body.a=1
body.b=2
body.op="-"
client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
Tampilan yang dihasilkan adalah`1 - 2 = -1`.
1. Panggil `GET /{a}/{b}/{op}` untuk melakukan`1/2`:
```
client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in
self.showResult(task)
return nil
}
```
Tampilan yang dihasilkan adalah`1 div 2 = 0.5`. Di sini, `div` digunakan sebagai pengganti `/` karena [fungsi Lambda sederhana](simple-calc-nodejs-lambda-function.md) di backend tidak menangani variabel jalur yang dikodekan URL.
# Kembangkan REST APIs menggunakan OpenAPI di API Gateway
Anda dapat menggunakan API Gateway untuk mengimpor REST API dari file definisi eksternal ke API Gateway. Saat ini, API Gateway mendukung file definisi [OpenAPIv2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) dan [OpenAPIv3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md), dengan pengecualian yang tercantum dalam file. [Catatan penting Amazon API Gateway untuk REST APIs](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis) Anda dapat memperbarui API dengan menimpa dengan definisi baru, atau Anda dapat menggabungkan definisi dengan API yang ada. Anda menentukan opsi dengan menggunakan parameter `mode` kueri di URL permintaan.
Untuk tutorial tentang penggunaan fitur Impor API dari konsol API Gateway, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md).
**Topics**
+ [Impor API yang dioptimalkan tepi ke API Gateway](import-edge-optimized-api.md)
+ [Impor API Regional ke API Gateway](import-export-api-endpoints.md)
+ [Impor file OpenAPI untuk memperbarui definisi API yang ada](api-gateway-import-api-update.md)
+ [Mengatur properti OpenAPI `basePath`](api-gateway-import-api-basePath.md)
+ [AWS variabel untuk impor OpenAPI](import-api-aws-variables.md)
+ [Kesalahan dan peringatan dari mengimpor API Anda ke API Gateway](api-gateway-import-api-errors-warnings.md)
+ [Ekspor REST API dari API Gateway](api-gateway-export-api.md)
# Impor API yang dioptimalkan tepi ke API Gateway
Anda dapat mengimpor file definisi OpenAPI API untuk membuat API baru yang dioptimalkan tepi dengan menentukan tipe `EDGE` titik akhir sebagai input tambahan, selain file OpenAPI, ke operasi impor. Anda dapat melakukannya menggunakan konsol API Gateway AWS CLI, atau AWS SDK.
Untuk tutorial tentang penggunaan fitur Impor API dari konsol API Gateway, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md).
**Topics**
+ [Impor API yang dioptimalkan tepi menggunakan konsol API Gateway](#import-edge-optimized-api-with-console)
+ [Impor API yang dioptimalkan tepi menggunakan AWS CLI](#import-edge-optimized-api-with-awscli)
## Impor API yang dioptimalkan tepi menggunakan konsol API Gateway
Untuk mengimpor API yang dioptimalkan tepi menggunakan konsol API Gateway, lakukan hal berikut:
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Buat API**.
1. Di bawah **REST API**, pilih **Impor**.
1. Salin definisi OpenAPI API dan tempelkan ke editor kode, atau pilih **Pilih file untuk memuat file** OpenAPI dari drive lokal.
1. Untuk **jenis titik akhir API, pilih Optimalisasi** **tepi**.
1. Pilih **Buat API** untuk mulai mengimpor definisi OpenAPI.
## Impor API yang dioptimalkan tepi menggunakan AWS CLI
[import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)Perintah berikut mengimpor API dari file definisi OpenAPI untuk membuat API baru yang dioptimalkan tepi:
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
atau dengan spesifikasi eksplisit dari parameter string `endpointConfigurationTypes` kueri untuk`EDGE`:
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# Impor API Regional ke API Gateway
Saat mengimpor API, Anda dapat memilih konfigurasi titik akhir regional untuk API. Anda dapat menggunakan konsol API Gateway, the AWS CLI, atau AWS SDK.
Saat Anda mengekspor API, konfigurasi titik akhir API tidak disertakan dalam definisi API yang diekspor.
Untuk tutorial tentang penggunaan fitur Impor API dari konsol API Gateway, lihat[Tutorial: Buat REST API dengan mengimpor contoh](api-gateway-create-api-from-example.md).
**Topics**
+ [Mengimpor API regional menggunakan konsol API Gateway](#import-regional-api-with-console)
+ [Impor API regional menggunakan AWS CLI](#import-regional-api-with-awscli)
## Mengimpor API regional menggunakan konsol API Gateway
Untuk mengimpor API titik akhir regional menggunakan konsol API Gateway, lakukan hal berikut:
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Buat API**.
1. Di bawah **REST API**, pilih **Impor**.
1. Salin definisi OpenAPI API dan tempelkan ke editor kode, atau pilih **Pilih file untuk memuat file** OpenAPI dari drive lokal.
1. Untuk **jenis titik akhir API**, pilih **Regional**.
1. Pilih **Buat API** untuk mulai mengimpor definisi OpenAPI.
## Impor API regional menggunakan AWS CLI
[import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)Perintah berikut mengimpor file definisi OpenAPI dan menetapkan tipe endpoint ke Regional:
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# Impor file OpenAPI untuk memperbarui definisi API yang ada
Anda dapat mengimpor definisi API hanya untuk memperbarui API yang ada, tanpa mengubah konfigurasi titik akhir, serta variabel tahapan dan tahap, atau referensi ke kunci API.
import-to-updateOperasi dapat terjadi dalam dua mode: menggabungkan atau menimpa.
Ketika API (`A`) digabungkan ke lain (`B`), API yang dihasilkan mempertahankan definisi keduanya `A` dan `B` jika keduanya APIs tidak berbagi definisi yang bertentangan. Ketika konflik muncul, definisi metode dari API penggabungan (`A`) akan mengesampingkan definisi metode yang sesuai dari API gabungan (). `B` Misalnya, misalkan `B` telah menyatakan metode berikut untuk kembali `200` dan `206` tanggapan:
```
GET /a
POST /a
```
dan `A` menyatakan metode berikut untuk kembali `200` dan `400` tanggapan:
```
GET /a
```
Saat `A` digabungkan`B`, API yang dihasilkan menghasilkan metode berikut:
```
GET /a
```
yang kembali `200` dan `400` tanggapan, dan
```
POST /a
```
yang kembali `200` dan `206` tanggapan.
Menggabungkan API berguna ketika Anda telah menguraikan definisi API eksternal Anda menjadi beberapa bagian yang lebih kecil dan hanya ingin menerapkan perubahan dari salah satu bagian tersebut pada satu waktu. Misalnya, ini mungkin terjadi jika beberapa tim bertanggung jawab atas bagian API yang berbeda dan memiliki perubahan yang tersedia dengan tarif yang berbeda. Dalam mode ini, item dari API yang ada yang tidak ditentukan secara khusus dalam definisi yang diimpor dibiarkan saja.
Saat API (`A`) menimpa API (`B`) lain, API yang dihasilkan mengambil definisi dari API penimpaan ()`A`. Menimpa API berguna ketika definisi API eksternal berisi definisi lengkap API. Dalam mode ini, item dari API yang ada yang tidak ditentukan secara khusus dalam definisi yang diimpor akan dihapus.
Untuk menggabungkan API, kirimkan `PUT` permintaan ke`https://apigateway..amazonaws.com/restapis/?mode=merge`. Nilai parameter `restapi_id` jalur menentukan API tempat definisi API yang disediakan akan digabungkan.
Cuplikan kode berikut menunjukkan contoh `PUT` permintaan untuk menggabungkan definisi OpenAPI API di JSON, sebagai payload, dengan API tertentu yang sudah ada di API Gateway.
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
Operasi pembaruan penggabungan mengambil dua definisi API lengkap dan menggabungkannya bersama-sama. Untuk perubahan kecil dan bertahap, Anda dapat menggunakan operasi [pembaruan sumber daya](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html).
Untuk menimpa API, kirimkan `PUT` permintaan ke`https://apigateway..amazonaws.com/restapis/?mode=overwrite`. Parameter `restapi_id` path menentukan API yang akan ditimpa dengan definisi API yang disediakan.
Cuplikan kode berikut menunjukkan contoh permintaan penimpaan dengan muatan definisi berformat JSON: OpenAPI
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
Ketika parameter `mode` kueri tidak ditentukan, penggabungan diasumsikan.
**catatan**
`PUT`Operasi itu idempoten, tetapi tidak atom. Itu berarti jika kesalahan sistem terjadi sebagian melalui pemrosesan, API dapat berakhir dalam keadaan buruk. Namun, mengulangi operasi berhasil menempatkan API ke status akhir yang sama seolah-olah operasi pertama telah berhasil.
# Mengatur properti OpenAPI `basePath`
Di [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), Anda dapat menggunakan `basePath` properti untuk menyediakan satu atau beberapa bagian jalur yang mendahului setiap jalur yang ditentukan dalam properti. `paths` Karena API Gateway memiliki beberapa cara untuk mengekspresikan jalur sumber daya, fitur Import API menyediakan opsi berikut untuk menafsirkan `basePath` properti selama import: ignore, prepend, dan split.
Di [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` bukan lagi properti tingkat atas. Sebagai gantinya, API Gateway menggunakan [variabel server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) sebagai konvensi. Fitur Import API menyediakan opsi yang sama untuk menafsirkan jalur dasar selama impor. Jalur dasar diidentifikasi sebagai berikut:
+ Jika API tidak berisi `basePath` variabel apa pun, fitur Import API akan memeriksa `server.url` string untuk melihat apakah itu berisi jalur di luar`"/"`. Jika ya, jalur itu digunakan sebagai jalur dasar.
+ Jika API hanya berisi satu `basePath` variabel, fitur Import API menggunakannya sebagai jalur dasar, meskipun tidak direferensikan `server.url` dalam.
+ Jika API berisi beberapa `basePath` variabel, fitur Impor API hanya menggunakan yang pertama sebagai jalur dasar.
## Abaikan
Jika file OpenAPI memiliki `basePath` nilai `/a/b/c` dan `paths` properti berisi `/e` dan`/f`, berikut `POST` atau `PUT` permintaan:
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
menghasilkan sumber daya berikut di API:
+ `/`
+ `/e`
+ `/f`
Efeknya adalah memperlakukan `basePath` seolah-olah tidak ada, dan semua sumber daya API yang dideklarasikan disajikan relatif terhadap host. Ini dapat digunakan, misalnya, ketika Anda memiliki nama domain khusus dengan pemetaan API yang tidak menyertakan *Jalur Dasar* dan nilai *Tahap* yang mengacu pada tahap produksi Anda.
**catatan**
API Gateway secara otomatis membuat sumber daya root untuk Anda, meskipun tidak dideklarasikan secara eksplisit dalam file definisi Anda.
Ketika tidak ditentukan, `basePath` mengambil secara `ignore` default.
## Prepend
Jika OpenAPI file memiliki `basePath` nilai `/a/b/c` dan `paths` properti berisi `/e` dan`/f`, berikut `POST` atau `PUT` permintaan:
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
menghasilkan sumber daya berikut di API:
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
Efeknya adalah memperlakukan `basePath` sebagai menentukan sumber daya tambahan (tanpa metode) dan menambahkannya ke kumpulan sumber daya yang dideklarasikan. Ini dapat digunakan, misalnya, ketika tim yang berbeda bertanggung jawab atas bagian API yang berbeda dan `basePath` dapat mereferensikan lokasi jalur untuk setiap bagian API tim.
**catatan**
API Gateway secara otomatis membuat sumber daya perantara untuk Anda, meskipun sumber daya tersebut tidak dideklarasikan secara eksplisit dalam definisi Anda.
## Split
Jika OpenAPI file memiliki `basePath` nilai `/a/b/c` dan `paths` properti berisi `/e` dan`/f`, berikut `POST` atau `PUT` permintaan:
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
menghasilkan sumber daya berikut di API:
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
Efeknya adalah memperlakukan bagian jalur paling atas,`/a`, sebagai awal dari setiap jalur sumber daya, dan untuk membuat sumber daya tambahan (tanpa metode) dalam API itu sendiri. Ini dapat, misalnya, digunakan ketika `a` merupakan nama panggung yang ingin Anda ekspos sebagai bagian dari API Anda.
# AWS variabel untuk impor OpenAPI
Anda dapat menggunakan AWS variabel berikut dalam definisi OpenAPI. API Gateway menyelesaikan variabel saat API diimpor. Untuk menentukan variabel, gunakan`${variable-name}`. Tabel berikut menjelaskan AWS variabel yang tersedia.
| Nama variabel | Deskripsi |
| --- | --- |
| AWS::AccountId | ID AWS akun yang mengimpor API. Misalnya, 123456789012. |
| AWS::Partition | AWS Partisi di mana API diimpor. Untuk AWS Wilayah standar, partisi adalahaws. |
| AWS::Region | AWS Wilayah di mana API diimpor. Misalnya, us-east-2. |
## AWS variabel contoh
Contoh berikut menggunakan AWS variabel untuk menentukan AWS Lambda fungsi untuk integrasi.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# Kesalahan dan peringatan dari mengimpor API Anda ke API Gateway
Saat Anda mengimpor file definisi eksternal ke API Gateway, API Gateway mungkin menghasilkan peringatan dan kesalahan. Bagian berikut membahas kesalahan dan peringatan yang mungkin terjadi selama impor.
## Kesalahan selama impor
Selama impor, kesalahan dapat dihasilkan untuk masalah utama seperti dokumen yang tidak validOpenAPI. Kesalahan dikembalikan sebagai pengecualian (misalnya,`BadRequestException`) dalam respons yang tidak berhasil. Ketika terjadi kesalahan, definisi API baru dibuang dan tidak ada perubahan yang dilakukan pada API yang ada.
## Peringatan selama impor
Selama impor, peringatan dapat dibuat untuk masalah kecil seperti referensi model yang hilang. Jika peringatan terjadi, operasi akan dilanjutkan jika ekspresi `failonwarnings=false` kueri ditambahkan ke URL permintaan. Jika tidak, pembaruan akan diputar kembali. Secara default, `failonwarnings` diatur ke `false`. Dalam kasus seperti itu, peringatan dikembalikan sebagai bidang di [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)sumber daya yang dihasilkan. Jika tidak, peringatan dikembalikan sebagai pesan dalam pengecualian.
# Ekspor REST API dari API Gateway
Setelah Anda membuat dan mengonfigurasi REST API di API Gateway, menggunakan konsol API Gateway atau sebaliknya, Anda dapat mengekspornya ke file OpenAPI menggunakan API Gateway Export API, yang merupakan bagian dari Amazon API Gateway Control Service. Untuk menggunakan API Gateway Export API, Anda harus menandatangani permintaan API Anda. Untuk informasi selengkapnya tentang permintaan [penandatanganan, lihat Menandatangani permintaan AWS API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) di *Panduan Pengguna IAM*. Anda memiliki opsi untuk menyertakan ekstensi integrasi API Gateway, serta ekstensi [Postman](https://www.postman.com), dalam file definisi OpenAPI yang diekspor.
**catatan**
Saat mengekspor API menggunakan AWS CLI, pastikan untuk menyertakan parameter ekstensi seperti yang ditunjukkan pada contoh berikut, untuk memastikan bahwa `x-amazon-apigateway-request-validator` ekstensi disertakan:
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
Anda tidak dapat mengekspor API jika payloadnya bukan dari `application/json` jenisnya. Jika Anda mencoba, Anda akan mendapatkan respons kesalahan yang menyatakan bahwa model tubuh JSON tidak ditemukan.
## Permintaan untuk mengekspor REST API
Dengan Export API, Anda mengekspor REST API yang ada dengan mengirimkan permintaan GET, menetapkan to-be-exported API sebagai bagian dari jalur URL. URL permintaan adalah dari format berikut:
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
Anda dapat menambahkan string `extensions` kueri untuk menentukan apakah akan menyertakan ekstensi API Gateway (dengan `integration` nilai) atau ekstensi Postman (dengan `postman` nilai).
Selain itu, Anda dapat mengatur `Accept` header ke `application/json` atau `application/yaml` untuk menerima output definisi API masing-masing dalam format JSON atau YAMAL.
Untuk informasi selengkapnya tentang mengirimkan permintaan GET menggunakan API Gateway Export API, lihat. [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)
**catatan**
Jika Anda mendefinisikan model di API Anda, model tersebut harus untuk jenis konten “application/json” agar API Gateway dapat mengekspor model. Jika tidak, API Gateway melempar pengecualian dengan pesan kesalahan “Hanya menemukan model tubuh non-JSON untuk...”.
Model harus berisi properti atau didefinisikan sebagai JSONSchema tipe tertentu.
## Unduh definisi REST API OpenAPI dalam JSON
Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dalam format JSON:
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
Di sini, `` bisa jadi, misalnya,`us-east-1`. Untuk semua wilayah di mana API Gateway tersedia, lihat [Wilayah dan Titik Akhir](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region).
## Unduh definisi REST API OpenAPI dalam YAMAL
Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dalam format YAMAL:
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Unduh definisi OpenAPI REST API dengan ekstensi Postman di JSON
Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dengan format Postman JSON:
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## Unduh definisi OpenAPI REST API dengan integrasi API Gateway di YAMAL
Untuk mengekspor dan mengunduh REST API dalam definisi OpenAPI dengan integrasi API Gateway dalam format YAMAL:
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Ekspor REST API menggunakan konsol API Gateway
Setelah [menerapkan REST API ke tahap](set-up-deployments.md#create-deployment), Anda dapat melanjutkan untuk mengekspor API di tahap ke file OpenAPI menggunakan konsol API Gateway.
Di panel **Tahapan** di konsol API Gateway, pilih **Tindakan tahap**, **Ekspor**.
![\[Ekspor REST API menggunakan konsol API Gateway\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/export-new-console.png)
Tentukan **jenis spesifikasi API**, **Format**, dan **Ekstensi** untuk mengunduh definisi OpenAPI API Anda.