Buat API Gateway REST APIs dengan Step Functions - AWS Step Functions
APIDukungan fitur gatewayFormat permintaanAutentikasi dan otorisasiPola integrasi layananFormat outputPenanganan kesalahanKebijakan IAM

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, HTTP dan memantau serta REST APIs dengan Step Functions. Untuk berintegrasi dengan API Gateway, Anda menentukan Task status di Step Functions yang secara langsung memanggil REST titik akhir API API Gateway HTTP atau Gateway, tanpa menulis kode atau mengandalkan infrastruktur lain. Definisi Task negara mencakup semua informasi yang diperlukan untuk API panggilan tersebut. Anda juga dapat memilih metode otorisasi yang berbeda.

Untuk mempelajari tentang mengintegrasikan dengan AWS layanan di Step Functions, lihat Integrasi layanan danMeneruskan parameter ke layanan API di Step Functions.

Fitur utama integrasi API Gateway yang Dioptimalkan

  • apigateway:invoke:tidak memiliki padanan dalam integrasi AWS SDK layanan. Sebagai gantinya, layanan API Gateway yang Dioptimalkan memanggil titik akhir API Gateway Anda secara langsung.

APIDukungan fitur gateway

Integrasi Step Functions API Gateway mendukung beberapa, tetapi tidak semua fitur API Gateway. Untuk daftar lebih detail fitur yang didukung, lihat berikut ini.

  • Didukung oleh HTTP API integrasi Step Functions API API Gateway REST API dan Gateway:

    • Authorizer: IAM (menggunakan Signature Version 4), No Auth, Lambda Authorizers (berbasis parameter permintaan dan berbasis token dengan header khusus)

    • APIjenis: Regional

    • APImanajemen: Nama API domain API Gateway, API panggung, Jalur, Parameter Kueri, Badan Permintaan

  • Didukung oleh HTTP API integrasi Step Functions API Gateway. RESTAPIIntegrasi Step Functions API Gateway yang menyediakan opsi untuk dioptimalkan Edge tidak APIs didukung.

  • Tidak didukung oleh integrasi Step Functions API Gateway:

    • Authorizer: Amazon Cognito, Native Open ID ConnectOAuth/2.0, Header otorisasi untuk otorisasi Lambda berbasis token

    • APIjenis: Pribadi

    • APImanajemen: Nama domain khusus

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

Format permintaan

Saat Anda membuat definisi Task status, Step Functions memvalidasi parameter, membangun yang diperlukan URL untuk melakukan panggilan, lalu memanggil. API Responsnya mencakup kode HTTP status, header, dan badan respons. Format permintaan memiliki parameter yang diperlukan dan opsional.

Parameter permintaan yang dibutuhkan

  • ApiEndpoint

    • Tipe: String

    • Nama host dari API GatewayURL. Formatnya adalah <API ID>.execute-api.<region>.amazonaws.com.

      APIID hanya dapat berisi kombinasi karakter alfanumerik berikut: 0123456789abcdefghijklmnopqrstuvwxyz

  • Method

    • Tipe: Enum

    • HTTPMetode, yang harus menjadi salah satu dari berikut ini:

      • GET

      • POST

      • PUT

      • DELETE

      • PATCH

      • HEAD

      • OPTIONS

Parameter permintaan opsional.

  • Headers

    • Tipe: JSON

    • HTTPheader memungkinkan daftar nilai yang terkait dengan kunci yang sama.

  • Stage

    • Tipe: String

    • Nama tahap di mana API digunakan di API Gateway. Ini opsional untuk semua HTTP API yang menggunakan $default panggung.

  • Path

    • Tipe: String

    • Parameter jalur yang ditambahkan setelah titik API akhir.

  • QueryParameters

    • Tipe: JSON

    • String kueri hanya mengizinkan daftar nilai yang terkait dengan kunci yang sama.

  • RequestBody

    • Tipe: JSON atau String

    • Badan HTTP Permintaan. Jenisnya bisa berupa JSON objek atauString. RequestBodyhanya didukung untukPATCH,POST, dan PUT HTTP metode.

  • AllowNullValues

    • Jenis: BOOLEAN — nilai default: false

    • Dengan pengaturan default, nilai null apa pun dalam status input permintaan tidak akan dikirim ke AndaAPI. 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 AndaAPI. Anda dapat memaksa nilai null untuk dikirim ke Anda API 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 HTTP header berikut saat 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:

  • Tanpa otorisasi: Panggil API langsung tanpa metode otorisasi.

  • IAMrole: Dengan metode ini, Step Functions mengasumsikan peran mesin state, menandatangani permintaan dengan Signature Version 4 (SigV4), lalu memanggil file. API

  • Kebijakan sumber daya: Step Functions mengautentikasi permintaan, lalu memanggil file. API Anda harus melampirkan kebijakan sumber daya API yang menentukan hal berikut:

    1. Mesin negara yang akan memanggil API Gateway.

      penting

      Anda harus menentukan mesin status Anda untuk membatasi akses ke sana. Jika tidak, maka mesin status apa pun yang mengautentikasi permintaan API Gateway dengan otentikasi kebijakan Sumber Daya ke Anda API akan diberikan akses.

    2. Step Functions itu adalah layanan yang memanggil API Gateway:"Service": "states.amazonaws.com".

    3. Sumber daya yang ingin Anda akses, termasuk:

      • Theregion.

      • account-idDi wilayah yang ditentukan.

      • Theapi-id.

      • Thestage-name.

      • HTTP-VERB(Metode).

      • Theresource-path-specifier.

    Untuk contoh kebijakan sumber daya, lihat IAMkebijakan untuk Step Functions dan API Gateway.

    Untuk informasi selengkapnya tentang format sumber daya, lihat Format sumber izin untuk mengeksekusi API di API Gateway dalam Panduan Pengembang API Gateway.

    catatan

    Kebijakan sumber daya hanya didukung untuk RESTAPI.

Pola integrasi layanan

Integrasi API Gateway mendukung dua pola integrasi layanan:

  • Minta Respons, yang merupakan pola integrasi default. Ini memungkinkan Step Functions maju ke langkah berikutnya segera setelah menerima HTTP respons.

  • Tunggu Callback dengan Task 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", 
    "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 Badan respons API panggilan.
Headers JSON Header respons
StatusCode Integer Kode HTTP status 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 HTTP status tersedia, maka kesalahan akan dikembalikan dalam formatApiGateway.<HTTP Status Code>.

  • Jika kode HTTP status tidak tersedia, maka kesalahan akan dikembalikan dalam formatApiGateway.<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.

IAMkebijakan untuk panggilan ke Amazon API Gateway

Contoh templat berikut menunjukkan cara AWS Step Functions menghasilkan IAM kebijakan berdasarkan sumber daya dalam definisi mesin status Anda. Untuk informasi selengkapnya, silakan lihat Bagaimana Step Functions menghasilkan IAM kebijakan untuk layanan terintegrasi dan Temukan pola integrasi layanan di Step Functions.

Sumber Daya:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:[[region]]:[[accountId]]:*"
            ]
        }
    ]
}

Contoh kode berikut 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:<region>:<account-id>:<api-id>/<stage-name>/<HTTP-VERB>/<resource-path-specifier>",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": [
                        "<SourceStateMachineArn>"
                    ]
                }
            }
        }
    ]
}