Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Kirim lalu lintas ke Anda APIs melalui nama domain kustom Anda di API Gateway
Ketika Anda mengkonfigurasi mode routing untuk nama domain kustom Anda, Anda mengatur bagaimana lalu lintas masuk diarahkan ke Anda. APIs Anda mengirim lalu lintas ke APIs menggunakan aturan perutean, pemetaan API, atau aturan perutean dan pemetaan API. Bagian berikut menjelaskan kapan harus menggunakan aturan perutean, kapan menggunakan pemetaan API, dan cara mengatur mode perutean untuk nama domain kustom Anda.
## Kapan menggunakan aturan perutean
Saat Anda menggunakan aturan perutean, Anda mengarahkan permintaan masuk yang cocok dengan kondisi tertentu ke tahapan REST APIs tertentu. Misalnya, aturan dapat merutekan permintaan ke `production` tahap `users` REST API Anda jika berisi header `version:v1` dan jalur dasar`/users`. Gunakan aturan perutean untuk membuat topologi perutean dinamis lanjutan yang mendukung kasus penggunaan seperti A/B pengujian atau peningkatan penggunaan versi baru Anda. APIs
Sebaiknya saat mengarahkan lalu lintas ke REST API, Anda menggunakan aturan perutean untuk nama domain kustom Anda. Anda dapat membuat ulang pemetaan API apa pun dengan menggunakan aturan perutean. Untuk informasi selengkapnya, lihat [Membuat ulang pemetaan API menggunakan aturan perutean](rest-api-routing-rules-recreate-api-mapping.md).
Untuk REST APIs, Anda juga dapat menggunakan aturan routing dan pemetaan API bersama-sama. Saat Anda menggunakan aturan perutean dan pemetaan API bersama-sama, API Gateway selalu mengevaluasi aturan perutean sebelum mengevaluasi pemetaan API apa pun. Gunakan aturan perutean dan pemetaan API bersama-sama untuk memigrasikan nama domain kustom Anda saat ini atau untuk menjelajahi aturan perutean.
### Pertimbangan untuk aturan perutean
Pertimbangan berikut dapat memengaruhi penggunaan aturan perutean Anda:
+ WebSocket atau HTTP APIs tidak didukung sebagai target APIs untuk aturan perutean.
+ Jika nama domain kustom Anda memiliki pemetaan API ke REST dan HTTP APIs, aturan perutean tidak didukung.
+ Anda dapat membuat aturan perutean untuk domain kustom pribadi ke REST API pribadi. Anda dapat membuat aturan perutean untuk domain kustom publik ke API Regional atau yang dioptimalkan tepi.
+ Anda tidak dapat membuat aturan perutean untuk domain kustom publik ke API pribadi. Anda tidak dapat membuat aturan perutean untuk nama domain kustom pribadi ke API publik.
## Pilih antara aturan perutean dan pemetaan API
Kami menyarankan bahwa jika memungkinkan, Anda menggunakan aturan routing. Hanya gunakan pemetaan API untuk mengirim lalu lintas ke HTTP atau WebSocket API.
# Mengatur mode routing untuk nama domain kustom Anda
Anda dapat memilih mode perutean yang digunakan API Gateway untuk merutekan lalu lintas ke Anda APIs. Untuk informasi selengkapnya, lihat [Kirim lalu lintas ke Anda APIs melalui nama domain kustom Anda di API Gateway](rest-api-routing-mode.md). Bagian ini membahas mode routing untuk nama domain kustom. Anda harus mengatur mode perutean untuk nama domain kustom Anda untuk mengarahkan lalu lintas ke Anda APIs. Mode perutean berikut didukung:
+ **ROUTING\$1RULE\$1THEN\$1 API\$1MAPPING** — Gunakan mode ini untuk mengirim lalu lintas ke Anda APIs dengan aturan perutean dan pemetaan API. Dalam mode ini, semua aturan perutean diprioritaskan daripada pemetaan API apa pun. Untuk contoh mode ini, lihat[Contoh 2: Aturan perutean dan pemetaan API](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings).
+ **ROUTING\$1RULE\$1ONLY — Gunakan mode ini untuk hanya** mengizinkan aturan routing untuk mengirim lalu lintas ke Anda. APIs Ketika nama domain kustom Anda menggunakan mode ini, Anda tidak dapat membuat pemetaan API, tetapi Anda dapat menggunakan [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html)perintah untuk melihatnya. Pemanggil API tidak dapat menggunakan pemetaan API untuk mengakses nama domain ini.
+ **API\$1MAPPING\$1ONLY** — Gunakan mode ini untuk hanya mengizinkan pemetaan API untuk mengirim lalu lintas ke Anda. APIs Saat nama domain kustom Anda menggunakan mode ini, Anda tidak dapat membuat aturan perutean, tetapi Anda dapat menggunakan `list-routing-rules` perintah untuk melihatnya. Pemanggil API tidak dapat menggunakan aturan perutean untuk mengakses nama domain ini.
Ini adalah mode routing default untuk semua nama domain yang ada, dan nama domain baru yang Anda buat.
Ketika Anda membuat nama domain kustom menggunakan`apigateway`, `API_MAPPING_ONLY` dipanggil `BASE_PATH_MAPPING_ONLY` dan `ROUTING_RULE_THEN_API_MAPPING` dipanggil`ROUTING_RULE_THEN_BASE_PATH_MAPPING`. Perilaku ini hanya ada untuk AWS CLI, CloudFormation, atau apa pun SDKs, tidak di Konsol Manajemen AWS.
Prosedur berikut menunjukkan cara mengubah mode routing untuk nama domain kustom yang ada. Saat Anda mengubah mode perutean nama domain kustom Anda, pemanggil API tidak dapat mengakses nama domain Anda menggunakan mode perutean yang tidak didukung.
------
#### [ Konsol Manajemen AWS ]
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus** dari panel navigasi utama.
1. Pilih nama domain khusus.
1. Untuk **detail Domain**, pilih **Edit**.
1. Untuk **mode Routing**, pilih **API\$1MAPPINGROUTING\$1RULE\$1THEN\$1**.
1. Pilih **Simpan**.
Jika Anda mengubah mode perutean ke `ROUTING_RULE_ONLY` atau`API_MAPPING_ONLY`, pemetaan API atau aturan perutean apa pun yang Anda buat akan dihapus dari halaman detail nama domain konsol. Jika Anda mengubah mode perutean untuk mendukung aturan perutean atau pemetaan API, sumber daya ini akan kembali.
------
#### [ AWS CLI - apigatewayv2 ]
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)Perintah berikut memperbarui nama domain untuk menggunakan mode `ROUTING_RULE_THEN_API_MAPPING` routing:
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
Outputnya akan terlihat seperti berikut:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
[update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)Perintah berikut memperbarui nama domain kustom pribadi untuk menggunakan mode `ROUTING_RULE_THEN_BASE_PATH_MAPPING` perutean:
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
Outputnya akan terlihat seperti berikut:
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# Aturan perutean untuk menghubungkan tahapan API ke nama domain khusus untuk REST APIs
Aturan routing adalah serangkaian kondisi yang ketika dicocokkan, memanggil tindakan. Misalnya, aturan dapat merutekan permintaan masuk ke nama domain kustom yang berisi header `Hello:World` dan berisi jalur dasar `users` ke `production` tahap REST API.
Aturan dievaluasi dalam urutan prioritas, dan jika Anda menyetel mode perutean`ROUTING_RULE_THEN_API_MAPPING`, API Gateway selalu mengevaluasi semua aturan perutean sebelum mengevaluasi pemetaan API apa pun. Daftar berikut menjelaskan bagaimana aturan routing menggunakan kondisi, tindakan, dan prioritas.
**Ketentuan**
Bila syarat untuk suatu peraturan terpenuhi, maka tindakannya dilakukan. API Gateway mendukung hingga dua kondisi header dan satu kondisi jalur. API Gateway mengevaluasi kondisi header dan kondisi jalur dasar secara bersamaan.
Anda dapat membuat aturan tanpa syarat apa pun. Saat API Gateway mengevaluasi aturan ini, tindakan selalu dilakukan. Anda dapat membuat aturan tanpa syarat apa pun sebagai aturan catch-all.
Untuk informasi selengkapnya tentang kondisi header, lihat[Ketentuan header pertandingan](#rest-api-routing-rules-condition-headers). Untuk informasi selengkapnya tentang kondisi jalur, lihat[Cocokkan kondisi jalur dasar](#rest-api-routing-rules-condition-path).
**Tindakan**
Tindakan adalah hasil dari kondisi pencocokan dengan aturan routing. Saat ini, satu-satunya tindakan yang didukung adalah memanggil tahap REST API.
Setiap aturan dapat memiliki satu tindakan.
**Prioritas**
Prioritas menentukan urutan aturan yang dievaluasi, dari nilai terendah hingga nilai tertinggi. Aturan tidak dapat memiliki prioritas yang sama.
Anda dapat menetapkan prioritas dari 1-1.000.000. Jika aturan memiliki prioritas satu, API Gateway mengevaluasinya terlebih dahulu. Kami menyarankan bahwa ketika Anda membuat aturan, Anda menambahkan kesenjangan dalam prioritas. Ini membantu Anda mengubah prioritas aturan dan menambahkan aturan baru. Untuk informasi selengkapnya, lihat [Mengubah prioritas aturan routing](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority).
Untuk contoh cara API Gateway mengevaluasi aturan perutean, lihat. [Contoh bagaimana API Gateway mengevaluasi aturan perutean](rest-api-routing-rules-examples.md)
## Jenis kondisi aturan perutean API Gateway
Bagian berikut menjelaskan jenis kondisi aturan routing. API Gateway hanya cocok dengan aturan jika semua kondisi benar.
### Ketentuan header pertandingan
Saat Anda membuat kondisi header, Anda dapat mencocokkan nama header dan nilai glob header, seperti`Hello:World`. API Gateway menggunakan kecocokan literal untuk memvalidasi kondisi header kecocokan. Kondisi Anda dapat menggunakan hingga dua header yang digunakan di `AND` antara mereka. Misalnya, kondisi Anda dapat cocok jika permintaan masuk berisi `Hello:World` dan`x-version:beta`.
Pencocokan nama header tidak peka huruf besar/kecil, tetapi nilai glob header peka huruf besar/kecil. `Hello:World`akan cocok`hello:World`, tapi tidak`Hello:world`.
Untuk daftar nilai header terbatas lihat,[Pembatasan](#rest-api-routing-rules-restrictions).
#### Menggunakan wildcard dengan kondisi header
Anda hanya dapat menggunakan wildcard dalam nilai header glob, dan wildcard harus`*prefix-match`,, `suffix-match*` atau. `*contains*` Tabel berikut menunjukkan contoh cara menggunakan wildcard untuk pencocokan kondisi header.
| Kondisi header | Permintaan yang cocok dengan aturan perutean | Permintaan yang tidak cocok dengan aturan perutean |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` dan `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` dan `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | Tidak ada |
Jika Anda membuat kondisi untuk beberapa nilai header, seperti`Accept:application/json,text/xml`, kami sarankan Anda menggunakan `*contains*` untuk kondisi header Anda dan menghindari membuat kondisi menggunakan karakter koma (`,`).
Karena API Gateway cocok dengan kondisi header secara harfiah, kecocokan semantik mungkin dirutekan secara berbeda. Tabel berikut menunjukkan perbedaan dalam hasil aturan routing.
| Kondisi header | Permintaan yang cocok dengan aturan perutean | Permintaan yang tidak cocok dengan aturan perutean |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/rest-api-routing-rules.html) | Tidak ada |
### Cocokkan kondisi jalur dasar
Saat Anda membuat kondisi jalur dasar, jika permintaan masuk berisi jalur yang Anda tentukan, aturannya cocok. Pencocokannya peka huruf besar/kecil, jadi jalurnya tidak `New/Users` akan cocok`new/users`.
Anda dapat membuat kondisi jalur dasar hanya untuk satu jalur dasar.
Untuk daftar kondisi jalur dasar terbatas,[Pembatasan](#rest-api-routing-rules-restrictions).
#### Lepaskan jalur dasar dengan kondisi jalur dasar
Saat Anda membuat kondisi jalur dasar, Anda dapat memilih untuk menghapus jalur dasar. Saat Anda menghapus jalur dasar, API Gateway menghapus jalur dasar yang cocok yang masuk saat memanggil API target. Ini adalah perilaku yang sama seperti ketika Anda menggunakan pemetaan API. Jika Anda tidak menghapus jalur dasar, API Gateway meneruskan seluruh jalur dasar ke API target. Sebaiknya Anda hanya menghapus jalur dasar saat membuat ulang pemetaan API.
Tabel berikut menunjukkan contoh bagaimana API Gateway mengevaluasi kondisi jalur dasar strip.
| Kondisi | Jalur dasar strip | Permintaan masuk | Hasil |
| --- | --- | --- | --- |
| Jika jalur dasar berisi `PetStoreShopper/dogs` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway memanggil `GET` metode `/` sumber daya. |
| Jika jalur dasar berisi`PetStoreShopper/dogs`. | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway memanggil `GET` metode `PetStoreShopper/dogs` sumber daya. |
| Jika jalur dasar berisi `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway memanggil `GET` metode `dogs` sumber daya. |
| Jika jalur dasar berisi `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway memanggil `GET` metode `PetStoreShopper/dogs` sumber daya. |
| Jika jalur dasar berisi `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway memanggil `GET` metode `/` sumber daya dengan parameter string kueri`birds=available`. |
| Jika jalur dasar berisi `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway memanggil `GET` metode `/PetStoreShopper` sumber daya dengan parameter string kueri`birds=available`. |
## Pembatasan
+ API target dan nama domain khusus harus berada di AWS akun yang sama.
+ Setiap aturan dapat memiliki satu API target.
+ Anda hanya dapat membuat aturan perutean untuk nama domain kustom pribadi ke API pribadi, dan untuk nama domain kustom publik ke API publik. Anda tidak dapat mencampur sumber daya publik dan swasta.
+ Jika nama domain kustom Anda memiliki pemetaan API ke REST dan HTTP APIs, aturan perutean tidak didukung.
+ Jumlah prioritas maksimum adalah 1.000.000.
+ Pembatasan header:
+ Setiap `anyOf` kondisi hanya dapat berisi satu nilai header.
+ Satu-satunya karakter yang diizinkan untuk nama header dan nilai glob header ditentukan oleh [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230), yaitu,`a-z`, `A-Z``0-9`, dan karakter khusus berikut:. `*?-!#$%&'.^_`|~`
+ Anda dapat menggunakan wildcard dalam nilai header glob, tetapi wildcard harus`*prefix-match`,, `suffix-match*` atau. `*contains*` Anda tidak dapat menggunakan `*` di tengah nilai glob header.
+ Nama header wildcard tidak didukung.
+ Nama header harus kurang dari 40 karakter.
+ Nilai header glob harus kurang dari 128 karakter.
+ Nilai header glob untuk kecocokan infix harus kurang dari 40 karakter.
+ Header berikut tidak didukung sebagai kondisi:
+ `access-control-*`
+ `apigw-*`
+ `Authorization`
+ `Connection`
+ `Content-Encoding`
+ `Content-Length`
+ `Content-Location`
+ `Forwarded`
+ `Keep-Alive`
+ `Origin`
+ `Proxy-Authenticate`
+ `Proxy-Authorization`
+ `TE`
+ `Trailers`
+ `Transfer-Encoding`
+ `Upgrade`
+ `x-amz-*`
+ `x-amzn-*`
+ `x-apigw-api-id`
+ `X-Forwarded-For`
+ `X-Forwarded-Host`
+ `X-Forwarded-Proto`
+ `x-restAPI`
+ `Via`
+ Batasan jalur dasar:
+ Panjang jalur dasar harus kurang dari 128 karakter.
+ Jalur dasar harus berisi hanya huruf, angka, dan karakter berikut:`$-_.+!*'()/`.
Karakter ini tidak didukung untuk ekspresi reguler (regex).
+ Jalur dasar tidak dapat memulai atau mengakhiri dengan karakter garis miring terbalik (`\`).
# Contoh bagaimana API Gateway mengevaluasi aturan perutean
Bagian berikut menunjukkan empat contoh bagaimana API Gateway mengevaluasi aturan routing dan pemetaan API.
## Contoh 1: Aturan perutean saja
Dalam contoh ini, nama domain khusus `https://petstore.example.com` memiliki mode perutean yang disetel ke `ROUTING_RULE_ONLY` dan memiliki aturan dan prioritas perutean berikut.
| ID aturan | Prioritas | Ketentuan | Tindakan |
| --- | --- | --- | --- |
| `abc123` | 10 | Jika permintaan berisi header: `Hello:World` | Target API 1 |
| `zzz000` | 50 | Jika permintaan berisi header: `Accept:image/webp` dan `Pet:Dog-*` dan jika jalur dasar berisi `PetStoreShopper` | Target API 2 |
| `efg456` | 100 | Tidak ada | Target API 3 |
Tabel berikut menunjukkan bagaimana API Gateway menerapkan aturan perutean sebelumnya ke permintaan contoh.
| Permintaan | API yang dipilih | Penjelasan |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | Target API 1 | Permintaan cocok dengan aturan `abc123` routing. |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | Target API 1 | API Gateway mengevaluasi semua aturan perutean dalam urutan prioritas. Aturan perutean `abc123` memiliki prioritas pertama dan kondisinya cocok, sehingga API Gateway memanggil Target API 1. Meskipun kondisi permintaan juga cocok dengan aturan perutean`zzz000`, API Gateway tidak mengevaluasi aturan perutean lainnya setelah membuat kecocokan. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | Target API 2 | Permintaan cocok dengan aturan `zzz000` routing. Ini adalah pertandingan karena itu `Pet:Dog-Bella` adalah string yang cocok `Pet:Dog-*` |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | Target API 3 | Permintaan tidak cocok dengan aturan `abc123` routing. Permintaan tidak cocok dengan aturan perutean `zzz000` karena semua header yang diperlukan tidak ada. Aturan prioritas berikutnya cocok dengan semua permintaan yang masuk, jadi API Gateway memanggil Target API 3. |
## Contoh 2: Aturan perutean dan pemetaan API
Dalam contoh ini, nama domain khusus `https://petstore.diagram.example.com` memiliki mode perutean yang disetel ke `ROUTING_RULE_THEN_API_MAPPING` dan memiliki aturan perutean dan pemetaan API berikut.
| ID aturan | Prioritas | Ketentuan | Tindakan |
| --- | --- | --- | --- |
| `abc123` | 1 | Jika permintaan basis berisi `pets` | Memanggil `Prod` tahap `PetStore` API. |
| `000zzz` | 5 | Jika permintaan berisi header:`Cookie`: `*ux=beta*` dan dan jika jalur dasar berisi `/refunds` | Memanggil `Beta` tahap `Refunds` API. |
Tabel berikut menunjukkan pemetaan API untuk. `https://petstore.backup.example.com`
| Pemetaan API | API yang dipilih |
| --- | --- |
| `/refunds` | Memanggil `Prod` tahap `Refunds` API. |
| `(none)` | Memanggil `Prod` tahap `Search` API. |
Diagram berikut menunjukkan bagaimana API Gateway menerapkan aturan perutean sebelumnya dan pemetaan API ke permintaan contoh. Contoh permintaan dirangkum dalam tabel setelah diagram ini.
![\[Diagram bagaimana API Gateway menerapkan aturan perutean dan pemetaan API sebelumnya.\]](http://docs.aws.amazon.com/id_id/apigateway/latest/developerguide/images/rr-diagram.png)
Tabel berikut menunjukkan bagaimana API Gateway menerapkan aturan perutean sebelumnya dan pemetaan API ke permintaan contoh.
| Permintaan | API yang dipilih | Penjelasan |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | `Prod`Tahap `PetStore` API. | Permintaan cocok dengan aturan `abc123` perutean. |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | `Beta`Tahap `Refunds` API. | Permintaan cocok dengan aturan `000zzz` perutean. `Cookie`Header berisi `*contains*` kecocokan yang benar dan pencocokan jalur dasar untuk kondisi ini. |
| `https://petstore.diagram.example.com/refunds` | `Prod`Tahap `Refunds` API. | Permintaan tidak memiliki header yang diperlukan untuk mencocokkan aturan perutean. `zzz000` Jika API Gateway tidak berhasil mencocokkan aturan perutean, itu akan kembali ke pemetaan API. API Gateway dapat memetakan jalur dasar ke `Prod` tahap `Refunds` API. |
| `https://petstore.diagram.example.com/` | `Prod`Tahap `Search` API. | Permintaan mencocokkan pemetaan API dengan jalur `(none)` kosong. |
## Contoh 3: Aturan perutean dan pemetaan API dengan beberapa level
Dalam contoh ini, nama domain khusus `https://petstore.backup.example.com` memiliki mode perutean yang disetel ke `ROUTING_RULE_THEN_API_MAPPING` dan memiliki aturan perutean dan pemetaan API berikut.
Tabel berikut menunjukkan aturan routing untuk`https://petstore.backup.example.com`.
| ID aturan | Prioritas | Ketentuan | Tindakan |
| --- | --- | --- | --- |
| `abc123` | 10 | Jika permintaan berisi header: `Hello:World` | Target API 1 |
| `000zzz` | 50 | Jika permintaan berisi header:`Accept`: `image/webp` dan `Pet:Dog-*` dan jika jalur dasar berisi `PetStoreShopper` | Target API 2 |
Tabel berikut menunjukkan pemetaan API untuk. `https://petstore.backup.example.com`
| Pemetaan API | API yang dipilih |
| --- | --- |
| `PetStoreShopper` | Target API 3 |
| `PetStoreShopper/cats` | Target API 4 |
Tabel berikut menunjukkan bagaimana API Gateway menerapkan aturan perutean sebelumnya dan pemetaan API ke permintaan contoh.
| Permintaan | API yang dipilih | Penjelasan |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | Target API 3 | Permintaan tidak memiliki header yang diperlukan untuk mencocokkan aturan perutean. `zzz000` Jika API Gateway tidak berhasil mencocokkan aturan perutean, itu akan kembali ke pemetaan API. API Gateway dapat memetakan jalur dasar ke Target API 3. |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | Target API 1 | Permintaan cocok dengan aturan `abc123` perutean. Jika mode perutean disetel ke`ROUTING_RULE_THEN_API_MAPPING`, aturan perutean selalu diprioritaskan daripada pemetaan API. |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | Tidak ada | Permintaan tidak cocok dengan aturan perutean atau pemetaan API apa pun. Karena tidak ada aturan perutean default, API Gateway menolak panggilan dan mengirimkan kode status kepada `403 Forbidden` pemanggil. |
## Contoh 4: Aturan perutean untuk nama domain wildcard
Dalam contoh ini, nama domain kustom `https://*.example.com` adalah nama domain wildcard. Wildcard mendukung semua subdomain yang merutekan kembali ke domain yang sama. Contoh aturan perutean berikut mengubah perilaku ini untuk memungkinkan subdomain merutekan ke target yang berbeda APIs dengan menggunakan header. `Host`
Tabel berikut menunjukkan aturan routing untuk`https://*.example.com`.
| ID aturan | Prioritas | Ketentuan | Tindakan |
| --- | --- | --- | --- |
| `abc123` | 10 | Jika permintaan berisi header: `Host:a.example.com` | Target API 1 |
| `000zzz` | 50 | Jika permintaan berisi header: `Host:b.example.com` | Target API 2 |
| `efg456` | 500 | Tidak ada | Target API 3 |
Tabel berikut menunjukkan bagaimana API Gateway menerapkan aturan perutean sebelumnya ke permintaan contoh.
| Permintaan | API yang dipilih | Penjelasan |
| --- | --- | --- |
| `https://a.example.com` | Target API 1 | `Host`Header adalah`a.example.com`. Permintaan ini cocok dengan aturan `abc123` routing. |
| `https://b.example.com` | Target API 2 | `Host`Header adalah`b.example.com`. Permintaan ini cocok dengan aturan `000zzz` routing. |
| `https://testing.example.com` | Target API 3 | Ini cocok dengan aturan perutean catch-all. `efg456` |
# Cara menggunakan aturan routing
Anda dapat membuat aturan perutean menggunakan Konsol Manajemen AWS, AWS CLI, atau AWS SDK apa pun. Setelah Anda membuat aturan, Anda dapat mengubah prioritasnya.
## Buat aturan perutean
Prosedur berikut menunjukkan cara membuat aturan routing untuk nama domain kustom dengan mode routing diatur ke salah satu atau`ROUTING_RULE_THEN_API_MAPPING`. `ROUTING_RULE_ONLY`
------
#### [ Konsol Manajemen AWS ]
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus** dari panel navigasi utama.
1. Pilih nama domain khusus.
1. Pada tab **Routing details**, pilih **Add routing rule.**
1. Pilih **Tambahkan kondisi baru** untuk menambahkan kondisi baru.
Anda dapat menambahkan header atau kondisi jalur dasar. Untuk mencocokkan semua permintaan yang masuk dengan nama domain kustom Anda, jangan tambahkan kondisi.
1. Untuk **Action**, gunakan dropdown untuk memilih API target dan tahap target Anda.
1. Pilih **Berikutnya**.
1. Di bidang prioritas, masukkan nomor untuk prioritas Anda.
API Gateway mengevaluasi aturan dalam urutan prioritas, dari nilai terendah hingga nilai tertinggi.
Jika Anda membuat aturan tanpa syarat, kami sarankan Anda menggunakan prioritas nilai tinggi.
1. Pilih **Buat aturan perutean**.
------
#### [ AWS CLI ]
[create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html)Perintah berikut membuat aturan routing dengan prioritas 50. Dalam contoh ini, API Gateway merutekan permintaan masuk yang memiliki header `Hello:World` dan `x-version:beta` dan jalur dasar `PetStoreShopper` ke API target. `a1b2c3`
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
Outputnya akan terlihat seperti berikut ini.
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## Mengubah prioritas aturan routing
Anda dapat mengubah prioritas aturan routing. Ini segera berlaku dan mungkin memengaruhi cara konsumen API memanggil nama domain kustom Anda. Kami menyarankan bahwa ketika Anda menetapkan prioritas aturan routing Anda, Anda meninggalkan kesenjangan di antara aturan.
Misalnya, pertimbangkan dua aturan routing, aturan `abc123` dengan prioritas 50 dan aturan `zzz000` dengan prioritas 150. Untuk mengubah prioritas aturan agar API Gateway mengevaluasi aturan `zzz000` terlebih dahulu, Anda dapat mengubah prioritas aturan `zzz000` menjadi 30.
------
#### [ Konsol Manajemen AWS ]
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus** dari panel navigasi utama.
1. Pilih nama domain khusus.
1. **Pada tab **Routing details**, pilih aturan routing Anda, lalu pilih Edit.**
1. Pilih **Berikutnya**.
1. Untuk prioritas, masukkan prioritas baru.
1. Pilih **Simpan perubahan**.
------
#### [ AWS CLI ]
[put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html)Perintah berikut mengubah prioritas aturan `abc123` routing.
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
Outputnya akan terlihat seperti berikut:
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# Membuat ulang pemetaan API menggunakan aturan perutean
Anda dapat membuat ulang pemetaan API menggunakan aturan perutean. Untuk membuat ulang pemetaan API, pastikan untuk mengaktifkan striping jalur dasar. Ini mempertahankan perilaku pemetaan API. Untuk informasi selengkapnya, lihat [Lepaskan jalur dasar dengan kondisi jalur dasar](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split).
Tutorial berikut menunjukkan cara membuat ulang pemetaan API `https:// api.example.com/orders/v2/items/categories/5` sebagai aturan perutean dan cara memperbarui log akses Anda untuk mencatat aturan perutean ID API Gateway yang digunakan untuk mengirim lalu lintas ke API Anda.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengatur mode perutean ke ROUTING\$1RULE\$1THEN\$1 API\$1MAPPING**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus** dari panel navigasi utama.
1. Pilih nama domain kustom Anda.
1. Untuk **detail Domain**, pilih **Edit**.
1. Untuk **mode Routing**, pilih **API\$1MAPPINGROUTING\$1RULE\$1THEN\$1**.
1. Pilih **Simpan**.
Setelah Anda mengatur mode routing, Anda membuat aturan routing.
**Untuk membuat aturan routing**
1. Pada tab **Routing details**, pilih **Add routing rule.**
1. Pilih **Tambahkan kondisi baru** dan kemudian pilih **Path**.
1. Untuk **Path**, masuk**orders/v2/items/categories/5**.
1. Untuk **jalur dasar Strip**, pilih **Aktif**.
1. Untuk **API Target**, pilih API target Anda.
1. Untuk **tahap Target**, pilih tahap target Anda.
1. Pilih **Berikutnya**.
1. Untuk prioritas, masukkan prioritas.
Bahkan jika Anda mempertahankan pemetaan API yang ada, API Gateway akan selalu menggunakan aturan perutean baru karena aturan perutean selalu diprioritaskan daripada pemetaan API.
1. Pilih **Simpan perubahan**.
Setelah Anda membuat aturan perutean, perbarui format log akses untuk tahap Anda atau buat log baru untuk mengonfirmasi bahwa API Gateway menggunakan aturan perutean Anda untuk mengirim lalu lintas ke API Anda.
**Untuk memperbarui log akses Anda**
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih API Anda.
1. Di panel navigasi utama, pilih **Tahapan**.
1. Untuk **Log dan penelusuran**, pilih **Edit**.
Jika Anda tidak memiliki grup log, lihat[Siapkan CloudWatch logging untuk REST APIs di API Gateway](set-up-logging.md).
1. Tambahkan **\$1context.customDomain.routingRuleIdMatched** ke format log Anda.
Grup log ini mencatat ID aturan perutean yang digunakan API Gateway untuk mengirim lalu lintas ke API Anda. Untuk informasi selengkapnya, lihat [Saya tidak tahu bagaimana API Gateway mengirim lalu lintas ke saya APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
1. Pilih **Simpan**.
Setelah memperbarui log akses, panggil nama domain kustom Anda. Berikut ini adalah contoh perintah curl untuk memanggil nama domain kustom `https://api.example.com` dengan jalur dasar. `orders/v2/items/categories/5`
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
Setelah Anda berhasil memanggil nama domain kustom Anda, konfirmasikan bahwa CloudWatch Log menunjukkan. `routingRuleIdMatched` Untuk mempelajari cara menggunakan konsol CloudWatch Log untuk melihat grup log, lihat[Melihat peristiwa log API Gateway di CloudWatch konsol](view-cloudwatch-log-events-in-cloudwatch-console.md).
------
#### [ AWS CLI ]
1. Gunakan [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)perintah berikut untuk memperbarui nama domain `api.example.com` untuk menggunakan mode `ROUTING_RULE_THEN_API_MAPPING` routing.
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. Gunakan [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html)perintah berikut untuk membuat aturan routing baru untuk membuat ulang pemetaan API. `https://api.example.com/orders/v2/items/categories/5`
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. Gunakan perintah [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) berikut untuk memperbarui format log akses untuk menyertakan variabel. `$context.customDomain.routingRuleIdMatched` Variabel ini mencatat ID aturan perutean yang digunakan API Gateway untuk mengirim lalu lintas ke API Anda. Anda menggunakan log ini untuk mengonfirmasi bahwa API Gateway menggunakan aturan perutean Anda untuk mengirim lalu lintas ke API Anda. Untuk informasi selengkapnya, lihat [Saya tidak tahu bagaimana API Gateway mengirim lalu lintas ke saya APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
Jika Anda tidak memiliki grup log, lihat[Siapkan CloudWatch logging untuk REST APIs di API Gateway](set-up-logging.md).
1. Gunakan contoh perintah curl berikut untuk memanggil nama domain kustom Anda dengan jalur dasar. `orders/v2/items/categories/5`
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. Gunakan [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html)perintah berikut untuk mendapatkan peristiwa log dari grup log `access-log-group-orders` yang berisi ID `abc123` aturan routing.
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
Ini mengonfirmasi bahwa API Gateway menggunakan aturan perutean untuk mengirim lalu lintas ke API Anda.
------
# Memecahkan masalah dengan aturan perutean
Panduan pemecahan masalah berikut dapat membantu menyelesaikan masalah dengan aturan perutean Anda.
## Saya tidak tahu bagaimana API Gateway mengirim lalu lintas ke saya APIs
Anda dapat menggunakan log akses untuk tahap REST API untuk mencatat dan memecahkan masalah aturan perutean Anda. Anda dapat melihat ID aturan perutean yang digunakan API Gateway untuk mengirim lalu lintas ke API menggunakan `$context.customDomain.routingRuleIdMatched` variabel. Untuk melihat pemetaan API yang digunakan API Gateway untuk mengirim lalu lintas ke API Anda, gunakan `$context.customDomain.basePathMatched` variabel tersebut.
Untuk mencatat aturan perutean, Anda perlu mengonfigurasi ARN [peran CloudWatch Log yang sesuai](set-up-logging.md#set-up-access-logging-permissions) untuk akun Anda dan membuat grup log.
Contoh grup log akses berikut dapat mengambil informasi yang relevan untuk memecahkan masalah aturan perutean dan pemetaan API. API Gateway hanya mengisi variabel konteks untuk mekanisme perutean yang digunakannya, jika tidak, variabel konteksnya. `-`
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
Kami juga menyarankan Anda mengonfirmasi mode perutean untuk nama domain kustom Anda. Untuk informasi selengkapnya, lihat [Mengatur mode routing untuk nama domain kustom Anda](set-routing-mode.md).
## Saya tidak dapat mengaktifkan aturan perutean pada nama domain khusus saya
Anda mungkin menerima error berikut dari API Gateway:
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
Anda akan menerima kesalahan ini jika memiliki atau memiliki kebijakan IAM yang menolak akses ke [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies)atau. [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies) Bila Anda mengaktifkan aturan perutean untuk nama domain kustom, meskipun kebijakan Anda akan terus menolak akses ke `BasePathMapping` atau`ApiMapping`, kebijakan yang sama dapat digunakan untuk mengakses`RoutingRule`. Ini mungkin memungkinkan pengguna untuk mengubah perilaku perutean nama domain kustom Anda.
Misalnya, jika Anda memiliki kebijakan seperti berikut:
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
Saat Anda mengaktifkan aturan perutean`example.com`, kebijakan ini akan terus menolak akses untuk membuat `ApiMapping` tetapi tidak akan menolak akses untuk membuat `RoutingRule` file.
Kami menyarankan Anda mengaudit kebijakan IAM di akun Anda. Contoh kebijakan berikut akan menolak akses untuk membuat`ApiMapping`,`BasePathMapping`, dan`RoutingRule`:
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
Setelah mengonfirmasi bahwa semua kebijakan telah diperbarui, Anda dapat memperbarui setelan tingkat akun API untuk mengaktifkan aturan perutean untuk Wilayah.
Gunakan perintah [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) berikut untuk memperbarui setelan setelan tingkat akun API Anda untuk Wilayah:
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
Setelah memperbarui setelan tingkat akun API, Anda dapat mengubah mode perutean nama domain kustom Anda. Anda juga dapat terus menggunakan kebijakan IAM untuk menolak akses ke`RoutingRules`, `ApiMapping` atau`BasePathMapping`.
# Gunakan pemetaan API untuk menghubungkan tahapan API ke nama domain khusus untuk REST APIs
Anda menggunakan pemetaan API untuk menghubungkan tahapan API ke nama domain kustom. Ini mengirimkan lalu lintas ke Anda APIs melalui nama domain kustom Anda.
Pemetaan API menentukan API, tahap, dan jalur opsional yang akan digunakan untuk pemetaan. Misalnya, Anda dapat `https://api.example.com/orders` memetakan ke `production` tahap API.
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 selengkapnya tentang membuat nama domain kustom, lihat[Siapkan nama domain kustom Regional di API Gateway](apigateway-regional-api-custom-domain-create.md).
## Permintaan masuk ke nama domain kustom Anda
Saat Anda memetakan nama domain kustom ke tahap API Anda, API Gateway menghapus jalur dasar yang masuk. Ini menghapus jalur dasar yang dipetakan dari pemanggilan ke API. Misalnya, jika pemetaan jalur dasar Anda `https://api.example.com/orders/shop/5` ke `test` panggung, dan Anda menggunakan permintaan berikut`https://api.example.com/orders/shop/5/hats`, API Gateway akan memanggil `/hats` sumber daya `test` tahap API Anda, bukan sumber daya. `orders/shop/5/hats`
## Memetakan permintaan API
Berikut ini menjelaskan bagaimana API Gateway mengevaluasi pemetaan API.
Anda dapat membuat pemetaan API menggunakan pemetaan tingkat tunggal, seperti pemetaan API dari `orders` `beta` tahap API dan pemetaan API dari `shipping` tahap API. `alpha` Untuk nama domain kustom Regional dengan kebijakan keamanan TLS 1.2, API Gateway mendukung pemetaan API multi-level. Anda dapat membuat pemetaan API dari `orders/v1/items` `alpha` tahap API dan `orders/v2/items` ke `beta` tahap API. Saat Anda membuat pemetaan dengan beberapa level, API Gateway mengirimkan permintaan ke pemetaan API yang memiliki jalur pencocokan terpanjang.
Anda dapat membuat pemetaan API ke jalur `(none)` kosong. Jika tidak ada jalur yang cocok dengan permintaan, API Gateway mengirimkan permintaan ke jalur kosong`(none)`.
Dalam contoh ini, nama domain kustom `https://api.example.com` memiliki pemetaan API berikut.
| Pemetaan API | API yang dipilih |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
Tabel berikut menunjukkan bagaimana API Gateway menerapkan pemetaan API sebelumnya ke permintaan contoh.
| 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. Lihat [Permintaan masuk ke nama domain kustom Anda](#rest-api-mappings-incoming-requests). |
| `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.
+ Setelah membuat pemetaan API, Anda harus membuat atau memperbarui catatan sumber daya penyedia DNS untuk dipetakan ke titik akhir API Anda.
+ 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. Nama domain kustom Anda harus memiliki mode routing yang disetel ke salah satu `ROUTING_RULE_THEN_API_MAPPING` atau`API_MAPPING_ONLY`. Untuk informasi tentang cara mengatur mode perutean, lihat[Mengatur mode routing untuk nama domain kustom Anda](set-routing-mode.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 ]
1. Masuk ke konsol API Gateway di [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Pilih **Nama domain khusus** dari panel navigasi utama.
1. Pilih nama domain khusus.
1. Pada tab **Routing details**, pilih **Configure API mappings**.
1. Masukkan **API**, **Stage**, dan **Path** untuk pemetaan.
1. Pilih **Simpan**.
------
#### [ AWS CLI ]
[create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html)Perintah berikut membuat pemetaan API. Dalam contoh ini, API Gateway mengirimkan permintaan `api.example.com/v1/orders` ke API dan tahap yang ditentukan.
**catatan**
Untuk membuat pemetaan API dengan beberapa level, Anda harus menggunakan. `apigatewayv2`
```
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.
**catatan**
Untuk membuat pemetaan API dengan beberapa level, Anda harus menggunakan. `AWS::ApiGatewayV2`
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------