Dukungan fitur API Gateway Format Permintaan Autentikasi dan otorisasi Pola integrasi layanan Format output Penanganan kesalahan

Panggil API Gateway dengan Step Functions

Step Functions dapat mengontrol AWS layanan tertentu langsung dari Amazon States Language (ASL). Untuk mempelajari selengkapnya, lihat Bekerja dengan layanan yang lain dan Meneruskan parameter ke API layanan.

Bagaimana integrasi API Gateway yang Dioptimalkan berbeda dari integrasi API Gateway AWS SDK

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.

Anda dapat menggunakan Amazon API Gateway untuk membuat, menerbitkan, memelihara, dan memantau API HTTP dan REST. 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.

catatan

Step Functions mendukung kemampuan untuk memanggil titik akhir HTTP melalui API Gateway, tetapi saat ini tidak mendukung kemampuan untuk memanggil titik akhir HTTP generik.

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), 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 API yang dioptimalkan Edge tidak didukung.
Tidak didukung oleh integrasi API Gateway Step Functions:
- Pengotorisasi: Amazon Cognito, Native Open ID Connect/OAuth 2.0, header Otorisasi untuk pengotorisasi Lambda berbasis token
- Tipe API: Privat
- Manajemen API: Nama domain kustom

Untuk informasi selengkapnya tentang API Gateway dan API HTTP dan REST, lihat berikut ini.

Halaman Konsep Amazon API Gateway.
Memilih antara API HTTP dan API REST di panduan developer 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 <API ID>.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
- Tipe: BOOLEAN
- Pengaturan AllowNullValues ke true akan memungkinkan Anda untuk meneruskan nilai null seperti berikut ini:
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "name": null
    }
}
```
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", 
    "Parameters": {
        "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 (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.
2. Step Functions itu adalah layanan memanggil API Gateway: "Service": "states.amazonaws.com".
3. Sumber daya yang ingin Anda akses, termasuk:
  - Wilayah.
  - account-id di wilayah yang ditentukan.
  - api-id.
  - stage-name.
  - HTTP-VERB (metode).
  - The resource-path-specifier.
Untuk contoh kebijakan sumber daya, lihat kebijakan IAM untuk Step Functions dan API Gateway.

Untuk informasi lebih lanjut tentang format sumber daya, lihat Format sumber daya dari izin untuk mengeksekusi API di API Gateway 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, yang merupakan pola integrasi default. Ini memungkinkan Step Functions maju ke langkah berikutnya segera setelah menerima respons HTTP.

Tunggu Panggilan Balik dengan Token Tugas (.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", 
    "Parameters": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "POST", 
        "Headers": { 
            "TaskToken.$": "States.Array($$.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.<HTTP Status Code>.
Jika kode status HTTP tidak tersedia, kesalahan akan dikembalikan dalam format ApiGateway.<Exception>.

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.

Untuk informasi selengkapnya, lihat:

Konsep Amazon API Gateway dalam Panduan Developer API Gateway.
Kebijakan IAM untuk Amazon API Gateway
Contoh proyek yang menunjukkan cara Buat panggilan ke API Gateway

Konsep Amazon API Gateway dalam Panduan Developer API Gateway.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Integrasi yang dioptimalkan

Amazon Athena

Panggil API Gateway dengan Step Functions

Bagaimana integrasi API Gateway yang Dioptimalkan berbeda dari integrasi API Gateway AWS SDK

catatan

Dukungan fitur API Gateway

Format Permintaan

Parameter permintaan yang dibutuhkan

Parameter permintaan opsional.

catatan

Autentikasi dan otorisasi

penting

catatan

Pola integrasi layanan

Format output

Penanganan kesalahan

catatan