Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# API Gateway HTTP APIs
REST APIs dan HTTP APIs keduanya adalah produk RESTful API. REST APIs mendukung lebih banyak fitur daripada HTTP APIs, sedangkan HTTP APIs dirancang dengan fitur minimal sehingga dapat ditawarkan dengan harga lebih murah. Untuk informasi selengkapnya, lihat [Pilih antara REST APIs dan HTTP APIs](http-api-vs-rest.md).
Anda dapat menggunakan HTTP APIs untuk mengirim permintaan ke AWS Lambda fungsi atau ke titik akhir HTTP yang dapat dirutekan. Misalnya, Anda dapat membuat API HTTP yang terintegrasi dengan fungsi Lambda di backend. Saat klien memanggil API Anda, API Gateway mengirimkan permintaan ke fungsi Lambda dan mengembalikan respons fungsi ke klien.
HTTP APIs mendukung [OpenID Connect dan otorisasi OAuth ](https://openid.net/developers/how-connect-works/) [2.0](https://oauth.net/2/). Mereka datang dengan dukungan bawaan untuk berbagi sumber daya lintas asal (CORS) dan penerapan otomatis.
Anda dapat membuat HTTP APIs dengan menggunakan AWS Management Console, AWS CLI, APIs, CloudFormation, atau SDKs.
**Topics**
+ [
# Kembangkan HTTP APIs di API Gateway
](http-api-develop.md)
+ [
# Publikasikan HTTP APIs agar pelanggan dapat dipanggil
](http-api-publish.md)
+ [
# Lindungi HTTP Anda APIs di API Gateway
](http-api-protect.md)
+ [
# Pantau HTTP APIs di API Gateway
](http-api-monitor.md)
+ [
# Memecahkan masalah dengan HTTP APIs di API Gateway
](http-api-troubleshooting.md)
# Kembangkan HTTP APIs di API Gateway
Bagian ini memberikan detail tentang kemampuan API Gateway yang Anda butuhkan saat mengembangkan API Gateway APIs.
Saat Anda mengembangkan API Gateway API, Anda memutuskan sejumlah karakteristik API Anda. Karakteristik ini bergantung pada kasus penggunaan API Anda. Misalnya, Anda mungkin hanya ingin mengizinkan klien tertentu untuk memanggil API Anda, atau Anda mungkin ingin itu tersedia untuk semua orang. Anda mungkin ingin panggilan API untuk menjalankan fungsi Lambda, membuat kueri database, atau memanggil aplikasi.
**Topics**
+ [
## Buat API HTTP
](#http-api-examples)
+ [
# Buat rute untuk HTTP APIs di API Gateway
](http-api-develop-routes.md)
+ [
# Jenis alamat IP untuk HTTP APIs di API Gateway
](http-api-ip-address-type.md)
+ [
# Kontrol dan kelola akses ke HTTP APIs di API Gateway
](http-api-access-control.md)
+ [
# Buat integrasi untuk HTTP APIs di API Gateway
](http-api-develop-integrations.md)
+ [
# Konfigurasikan CORS untuk HTTP APIs di API Gateway
](http-api-cors.md)
+ [
# Mengubah permintaan dan tanggapan API untuk HTTP APIs di API Gateway
](http-api-parameter-mapping.md)
+ [
# Gunakan definisi OpenAPI untuk HTTP APIs di API Gateway
](http-api-open-api.md)
## Buat API HTTP
Untuk membuat API fungsional, Anda harus memiliki setidaknya satu rute, integrasi, tahapan, dan penerapan.
Contoh berikut menunjukkan cara membuat API dengan integrasi AWS Lambda atau HTTP, rute, dan tahap default yang dikonfigurasi untuk menerapkan perubahan secara otomatis.
Panduan ini mengasumsikan bahwa Anda sudah terbiasa dengan API Gateway dan Lambda. Untuk panduan yang lebih rinci, lihat[Memulai dengan API Gateway](getting-started.md).
**Topics**
+ [
### Buat API HTTP dengan menggunakan Konsol Manajemen AWS
](#apigateway-http-api-create.console)
+ [
### Buat API HTTP dengan menggunakan AWS CLI
](#http-api-examples.cli.quick-create)
### Buat API HTTP dengan menggunakan Konsol Manajemen AWS
1. Buka [konsol API Gateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Buat API**.
1. Di bawah **HTTP API**, pilih **Build**.
1. Pilih **Tambahkan integrasi**, lalu pilih AWS Lambda fungsi atau masukkan titik akhir HTTP.
1. Untuk **Nama**, masukkan nama untuk API Anda.
1. Pilih **Periksa dan buat**.
1. Pilih **Buat**.
Sekarang API Anda siap untuk dipanggil. Anda dapat menguji API Anda dengan memasukkan URL pemanggilannya di browser, atau dengan menggunakan Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
### Buat API HTTP dengan menggunakan AWS CLI
Anda dapat menggunakan quick create untuk membuat API dengan integrasi Lambda atau HTTP, rute catch-all default, dan tahap default yang dikonfigurasi untuk menerapkan perubahan secara otomatis. Perintah [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) berikut menggunakan quick create untuk membuat API yang terintegrasi dengan fungsi Lambda di backend.
**catatan**
Untuk memanggil integrasi Lambda, API Gateway harus memiliki izin yang diperlukan. Anda dapat menggunakan kebijakan berbasis sumber daya atau IAM role untuk memberikan izin API Gateway guna menjalankan fungsi Lambda. Untuk mempelajari lebih lanjut, lihat [AWS Lambda Izin](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) di *Panduan AWS Lambda Pengembang*.
**Example**
```
aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name
```
Sekarang API Anda siap untuk dipanggil. Anda dapat menguji API Anda dengan memasukkan URL pemanggilannya di browser, atau dengan menggunakan Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
# Buat rute untuk HTTP APIs di API Gateway
Merutekan permintaan API yang masuk langsung ke sumber daya backend. Rute terdiri dari dua bagian: metode HTTP dan jalur sumber daya—misalnya,. `GET /pets` Anda dapat menentukan metode HTTP spesifik untuk rute Anda. Atau, Anda dapat menggunakan `ANY` metode untuk mencocokkan semua metode yang belum Anda tetapkan untuk sumber daya. Anda dapat membuat `$default` rute yang bertindak sebagai tangkapan semua untuk permintaan yang tidak cocok dengan rute lain.
**catatan**
API Gateway menerjemahkan parameter permintaan yang disandikan URL sebelum meneruskannya ke integrasi backend Anda.
## Bekerja dengan variabel jalur
Anda dapat menggunakan variabel jalur di rute API HTTP.
Misalnya, `GET /pets/{petID}` rute menangkap `GET` permintaan yang dikirimkan klien. `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6`
*Variabel jalur serakah* menangkap semua sumber daya anak dari suatu rute. Untuk membuat variabel jalur serakah, tambahkan `+` ke nama variabel—misalnya,. `{proxy+}` Variabel jalur serakah harus berada di ujung jalur sumber daya.
## Bekerja dengan parameter string kueri
Secara default, API Gateway mengirimkan parameter string kueri ke integrasi backend Anda jika mereka disertakan dalam permintaan ke API HTTP.
Misalnya, ketika klien mengirim permintaan ke`https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`, parameter string kueri `?id=4&type=dog` dikirim ke integrasi Anda.
## Bekerja dengan `$default` rute
`$default`Rute menangkap permintaan yang tidak secara eksplisit cocok dengan rute lain di API Anda.
Saat `$default` rute menerima permintaan, API Gateway mengirimkan jalur permintaan lengkap ke integrasi. Misalnya, Anda dapat membuat API hanya dengan `$default` rute dan mengintegrasikannya pada `ANY` metode dengan titik akhir `https://petstore-demo-endpoint.execute-api.com` HTTP. Saat Anda mengirim permintaan ke`https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`, API Gateway mengirimkan permintaan ke`https://petstore-demo-endpoint.execute-api.com/store/checkout`.
Untuk mempelajari lebih lanjut tentang integrasi HTTP, lihat[Buat integrasi proxy HTTP untuk HTTP APIs](http-api-develop-integrations-http.md).
## Permintaan API perutean
Saat klien mengirim permintaan API, API Gateway terlebih dahulu menentukan [tahap](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html) mana yang akan merutekan permintaan tersebut. Jika permintaan secara eksplisit cocok dengan tahapan, API Gateway mengirimkan permintaan ke tahap tersebut. Jika tidak ada tahap yang sepenuhnya cocok dengan permintaan, API Gateway mengirimkan permintaan ke `$default` panggung. Jika tidak ada `$default` tahap, maka API kembali `{"message":"Not Found"}` dan tidak menghasilkan CloudWatch log.
Setelah memilih tahapan, API Gateway memilih rute. API Gateway memilih rute dengan kecocokan paling spesifik, menggunakan prioritas berikut:
1. Pertandingan penuh untuk rute dan metode.
1. Cocokkan rute dan metode dengan variabel jalur serakah (`{proxy+}`).
1. `$default`Rute.
Jika tidak ada rute yang cocok dengan permintaan, API Gateway `{"message":"Not Found"}` akan kembali ke klien.
Misalnya, pertimbangkan API dengan `$default` tahapan dan contoh rute berikut:
1. `GET /pets/dog/1`
1. `GET /pets/dog/{id}`
1. `GET /pets/{proxy+}`
1. `ANY /{proxy+}`
1. `$default`
Tabel berikut merangkum cara API Gateway merutekan permintaan ke rute contoh.
| Permintaan | Rute yang dipilih | Penjelasan |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | Permintaan sepenuhnya cocok dengan rute statis ini. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | Permintaan sepenuhnya cocok dengan rute ini. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | Permintaan tidak sepenuhnya cocok dengan rute. Rute dengan `GET` metode dan variabel jalur serakah menangkap permintaan ini. |
| `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | `ANY`Metode ini cocok dengan semua metode yang belum Anda tetapkan untuk rute. Rute dengan variabel jalur serakah memiliki prioritas lebih tinggi daripada `$default` rute. |
# Jenis alamat IP untuk HTTP 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. Anda mungkin ingin 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)
## Pertimbangan untuk jenis alamat IP
Pertimbangan berikut dapat memengaruhi penggunaan jenis alamat IP Anda:
+ Jenis alamat IP default untuk HTTP APIs adalah IPv4.
+ 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.
+ 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.
## Mengubah jenis alamat IP dari API HTTP
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.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengubah jenis alamat IP dari API HTTP**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API HTTP.
1. Untuk **pengaturan API**, pilih **Edit**.
1. Untuk jenis alamat IP, pilih salah satu **IPv4**atau **Dualstack**.
1. Pilih **Simpan**.
Perubahan pada konfigurasi API Anda akan segera berlaku.
------
#### [ AWS CLI ]
Perintah [update-api berikut memperbarui API](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) agar memiliki tipe alamat IP dualstack:
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
Outputnya akan terlihat seperti berikut:
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-HTTP-API",
"ProtocolType": "HTTP",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Kontrol dan kelola akses ke HTTP APIs di API Gateway
API Gateway mendukung beberapa mekanisme untuk mengontrol dan mengelola akses ke HTTP API Anda:
+ **Otorisasi Lambda menggunakan** fungsi Lambda untuk mengontrol akses ke. APIs Untuk informasi selengkapnya, lihat [Kontrol akses ke HTTP APIs dengan AWS Lambda otorisasi](http-api-lambda-authorizer.md).
+ **Authorizer JWT** menggunakan token web JSON untuk mengontrol akses ke. APIs Untuk informasi selengkapnya, lihat [Kontrol akses ke HTTP APIs dengan otorisasi JWT di API Gateway](http-api-jwt-authorizer.md).
+ **Peran dan kebijakan AWS IAM standar** menawarkan kontrol akses yang fleksibel dan kuat. Anda dapat menggunakan peran dan kebijakan IAM untuk mengontrol siapa yang dapat membuat dan mengelola Anda APIs, serta siapa yang dapat memanggilnya. Untuk informasi selengkapnya, lihat [Kontrol akses ke HTTP APIs dengan otorisasi IAM di API Gateway](http-api-access-control-iam.md).
Untuk meningkatkan postur keamanan Anda, kami sarankan Anda mengonfigurasi otorisasi untuk semua rute di HTTP API Anda. Anda mungkin perlu melakukan ini untuk mematuhi berbagai kerangka kerja kepatuhan. Untuk informasi selengkapnya, lihat [kontrol Amazon API Gateway](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) di *Panduan AWS Security Hub Pengguna*.
# Kontrol akses ke HTTP APIs dengan AWS Lambda otorisasi
Anda menggunakan otorisasi Lambda untuk menggunakan fungsi Lambda untuk mengontrol akses ke HTTP API Anda. Kemudian, ketika klien memanggil API Anda, API Gateway memanggil fungsi Lambda Anda. API Gateway menggunakan respons dari fungsi Lambda Anda untuk menentukan apakah klien dapat mengakses API Anda.
## Versi format muatan
Versi format payload authorizer menentukan format data yang dikirimkan API Gateway ke pengotorisasi Lambda, dan bagaimana API Gateway menafsirkan respons dari Lambda. Jika Anda tidak menentukan versi format payload, akan Konsol Manajemen AWS menggunakan versi terbaru secara default. Jika Anda membuat otorisasi Lambda menggunakan AWS CLI,, atau SDK CloudFormation, Anda harus menentukan. `authorizerPayloadFormatVersion` Nilai yang di-support adalah `1.0` dan `2.0`.
Jika Anda membutuhkan kompatibilitas dengan REST APIs, gunakan versi`1.0`.
Contoh berikut menunjukkan struktur setiap versi format payload.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"header1": "value1",
"header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"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"
}
}
```
------
## Format respons otorisasi Lambda
Versi format payload juga menentukan struktur respons yang harus Anda kembalikan dari fungsi Lambda Anda.
### Respons fungsi Lambda untuk format 1.0
Jika Anda memilih versi `1.0` format, otorisasi Lambda harus menampilkan kebijakan IAM yang mengizinkan atau menolak akses ke rute API Anda. Anda dapat menggunakan sintaks kebijakan IAM standar dalam kebijakan. Untuk contoh kebijakan IAM, lihat[Kontrol akses untuk menjalankan API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Anda dapat meneruskan properti konteks ke integrasi Lambda atau mengakses log dengan menggunakan. `$context.authorizer.property` `context`Objek adalah opsional dan `claims` merupakan placeholder yang dicadangkan dan tidak dapat digunakan sebagai objek konteks. Untuk mempelajari selengkapnya, lihat [Sesuaikan log akses HTTP API](http-api-logging-variables.md).
**Example**
****
```
{
"principalId": "abcdef",
"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": {
"exampleKey": "exampleValue"
}
}
```
### Respons fungsi Lambda untuk format 2.0
Jika Anda memilih versi `2.0` format, Anda dapat mengembalikan nilai Boolean atau kebijakan IAM yang menggunakan sintaks kebijakan IAM standar dari fungsi Lambda Anda. Untuk mengembalikan nilai Boolean, aktifkan tanggapan sederhana untuk otorisasi. Contoh berikut menunjukkan format yang harus Anda kodekan fungsi Lambda Anda untuk kembali. `context`Objek adalah opsional. Anda dapat meneruskan properti konteks ke integrasi Lambda atau mengakses log dengan menggunakan. `$context.authorizer.property` Untuk mempelajari selengkapnya, lihat [Sesuaikan log akses HTTP API](http-api-logging-variables.md).
------
#### [ Simple response ]
```
{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}
```
------
#### [ IAM policy ]
****
```
{
"principalId": "abcdef",
"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": {
"exampleKey": "exampleValue"
}
}
```
------
## Contoh fungsi otorisasi Lambda
Contoh berikut fungsi Lambda Node.js menunjukkan format respons yang diperlukan yang perlu Anda kembalikan dari fungsi Lambda Anda untuk versi format payload. `2.0`
------
#### [ Simple response - Node.js ]
```
export const handler = async(event) => {
let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
if (event.headers.authorization === "secretToken") {
console.log("allowed");
response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}
return response;
};
```
------
#### [ Simple response - Python ]
```
import json
def lambda_handler(event, context):
response = {
"isAuthorized": False,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
"isAuthorized": True,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
#### [ IAM policy - Node.js ]
```
export const handler = async(event) => {
if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};
```
------
#### [ IAM policy - Python ]
```
import json
def lambda_handler(event, context):
response = {
# The principal user identification associated with the token sent by
# the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
# The principal user identification associated with the token
# sent by the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
## Sumber identitas
Anda dapat secara opsional menentukan sumber identitas untuk otorisasi Lambda. Sumber identitas menentukan lokasi data yang diperlukan untuk mengotorisasi permintaan. Misalnya, Anda dapat menentukan nilai string header atau kueri sebagai sumber identitas. Jika Anda menentukan sumber identitas, klien harus memasukkannya dalam permintaan. Jika permintaan klien tidak menyertakan sumber identitas, API Gateway tidak memanggil otorisasi Lambda Anda, dan klien menerima kesalahan. `401`
Tabel berikut menjelaskan sumber identitas yang didukung untuk otorisasi Lambda.
| **Jenis** | **Contoh** | **Catatan** |
| --- | --- | --- |
| Nilai header | \$1 request.header. name | Nama header tidak peka huruf besar/kecil. |
| Nilai string kueri | \$1request.querystring. name | Nama string kueri peka huruf besar/kecil. |
| Variabel konteks | \$1 konteks. variableName | Nilai [variabel konteks](http-api-logging-variables.md) yang didukung. |
| Variabel tahap | \$1 StageVariables. variableName | Nilai [variabel tahap](http-api-stages.stage-variables.md). |
Anda juga dapat langsung kembali ` {"errorMessage" : "Unauthorized"}` dari fungsi Lambda Anda untuk mengembalikan `401` kesalahan ke klien Anda. Jika Anda langsung mengembalikan `401` kesalahan dari fungsi Lambda ke klien Anda, jangan tentukan sumber identitas apa pun saat Anda membuat otorisasi Lambda.
## Tanggapan otorisasi cache
Anda dapat mengaktifkan caching untuk otorisasi Lambda dengan menentukan file. [authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds) Saat caching diaktifkan untuk otorisasi, API Gateway menggunakan sumber identitas otorisasi sebagai kunci cache. Jika klien menentukan parameter yang sama dalam sumber identitas dalam TTL yang dikonfigurasi, API Gateway menggunakan hasil otorisasi yang di-cache, daripada menjalankan fungsi Lambda Anda.
Untuk mengaktifkan caching, otorisasi Anda harus memiliki setidaknya satu sumber identitas.
Jika Anda mengaktifkan respons sederhana untuk otorisasi, respons otorisasi sepenuhnya mengizinkan atau menolak semua permintaan API yang cocok dengan nilai sumber identitas cache. Untuk izin yang lebih terperinci, nonaktifkan tanggapan sederhana dan kembalikan kebijakan IAM. Bergantung pada otorisasi Anda, kebijakan IAM Anda mungkin perlu mengontrol akses ke beberapa.
Secara default, API Gateway menggunakan respons otorisasi yang di-cache untuk semua rute API yang menggunakan otorisasi. Untuk menyimpan respons per rute, tambahkan `$context.routeKey` ke sumber identitas otorisasi Anda.
## Buat Authorizer Lambda
Saat membuat otorisasi Lambda, Anda menentukan fungsi Lambda untuk API Gateway yang akan digunakan. Anda harus memberikan izin API Gateway untuk menjalankan fungsi Lambda dengan menggunakan kebijakan sumber daya fungsi atau peran IAM. Perintah [create-authorizer berikut membuat authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) Lambda:
```
aws apigatewayv2 create-authorizer \
--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses
```
Perintah [izin tambahan](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) berikut memperbarui kebijakan sumber daya fungsi Lambda untuk memberikan izin API Gateway untuk menjalankan fungsi tersebut. Jika API Gateway tidak memiliki izin untuk menjalankan fungsi Anda, klien akan menerima file. `500 Internal Server Error`
```
aws lambda add-permission \
--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"
```
Setelah Anda membuat otorisasi dan memberikan izin API Gateway untuk memanggilnya, perbarui rute Anda untuk menggunakan otorisasi. Perintah [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) berikut menambahkan Lambda authorizer ke rute. Jika otorisasi Lambda Anda menggunakan caching kebijakan, pastikan Anda memperbarui kebijakan untuk mengontrol akses untuk rute tambahan.
```
aws apigatewayv2 update-route \
--api-id abcdef123 \
--route-id abc123 \
--authorization-type CUSTOM \
--authorizer-id def123
```
## Memecahkan masalah otorisasi Lambda
Jika API Gateway tidak dapat memanggil otorisasi Lambda Anda, atau otorisasi Lambda Anda mengembalikan respons dalam format yang tidak valid, klien akan menerima file. `500 Internal Server Error`
Untuk memecahkan masalah kesalahan, [aktifkan pencatatan akses untuk tahap](http-api-logging.md) API Anda. Sertakan variabel `$context.authorizer.error` logging dalam format log Anda.
Jika log menunjukkan bahwa API Gateway tidak memiliki izin untuk menjalankan fungsi Anda, perbarui kebijakan sumber daya fungsi Anda atau berikan peran IAM untuk memberikan izin API Gateway untuk memanggil otorisasi Anda.
[Jika log menunjukkan bahwa fungsi Lambda Anda mengembalikan respons yang tidak valid, verifikasi bahwa fungsi Lambda Anda mengembalikan respons dalam format yang diperlukan.](#http-api-lambda-authorizer.payload-format-response)
# Kontrol akses ke HTTP APIs dengan otorisasi JWT di API Gateway
Anda dapat menggunakan JSON Web Tokens (JWTs) sebagai bagian dari [OpenID Connect (](https://openid.net/specs/openid-connect-core-1_0.html)OIDC [OAuth )](https://oauth.net/2/) dan 2.0 framework untuk membatasi akses klien ke Anda. APIs
Jika Anda mengonfigurasi otorisasi JWT untuk rute API Anda, API Gateway memvalidasi yang dikirimkan klien dengan JWTs permintaan API. API Gateway memungkinkan atau menolak permintaan berdasarkan validasi token, dan secara opsional, cakupan dalam token. Jika Anda mengonfigurasi cakupan untuk rute, token harus menyertakan setidaknya satu cakupan rute.
Anda dapat mengonfigurasi otorisasi yang berbeda untuk setiap rute API, atau menggunakan otorisasi yang sama untuk beberapa rute.
**catatan**
Tidak ada mekanisme standar untuk membedakan token akses JWT dari jenis lain JWTs, seperti token ID OpenID Connect. Kecuali Anda memerlukan token ID untuk otorisasi API, kami sarankan Anda mengonfigurasi rute Anda agar memerlukan cakupan otorisasi. Anda juga dapat mengonfigurasi otorisasi JWT Anda untuk meminta penerbit atau audiens yang hanya digunakan penyedia identitas Anda saat mengeluarkan token akses JWT.
## Mengotorisasi permintaan API dengan otorisasi JWT
API Gateway menggunakan alur kerja umum berikut untuk mengotorisasi permintaan ke rute yang dikonfigurasi untuk menggunakan otorisasi JWT.
1. [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource)Periksa token. `identitySource`Dapat hanya menyertakan token, atau token yang diawali dengan`Bearer`.
1. Mendekode token.
1. Periksa algoritma dan tanda tangan token dengan menggunakan kunci publik yang diambil dari penerbit. `jwks_uri` Saat ini, hanya algoritma berbasis RSA yang didukung. API Gateway dapat menyimpan kunci publik selama dua jam. Sebagai praktik terbaik, saat Anda memutar tombol, izinkan masa tenggang di mana kunci lama dan baru valid.
1. Validasi klaim. API Gateway mengevaluasi klaim token berikut:
+ [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5)— Token harus memiliki klaim header yang cocok dengan kunci `jwks_uri` yang menandatangani token.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1)— Harus cocok dengan [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)yang dikonfigurasi untuk otorisasi.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)atau `client_id` — Harus cocok dengan salah satu [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)entri yang dikonfigurasi untuk otorisasi. API Gateway `client_id` hanya memvalidasi jika tidak `aud` ada. Saat keduanya `aud` dan `client_id` ada, API Gateway mengevaluasi. `aud`
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4)— Harus setelah waktu saat ini di UTC.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5)— Harus sebelum waktu saat ini di UTC.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6)— Harus sebelum waktu saat ini di UTC.
+ [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)atau `scp` — Token harus menyertakan setidaknya satu cakupan dalam rute. [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes)
Jika salah satu langkah ini gagal, API Gateway menolak permintaan API.
Setelah memvalidasi JWT, API Gateway meneruskan klaim dalam token ke integrasi rute API. Sumber daya backend, seperti fungsi Lambda, dapat mengakses klaim JWT. Misalnya, jika JWT menyertakan klaim identitas`emailID`, itu tersedia untuk integrasi Lambda di. `$event.requestContext.authorizer.jwt.claims.emailID` Untuk informasi selengkapnya tentang payload yang dikirimkan API Gateway ke integrasi Lambda, lihat. [Buat integrasi AWS Lambda proxy untuk HTTP APIs di API Gateway](http-api-develop-integrations-lambda.md)
## Buat otorisasi JWT
Sebelum Anda membuat otorisasi JWT, Anda harus mendaftarkan aplikasi klien dengan penyedia identitas. Anda juga harus membuat API HTTP. Untuk contoh pembuatan API HTTP, lihat[Buat API HTTP](http-api-develop.md#http-api-examples).
### Buat otorisasi JWT menggunakan konsol
Langkah-langkah berikut menunjukkan cara membuat otorisasi JWT menggunakan konsol.
**Untuk membuat otorisasi JWT menggunakan konsol**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API HTTP.
1. Di panel navigasi utama, pilih **Otorisasi**.
1. Pilih tab **Kelola otorisasi**.
1. Pilih **Buat**.
1. Untuk **jenis Authorizer**, pilih **JWT**.
1. Konfigurasikan otorisasi JWT Anda, dan tentukan **sumber Identitas** yang menentukan sumber token.
1. Pilih **Buat**.
#### Buat otorisasi JWT menggunakan AWS CLI
Perintah [create-authorizer berikut membuat authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) JWT. Untuk`jwt-configuration`, tentukan `Audience` dan `Issuer` untuk penyedia identitas Anda. Jika Anda menggunakan Amazon Cognito sebagai penyedia identitas, itu adalah. `IssuerUrl` `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`
```
aws apigatewayv2 create-authorizer \
--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=IssuerUrl
```
##### Buat otorisasi JWT menggunakan AWS CloudFormation
CloudFormation Template berikut membuat API HTTP dengan otorisasi JWT yang menggunakan Amazon Cognito sebagai penyedia identitas.
Output dari CloudFormation template adalah URL untuk UI yang dihosting Amazon Cognito tempat klien dapat mendaftar dan masuk untuk menerima JWT. Setelah klien masuk, klien dialihkan ke HTTP API Anda dengan token akses di URL. Untuk menjalankan API dengan token akses, ubah URL ke a `?` untuk menggunakan token sebagai parameter string kueri. `#`
##### Contoh CloudFormation template
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## Perbarui rute untuk menggunakan otorisasi JWT
Anda dapat menggunakan konsol, SDK AWS CLI, atau AWS SDK untuk memperbarui rute untuk menggunakan otorisasi JWT.
### Perbarui rute untuk menggunakan otorisasi JWT dengan menggunakan konsol
Langkah-langkah berikut menunjukkan cara memperbarui rute untuk menggunakan otorisasi JWT menggunakan konsol.
**Untuk membuat otorisasi JWT menggunakan konsol**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API HTTP.
1. Di panel navigasi utama, pilih **Otorisasi**.
1. **Pilih metode, lalu pilih otorisasi Anda dari menu tarik-turun, dan pilih Lampirkan otorisasi.**
#### Perbarui rute untuk menggunakan otorisasi JWT dengan menggunakan AWS CLI
Perintah [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) berikut memperbarui rute untuk menggunakan otorisasi JWT:
```
aws apigatewayv2 update-route \
--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.email
```
# Kontrol akses ke HTTP APIs dengan otorisasi IAM di API Gateway
Anda dapat mengaktifkan otorisasi IAM untuk rute API HTTP. Ketika otorisasi IAM diaktifkan, klien harus menggunakan [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) untuk menandatangani permintaan mereka dengan kredensi. AWS API Gateway memanggil rute API Anda hanya jika klien memiliki `execute-api` izin untuk rute tersebut.
[Otorisasi IAM untuk HTTP APIs mirip dengan yang untuk REST. APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md)
**catatan**
Kebijakan sumber daya saat ini tidak didukung untuk HTTP APIs.
Untuk contoh kebijakan IAM yang memberikan izin kepada klien untuk memanggil APIs, lihat. [Kontrol akses untuk menjalankan API](api-gateway-control-access-using-iam-policies-to-invoke-api.md)
## Aktifkan otorisasi IAM untuk rute
Perintah [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) berikut memungkinkan otorisasi IAM untuk rute API HTTP:
```
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM
```
# Buat integrasi untuk HTTP APIs di API Gateway
*Integrasi* menghubungkan rute ke sumber daya backend. HTTP APIs mendukung Lambda proxy, AWS layanan, dan integrasi proxy HTTP. Misalnya, Anda dapat mengonfigurasi `POST` permintaan ke `/signup` rute API Anda untuk diintegrasikan dengan fungsi Lambda yang menangani pelanggan yang mendaftar.
**Topics**
+ [
# Buat integrasi AWS Lambda proxy untuk HTTP APIs di API Gateway
](http-api-develop-integrations-lambda.md)
+ [
# Buat integrasi proxy HTTP untuk HTTP APIs
](http-api-develop-integrations-http.md)
+ [
# Buat integrasi AWS layanan untuk HTTP APIs di API Gateway
](http-api-develop-integrations-aws-services.md)
+ [
# Buat integrasi pribadi untuk HTTP APIs di API Gateway
](http-api-develop-integrations-private.md)
# Buat integrasi AWS Lambda proxy untuk HTTP APIs di API Gateway
Integrasi proxy Lambda memungkinkan Anda mengintegrasikan rute API dengan fungsi Lambda. Saat klien memanggil API Anda, API Gateway mengirimkan permintaan ke fungsi Lambda dan mengembalikan respons fungsi ke klien. Untuk contoh pembuatan API HTTP, lihat[Buat API HTTP](http-api-develop.md#http-api-examples).
## Versi format muatan
Versi format payload menentukan format event yang dikirimkan API Gateway ke integrasi Lambda, dan bagaimana API Gateway menafsirkan respons dari Lambda. Jika Anda tidak menentukan versi format payload, akan Konsol Manajemen AWS menggunakan versi terbaru secara default. Jika Anda membuat integrasi Lambda menggunakan AWS CLI, CloudFormation, atau SDK, Anda harus menentukan. `payloadFormatVersion` Nilai yang di-support adalah `1.0` dan `2.0`.
Untuk informasi selengkapnya tentang cara menyetel`payloadFormatVersion`, lihat [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). Untuk informasi selengkapnya tentang cara menentukan integrasi `payloadFormatVersion` yang ada, lihat [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html)
### Perbedaan format payload
Daftar berikut menunjukkan perbedaan antara versi format payload `1.0` dan `2.0` payload:
+ Format `2.0` tidak memiliki `multiValueHeaders` atau `multiValueQueryStringParameters` bidang. Header duplikat dikombinasikan dengan koma dan termasuk dalam bidang. `headers` String kueri duplikat digabungkan dengan koma dan disertakan dalam bidang. `queryStringParameters`
+ Format `2.0` memiliki`rawPath`. Jika Anda menggunakan pemetaan API untuk menghubungkan stage Anda ke nama domain kustom, tidak `rawPath` akan memberikan nilai pemetaan API. Gunakan format `1.0` dan `path` untuk mengakses pemetaan API untuk nama domain kustom Anda.
+ Format `2.0` termasuk `cookies` bidang baru. Semua header cookie dalam permintaan digabungkan dengan koma dan ditambahkan ke bidang. `cookies` Dalam menanggapi klien, setiap cookie menjadi `set-cookie` header.
### Struktur format muatan
Contoh berikut menunjukkan struktur setiap versi format payload. Semua headername diberi huruf kecil.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"header1": "value1",
"header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"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"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "192.0.2.1",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2"
},
"multiValueHeaders": {
"header1": [
"value1"
],
"header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"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": "192.0.2.1",
"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
}
```
------
## Format respons fungsi Lambda
Versi format payload menentukan struktur respons yang harus dikembalikan oleh fungsi Lambda Anda.
### Respons fungsi Lambda untuk format 1.0
Dengan versi `1.0` format, integrasi Lambda harus mengembalikan respons dalam format JSON berikut:
**Example**
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
```
### Respons fungsi Lambda untuk format 2.0
Dengan versi `2.0` formatnya, API Gateway dapat menyimpulkan format respons untuk Anda. API Gateway membuat asumsi berikut jika fungsi Lambda Anda mengembalikan JSON yang valid dan tidak mengembalikan: `statusCode`
+ `isBase64Encoded` adalah `false`.
+ `statusCode` adalah `200`.
+ `content-type` adalah `application/json`.
+ `body`adalah respon dari fungsi tersebut.
Contoh berikut menunjukkan output dari fungsi Lambda dan interpretasi API Gateway.
| Keluaran fungsi Lambda | Interpretasi API Gateway |
| --- | --- |
| "Hello from Lambda!"
| {
"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"content-type": "application/json"
}
} |
| { "message": "Hello from Lambda!" } | {
"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from Lambda!\" }",
"headers": {
"content-type": "application/json"
}
} |
Untuk menyesuaikan respons, fungsi Lambda Anda harus mengembalikan respons dengan format berikut.
```
{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"body": "Hello from Lambda!"
}
```
# Buat integrasi proxy HTTP untuk HTTP APIs
Integrasi proxy HTTP memungkinkan Anda menghubungkan rute API ke titik akhir HTTP yang dapat dirutekan secara publik. Dengan tipe integrasi ini, API Gateway meneruskan seluruh permintaan dan respons antara frontend dan backend.
Untuk membuat integrasi proxy HTTP, berikan URL titik akhir HTTP yang dapat dirutekan secara publik.
## Integrasi proxy HTTP dengan variabel jalur
Anda dapat menggunakan variabel jalur di rute API HTTP.
Misalnya, rute `/pets/{petID}` menangkap permintaan ke`/pets/6`. Anda dapat mereferensikan variabel jalur dalam URI integrasi untuk mengirim konten variabel ke integrasi. Contohnya adalah `/pets/extendedpath/{petID}`.
Anda dapat menggunakan variabel jalur serakah untuk menangkap semua sumber daya anak dari suatu rute. Untuk membuat variabel jalur serakah, tambahkan `+` ke nama variabel—misalnya,. `{proxy+}`
Untuk menyiapkan rute dengan integrasi proxy HTTP yang menangkap semua permintaan, buat rute API dengan variabel jalur serakah (misalnya,`/parent/{proxy+}`). Integrasikan rute dengan titik akhir HTTP (misalnya,`https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) pada `ANY` metode. Variabel jalur serakah harus berada di ujung jalur sumber daya.
# Buat integrasi AWS layanan untuk HTTP APIs di API Gateway
Anda dapat mengintegrasikan HTTP API Anda dengan AWS layanan dengan menggunakan *integrasi kelas satu*. Integrasi kelas satu menghubungkan rute API HTTP ke API AWS layanan. Saat klien memanggil rute yang didukung oleh integrasi kelas satu, API Gateway akan memanggil API AWS layanan untuk Anda. Misalnya, Anda dapat menggunakan integrasi kelas satu untuk mengirim pesan ke antrean Amazon Simple Queue Service, atau untuk memulai mesin status. AWS Step Functions Untuk tindakan layanan yang didukung, lihat[Referensi subtipe integrasi](http-api-develop-integrations-aws-services-reference.md).
## Parameter permintaan pemetaan
Integrasi kelas satu memiliki parameter yang diperlukan dan opsional. Anda harus mengkonfigurasi semua parameter yang diperlukan untuk membuat integrasi. Anda dapat menggunakan nilai statis atau parameter peta yang dievaluasi secara dinamis saat runtime. Untuk daftar lengkap integrasi dan parameter yang didukung, lihat[Referensi subtipe integrasi](http-api-develop-integrations-aws-services-reference.md).
Tabel berikut menjelaskan parameter permintaan pemetaan yang didukung.
| Tipe | Contoh | Catatan |
| --- | --- | --- |
| Nilai header | \$1 request.header. name | Nama header tidak peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai header dengan koma, misalnya"header1": "value1,value2". |
| Nilai string kueri | \$1request.querystring. name | Nama string kueri peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai dengan koma, misalnya"querystring1": "Value1,Value2". |
| Parameter jalur | \$1request.path. name | Nilai parameter jalur dalam permintaan. Misalnya jika rutenya/pets/\$1petId\$1, Anda dapat memetakan petId parameter dari permintaan dengan\$1request.path.petId. |
| Minta passthrough tubuh | \$1 request.body | API Gateway melewati seluruh isi permintaan. |
| Isi permintaan | \$1 request.body. name | [Ekspresi jalur JSON](https://goessner.net/articles/JsonPath/index.html#e2). Descent rekursif (\$1request.body..name) dan ekspresi filter (?(expression)) tidak didukung. Saat Anda menentukan jalur JSON, API Gateway memotong isi permintaan pada 100 KB dan kemudian menerapkan ekspresi seleksi. Untuk mengirim muatan yang lebih besar dari 100 KB, tentukan`$request.body`. |
| Variabel konteks | \$1 konteks. variableName | Nilai [variabel konteks](http-api-logging-variables.md) yang didukung. |
| Variabel tahap | \$1 StageVariables. variableName | Nilai [variabel tahap](http-api-stages.stage-variables.md). |
| Nilai statis | string | Nilai konstan. |
## Buat integrasi kelas satu
Sebelum membuat integrasi kelas satu, Anda harus membuat peran IAM yang memberikan izin API Gateway untuk menjalankan tindakan AWS layanan yang Anda integrasikan. Untuk mempelajari lebih lanjut, lihat [Membuat peran untuk AWS layanan](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
Untuk membuat integrasi kelas satu, pilih tindakan AWS layanan yang didukung, seperti`SQS-SendMessage`, mengonfigurasi parameter permintaan, dan berikan peran yang memberikan izin API Gateway untuk menjalankan API layanan terintegrasi. AWS Tergantung pada subtipe integrasi, parameter permintaan yang berbeda diperlukan. Untuk mempelajari selengkapnya, lihat [Referensi subtipe integrasi](http-api-develop-integrations-aws-services-reference.md).
Perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut membuat integrasi yang mengirimkan pesan Amazon SQS:
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'
```
## Buat integrasi kelas satu menggunakan CloudFormation
Contoh berikut menunjukkan CloudFormation cuplikan yang membuat `/{source}/{detailType}` rute dengan integrasi kelas satu dengan Amazon. EventBridge
`Source`Parameter dipetakan ke parameter `{source}` jalur, `DetailType` dipetakan ke parameter `{DetailType}` jalur, dan `Detail` parameter dipetakan ke badan permintaan.
Cuplikan tidak menampilkan bus acara atau peran IAM yang memberikan izin API Gateway untuk menjalankan tindakan. `PutEvents`
```
Route:
Type: AWS::ApiGatewayV2::Route
Properties:
ApiId: !Ref HttpApi
AuthorizationType: None
RouteKey: 'POST /{source}/{detailType}'
Target: !Join
- /
- - integrations
- !Ref Integration
Integration:
Type: AWS::ApiGatewayV2::Integration
Properties:
ApiId: !Ref HttpApi
IntegrationType: AWS_PROXY
IntegrationSubtype: EventBridge-PutEvents
CredentialsArn: !GetAtt EventBridgeRole.Arn
RequestParameters:
Source: $request.path.source
DetailType: $request.path.detailType
Detail: $request.body
EventBusName: !GetAtt EventBus.Arn
PayloadFormatVersion: "1.0"
```
# Referensi subtipe integrasi
[Subtipe integrasi](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) berikut didukung untuk HTTP APIs.
**Topics**
+ [
## EventBridge- PutEvents 1.0
](#EventBridge-PutEvents)
+ [
## SQS- 1.0 SendMessage
](#SQS-SendMessage)
+ [
## SQS- 1.0 ReceiveMessage
](#SQS-ReceiveMessage)
+ [
## SQS- 1.0 DeleteMessage
](#SQS-DeleteMessage)
+ [
## SQS- 1.0 PurgeQueue
](#SQS-PurgeQueue)
+ [
## AppConfig- GetConfiguration 1.0
](#AppConfig-GetConfiguration)
+ [
## Kinesis- 1.0 PutRecord
](#Kinesis-PutRecord)
+ [
## StepFunctions- StartExecution 1.0
](#StepFunctions-StartExecution)
+ [
## StepFunctions- StartSyncExecution 1.0
](#StepFunctions-StartSyncExecution)
+ [
## StepFunctions- StopExecution 1.0
](#StepFunctions-StopExecution)
## EventBridge- PutEvents 1.0
Mengirim acara khusus ke Amazon EventBridge sehingga dapat dicocokkan dengan aturan.
| Parameter | Diperlukan |
| --- | --- |
| Detail | True |
| DetailType | True |
| Sumber | True |
| Waktu | False |
| EventBusName | False |
| Sumber daya | False |
| Wilayah | False |
| TraceHeader | False |
Untuk mempelajari lebih lanjut, lihat [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html)di *Referensi Amazon EventBridge API*.
## SQS- 1.0 SendMessage
Mengirimkan pesan ke antrian yang ditentukan.
| Parameter | Diperlukan |
| --- | --- |
| QueueUrl | True |
| MessageBody | Benar |
| DelaySeconds | Salah |
| MessageAttributes | Salah |
| MessageDeduplicationId | Salah |
| MessageGroupId | Salah |
| MessageSystemAttributes | False |
| Wilayah | False |
Untuk mempelajari selengkapnya, lihat [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)di *Referensi API Layanan Antrian Sederhana Amazon*.
## SQS- 1.0 ReceiveMessage
Mengambil satu atau beberapa pesan (hingga 10), dari antrian yang ditentukan.
| Parameter | Diperlukan |
| --- | --- |
| QueueUrl | True |
| AttributeNames | Salah |
| MaxNumberOfMessages | Salah |
| MessageAttributeNames | Salah |
| ReceiveRequestAttemptId | Salah |
| VisibilityTimeout | Salah |
| WaitTimeSeconds | False |
| Wilayah | False |
Untuk mempelajari selengkapnya, lihat [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html)di *Referensi API Layanan Antrian Sederhana Amazon*.
## SQS- 1.0 DeleteMessage
Menghapus pesan yang ditentukan dari antrian yang ditentukan.
| Parameter | Diperlukan |
| --- | --- |
| ReceiptHandle | True |
| QueueUrl | True |
| Wilayah | False |
Untuk mempelajari selengkapnya, lihat [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html)di *Referensi API Layanan Antrian Sederhana Amazon*.
## SQS- 1.0 PurgeQueue
Menghapus semua pesan dalam antrian yang ditentukan.
| Parameter | Diperlukan |
| --- | --- |
| QueueUrl | True |
| Wilayah | False |
Untuk mempelajari selengkapnya, lihat [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html)di *Referensi API Layanan Antrian Sederhana Amazon*.
## AppConfig- GetConfiguration 1.0
Menerima informasi tentang konfigurasi.
| Parameter | Diperlukan |
| --- | --- |
| Aplikasi | True |
| Lingkungan | True |
| Konfigurasi | True |
| ClientId | Benar |
| ClientConfigurationVersion | False |
| Wilayah | False |
Untuk mempelajari lebih lanjut, lihat [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html)di *Referensi AWS AppConfig API*.
## Kinesis- 1.0 PutRecord
Menulis catatan data tunggal ke dalam aliran data Amazon Kinesis.
| Parameter | Diperlukan |
| --- | --- |
| StreamName | True |
| Data | True |
| PartitionKey | Benar |
| SequenceNumberForOrdering | Salah |
| ExplicitHashKey | False |
| Wilayah | False |
Untuk mempelajari selengkapnya, lihat [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)di *Referensi API Amazon Kinesis Data Streams*.
## StepFunctions- StartExecution 1.0
Memulai eksekusi mesin negara.
| Parameter | Diperlukan |
| --- | --- |
| StateMachineArn | True |
| Nama | False |
| Input | False |
| Wilayah | False |
Untuk mempelajari lebih lanjut, lihat [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)di *Referensi AWS Step Functions API*.
## StepFunctions- StartSyncExecution 1.0
Memulai eksekusi mesin keadaan sinkron.
| Parameter | Diperlukan |
| --- | --- |
| StateMachineArn | True |
| Nama | False |
| Input | False |
| Wilayah | False |
| TraceHeader | False |
Untuk mempelajari lebih lanjut, lihat [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html)di *Referensi AWS Step Functions API*.
## StepFunctions- StopExecution 1.0
Menghentikan eksekusi.
| Parameter | Diperlukan |
| --- | --- |
| ExecutionArn | True |
| Penyebab | False |
| Kesalahan | False |
| Wilayah | False |
Untuk mempelajari lebih lanjut, lihat [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html)di *Referensi AWS Step Functions API*.
# Buat integrasi pribadi untuk HTTP APIs di API Gateway
Integrasi pribadi memungkinkan Anda membuat integrasi API dengan sumber daya pribadi di VPC, seperti Application Load Balancers atau aplikasi berbasis container Amazon ECS.
Anda dapat mengekspos sumber daya Anda dalam VPC untuk diakses oleh klien di luar VPC dengan menggunakan integrasi pribadi. Anda dapat mengontrol akses ke API Anda dengan menggunakan salah satu [metode otorisasi](http-api-access-control.md) yang didukung API Gateway.
**catatan**
Untuk membuat integrasi pribadi, Anda harus terlebih dahulu membuat tautan VPC. Tautan VPC V2 sekarang didukung untuk HTTP dan REST. APIs Untuk mempelajari selengkapnya tentang tautan VPC V2, lihat. [Siapkan tautan VPC V2 di API Gateway](apigateway-vpc-links-v2.md)
Setelah membuat tautan VPC V2, Anda dapat mengatur integrasi pribadi yang terhubung ke Application Load Balancer, Network Load Balancer, atau sumber daya yang terdaftar dengan layanan. AWS Cloud Map
## Pertimbangan-pertimbangan
Pertimbangan berikut dapat memengaruhi penggunaan integrasi pribadi Anda:
+ Semua sumber daya harus dimiliki oleh yang sama Akun AWS. Ini termasuk penyeimbang beban atau AWS Cloud Map layanan, tautan VPC, dan HTTP API.
+ Secara default, lalu lintas integrasi pribadi menggunakan protokol HTTP. Untuk menggunakan HTTPS, tentukan file [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html). Untuk melakukan ini menggunakan Konsol Manajemen AWS, ketika Anda membuat integrasi pribadi Anda, pilih **Pengaturan lanjutan** dan kemudian masukkan nama server yang aman.
+ Untuk integrasi pribadi, API Gateway menyertakan bagian [tahap](http-api-stages.md) titik akhir API dalam permintaan ke sumber daya backend Anda. Misalnya, permintaan ke `test` tahap API termasuk `test/route-path` dalam permintaan untuk integrasi pribadi Anda. Untuk menghapus nama panggung dari permintaan ke sumber daya backend Anda, gunakan [pemetaan parameter](http-api-parameter-mapping.md) untuk menimpa jalur permintaan. `$request.path`
## Buat integrasi pribadi menggunakan Application Load Balancer atau Network Load Balancer
Sebelum Anda membuat integrasi pribadi, Anda harus membuat tautan VPC V2. Untuk mempelajari selengkapnya tentang tautan VPC V2, lihat. [Siapkan tautan VPC V2 di API Gateway](apigateway-vpc-links-v2.md)
Untuk membuat integrasi pribadi dengan Application Load Balancer atau Network Load Balancer, buat integrasi proxy HTTP, tentukan tautan VPC yang akan digunakan, dan berikan ARN pendengar penyeimbang beban.
Perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut membuat integrasi pribadi yang terhubung ke penyeimbang beban dengan menggunakan tautan VPC:
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0
```
## Buat integrasi pribadi menggunakan penemuan AWS Cloud Map layanan
Sebelum Anda membuat integrasi pribadi, Anda harus membuat tautan VPC V2. Untuk mempelajari lebih lanjut tentang tautan VPC, lihat. [Siapkan tautan VPC V2 di API Gateway](apigateway-vpc-links-v2.md)
Untuk integrasi dengan AWS Cloud Map, API Gateway digunakan `DiscoverInstances` untuk mengidentifikasi sumber daya. Anda dapat menggunakan parameter kueri untuk menargetkan sumber daya tertentu. Atribut sumber daya terdaftar harus menyertakan alamat IP dan port. API Gateway mendistribusikan permintaan di seluruh sumber daya sehat yang dikembalikan. `DiscoverInstances` Untuk mempelajari lebih lanjut, lihat [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html)di Referensi AWS Cloud Map API.
**catatan**
Jika Anda menggunakan Amazon ECS untuk mengisi entri AWS Cloud Map, Anda harus mengonfigurasi tugas Amazon ECS untuk menggunakan catatan SRV dengan Amazon ECS Service Discovery atau mengaktifkan Amazon ECS Service Connect. Untuk informasi selengkapnya, lihat [Layanan interkoneksi](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) di Panduan Pengembang Layanan Kontainer Elastis Amazon.
Untuk membuat integrasi pribadi dengan AWS Cloud Map, buat integrasi proxy HTTP, tentukan tautan VPC yang akan digunakan, dan berikan ARN layanan. AWS Cloud Map
Perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut menciptakan integrasi pribadi yang menggunakan penemuan AWS Cloud Map layanan untuk mengidentifikasi sumber daya:
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment
--payload-format-version 1.0
```
# Konfigurasikan CORS untuk HTTP 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 yang dimulai dari skrip yang berjalan di browser. Jika Anda tidak dapat mengakses API dan menerima pesan kesalahan yang berisi`Cross-Origin Request Blocked`, Anda mungkin perlu mengaktifkan CORS. Untuk informasi lebih lanjut, lihat [Apa itu CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/) .
CORS biasanya diperlukan untuk membangun aplikasi web yang mengakses APIs host pada domain atau asal yang berbeda. Anda dapat mengaktifkan CORS untuk mengizinkan permintaan ke API Anda dari aplikasi web yang dihosting di domain lain. Misalnya, jika API Anda di-host `https://{api_id}.execute-api.{region}.amazonaws.com/` dan Anda ingin memanggil API Anda dari aplikasi web yang di-host`example.com`, API Anda harus mendukung CORS.
Jika Anda mengonfigurasi CORS untuk API, API Gateway secara otomatis mengirimkan respons ke permintaan OPTIONS preflight, meskipun tidak ada rute OPTIONS yang dikonfigurasi untuk API Anda. Untuk permintaan CORS, API Gateway menambahkan header CORS yang dikonfigurasi ke respons dari integrasi.
**catatan**
Jika Anda mengonfigurasi CORS untuk API, API Gateway mengabaikan header CORS yang dikembalikan dari integrasi backend Anda.
Anda dapat menentukan parameter berikut dalam konfigurasi CORS. Untuk menambahkan parameter ini menggunakan API Gateway HTTP API console, pilih **Tambah** setelah Anda memasukkan nilai.
| Header CORS | Properti konfigurasi CORS | Contoh nilai |
| --- | --- | --- |
| Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/http-api-cors.html) |
| Access-Control-Allow-Credentials | allowCredentials | true |
| Access-Control-Expose-Header | exposeHeaders | tanggal, x-api-id, \$1 |
| Akses-Kontrol-Max-Age | maxAge | 300 |
| Access-Control-Allow-Methods | allowMethods | DAPATKAN, POSTING, HAPUS, \$1 |
| Access-Control-Allow-Header | allowHeaders | otorisasi, \$1 |
Untuk mengembalikan header CORS, permintaan Anda harus berisi header. `origin` Untuk `OPTIONS` metode ini, permintaan Anda harus berisi `origin` header dan `Access-Control-Request-Method` header.
Konfigurasi CORS Anda mungkin terlihat mirip dengan yang berikut ini:
![\[Konfigurasi CORS untuk HTTP APIs\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/http-cors-console.png)
## Mengonfigurasi CORS untuk API HTTP dengan `$default` rute dan otorisasi
Anda dapat mengaktifkan CORS dan mengonfigurasi otorisasi untuk rute apa pun dari API HTTP. Ketika Anda mengaktifkan CORS dan otorisasi untuk [`$default`rute](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default), ada beberapa pertimbangan khusus. `$default`Rute menangkap permintaan untuk semua metode dan rute yang belum Anda tetapkan secara eksplisit, termasuk permintaan. `OPTIONS` Untuk mendukung `OPTIONS` permintaan yang tidak sah, tambahkan `OPTIONS /{proxy+}` rute ke API Anda yang tidak memerlukan otorisasi dan lampirkan integrasi ke rute. `OPTIONS /{proxy+}`Rute ini memiliki prioritas lebih tinggi daripada `$default` rute. Akibatnya, ini memungkinkan klien untuk mengirimkan `OPTIONS` permintaan ke API Anda tanpa otorisasi. Untuk informasi selengkapnya tentang prioritas perutean, lihat. [Permintaan API perutean](http-api-develop-routes.md#http-api-develop-routes.evaluation)
## Konfigurasikan CORS untuk API HTTP dengan menggunakan CLI AWS
Perintah [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) berikut memungkinkan permintaan CORS dari: `https://www.example.com`
**Example**
```
aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com"
```
Untuk informasi selengkapnya, lihat [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors) di Referensi API Amazon API Gateway Versi 2.
# Mengubah permintaan dan tanggapan API untuk HTTP APIs di API Gateway
Anda dapat memodifikasi permintaan API dari klien sebelum mereka mencapai integrasi backend Anda. Anda juga dapat mengubah respons dari integrasi sebelum API Gateway mengembalikan respons ke klien. Anda menggunakan *pemetaan parameter* untuk memodifikasi permintaan API dan tanggapan untuk HTTP APIs. Untuk menggunakan pemetaan parameter, Anda menentukan permintaan API atau parameter respons untuk dimodifikasi, dan menentukan cara memodifikasi parameter tersebut.
## Mengubah permintaan API
Anda menggunakan parameter permintaan untuk mengubah permintaan sebelum mencapai integrasi backend Anda. Anda dapat memodifikasi header, string kueri, atau jalur permintaan.
Parameter permintaan adalah peta nilai kunci. Kunci mengidentifikasi lokasi parameter permintaan untuk diubah, dan bagaimana mengubahnya. Nilai menentukan data baru untuk parameter.
Tabel berikut menunjukkan kunci yang didukung.
| Tipe | Sintaks |
| --- | --- |
| Header | append\$1overwrite\$1remove:header.headername |
| String kueri | append\$1overwrite\$1remove:querystring.querystring-name |
| Jalur | overwrite:path |
Tabel berikut menunjukkan nilai yang didukung yang dapat Anda petakan ke parameter.
| Tipe | Sintaks | Catatan |
| --- | --- | --- |
| Nilai header | \$1 request.header. nameatau \$1 \$1request.header. name\$1 | Nama header tidak peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai header dengan koma, misalnya"header1": "value1,value2". Beberapa header dicadangkan. Untuk mempelajari selengkapnya, lihat [Header yang dicadangkan](#http-api-mapping-reserved-headers). |
| Nilai string kueri | \$1request.querystring. nameatau \$1 \$1request.querystring. name\$1 | Nama string kueri peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai dengan koma, misalnya"querystring1" "Value1,Value2". |
| Isi permintaan | \$1 request.body. nameatau \$1 \$1request.body. name\$1 | Ekspresi jalur JSON. Penurunan rekursif (\$1request.body..name)dan ekspresi filter (?(expression)) tidak didukung. Saat Anda menentukan jalur JSON, API Gateway memotong isi permintaan pada 100 KB dan kemudian menerapkan ekspresi seleksi. Untuk mengirim muatan yang lebih besar dari 100 KB, tentukan`$request.body`. |
| Jalur permintaan | \$1request.path atau \$1 \$1request.path\$1 | Jalur permintaan, tanpa nama panggung. |
| Parameter jalur | \$1request.path. nameatau \$1 \$1request.path. name\$1 | Nilai parameter jalur dalam permintaan. Misalnya jika rutenya/pets/\$1petId\$1, Anda dapat memetakan petId parameter dari permintaan dengan\$1request.path.petId. |
| Variabel konteks | \$1 konteks. variableNameatau \$1 \$1context. variableName\$1 | Nilai [variabel konteks](http-api-logging-variables.md). Hanya karakter khusus `.` dan `_` didukung. |
| Variabel tahap | \$1 StageVariables. variableNameatau \$1 \$1stageVariables. variableName\$1 | Nilai [variabel tahap](http-api-stages.stage-variables.md). |
| Nilai statis | string | Nilai konstan. |
**catatan**
Untuk menggunakan beberapa variabel dalam ekspresi seleksi, lampirkan variabel dalam tanda kurung. Misalnya, `${request.path.name} ${request.path.id}`.
## Mengubah respons API
Anda menggunakan parameter respons untuk mengubah respons HTTP dari integrasi backend sebelum mengembalikan respons ke klien. Anda dapat mengubah header atau kode status respons sebelum API Gateway mengembalikan respons ke klien.
Anda mengonfigurasi parameter respons untuk setiap kode status yang dikembalikan oleh integrasi Anda. Parameter respons adalah peta nilai kunci. Kunci mengidentifikasi lokasi parameter permintaan untuk diubah, dan bagaimana mengubahnya. Nilai menentukan data baru untuk parameter.
Tabel berikut menunjukkan kunci yang didukung.
| Tipe | Sintaks |
| --- | --- |
| Header | append\$1overwrite\$1remove:header.headername |
| Kode status | overwrite:statuscode |
Tabel berikut menunjukkan nilai yang didukung yang dapat Anda petakan ke parameter.
| Tipe | Sintaks | Catatan |
| --- | --- | --- |
| Nilai header | \$1 response.header. nameatau \$1 \$1response.header. name\$1 | Nama header tidak peka huruf besar/kecil. API Gateway menggabungkan beberapa nilai header dengan koma, misalnya"header1": "value1,value2". Beberapa header dicadangkan. Untuk mempelajari selengkapnya, lihat [Header yang dicadangkan](#http-api-mapping-reserved-headers). |
| Isi respons | \$1response.body. nameatau \$1 \$1response.body. name\$1 | Ekspresi jalur JSON. Descent rekursif (\$1response.body..name) dan ekspresi filter (?(expression)) tidak didukung. Saat Anda menentukan jalur JSON, API Gateway memotong badan respons pada 100 KB dan kemudian menerapkan ekspresi pemilihan. Untuk mengirim muatan yang lebih besar dari 100 KB, tentukan`$response.body`. |
| Variabel konteks | \$1 konteks. variableNameatau \$1 \$1context. variableName\$1 | Nilai [variabel konteks](http-api-logging-variables.md) yang didukung. |
| Variabel tahap | \$1 StageVariables. variableNameatau \$1 \$1stageVariables. variableName\$1 | Nilai [variabel tahap](http-api-stages.stage-variables.md). |
| Nilai statis | string | Nilai konstan. |
**catatan**
Untuk menggunakan beberapa variabel dalam ekspresi seleksi, lampirkan variabel dalam tanda kurung. Misalnya, `${request.path.name} ${request.path.id}`.
## Header yang dicadangkan
Header berikut dicadangkan. Anda tidak dapat mengonfigurasi pemetaan permintaan atau respons untuk header ini.
+ akses-kontrol-\$1
+ apigw-\$1
+ Otorisasi
+ Koneksi
+ Pengkodean Konten
+ Content-Length
+ Content-Location
+ Diteruskan
+ Tetap Hidup
+ Asal
+ Proksi-Otentikasi
+ Otorisasi Proksi
+ TE
+ Trailer
+ Transfer-Encoding
+ Peningkatan
+ x-amz-\$1
+ x-amzn-\$1
+ X-Diteruskan-Untuk
+ X-Forwarded-Host
+ X-Diteruskan-Proto
+ Melalui
## Contoh
AWS CLI Contoh berikut mengkonfigurasi pemetaan parameter. Misalnya CloudFormation template, lihat [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).
### Menambahkan header ke permintaan API
Perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut membuat header yang diberi nama `header1` ke permintaan API sebelum mencapai integrasi backend Anda. API Gateway mengisi header dengan ID permintaan.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### Ganti nama header permintaan
Perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut mengganti nama header permintaan dari ke: `header1` `header2`
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### Mengubah respon dari integrasi
Perintah [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut mengkonfigurasi parameter respons untuk integrasi. Saat integrasi mengembalikan kode status 500, API Gateway mengubah kode status menjadi 403, dan menambahkan `header1` 1 ke respons. Saat integrasi mengembalikan kode status 404, API Gateway menambahkan `error` header ke respons.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### Hapus pemetaan parameter yang dikonfigurasi
Perintah [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) berikut menghapus parameter permintaan yang dikonfigurasi sebelumnya untuk. `append:header.header1` Ini juga menghapus parameter respons yang dikonfigurasi sebelumnya untuk kode status 200.
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```
# Gunakan definisi OpenAPI untuk HTTP APIs di API Gateway
Anda dapat menentukan HTTP API Anda dengan menggunakan file definisi OpenAPI 3.0. Kemudian Anda dapat mengimpor definisi ke API Gateway untuk membuat API. Untuk mempelajari lebih lanjut tentang ekstensi API Gateway ke OpenAPI, lihat. [Ekstensi OpenAPI untuk API Gateway](api-gateway-swagger-extensions.md)
## Mengimpor API HTTP
Anda dapat membuat API HTTP dengan mengimpor file definisi OpenAPI 3.0.
Untuk bermigrasi dari REST API ke HTTP API, Anda dapat mengekspor REST API Anda sebagai file definisi OpenAPI 3.0. Kemudian impor definisi API sebagai HTTP API. Untuk mempelajari lebih lanjut tentang mengekspor REST API, lihat[Ekspor REST API dari API Gateway](api-gateway-export-api.md).
**catatan**
HTTP APIs mendukung AWS variabel yang sama dengan REST APIs. Untuk mempelajari selengkapnya, lihat [AWS variabel untuk impor OpenAPI](import-api-aws-variables.md).
### Impor informasi validasi
Saat Anda mengimpor API, API Gateway menyediakan tiga kategori informasi validasi.
**Info**
Properti valid sesuai dengan spesifikasi OpenAPI, tetapi properti itu tidak didukung untuk HTTP. APIs
Misalnya, cuplikan OpenAPI 3.0 berikut menghasilkan info tentang impor karena HTTP APIs tidak mendukung validasi permintaan. API Gateway mengabaikan `schema` bidang `requestBody` dan.
```
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
```
**Peringatan**
Properti atau struktur tidak valid sesuai dengan spesifikasi OpenAPI, tetapi tidak memblokir pembuatan API. Anda dapat menentukan apakah API Gateway harus mengabaikan peringatan ini dan terus membuat API, atau berhenti membuat API pada peringatan.
Dokumen OpenAPI 3.0 berikut menghasilkan peringatan tentang impor karena HTTP APIs hanya mendukung proxy Lambda dan integrasi proxy HTTP.
```
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
```
**Kesalahan**
Spesifikasi OpenAPI tidak valid atau salah bentuk. API Gateway tidak dapat membuat sumber daya apa pun dari dokumen yang salah format. Anda harus memperbaiki kesalahan, dan kemudian coba lagi.
Definisi API berikut menghasilkan kesalahan pada impor karena HTTP hanya APIs mendukung spesifikasi OpenAPI 3.0.
```
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
```
Sebagai contoh lain, sementara OpenAPI memungkinkan pengguna untuk mendefinisikan API dengan beberapa persyaratan keamanan yang dilampirkan pada operasi tertentu, API Gateway tidak mendukung ini. Setiap operasi hanya dapat memiliki satu otorisasi IAM, otorisasi Lambda, atau otorisasi JWT. Mencoba memodelkan beberapa persyaratan keamanan menghasilkan kesalahan.
### Impor API dengan menggunakan AWS CLI
Perintah [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) berikut mengimpor file `api-definition.json` definisi OpenAPI 3.0 sebagai API HTTP:
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
Anda dapat mengimpor contoh definisi OpenAPI 3.0 berikut untuk membuat API HTTP.
```
{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"
},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}
```
# Ekspor HTTP APIs dari API Gateway
Setelah membuat API HTTP, Anda dapat mengekspor definisi OpenAPI 3.0 API Anda dari API Gateway. Anda dapat memilih tahap untuk mengekspor, atau mengekspor konfigurasi terbaru API Anda. Anda juga dapat mengimpor definisi API yang diekspor ke API Gateway untuk membuat API lain yang identik. Untuk mempelajari lebih lanjut tentang mengimpor definisi API, lihat[Mengimpor API HTTP](http-api-open-api.md#http-api-import).
## Ekspor definisi OpenAPI 3.0 dari sebuah tahap dengan menggunakan CLI AWS
Perintah [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) berikut mengekspor definisi OpenAPI dari tahap API yang diberi nama ke file YAMAL `prod` bernama. `stage-definition.yaml` File definisi yang diekspor menyertakan [ekstensi API Gateway](api-gateway-swagger-extensions.md) secara default.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## Ekspor definisi OpenAPI 3.0 dari perubahan terbaru API Anda dengan menggunakan CLI AWS
Perintah [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) berikut mengekspor definisi OpenAPI dari API HTTP ke file JSON bernama. `latest-api-definition.json` Karena perintah tidak menentukan tahapan, API Gateway mengekspor konfigurasi terbaru API Anda, apakah itu telah diterapkan ke panggung atau belum. File definisi yang diekspor tidak menyertakan [ekstensi API Gateway](api-gateway-swagger-extensions.md).
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
Untuk informasi selengkapnya, lihat [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) di Referensi API *Amazon API Gateway Versi 2*.
## Ekspor definisi OpenAPI 3.0 menggunakan konsol API Gateway
Prosedur berikut menunjukkan cara mengekspor definisi OpenAPI dari API HTTP.
**Untuk mengekspor definisi OpenAPI 3.0 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 API HTTP.
1. Pada panel navigasi utama, di bawah **Kembangkan**, pilih **Ekspor**.
1. Pilih dari opsi berikut untuk mengekspor API Anda:
![\[Opsi ekspor untuk HTTP APIs.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/export-http-api.png)
1. Untuk **Sumber**, pilih sumber untuk definisi OpenAPI 3.0. Anda dapat memilih tahap untuk mengekspor, atau mengekspor konfigurasi terbaru API Anda.
1. Aktifkan **Sertakan ekstensi API Gateway** untuk menyertakan [ekstensi API Gateway](api-gateway-swagger-extensions.md).
1. Untuk **format Output**, pilih format output.
1. Pilih **Unduh**.
# Publikasikan HTTP APIs agar pelanggan dapat dipanggil
Anda dapat menggunakan tahapan dan nama domain khusus untuk mempublikasikan API agar klien dapat dipanggil.
Tahap API adalah referensi logis ke status siklus hidup API Anda (misalnya,,, `dev` `prod``beta`, atau`v2`). Setiap tahap adalah referensi bernama untuk deployment API dan dibuat tersedia bagi aplikasi klien untuk dipanggil. Anda dapat mengonfigurasi integrasi dan pengaturan yang berbeda untuk setiap tahap API.
Anda dapat menggunakan nama domain khusus untuk memberikan URL yang lebih sederhana dan lebih intuitif bagi klien untuk memanggil API Anda daripada URL default. `https://api-id.execute-api.region.amazonaws.com/stage`
**catatan**
Untuk meningkatkan keamanan API Gateway Anda APIs, `execute-api.{region}.amazonaws.com` domain terdaftar di [Daftar Akhiran Publik (PSL](https://publicsuffix.org/)). Untuk keamanan lebih lanjut, kami menyarankan Anda menggunakan cookie dengan `__Host-` awalan jika Anda perlu mengatur cookie sensitif di nama domain default untuk API Gateway APIs Anda. Praktik ini akan membantu mempertahankan domain Anda dari upaya pemalsuan permintaan lintas situs (CSRF). Untuk informasi selengkapnya, lihat halaman [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) di Jaringan Pengembang Mozilla.
**Topics**
+ [
# Tahapan untuk HTTP APIs di API Gateway
](http-api-stages.md)
+ [
# Kebijakan keamanan untuk HTTP APIs di API Gateway
](http-api-ciphers.md)
+ [
# Nama domain khusus untuk HTTP APIs di API Gateway
](http-api-custom-domain-names.md)
# Tahapan untuk HTTP APIs di API Gateway
Tahap API adalah referensi logis ke status siklus hidup API Anda (misalnya,,, `dev` `prod``beta`, atau`v2`). Tahapan API diidentifikasi oleh ID API dan nama stage mereka, dan mereka disertakan dalam URL yang Anda gunakan untuk memanggil API. Setiap tahap adalah referensi bernama untuk deployment API dan dibuat tersedia bagi aplikasi klien untuk dipanggil.
Anda dapat membuat `$default` stage yang disajikan dari dasar URL API Anda—misalnya,. `https://{api_id}.execute-api.{region}.amazonaws.com/` Anda menggunakan URL ini untuk memanggil tahap API.
Deployment adalah snapshot dari konfigurasi API Anda. Setelah Anda menerapkan API ke tahap, itu tersedia bagi klien untuk dipanggil. Anda harus menerapkan API agar perubahan diterapkan. Jika Anda mengaktifkan penerapan otomatis, perubahan pada API akan dirilis secara otomatis untuk Anda.
# Gunakan variabel tahap untuk HTTP APIs di API Gateway
Variabel tahap adalah pasangan nilai kunci yang dapat Anda tentukan untuk tahap API HTTP. Mereka bertindak seperti variabel lingkungan dan dapat digunakan dalam pengaturan API Anda.
Variabel tahap tidak dimaksudkan untuk digunakan untuk data sensitif, seperti kredensional. Untuk meneruskan data sensitif ke integrasi, gunakan AWS Lambda otorisasi. Anda dapat meneruskan data sensitif ke integrasi dalam output otorisasi Lambda. Untuk mempelajari selengkapnya, lihat [Format respons otorisasi Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
## Contoh - Gunakan variabel panggung untuk menyesuaikan titik akhir integrasi HTTP
Misalnya, Anda dapat menentukan variabel tahap, dan kemudian menetapkan nilainya sebagai titik akhir HTTP untuk integrasi proxy HTTP. Kemudian, Anda dapat mereferensikan titik akhir dengan menggunakan nama variabel tahap terkait. Dengan melakukan ini, Anda dapat menggunakan penyiapan API yang sama dengan titik akhir yang berbeda di setiap tahap. Demikian pula, Anda dapat menggunakan variabel tahap untuk menentukan integrasi AWS Lambda fungsi yang berbeda untuk setiap tahap API Anda.
Untuk menggunakan variabel tahap untuk menyesuaikan titik akhir integrasi HTTP, Anda harus terlebih dahulu mengatur nama dan nilai variabel tahap (misalnya,`url`) dengan nilai`example.com`. Selanjutnya, siapkan integrasi proxy HTTP. Alih-alih memasukkan URL titik akhir, Anda dapat memberi tahu API Gateway untuk menggunakan nilai variabel stage,**http://\$1\$1stageVariables.url\$1**. Nilai ini memberi tahu API Gateway untuk mengganti variabel stage Anda `${}` saat runtime, tergantung pada tahap API Anda.
Anda dapat mereferensikan variabel tahap dengan cara yang sama untuk menentukan nama fungsi Lambda atau peran AWS ARN.
Saat menentukan nama fungsi Lambda sebagai nilai variabel tahap, Anda harus mengonfigurasi izin pada fungsi Lambda secara manual. Perintah [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) berikut mengonfigurasi izin untuk fungsi Lambda:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
# Referensi variabel tahap API Gateway untuk HTTP APIs di API Gateway
Anda dapat menggunakan variabel tahap API Gateway untuk HTTP APIs dalam kasus berikut.
## Integrasi HTTP URIs
Anda dapat menggunakan variabel tahap sebagai bagian dari URI integrasi HTTP, seperti yang ditunjukkan pada contoh berikut.
+ URI lengkap tanpa protokol — `http://${stageVariables.}`
+ Domain lengkap — `http://${stageVariables.}/resource/operation`
+ Sebuah subdomain — `http://${stageVariables.}.example.com/resource/operation`
+ Sebuah jalan — `http://example.com/${stageVariables.}/bar`
+ Sebuah string kueri - `http://example.com/foo?q=${stageVariables.}`
## Fungsi Lambda
Anda dapat menggunakan variabel tahap sebagai pengganti nama integrasi fungsi Lambda atau alias, seperti yang ditunjukkan pada contoh berikut.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**catatan**
Untuk menggunakan variabel stage untuk fungsi Lambda, fungsi tersebut harus berada di akun yang sama dengan API. Variabel tahap tidak mendukung fungsi Lambda lintas akun.
## AWS kredensi integrasi
Anda dapat menggunakan variabel tahap sebagai bagian dari ARN kredensi AWS pengguna atau peran, seperti yang ditunjukkan pada contoh berikut.
+ `arn:aws:iam:::${stageVariables.}`
# Kebijakan keamanan untuk HTTP APIs di API Gateway
API Gateway memberlakukan kebijakan keamanan `TLS_1_2` untuk semua titik akhir HTTP API.
*Kebijakan keamanan* adalah kombinasi standar dari versi TLS minimum dan cipher suite yang ditawarkan oleh Amazon API Gateway. Protokol TLS mengatasi masalah keamanan jaringan seperti gangguan dan penyadapan antara klien dan server. Ketika klien Anda membuat jabat tangan TLS ke API Anda melalui domain kustom, kebijakan keamanan memberlakukan versi TLS dan pilihan cipher suite yang dapat dipilih klien Anda untuk digunakan. Kebijakan keamanan ini menerima lalu lintas TLS 1.2 dan TLS 1.3 dan menolak lalu lintas TLS 1.0.
## Protokol dan cipher TLS yang didukung untuk HTTP APIs
Tabel berikut menjelaskan protokol TLS didukung untuk HTTP. APIs
| **Protokol TLS** | **Kebijakan keamanan TLS\$11\$12** |
| --- | --- |
| TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
Tabel berikut menjelaskan cipher TLS yang tersedia untuk kebijakan keamanan TLS 1\$12 untuk HTTP. APIs
| **Cipher TLS** | **Kebijakan keamanan TLS\$11\$12** |
| --- | --- |
| TLS-AES-128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| TLS-AES-256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| TLS- CHACHA20 - - POLY1305 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- -GCM- AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- - AES128 SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- -GCM- AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-ECDSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| ECDHE-RSA- - AES256 SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES128-GCM- SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES256-GCM- SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/success_icon.svg) Ya |
## Nama sandi OpenSSL dan RFC
OpenSSL dan IETF RFC 5246 menggunakan nama yang berbeda untuk cipher yang sama. Untuk daftar nama sandi, lihat. [Nama sandi OpenSSL dan RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names)
## Informasi tentang REST APIs dan WebSocket APIs
Untuk informasi lebih lanjut tentang REST APIs dan WebSocket APIs, lihat [Pilih kebijakan keamanan untuk domain kustom Anda di API Gateway](apigateway-custom-domain-tls-version.md) dan[Kebijakan keamanan untuk WebSocket APIs di API Gateway](websocket-api-ciphers.md).
# Nama domain khusus untuk HTTP APIs di API Gateway
*Nama domain khusus* lebih sederhana dan lebih intuitif URLs yang dapat Anda berikan kepada pengguna API Anda.
Setelah menerapkan API Anda, Anda (dan pelanggan Anda) dapat memanggil API menggunakan URL dasar default dari format berikut:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
dimana *api-id* dihasilkan oleh API Gateway, *region* adalah AWS Region, dan *stage* ditentukan oleh Anda saat menerapkan API.
Bagian nama host dari URL, `api-id.execute-api.region.amazonaws.com` mengacu pada titik akhir API. Nama endpoint API default dibuat secara acak, sulit diingat, dan tidak ramah pengguna.
Dengan nama domain khusus, Anda dapat mengatur nama host API Anda, dan memilih jalur dasar (misalnya,`myservice`) untuk memetakan URL alternatif ke API Anda. Misalnya, URL dasar API yang lebih ramah pengguna dapat menjadi:
```
https://api.example.com/myservice
```
## Pertimbangan
Pertimbangan berikut dapat memengaruhi penggunaan nama domain kustom Anda.
+ Nama domain kustom Regional dapat dikaitkan dengan REST APIs dan HTTP APIs. Anda dapat menggunakan API Gateway Versi 2 APIs untuk membuat dan mengelola nama domain kustom Regional untuk REST APIs.
+ Untuk versi TLS minimum, hanya TLS 1.2 yang didukung.
+ Anda harus membuat atau memperbarui catatan sumber daya penyedia DNS Anda untuk dipetakan ke titik akhir API Anda. Tanpa pemetaan seperti itu, permintaan API yang terikat untuk nama domain khusus tidak dapat mencapai API Gateway.
+ Anda dapat mendukung jumlah nama domain yang hampir tak terbatas tanpa melebihi kuota default dengan menggunakan sertifikat wildcard. Untuk informasi selengkapnya, lihat [Nama domain kustom wildcard](#http-wildcard-custom-domain-names).
## Prasyarat
Berikut ini adalah prasyarat untuk membuat nama domain khusus.
### Daftarkan nama domain
Anda harus memiliki nama domain internet terdaftar untuk mengatur nama domain khusus untuk Anda APIs. Anda dapat mendaftarkan nama domain internet Anda menggunakan [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) atau menggunakan registrar domain pihak ketiga pilihan Anda. Nama domain kustom Anda dapat berupa nama subdomain atau domain root (juga dikenal sebagai “zone apex”) dari domain internet terdaftar.
Nama domain Anda harus mengikuti spesifikasi [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) dan dapat memiliki maksimum 63 oktet per label dan total 255 oktet.
### Sertifikat untuk nama domain kustom
Sebelum menyiapkan nama domain khusus untuk API, Anda harus memiliki sertifikat SSL/TLS yang siap di ACM. Jika ACM tidak tersedia di AWS Wilayah tempat Anda membuat nama domain kustom, Anda harus mengimpor sertifikat ke API Gateway di Wilayah tersebut.
Untuk mengimpor badan SSL/TLS certificate, you must provide the PEM-formatted SSL/TLS sertifikat, kunci pribadinya, dan rantai sertifikat untuk nama domain kustom.
Setiap sertifikat yang disimpan dalam ACM diidentifikasi oleh ARN-nya. Dengan sertifikat yang dikeluarkan oleh ACM, Anda tidak perlu khawatir mengekspos detail sertifikat sensitif apa pun, seperti kunci pribadi. Untuk menggunakan sertifikat AWS terkelola untuk nama domain, Anda cukup mereferensikan ARN-nya.
Jika aplikasi Anda menggunakan pinning sertifikat, kadang-kadang dikenal sebagai penyematan SSL, untuk menyematkan sertifikat ACM, aplikasi mungkin tidak dapat terhubung ke domain Anda setelah AWS memperbarui sertifikat. Untuk informasi selengkapnya, lihat [Masalah penyematan sertifikat](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) di *Panduan AWS Certificate Manager Pengguna*.
## Nama domain kustom wildcard
Dengan nama domain khusus wildcard, Anda dapat mendukung jumlah nama domain yang hampir tak terbatas tanpa melebihi kuota [default](limits.md). Misalnya, Anda bisa memberi setiap pelanggan Anda nama domain mereka sendiri`customername.api.example.com`.
Untuk membuat nama domain kustom wildcard, tentukan wildcard (`*`) sebagai subdomain pertama dari domain kustom yang mewakili semua kemungkinan subdomain dari domain root.
Misalnya, nama domain kustom wildcard `*.example.com` menghasilkan subdomain seperti`a.example.com`,, dan `b.example.com``c.example.com`, yang semuanya merutekan ke domain yang sama.
Nama domain kustom wildcard mendukung konfigurasi yang berbeda dari nama domain kustom standar API Gateway. Misalnya, dalam satu AWS akun, Anda dapat mengkonfigurasi `*.example.com` dan `a.example.com` berperilaku berbeda.
Untuk membuat nama domain kustom wildcard, Anda harus memberikan sertifikat yang dikeluarkan oleh ACM yang telah divalidasi menggunakan DNS atau metode validasi email.
**catatan**
Anda tidak dapat membuat nama domain khusus wildcard jika AWS akun lain telah membuat nama domain kustom yang bertentangan dengan nama domain kustom wildcard. Misalnya, jika akun A telah dibuat`a.example.com`, maka akun B tidak dapat membuat nama `*.example.com` domain khusus wildcard.
Jika akun A dan akun B berbagi pemilik, Anda dapat menghubungi [Pusat AWS Dukungan](https://console.aws.amazon.com/support/home#/) untuk meminta pengecualian.
## Langkah selanjutnya untuk nama domain kustom
Untuk menyiapkan nama domain kustom untuk API HTTP, Anda menggunakan dokumentasi dari bagian REST API dari Panduan Pengembang API Gateway.
Pertama, tentukan sertifikat untuk nama domain kustom Anda. Untuk informasi selengkapnya, lihat [Siapkan sertifikat AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Selanjutnya, Anda membuat nama domain kustom Regional. Lihat informasi yang lebih lengkap di [Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
# Memetakan tahapan API ke nama domain khusus untuk HTTP APIs
Anda menggunakan pemetaan API untuk menghubungkan tahapan API ke nama domain khusus. Setelah membuat nama domain dan mengonfigurasi catatan DNS, Anda menggunakan pemetaan API untuk mengirim lalu lintas ke nama domain khusus Anda. APIs
Pemetaan API menentukan API, tahap, dan jalur opsional yang akan digunakan untuk pemetaan. Misalnya, Anda dapat memetakan `production` tahap API ke`https://api.example.com/orders`.
Anda dapat memetakan tahap HTTP dan REST API ke nama domain kustom yang sama.
Sebelum membuat pemetaan API, Anda harus memiliki API, panggung, dan nama domain khusus. Untuk mempelajari lebih lanjut tentang membuat nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
## Permintaan API perutean
Anda dapat mengonfigurasi pemetaan API dengan beberapa level, misalnya `orders/v1/items` dan. `orders/v2/items`
Untuk pemetaan API dengan beberapa level, API Gateway merutekan permintaan ke pemetaan API yang memiliki jalur pencocokan terpanjang. API Gateway hanya mempertimbangkan jalur yang dikonfigurasi untuk pemetaan API, dan bukan rute API, untuk memilih API yang akan dipanggil. Jika tidak ada jalur yang cocok dengan permintaan, API Gateway mengirimkan permintaan ke API yang telah Anda petakan ke jalur `(none)` kosong.
Untuk nama domain kustom yang menggunakan pemetaan API dengan beberapa level, API Gateway merutekan permintaan ke pemetaan API yang memiliki awalan pencocokan terpanjang.
Misalnya, pertimbangkan nama domain khusus `https://api.example.com` dengan pemetaan API berikut:
1. `(none)`dipetakan ke API 1.
1. `orders`dipetakan ke API 2.
1. `orders/v1/items`dipetakan ke API 3.
1. `orders/v2/items`dipetakan ke API 4.
1. `orders/v2/items/categories`dipetakan ke API 5.
| Permintaan | API yang dipilih | Penjelasan |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | Permintaan sama persis dengan pemetaan API ini. |
| `https://api.example.com/orders/v1/items` | `API 3` | Permintaan sama persis dengan pemetaan API ini. |
| `https://api.example.com/orders/v2/items` | `API 4` | Permintaan sama persis dengan pemetaan API ini. |
| `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway memilih pemetaan yang memiliki jalur pencocokan terpanjang. `123`Pada akhir permintaan tidak mempengaruhi pemilihan. |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway memilih pemetaan yang memiliki jalur pencocokan terpanjang. |
| `https://api.example.com/customers` | `API 1` | API Gateway menggunakan pemetaan kosong sebagai tangkapan semua. |
| `https://api.example.com/ordersandmore` | `API 2` | API Gateway memilih pemetaan yang memiliki awalan pencocokan terpanjang. Untuk nama domain khusus yang dikonfigurasi dengan pemetaan tingkat tunggal, seperti hanya `https://api.example.com/orders` dan, API `https://api.example.com/` Gateway akan memilih`API 1`, karena tidak ada jalur yang cocok dengannya. `ordersandmore` |
## Pembatasan
+ Dalam pemetaan API, nama domain khusus dan dipetakan APIs harus berada di akun yang sama AWS .
+ Pemetaan API harus hanya berisi huruf, angka, dan karakter berikut:. `$-_.+!*'()/`
+ Panjang maksimum jalur dalam pemetaan API adalah 300 karakter.
+ Anda dapat memiliki 200 pemetaan API dengan beberapa level untuk setiap nama domain. Batas ini tidak termasuk pemetaan API dengan level tunggal, seperti`/prod`.
+ Anda hanya dapat memetakan HTTP APIs ke nama domain kustom regional dengan kebijakan keamanan TLS 1.2.
+ Anda tidak dapat memetakan WebSocket APIs ke nama domain kustom yang sama dengan HTTP API atau REST API.
+ Jika Anda membuat pemetaan API dengan beberapa level, API Gateway mengonversi semua nama header menjadi huruf kecil.
## Buat pemetaan API
Untuk membuat pemetaan API, Anda harus terlebih dahulu membuat nama domain kustom, API, dan stage. Untuk informasi tentang membuat nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
Misalnya AWS Serverless Application Model template yang membuat semua sumber daya, lihat [Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) on GitHub.
------
#### [ Konsol Manajemen AWS ]
**Untuk membuat pemetaan API**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus**.
1. Pilih nama domain khusus yang sudah Anda buat.
1. Pilih **pemetaan API**.
1. Pilih **Konfigurasi pemetaan API**.
1. Pilih **Tambahkan pemetaan baru**.
1. Masukkan **API**, **Stage**, dan opsional **Path**.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html)Perintah berikut membuat pemetaan API. Dalam contoh ini, API Gateway mengirimkan permintaan `api.example.com/v1/orders` ke API dan tahap yang ditentukan.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
CloudFormation Contoh berikut membuat pemetaan API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Nonaktifkan titik akhir default untuk HTTP APIs
Secara default, klien dapat memanggil API Anda dengan menggunakan `execute-api` titik akhir yang dihasilkan API Gateway untuk API Anda. Untuk memastikan bahwa klien dapat mengakses API Anda hanya dengan menggunakan nama domain khusus, nonaktifkan `execute-api` titik akhir default. Saat Anda menonaktifkan titik akhir default, itu memengaruhi semua tahapan API.
Prosedur berikut menunjukkan cara menonaktifkan endpoint default untuk HTTP API.
------
#### [ Konsol Manajemen AWS ]
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API HTTP.
1. Pilih ID API Anda untuk membuka halaman **detail API**.
1. Pada **detail API**, pilih **Edit**.
1. Untuk **titik akhir Default**, pilih **Nonaktifkan**.
1. Pilih **Simpan**.
Jika Anda mengaktifkan penerapan otomatis untuk tahap Anda, Anda tidak perlu menerapkan ulang API agar perubahan diterapkan. Jika tidak, Anda harus menerapkan ulang API Anda.
1. (Opsional) Pilih **Deploy**, lalu terapkan ulang API Anda atau buat tahap baru agar perubahan diterapkan.
------
#### [ AWS CLI ]
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut menonaktifkan titik akhir default untuk HTTP API:
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Setelah menonaktifkan titik akhir default, Anda harus menerapkan API agar perubahan diterapkan, kecuali penerapan otomatis diaktifkan.
Perintah [create-deployment berikut membuat deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html):
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Jenis alamat IP untuk nama domain kustom untuk HTTP APIs
Saat membuat API, Anda menentukan jenis alamat IP yang dapat memanggil domain Anda. Anda dapat memilih IPv4 untuk menyelesaikan IPv4 alamat untuk memanggil domain Anda, atau Anda dapat memilih dualstack untuk mengizinkan keduanya IPv4 dan IPv6 alamat memanggil domain 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)
## Pertimbangan untuk jenis alamat IP
Pertimbangan berikut dapat memengaruhi penggunaan jenis alamat IP Anda.
+ Jenis alamat IP default untuk nama domain kustom API Gateway adalah IPv4.
+ Nama domain kustom Anda tidak perlu memiliki jenis alamat IP yang sama untuk semua yang APIs dipetakan ke sana. Jika Anda menonaktifkan titik akhir API default, hal ini dapat memengaruhi cara penelepon dapat menjalankan API Anda.
## Mengubah jenis alamat IP dari nama domain kustom
Anda dapat mengubah jenis alamat IP dengan memperbarui konfigurasi endpoint domain. Anda dapat memperbarui konfigurasi endpoint domain dengan menggunakan Konsol Manajemen AWS, the AWS CLI CloudFormation, atau AWS SDK.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengubah jenis alamat IP dari nama domain kustom**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih nama domain kustom publik.
1. Pilih **konfigurasi Endpoint**.
1. Untuk jenis alamat IP, pilih salah satu **IPv4**atau **Dualstack**.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui API untuk memiliki tipe alamat IP dualstack:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
Outputnya akan terlihat seperti berikut:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Lindungi HTTP Anda APIs di API Gateway
API Gateway menyediakan sejumlah cara untuk melindungi API Anda dari ancaman tertentu, seperti pengguna jahat atau lonjakan lalu lintas. Anda dapat melindungi API Anda menggunakan strategi seperti menyetel target pelambatan, dan mengaktifkan TLS timbal balik. Di bagian ini Anda dapat mempelajari cara mengaktifkan kemampuan ini menggunakan API Gateway.
**Topics**
+ [
# Permintaan Throttle ke HTTP APIs Anda untuk throughput yang lebih baik di API Gateway
](http-api-throttling.md)
+ [
# Cara mengaktifkan otentikasi TLS timbal balik untuk HTTP Anda APIs di API Gateway
](http-api-mutual-tls.md)
# Permintaan Throttle ke HTTP APIs Anda untuk throughput yang lebih baik di API Gateway
Anda dapat mengonfigurasi pembatasan APIs untuk membantu melindungi mereka dari kewalahan oleh terlalu banyak permintaan. Throttle diterapkan atas dasar upaya terbaik dan harus dianggap sebagai target daripada plafon permintaan yang dijamin.
API Gateway membatasi permintaan ke API Anda menggunakan algoritme token bucket, tempat token diperhitungkan untuk permintaan. Secara khusus, API Gateway memeriksa tarif dan ledakan pengiriman permintaan terhadap semua yang ada APIs di akun Anda, per Wilayah. Dalam algoritma token bucket, burst dapat memungkinkan overrun yang telah ditentukan sebelumnya dari batas-batas tersebut, tetapi faktor lain juga dapat menyebabkan batas dikuasai dalam beberapa kasus.
Jika pengiriman permintaan melebihi tingkat permintaan kondisi tunak dan batas burst, API Gateway mulai membatasi permintaan. Klien mungkin menerima tanggapan `429 Too Many Requests` kesalahan pada saat ini. Setelah menangkap pengecualian tersebut, klien dapat mengirimkan kembali permintaan yang gagal dengan cara yang membatasi tarif.
Sebagai pengembang API, Anda dapat menetapkan batas target untuk setiap tahapan atau rute API untuk meningkatkan kinerja keseluruhan APIs di semua akun Anda.
## Pelambatan tingkat akun per Wilayah
Secara default, API Gateway membatasi permintaan kondisi tunak per detik (RPS) APIs di semua AWS akun, per Wilayah. Ini juga membatasi burst (yaitu, ukuran bucket maksimum) di semua APIs dalam AWS akun, per Wilayah. Di API Gateway, batas burst mewakili jumlah maksimum target pengiriman permintaan bersamaan yang akan dipenuhi oleh API Gateway sebelum mengembalikan respons `429 Too Many Requests` kesalahan. Untuk informasi lebih lanjut tentang pembatasan kuota, lihat. [Kuota Amazon API Gateway](limits.md)
Batas per akun diterapkan ke semua akun APIs di Wilayah tertentu. Batas tingkat tingkat akun dapat ditingkatkan berdasarkan permintaan - batas yang lebih tinggi dimungkinkan dengan batas waktu APIs yang lebih pendek dan muatan yang lebih kecil. [Untuk meminta peningkatan batas pembatasan tingkat akun per Wilayah, hubungi Pusat Dukungan.AWS](https://console.aws.amazon.com/support/home#/) Untuk informasi selengkapnya, lihat [Kuota Amazon API Gateway](limits.md). Perhatikan bahwa batas ini tidak boleh lebih tinggi dari batas AWS pelambatan.
## Pelambatan tingkat rute
Anda dapat menyetel pembatasan tingkat rute untuk mengganti batas pembatasan permintaan tingkat akun untuk tahap tertentu atau untuk rute individual di API Anda. Batas pembatasan rute default tidak dapat melebihi batas tingkat akun.
Anda dapat mengonfigurasi pelambatan tingkat rute dengan menggunakan file. AWS CLI Perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) berikut mengonfigurasi pelambatan kustom untuk tahap dan rute API yang ditentukan:
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Cara mengaktifkan otentikasi TLS timbal balik untuk HTTP Anda APIs di API Gateway
Mutual TLS otentikasi membutuhkan otentikasi dua arah antara klien dan server. Dengan TLS bersama, klien harus menunjukkan sertifikat X.509 untuk memverifikasi identitas mereka untuk mengakses API Anda. Mutual TLS adalah persyaratan umum untuk Internet of Things (IoT) business-to-business dan aplikasi.
Anda dapat menggunakan TLS timbal balik bersama dengan [operasi otorisasi dan otentikasi](apigateway-control-access-to-api.md) lain yang didukung API Gateway. API Gateway meneruskan sertifikat yang disediakan klien kepada otorisasi Lambda dan integrasi backend.
**penting**
Secara default, klien dapat memanggil API Anda dengan menggunakan `execute-api` titik akhir yang dihasilkan API Gateway untuk API Anda. Untuk memastikan bahwa klien dapat mengakses API Anda hanya dengan menggunakan nama domain khusus dengan TLS timbal balik, nonaktifkan titik `execute-api` akhir default. Untuk mempelajari selengkapnya, lihat [Nonaktifkan titik akhir default untuk HTTP APIs](http-api-disable-default-endpoint.md).
## Prasyarat untuk TLS timbal balik
Untuk mengkonfigurasi TLS timbal balik yang Anda butuhkan:
+ Sebuah nama domain kustom
+ Setidaknya satu sertifikat yang dikonfigurasi AWS Certificate Manager untuk nama domain kustom Anda
+ Truststore yang dikonfigurasi dan diunggah ke Amazon S3
### Nama domain kustom
Untuk mengaktifkan TLS timbal balik untuk API HTTP, Anda harus mengonfigurasi nama domain khusus untuk API Anda. Anda dapat mengaktifkan TLS timbal balik untuk nama domain khusus, dan kemudian memberikan nama domain khusus kepada klien. Untuk mengakses API dengan menggunakan nama domain kustom yang mengaktifkan TLS bersama, klien harus menunjukkan sertifikat yang Anda percayai dalam permintaan API. Anda dapat menemukan informasi lebih lanjut di[Nama domain khusus untuk HTTP APIs di API Gateway](http-api-custom-domain-names.md).
### Menggunakan sertifikat AWS Certificate Manager yang dikeluarkan
Anda dapat meminta sertifikat tepercaya publik langsung dari ACM atau mengimpor sertifikat publik atau yang ditandatangani sendiri. Untuk menyiapkan sertifikat di ACM, buka [ACM](https://console.aws.amazon.com/acm/). Jika Anda ingin mengimpor sertifikat, lanjutkan membaca di bagian berikut.
### Menggunakan impor atau AWS Private Certificate Authority sertifikat
Untuk menggunakan sertifikat yang diimpor ke ACM atau sertifikat dari TLS AWS Private Certificate Authority bersama, API Gateway memerlukan yang `ownershipVerificationCertificate` dikeluarkan oleh ACM. Sertifikat kepemilikan ini hanya digunakan untuk memverifikasi bahwa Anda memiliki izin untuk menggunakan nama domain. Ini tidak digunakan untuk jabat tangan TLS. Jika Anda belum memiliki`ownershipVerificationCertificate`, pergi ke [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/)untuk mengaturnya.
Anda harus menjaga sertifikat ini tetap berlaku selama masa pakai nama domain Anda. Jika sertifikat kedaluwarsa dan perpanjangan otomatis gagal, semua pembaruan pada nama domain akan dikunci. Anda perlu memperbarui `ownershipVerificationCertificateArn` dengan valid `ownershipVerificationCertificate` sebelum Anda dapat membuat perubahan lainnya. Ini `ownershipVerificationCertificate` tidak dapat digunakan sebagai sertifikat server untuk domain TLS timbal balik lainnya di API Gateway. Jika sertifikat langsung diimpor kembali ke ACM, penerbit harus tetap sama.
### Mengkonfigurasi truststore Anda
Truststores adalah file teks dengan ekstensi `.pem` file. Mereka adalah daftar sertifikat tepercaya dari Otoritas Sertifikat. Untuk menggunakan TLS timbal balik, buat truststore sertifikat X.509 yang Anda percayai untuk mengakses API Anda.
Anda harus menyertakan rantai kepercayaan lengkap, mulai dari sertifikat CA penerbitan, hingga sertifikat CA root, di truststore Anda. API Gateway menerima sertifikat klien yang dikeluarkan oleh CA mana pun yang ada dalam rantai kepercayaan. Sertifikat dapat dari otoritas sertifikat publik atau swasta. Sertifikat dapat memiliki panjang rantai maksimum empat. Anda juga dapat memberikan sertifikat yang ditandatangani sendiri. Algoritma hashing berikut didukung di truststore:
+ SHA-256 atau lebih kuat
+ RSA-2048 atau lebih kuat
+ ECDSA-256 atau lebih kuat
API Gateway memvalidasi sejumlah properti sertifikat. Anda dapat menggunakan otorisasi Lambda untuk melakukan pemeriksaan tambahan saat klien memanggil API, termasuk memeriksa apakah sertifikat telah dicabut. API Gateway memvalidasi properti berikut:
| Validasi | Deskripsi |
| --- | --- |
| Sintaks X.509 | Sertifikat harus memenuhi persyaratan sintaks X.509. |
| Integritas | Konten sertifikat tidak boleh diubah dari yang ditandatangani oleh otoritas sertifikat dari truststore. |
| Validitas | Masa berlaku sertifikat harus terkini. |
| Nama rantai/rantai kunci | Nama dan subjek sertifikat harus membentuk rantai yang tidak terputus. Sertifikat dapat memiliki panjang rantai maksimum empat. |
### Unggah truststore ke bucket Amazon S3 dalam satu file
**Example sertifikat.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
AWS CLI Perintah [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) berikut diunggah `certificates.pem` ke bucket Amazon S3 Anda:
```
aws s3 cp certificates.pem s3://bucket-name
```
## Mengkonfigurasi TLS timbal balik untuk nama domain khusus
Untuk mengonfigurasi TLS timbal balik untuk API HTTP, Anda harus menggunakan nama domain kustom Regional untuk API Anda, dengan versi TLS minimal 1.2. Untuk mempelajari selengkapnya tentang membuat dan mengonfigurasi nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
**catatan**
Mutual TLS tidak didukung untuk pribadi APIs.
Setelah Anda mengunggah truststore Anda ke Amazon S3, Anda dapat mengonfigurasi nama domain khusus Anda untuk menggunakan TLS bersama. Berikut ini [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html)membuat nama domain kustom dengan TLS timbal balik:
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
Setelah membuat nama domain, Anda harus mengonfigurasi catatan DNS dan pemetaan basepath untuk operasi API. Untuk mempelajari selengkapnya, lihat [Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
## Memanggil API dengan menggunakan nama domain khusus yang membutuhkan TLS timbal balik
Untuk menjalankan API dengan TLS timbal balik diaktifkan, klien harus menunjukkan sertifikat tepercaya dalam permintaan API. Saat klien mencoba menjalankan API Anda, API Gateway mencari penerbit sertifikat klien di truststore Anda. Agar API Gateway dapat melanjutkan permintaan, penerbit sertifikat dan rantai kepercayaan lengkap hingga sertifikat CA root harus ada di truststore Anda.
Contoh `curl` perintah berikut mengirimkan permintaan ke `api.example.com,` yang termasuk `my-cert.pem` dalam permintaan. `my-key.key`adalah kunci pribadi untuk sertifikat.
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
API Anda dipanggil hanya jika truststore Anda mempercayai sertifikat. Kondisi berikut akan menyebabkan API Gateway gagal dalam jabat tangan TLS dan menolak permintaan dengan kode `403` status. Jika sertifikat Anda:
+ tidak dipercaya
+ kedaluwarsa
+ tidak menggunakan algoritme yang didukung
**catatan**
API Gateway tidak memverifikasi apakah sertifikat telah dicabut.
## Memperbarui truststore Anda
Untuk memperbarui sertifikat di truststore Anda, unggah bundel sertifikat baru ke Amazon S3. Kemudian, Anda dapat memperbarui nama domain kustom Anda untuk menggunakan sertifikat yang diperbarui.
Gunakan versi [Amazon S3 untuk mempertahankan beberapa versi](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) truststore Anda. Saat memperbarui nama domain khusus untuk menggunakan versi truststore baru, API Gateway mengembalikan peringatan jika sertifikat tidak valid.
API Gateway menghasilkan peringatan sertifikat hanya ketika Anda memperbarui nama domain Anda. API Gateway tidak memberi tahu Anda jika sertifikat yang diunggah sebelumnya kedaluwarsa.
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui nama domain kustom untuk menggunakan versi truststore baru:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## Nonaktifkan TLS timbal balik
Untuk menonaktifkan TLS timbal balik untuk nama domain kustom, hapus truststore dari nama domain kustom Anda, seperti yang ditunjukkan pada perintah berikut.
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui nama domain khusus untuk menghapus truststore dari nama domain kustom Anda:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## Memecahkan masalah TLS timbal balik untuk HTTP API Anda
Berikut ini memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat mengaktifkan TLS timbal balik.
### Memecahkan masalah peringatan sertifikat
Saat membuat nama domain khusus dengan TLS timbal balik, API Gateway mengembalikan peringatan jika sertifikat di truststore tidak valid. Ini juga dapat terjadi saat memperbarui nama domain khusus untuk menggunakan truststore baru. Peringatan menunjukkan masalah dengan sertifikat dan subjek sertifikat yang menghasilkan peringatan. Mutual TLS masih diaktifkan untuk API Anda, tetapi beberapa klien mungkin tidak dapat mengakses API Anda.
Anda harus memecahkan kode sertifikat di truststore Anda untuk mengidentifikasi sertifikat mana yang menghasilkan peringatan. Anda dapat menggunakan alat seperti `openssl` untuk memecahkan kode sertifikat dan mengidentifikasi subjek mereka.
Perintah berikut menampilkan isi sertifikat, termasuk subjeknya:
```
openssl x509 -in certificate.crt -text -noout
```
Perbarui atau hapus sertifikat yang menghasilkan peringatan, lalu unggah truststore baru ke Amazon S3. Setelah mengunggah truststore baru, perbarui nama domain kustom Anda untuk menggunakan truststore baru.
### Memecahkan masalah konflik nama domain
Kesalahan `"The certificate subject conflicts with an existing certificate from a different issuer."` berarti beberapa Otoritas Sertifikat telah mengeluarkan sertifikat untuk domain ini. Untuk setiap subjek dalam sertifikat, hanya ada satu penerbit di API Gateway untuk domain TLS bersama. Anda harus mendapatkan semua sertifikat Anda untuk subjek itu melalui satu penerbit. Jika masalahnya adalah dengan sertifikat yang tidak Anda kendalikan tetapi Anda dapat membuktikan kepemilikan nama domain, [hubungi Dukungan](https://console.aws.amazon.com/support/cases#/create) untuk membuka tiket.
### Memecahkan masalah pesan status nama domain
`PENDING_CERTIFICATE_REIMPORT`: Ini berarti Anda mengimpor ulang sertifikat ke ACM dan validasi gagal karena sertifikat baru memiliki SAN (nama alternatif subjek) yang tidak tercakup oleh `ownershipVerificationCertificate` atau subjek atau SANs dalam sertifikat tidak mencakup nama domain. Sesuatu mungkin dikonfigurasi dengan tidak benar atau sertifikat yang tidak valid diimpor. Anda perlu mengimpor ulang sertifikat yang valid ke ACM. Untuk informasi selengkapnya tentang validasi, lihat [Memvalidasi kepemilikan domain](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html).
`PENDING_OWNERSHIP_VERIFICATION`: Ini berarti sertifikat Anda yang telah diverifikasi sebelumnya telah kedaluwarsa dan ACM tidak dapat memperbaruinya secara otomatis. Anda perlu memperbarui sertifikat atau meminta sertifikat baru. Informasi lebih lanjut tentang perpanjangan sertifikat dapat ditemukan di panduan perpanjangan sertifikat [terkelola pemecahan masalah ACM](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html).
# Pantau HTTP APIs di API Gateway
Anda dapat menggunakan CloudWatch metrik dan CloudWatch Log untuk memantau HTTP APIs. Dengan menggabungkan log dan metrik, Anda dapat mencatat kesalahan dan memantau kinerja API Anda.
**catatan**
API Gateway mungkin tidak menghasilkan log dan metrik dalam kasus berikut:
413 Kesalahan Permintaan Entitas Terlalu Besar
Berlebihan 429 Terlalu Banyak Kesalahan Permintaan
400 error seri dari permintaan yang dikirim ke domain kustom yang tidak memiliki pemetaan API
500 kesalahan seri yang disebabkan oleh kegagalan internal
**Topics**
+ [
# Pantau CloudWatch metrik untuk HTTP APIs di API Gateway
](http-api-metrics.md)
+ [
# Konfigurasikan logging untuk HTTP APIs di API Gateway
](http-api-logging.md)
# Pantau CloudWatch metrik untuk HTTP APIs di API Gateway
Anda dapat memantau eksekusi API dengan menggunakan CloudWatch, yang mengumpulkan dan memproses data mentah dari API Gateway menjadi metrik yang dapat dibaca. near-real-time Statistik ini dicatat untuk jangka waktu 15 bulan sehingga Anda dapat mengakses informasi historis dan mendapatkan perspektif yang lebih baik tentang kinerja aplikasi atau layanan web Anda. Secara default, data metrik API Gateway dikirim secara otomatis CloudWatch dalam periode satu menit. Untuk memantau metrik Anda, buat CloudWatch dasbor untuk API Anda. Untuk informasi selengkapnya tentang cara membuat CloudWatch dasbor, lihat [Membuat CloudWatch dasbor](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html) di *Panduan CloudWatch Pengguna Amazon*. Untuk informasi selengkapnya, lihat [Apa itu Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) di *Panduan CloudWatch Pengguna Amazon*.
Metrik berikut didukung untuk HTTP APIs. Anda juga dapat mengaktifkan metrik terperinci untuk menulis metrik tingkat rute ke Amazon. CloudWatch
| Metrik | Deskripsi |
| --- | --- |
| 4xx | Jumlah kesalahan sisi klien yang ditangkap dalam periode tertentu. |
| 5xx | Jumlah kesalahan sisi server yang ditangkap dalam periode tertentu. |
| Hitung | Jumlah total permintaan API dalam periode tertentu. |
| IntegrationLatency | Waktu antara saat API Gateway menyampaikan permintaan ke backend dan saat menerima respons dari backend. |
| Latensi | Waktu antara saat API Gateway menerima permintaan dari klien dan saat mengembalikan respons ke klien. Latensi mencakup latensi integrasi dan overhead API Gateway lainnya. |
| DataProcessed | Jumlah data yang diproses dalam byte. |
Anda dapat menggunakan dimensi dalam tabel berikut untuk memfilter metrik API Gateway.
| Dimensi | Deskripsi |
| --- | --- |
| ApiId | Memfilter metrik API Gateway untuk API dengan ID API yang ditentukan. |
| ApiId, Panggung | Memfilter metrik API Gateway untuk tahap API dengan ID API dan ID tahap yang ditentukan. |
| ApiId, Metode, Sumber Daya, Panggung | Memfilter metrik API Gateway untuk metode API dengan ID API, ID tahap, jalur sumber daya, dan ID rute yang ditentukan. API Gateway tidak akan mengirimkan metrik ini kecuali Anda telah mengaktifkan metrik terperinci secara eksplisit. CloudWatch Anda dapat melakukan ini dengan memanggil [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html)aksi API Gateway V2 REST API untuk memperbarui `detailedMetricsEnabled` properti ke`true`. Atau, Anda dapat memanggil AWS CLI perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) untuk memperbarui properti ke. `DetailedMetricsEnabled` `true` Mengaktifkan metrik tersebut akan dikenakan biaya tambahan ke akun Anda. Untuk informasi harga, lihat [ CloudWatchHarga Amazon](https://aws.amazon.com/cloudwatch/pricing/). |
# Konfigurasikan logging untuk HTTP APIs di API Gateway
Anda dapat mengaktifkan logging untuk menulis log ke CloudWatch Log. Anda dapat menggunakan [variabel logging](http-api-logging-variables.md) untuk menyesuaikan konten log Anda.
Untuk meningkatkan postur keamanan Anda, sebaiknya Anda menulis CloudWatch log ke Log untuk semua tahapan API HTTP Anda. Anda mungkin perlu melakukan ini untuk mematuhi berbagai kerangka kerja kepatuhan. Untuk informasi selengkapnya, lihat [kontrol Amazon API Gateway](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) di *Panduan AWS Security Hub Pengguna*.
Untuk mengaktifkan logging untuk API HTTP, Anda harus melakukan hal berikut.
1. Pastikan bahwa pengguna Anda memiliki izin yang diperlukan untuk mengaktifkan logging.
1. Buat grup CloudWatch log Log.
1. Berikan ARN dari grup CloudWatch log Log untuk tahap API Anda.
## Izin untuk mengaktifkan logging
Untuk mengaktifkan logging untuk API, pengguna Anda harus memiliki izin berikut.
**Example**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}
```
## Buat grup log dan aktifkan logging untuk HTTP APIs
Anda dapat membuat grup log dan mengaktifkan log akses menggunakan Konsol Manajemen AWS atau AWS CLI.
------
#### [ Konsol Manajemen AWS ]
1. Membuat sebuah grup log.
Untuk mempelajari cara membuat grup log menggunakan konsol, lihat [Membuat Grup Log di Panduan Pengguna CloudWatch Log Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API HTTP.
1. Di bawah tab **Monitor** di panel navigasi utama, pilih **Logging**.
1. Pilih tahap untuk mengaktifkan logging dan pilih **Pilih**.
1. Pilih **Edit** untuk mengaktifkan pencatatan akses.
1. Aktifkan **Pencatatan akses**, masukkan CloudWatch Log, dan pilih format log.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html)Perintah berikut membuat grup log:
```
aws logs create-log-group --log-group-name my-log-group
```
Anda memerlukan Nama Sumber Daya Amazon (ARN) untuk grup log Anda untuk mengaktifkan logging. Format ARN adalah arn:aws:logs: ::log-group:. *region* *account-id* *log-group-name*
Perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) berikut mengaktifkan logging untuk `$default` tahap HTTP API:
```
aws apigatewayv2 update-stage --api-id abcdef \
--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```
------
## Contoh format log
Contoh beberapa format log akses umum tersedia di konsol API Gateway dan dicantumkan sebagai berikut.
+ `CLF`([Format Log Umum](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
```
+ `XML`:
```
$context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId
```
+ `CSV`(nilai yang dipisahkan koma):
```
$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
# Sesuaikan log akses HTTP API
Anda dapat menggunakan variabel berikut untuk menyesuaikan log akses HTTP API. Untuk mempelajari lebih lanjut tentang log akses untuk HTTP APIs, lihat[Konfigurasikan logging untuk HTTP APIs di API Gateway](http-api-logging.md).
| 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 JSON Web Token (JWT) setelah pemanggil metode berhasil diautentikasi, seperti. `$context.authorizer.claims.username` Untuk informasi selengkapnya, lihat [Kontrol akses ke HTTP APIs dengan otorisasi JWT di API Gateway](http-api-jwt-authorizer.md). Memanggil `$context.authorizer.claims` mengembalikan null. |
| \$1context.authorizer.error | Pesan kesalahan dikembalikan dari otorisasi. |
| \$1context.authorizer.property | Nilai pasangan nilai kunci yang ditentukan dari `context` peta dikembalikan dari fungsi otorisasi API Gateway Lambda. Misalnya, jika otorisasi mengembalikan `context` peta berikut: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} memanggil `$context.authorizer.key` mengembalikan `"value"` string, memanggil `$context.authorizer.numKey` mengembalikan`1`, dan memanggil `$context.authorizer.boolKey` kembali`true`. |
| \$1context.awsEndpointRequestId | ID permintaan AWS titik akhir dari `x-amzn-requestId` header `x-amz-request-id` atau. |
| \$1context.awsEndpointRequestId2 | ID permintaan AWS titik akhir dari `x-amz-id-2` header. |
| \$1context.customDomain.basePathMatched | Jalur untuk pemetaan API yang cocok dengan permintaan masuk. Berlaku ketika klien menggunakan nama domain khusus untuk mengakses API. Misalnya jika klien mengirim permintaan ke`https://api.example.com/v1/orders/1234`, dan permintaan tersebut cocok dengan pemetaan API dengan jalur`v1/orders`, nilainya adalah`v1/orders`. Untuk mempelajari selengkapnya, lihat [Memetakan tahapan API ke nama domain khusus untuk HTTP APIs](http-api-mappings.md). |
| \$1context.dataProcessed | Jumlah data yang diproses dalam byte. |
| \$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. |
| \$1context.error.messageString | Nilai yang dikutip dari\$1context.error.message, yaitu"\$1context.error.message". |
| \$1context.error.responseType | Jenis`GatewayResponse`. 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.extendedRequestId | Setara dengan\$1context.requestId. |
| \$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. Didukung untuk rute yang menggunakan otorisasi IAM. |
| \$1context.identity.caller | Pengidentifikasi utama penelepon yang menandatangani permintaan. Didukung untuk rute 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). Didukung untuk rute yang menggunakan otorisasi IAM. |
| \$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. |
| \$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. |
| \$1context.identity.clientCert.issuerDN | Nama terkemuka penerbit sertifikat yang disajikan klien. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. |
| \$1context.identity.clientCert.serialNumber | Nomor seri sertifikat. Hadir saat klien mengakses API dengan menggunakan nama domain khusus yang mengaktifkan TLS timbal balik. |
| \$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. |
| \$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. |
| \$1context.identity.sourceIp | Alamat IP sumber dari koneksi TCP langsung membuat permintaan ke titik akhir API Gateway. |
| \$1context.identity.user | Pengidentifikasi utama pengguna yang akan diotorisasi terhadap akses sumber daya. Didukung untuk rute 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. Didukung untuk rute yang menggunakan otorisasi IAM. 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.integration.error | Pesan kesalahan dikembalikan dari integrasi. Setara dengan\$1context.integrationErrorMessage. |
| \$1context.integration.integrationStatus | Untuk integrasi proxy Lambda, kode status dikembalikan dari AWS Lambda, bukan dari kode fungsi Lambda backend. |
| \$1context.integration.latency | Latensi integrasi dalam ms. Setara dengan\$1context.integrationLatency. |
| \$1context.integration.requestId | ID permintaan AWS titik akhir. Setara dengan\$1context.awsEndpointRequestId. |
| \$1context.integration.status | Kode status dikembalikan dari integrasi. Untuk integrasi proxy Lambda, ini adalah kode status yang dikembalikan oleh kode fungsi Lambda Anda. |
| \$1context.integrationErrorMessage | String yang berisi pesan kesalahan integrasi. |
| \$1context.integrationLatency | Latensi integrasi dalam ms. |
| \$1context.integrationStatus | Untuk integrasi proxy Lambda, parameter ini mewakili kode status yang dikembalikan dari AWS Lambda, bukan dari fungsi Lambda backend. |
| \$1context.path | Jalur permintaan. Misalnya, /\$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 yang ditetapkan API Gateway ke permintaan API. |
| \$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). |
| \$1context.responseLatency | Latensi respons dalam ms. |
| \$1context.responseLength | Panjang payload respon dalam byte. |
| \$1context.routeKey | Kunci rute permintaan API, misalnya`/pets`. |
| \$1context.stage | Tahap penerapan permintaan API (misalnya, `beta` atau`prod`). |
| \$1context.status | Status respons metode. |
# Memecahkan masalah dengan HTTP APIs di API Gateway
Topik berikut memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat menggunakan HTTP. APIs
**Topics**
+ [
# Memecahkan masalah dengan integrasi Lambda API HTTP
](http-api-troubleshooting-lambda.md)
+ [
# Memecahkan masalah dengan otorisasi HTTP API JWT
](http-api-troubleshooting-jwt.md)
# Memecahkan masalah dengan integrasi Lambda API HTTP
Berikut ini memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat menggunakan [AWS Lambda integrasi](http-api-develop-integrations-lambda.md) dengan HTTP. APIs
## Masalah: API saya dengan integrasi Lambda kembali `{"message":"Internal Server Error"}`
Untuk memecahkan masalah kesalahan server internal, tambahkan [variabel `$context.integrationErrorMessage` logging](http-api-logging-variables.md) ke format log Anda, dan lihat log HTTP API Anda. Untuk mencapai ini, lakukan hal berikut:
**Untuk membuat grup log dengan menggunakan Konsol Manajemen AWS**
1. Buka CloudWatch konsol di [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Pilih **Grup log**.
1. Pilih **Buat grup log**.
1. Masukkan nama grup log, lalu pilih **Buat**.
1. Perhatikan Nama Sumber Daya Amazon (ARN) untuk grup log Anda. Format ARN adalah arn:aws:logs: ::log-group:. *region* *account-id* *log-group-name* Anda memerlukan grup log ARN untuk mengaktifkan pencatatan akses untuk HTTP API Anda.
**Untuk menambahkan variabel `$context.integrationErrorMessage` logging**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih HTTP API Anda.
1. Di bawah **Monitor**, pilih **Logging**.
1. Pilih tahap API Anda.
1. Pilih **Edit**, lalu aktifkan pencatatan akses.
1. Untuk **tujuan Log**, masukkan ARN dari grup log yang Anda buat pada langkah sebelumnya.
1. Untuk **format Log**, pilih **CLF**. API Gateway membuat contoh format log.
1. Tambahkan `$context.integrationErrorMessage` ke akhir format log.
1. Pilih **Simpan**.
**Untuk melihat log API Anda**
1. Hasilkan log. Gunakan browser atau `curl` untuk menjalankan API Anda.
```
$curl https://api-id.execute-api.us-west-2.amazonaws.com/route
```
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih HTTP API Anda.
1. Di bawah **Monitor**, pilih **Logging**.
1. Pilih tahap API yang Anda aktifkan logging.
1. Pilih **Lihat log masuk CloudWatch**.
1. Pilih aliran log terbaru untuk melihat log HTTP API Anda.
1. Entri log Anda akan terlihat mirip dengan yang berikut ini:
![\[CloudWatch Entri log log yang menunjukkan pesan kesalahan integrasi dari Lambda.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png)
Karena kami menambahkan `$context.integrationErrorMessage` ke format log, kami melihat pesan kesalahan di log kami yang merangkum masalah.
Log Anda mungkin menyertakan pesan kesalahan berbeda yang menunjukkan bahwa ada masalah dengan kode fungsi Lambda Anda. [Dalam hal ini, periksa kode fungsi Lambda Anda, dan verifikasi bahwa fungsi Lambda Anda mengembalikan respons dalam format yang diperlukan.](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response) Jika log Anda tidak menyertakan pesan kesalahan, tambahkan `$context.error.message` dan `$context.error.responseType` ke format log Anda untuk informasi selengkapnya guna membantu memecahkan masalah.
Dalam kasus ini, log menunjukkan bahwa API Gateway tidak memiliki izin yang diperlukan untuk menjalankan fungsi Lambda.
Saat Anda membuat integrasi Lambda di konsol API Gateway, API Gateway secara otomatis mengonfigurasi izin untuk menjalankan fungsi Lambda. Saat membuat integrasi Lambda dengan menggunakan AWS CLI,, atau SDK CloudFormation, Anda harus memberikan izin kepada API Gateway untuk menjalankan fungsi tersebut. Perintah [izin tambahan](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) berikut memberikan izin untuk rute API HTTP yang berbeda untuk menjalankan fungsi Lambda.
**Example Contoh - Untuk `$default` tahap dan `$default` rute API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"
```
**Example Contoh - Untuk `prod` tahap dan `test` rute API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test"
```
[Konfirmasi kebijakan fungsi](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html) di tab **Izin** di konsol Lambda.
Coba jalankan API Anda lagi. Anda akan melihat respons fungsi Lambda Anda.
# Memecahkan masalah dengan otorisasi HTTP API JWT
Berikut ini memberikan saran pemecahan masalah untuk kesalahan dan masalah yang mungkin Anda temui saat menggunakan otorisasi JSON Web Token (JWT) dengan HTTP. APIs
## Masalah: API saya kembali `401 {"message":"Unauthorized"}`
Periksa `www-authenticate` header dalam respons dari API.
Perintah berikut digunakan `curl` untuk mengirim permintaan ke API dengan otorisasi JWT yang digunakan `$request.header.Authorization` sebagai sumber identitasnya.
```
$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route
```
Respons dari API termasuk `www-authenticate` header.
```
...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}
```
Dalam hal ini, `www-authenticate` header menunjukkan bahwa token tidak dikeluarkan untuk audiens yang valid. Agar API Gateway dapat mengotorisasi permintaan, JWT `aud` atau `client_id` klaim harus cocok dengan salah satu entri audiens yang dikonfigurasi untuk otorisasi. API Gateway `client_id` hanya memvalidasi jika tidak `aud` ada. Saat keduanya `aud` dan `client_id` ada, API Gateway mengevaluasi. `aud`
Anda juga dapat memecahkan kode JWT dan memverifikasi bahwa JWT cocok dengan penerbit, audiens, dan cakupan yang dibutuhkan API Anda. Situs web [jwt.io](https://jwt.io/) dapat melakukan debug JWTs di browser. OpenID Foundation menyimpan [daftar pustaka untuk dikerjakan](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/). JWTs
Untuk mempelajari selengkapnya tentang otorisasi JWT, lihat. [Kontrol akses ke HTTP APIs dengan otorisasi JWT di API Gateway](http-api-jwt-authorizer.md)