Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Buat API Gateway REST APIs dengan Step Functions
Pelajari cara menggunakan Amazon API Gateway untuk membuat, menerbitkan, memelihara, dan memantau HTTP dan REST APIs dengan Step Functions. Untuk mengintegrasikan dengan API Gateway, Anda menentukan status `Task` di Step Functions yang langsung memanggil HTTP API Gateway atau titik akhir REST API Gateway, tanpa menulis kode atau mengandalkan infrastruktur lainnya. Ketentuan status `Task` mencakup semua informasi yang diperlukan untuk panggilan API. Anda juga dapat memilih metode otorisasi yang berbeda.
Untuk mempelajari tentang mengintegrasikan dengan AWS layanan di Step Functions, lihat [Integrasi layanan ](integrate-services.md) dan[Meneruskan parameter ke API layanan di Step Functions](connect-parameters.md).
**Fitur utama integrasi API Gateway yang Dioptimalkan**
`apigateway:invoke:`tidak memiliki padanan dalam integrasi layanan AWS SDK. Sebagai gantinya, layanan API Gateway yang Dioptimalkan memanggil titik akhir API Gateway Anda secara langsung.
## Dukungan fitur API Gateway
Integrasi API Gateway Step Functions mendukung beberapa, tetapi tidak semua fitur API Gateway. Untuk daftar lebih detail fitur yang didukung, lihat berikut ini.
+ Didukung oleh kedua integrasi API REST API Gateway Step Functions dan API HTTP API Gateway:
+ **Pengotorisasi**: IAM (menggunakan [Versi Tanda Tangan 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)), Tidak ada Otorisasi, Pengotorisasi Lambda (berbasis parameter permintaan dan berbasis token dengan header kustom)
+ **Tipe API**: Wilayah
+ **Manajemen API**: Nama domain API Gateway API, tahap API, Jalur, Parameter Kueri, Isi Permintaan
+ Didukung oleh integrasi API Step Functions API Gateway HTTP. Integrasi Step Functions API Gateway REST API yang menyediakan opsi untuk dioptimalkan EDGE tidak APIs didukung.
+ Tidak didukung oleh integrasi API Gateway Step Functions:
+ **Authorizer**: Amazon Cognito, Native Open ID Connect OAuth /2.0, Header otorisasi untuk otorisasi Lambda berbasis token
+ **Tipe API**: Privat
+ **Manajemen API**: Nama domain kustom
Untuk informasi selengkapnya tentang API Gateway dan HTTP dan REST APIs, lihat berikut ini.
+ Halaman [Konsep Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html).
+ [Memilih antara HTTP APIs dan REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) dalam panduan pengembang API Gateway.
## Format Permintaan
Saat Anda membuat ketentuan status `Task`, Step Functions memvalidasi parameter, membangun URL yang diperlukan untuk melakukan panggilan, kemudian memanggil API. Respons meliputi kode status HTTP, header dan isi respons. Format permintaan memiliki parameter yang diperlukan dan opsional.
### Parameter permintaan yang dibutuhkan
+ `ApiEndpoint`
+ Tipe: `String`
+ Nama host dari URL API Gateway. Formatnya adalah `{{}}.execute-api.{{region}}.amazonaws.com`.
ID API hanya dapat berisi kombinasi karakter alfanumerik berikut ini: `0123456789abcdefghijklmnopqrstuvwxyz`
+ `Method`
+ Tipe: `Enum`
+ Metode HTTP, yang harus berupa salah satu dari berikut:
+ `GET`
+ `POST`
+ `PUT`
+ `DELETE`
+ `PATCH`
+ `HEAD`
+ `OPTIONS`
### Parameter permintaan opsional.
+ `Headers`
+ Tipe: `JSON`
+ Header HTTP mengizinkan daftar nilai yang terkait dengan kunci yang sama.
+ `Stage`
+ Tipe: `String`
+ Nama tahap tempat API di-deploy ke dalam API Gateway. Ini opsional untuk API HTTP yang menggunakan tahap `$default`.
+ `Path`
+ Tipe: `String`
+ Parameter jalur yang ditambahkan setelah titik akhir API.
+ `QueryParameters`
+ Tipe: `JSON`
+ String kueri hanya mengizinkan daftar nilai yang terkait dengan kunci yang sama.
+ `RequestBody`
+ Tipe: `JSON` atau `String`
+ Isi Permintaan HTTP. Tipenya bisa berupa objek `JSON` atau `String`. `RequestBody` hanya didukung untuk `PATCH`, `POST`, dan metode HTTP `PUT`.
+ `AllowNullValues`
+ Jenis: `BOOLEAN` — nilai default: `false`
+ Dengan pengaturan default, nilai **null** apa pun dalam status input permintaan **tidak** akan dikirim ke API Anda. Dalam contoh berikut, `category` bidang **tidak** akan disertakan dalam permintaan, kecuali `AllowNullValues` diatur ke `true` dalam definisi mesin status Anda.
```
{
"NewPet": {
"type": "turtle",
"price": 123,
"category": null
}
}
```
**catatan**
Secara default, bidang dengan nilai **null** dalam status input permintaan **tidak** akan dikirim ke API Anda. Anda dapat memaksa nilai null untuk dikirim ke API Anda dengan menyetel `AllowNullValues` ke `true` dalam definisi mesin status Anda.
+ `AuthType`
+ Tipe: `JSON`
+ Metode autentikasi. Metode default adalah `NO_AUTH`. Nilai yang diizinkan adalah:
+ `NO_AUTH`
+ `IAM_ROLE`
+ `RESOURCE_POLICY`
Lihat **Autentikasi dan otorisasi** untuk informasi lebih lanjut.
**catatan**
Untuk pertimbangan keamanan, kunci header HTTP berikut ini tidak diizinkan:
Apa pun berprefiks `X-Forwarded`, `X-Amz` atau `X-Amzn`.
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`
Contoh kode berikut menunjukkan cara memanggil API Gateway menggunakan Step Functions.
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "GET",
"Headers": {
"key": ["value1", "value2"]
},
"Stage": "prod",
"Path": "bills",
"QueryParameters": {
"billId": ["123456"]
},
"RequestBody": {},
"AuthType": "NO_AUTH"
}
}
```
## Autentikasi dan otorisasi
Anda dapat menggunakan metode autentikasi berikut:
+ **Tidak ada otorisasi**: Panggil API secara langsung tanpa metode otorisasi.
+ **IAM role**: Dengan metode ini, Step Functions menggunakan peran mesin status, menandatangani permintaan dengan [Versi Tanda Tangan 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (SigV4), lalu memanggil API.
+ **Kebijakan sumber daya**: Step Functions mengautentikasi permintaan, dan kemudian memanggil API. Anda harus melampirkan kebijakan sumber daya ke API yang menentukan berikut ini:
1. Mesin status yang akan memanggil API Gateway.
**penting**
Anda harus menentukan mesin status Anda untuk membatasi akses ke sana. Jika Anda tidak, setiap mesin status yang mengautentikasi permintaan API Gateway dengan autentikasi **Kebijakan sumber daya** ke API Anda akan diberikan akses.
1. Step Functions itu adalah layanan memanggil API Gateway: `"Service": "states.amazonaws.com"`.
1. Sumber daya yang ingin Anda akses, termasuk:
+ Itu{{region}}.
+ {{account-id}}Di wilayah yang ditentukan.
+ Itu{{api-id}}.
+ Itu{{stage-name}}.
+ {{HTTP-VERB}}(Metode).
+ Itu{{resource-path-specifier}}.
Untuk contoh kebijakan sumber daya, lihat [kebijakan IAM untuk Step Functions dan API Gateway](#api-gateway-iam).
Untuk informasi lebih lanjut tentang format sumber daya, lihat [Format sumber daya dari izin untuk mengeksekusi API di API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api) dalam Panduan Developer API Gateway.
**catatan**
Kebijakan sumber daya hanya didukung untuk API REST.
## Pola integrasi layanan
Integrasi API Gateway mendukung dua pola integrasi layanan:
+ [Minta Tanggapan](connect-to-resource.md#connect-default), yang merupakan pola integrasi default. Ini memungkinkan Step Functions maju ke langkah berikutnya segera setelah menerima respons HTTP.
+ [Tunggu Callback dengan Task Token](connect-to-resource.md#connect-wait-token) (`.waitForTaskToken`), yang menunggu sampai token tugas dikembalikan dengan muatan. Untuk menggunakan `.waitForTaskToken` pola, tambahkan. waitForTaskToken ke akhir bidang **Sumber daya** definisi tugas Anda seperti yang ditunjukkan pada contoh berikut:
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "POST",
"Headers": {
"TaskToken": "{% $states.context.Task.Token %}"
},
"Stage": "prod",
"Path": "bills/add",
"QueryParameters": {},
"RequestBody": {
"billId": "my-new-bill"
},
"AuthType": "IAM_ROLE"
}
}
```
## Format output
Parameter output berikut disediakan:
| Nama | Tipe | Deskripsi |
| --- | --- | --- |
| ResponseBody | JSON atau String | Isi respons dari panggilan API. |
| Headers | JSON | Header respons |
| StatusCode | Integer | Kode status HTTP dari respons. |
| StatusText | String | Teks status respons. |
Contoh respons
```
{
"ResponseBody": {
"myBills": []
},
"Headers": {
"key": ["value1", "value2"]
},
"StatusCode": 200,
"StatusText": "OK"
}
```
## Penanganan kesalahan
Ketika terjadi kesalahan, `error` dan `cause` dikembalikan sebagai berikut:
+ Jika kode status HTTP tersedia, kesalahan akan dikembalikan dalam format `ApiGateway.{{}}`.
+ Jika kode status HTTP tidak tersedia, kesalahan akan dikembalikan dalam format `ApiGateway.{{}}`.
Dalam kedua kasus, `cause` dikembalikan sebagai string.
Contoh berikut menunjukkan respons tempat kesalahan telah terjadi:
```
{
"error": "ApiGateway.403",
"cause": "{\"message\":\"Missing Authentication Token\"}"
}
```
**catatan**
Kode status `2XX` menunjukkan keberhasilan, dan tidak ada kesalahan yang dikembalikan. Semua kode status lain atau pengecualian yang dibuang akan mengakibatkan kesalahan.
## Kebijakan IAM untuk panggilan ke Amazon API Gateway
Contoh templat berikut menunjukkan cara AWS Step Functions menghasilkan kebijakan IAM berdasarkan sumber daya dalam definisi mesin status Anda. Untuk informasi selengkapnya, lihat [Bagaimana Step Functions menghasilkan kebijakan IAM untuk layanan terintegrasi](service-integration-iam-templates.md) dan [Temukan pola integrasi layanan di Step Functions](connect-to-resource.md).
*Sumber Daya:*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/GET/pets",
"arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/POST/pets"
],
"Effect": "Allow"
}
]
}
```
Contoh kode berikut ini menunjukkan kebijakan sumber daya untuk memanggil API Gateway.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "states.amazonaws.com"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:myApi-id/{{stage-name}}/{{HTTP-VERB}}/{{resource-path-specifier}}",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
"{{}}"
]
}
}
}
]
}
```