Panggil HTTPS APIs dalam alur kerja Step Functions

Tugas HTTP adalah jenis Status alur kerja tugas status yang memungkinkan Anda memanggil API HTTPS dalam alur kerja Anda. API dapat bersifat publik, seperti aplikasi SaaS pihak ketiga seperti Stripe atau Salesforce. Anda juga dapat memanggil API pribadi, seperti aplikasi berbasis HTTP di Amazon Virtual Private Cloud.

Untuk otorisasi dan konektivitas jaringan, Tugas HTTP memerlukan EventBridge koneksi.

Untuk memanggil API HTTPS, gunakan status Tugas dengan arn:aws:states:::http:invoke sumber daya. Kemudian, berikan detail konfigurasi titik akhir API, seperti URL API, metode yang ingin Anda gunakan, dan detail koneksi.

Jika Anda menggunakan Workflow Studio untuk membangun mesin status yang berisi Tugas HTTP, Workflow Studio akan secara otomatis menghasilkan peran eksekusi IAM kebijakan untuk Tugas HTTP. Untuk informasi selengkapnya, lihat Peran untuk menguji Tugas HTTP di Workflow Studio.

Konektivitas untuk Tugas HTTP

Tugas HTTP memerlukan EventBridgekoneksi, yang mengelola kredensi otentikasi penyedia API dengan aman. Koneksi mendefinisikan metode otorisasi dan kredensi yang akan digunakan dalam menghubungkan ke API tertentu. Jika Anda terhubung ke API pribadi, seperti API pribadi di Amazon Virtual Private Cloud (Amazon VPC), Anda juga dapat menggunakan koneksi untuk menentukan konektivitas point-to-point jaringan yang aman. Menggunakan koneksi membantu Anda menghindari rahasia hard-coding, seperti kunci API, ke dalam definisi mesin status Anda. EventBridge Koneksi mendukung skema otorisasi Basic OAuth, dan API Key.

Saat Anda membuat EventBridge koneksi, Anda memberikan otorisasi dan detail konektivitas jaringan Anda. Anda juga dapat menyertakan parameter header, body, dan query yang diperlukan untuk otorisasi dengan API. Anda harus menyertakan ARN koneksi dalam Tugas HTTP apa pun yang memanggil API HTTPS.

Saat Anda membuat koneksi, EventBridge buat rahasia di AWS Secrets Manager. Dalam rahasia ini, EventBridge menyimpan parameter koneksi dan otorisasi dalam bentuk terenkripsi. Agar berhasil membuat atau memperbarui koneksi, Anda harus menggunakan Secrets Manager Akun AWS yang memiliki izin untuk menggunakan Secrets Manager. Untuk informasi lebih lanjut tentang IAM izin yang dibutuhkan mesin status Anda untuk mengakses EventBridge koneksi, lihatIzin IAM untuk menjalankan Tugas HTTP.

Gambar berikut menunjukkan bagaimana Step Functions menangani otorisasi untuk panggilan API HTTPS menggunakan EventBridge koneksi. Bagian EventBridge koneksi mengelola kredensyal penyedia API HTTPS. EventBridge menciptakan rahasia di Secrets Manager untuk menyimpan parameter koneksi dan otorisasi dalam bentuk terenkripsi. Dalam kasus pribadi APIs, EventBridge juga menyimpan konfigurasi konektivitas jaringan.

Definisi Tugas HTTP

Definisi ASL mewakili Tugas HTTP dengan http:invoke sumber daya. Definisi HTTP Task berikut memanggil Stripe API publik yang mengembalikan daftar semua pelanggan.

"Call HTTPS API": {
  "Type": "Task",
  "Resource": "arn:aws:states:::http:invoke",
  "Parameters": {
    "ApiEndpoint": "https://api.stripe.com/v1/customers",
    "Authentication": {
      "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

Bidang Tugas HTTP

Tugas HTTP mencakup bidang-bidang berikut dalam definisinya.

Penggabungan EventBridge koneksi dan data definisi Tugas HTTP

Saat Anda memanggil Tugas HTTP, Anda dapat menentukan data di EventBridge koneksi dan definisi Tugas HTTP Anda. Data ini mencakupHeaders,QueryParameters, dan RequestBody parameter. Sebelum memanggil API HTTPS, Step Functions menggabungkan badan permintaan dengan parameter badan koneksi dalam semua kasus kecuali jika badan permintaan Anda adalah string dan parameter badan koneksi tidak kosong. Dalam hal ini, Tugas HTTP gagal dengan States.Runtime kesalahan.

Jika ada kunci duplikat yang ditentukan dalam definisi Tugas HTTP dan EventBridge koneksi, Step Functions menimpa nilai-nilai dalam Tugas HTTP dengan nilai-nilai dalam koneksi.

Daftar berikut menjelaskan bagaimana Step Functions menggabungkan data sebelum memanggil API HTTPS:

Contoh berikut menetapkanHeaders,QueryParameters, dan RequestBody bidang di kedua Tugas HTTP dan EventBridge koneksi.

Definisi Tugas HTTP

{
  "Comment": "Data merging example for HTTP Task and EventBridge connection",
  "StartAt": "ListCustomers",
  "States": {
    "ListCustomers": {
      "Type": "Task",
      "Resource": "arn:aws:states:::http:invoke",
      "Parameters": {
        "Authentication": {
          "ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/Example/81210c42-8af1-456b-9c4a-6ff02fc664ac"
        },
        "ApiEndpoint": "https:/example.com/path",
        "Method": "GET",
        "Headers": {
          "Request-Id": "my_request_id",
          "Header-Param": "state_machine_header_param"
        },
        "RequestBody": {
          "Job": "Software Engineer",
          "Company": "AnyCompany",
          "BodyParam": "state_machine_body_param"
        },
        "QueryParameters": {
          "QueryParam": "state_machine_query_param"
        }
      }
    }
  }
}

EventBridge koneksi

{
  "AuthorizationType": "API_KEY",
  "AuthParameters": {
    "ApiKeyAuthParameters": {
      "ApiKeyName": "ApiKey",
      "ApiKeyValue": "key_value"
    },
    "InvocationHttpParameters": {
      "BodyParameters": [
        {
          "Key": "BodyParam",
          "Value": "connection_body_param"
        }
      ],
      "HeaderParameters": [
        {
          "Key": "Header-Param",
          "Value": "connection_header_param"
        }
      ],
      "QueryStringParameters": [
        {
          "Key": "QueryParam",
          "Value": "connection_query_param"
        }
      ]
    }
  }
}

Dalam contoh ini, kunci duplikat ditentukan dalam Tugas HTTP dan EventBridge koneksi. Oleh karena itu, Step Functions menimpa nilai-nilai dalam Tugas HTTP dengan nilai-nilai dalam koneksi. Cuplikan kode berikut menunjukkan permintaan HTTP yang Step Functions mengirim ke HTTPS API.

POST /path?QueryParam=connection_query_param HTTP/1.1
Apikey: key_value
Content-Length: 79
Content-Type: application/json; charset=UTF-8
Header-Param: connection_header_param
Host: example.com
Range: bytes=0-262144
Request-Id: my_request_id
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}

Menerapkan pengkodean URL pada badan permintaan

Secara default, Step Functions mengirimkan badan permintaan sebagai data JSON ke titik akhir API. Jika penyedia API HTTPS Anda memerlukan badan form-urlencoded permintaan, Anda harus menentukan pengkodean URL untuk badan permintaan. Step Functions kemudian secara otomatis URL-menyandikan badan permintaan berdasarkan opsi pengkodean URL yang Anda pilih.

Anda menentukan pengkodean URL menggunakan bidang. Transform Bidang ini berisi RequestBodyEncoding bidang yang menentukan apakah Anda ingin menerapkan pengkodean URL untuk badan permintaan Anda atau tidak. Saat Anda menentukan RequestBodyEncoding bidang, Step Functions mengonversi badan permintaan JSON Anda menjadi badan form-urlencoded permintaan sebelum memanggil HTTPS API. Anda juga harus menentukan content-type header application/x-www-form-urlencoded karena menerima data APIs yang dikodekan URL mengharapkan header. content-type

Untuk menyandikan array di badan permintaan Anda, Step Functions menyediakan opsi pengkodean array berikut.

Izin IAM untuk menjalankan Tugas HTTP

Peran eksekusi mesin status Anda harus memiliki izin berikut untuk Tugas HTTP untuk memanggil API HTTPS:

Contoh kebijakan IAM berikut memberikan hak istimewa paling sedikit yang diperlukan untuk peran mesin status Anda untuk memanggil Stripe. APIs Kebijakan IAM ini juga memberikan izin ke peran mesin status untuk mengakses EventBridge koneksi tertentu, termasuk rahasia untuk koneksi ini yang disimpan di Secrets Manager.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": "states:InvokeHTTPEndpoint",
            "Resource": "arn:aws:states:us-east-2:123456789012:stateMachine:myStateMachine",
            "Condition": {
                "StringEquals": {
                    "states:HTTPMethod": "GET"
                },
                "StringLike": {
                    "states:HTTPEndpoint": "https://api.stripe.com/*"
                }
            }
        },
        {
            "Sid": "Statement2",
            "Effect": "Allow",
            "Action": [
                "events:RetrieveConnectionCredentials",
            ],
            "Resource": "arn:aws:events:us-east-2:123456789012:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a"
        },
        {
            "Sid": "Statement3",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

Contoh Tugas HTTP

Definisi mesin status berikut menunjukkan Tugas HTTP yang mencakupHeaders,, QueryParametersTransform, dan RequestBody parameter. Tugas HTTP memanggil Stripe API, https://api.stripe.com/v1/ faktur, untuk menghasilkan faktur. Tugas HTTP juga menentukan URL-encoding untuk badan permintaan menggunakan opsi encoding. INDICES

Pastikan bahwa Anda telah membuat sebuah EventBridge koneksi. Contoh berikut menunjukkan koneksi yang dibuat menggunakan jenis autentikasi BASIC.

{
    "Type": "BASIC",
    "AuthParameters": { 
        "BasicAuthParameters": { 
            "Password": "myPassword",
            "Username": "myUsername"
         },
    }
}

Ingatlah untuk mengganti italicized teks dengan informasi spesifik sumber daya Anda.

{
  "Comment": "A state machine that uses HTTP Task",
  "StartAt": "CreateInvoiceAPI",
  "States": {
    "CreateInvoiceAPI": {
      "Type": "Task",
      "Resource": "arn:aws:states:::http:invoke",
      "Parameters": {
        "ApiEndpoint": "https://api.stripe.com/v1/invoices",
        "Method": "POST",
        "Authentication": {
          "ConnectionArn": ""arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
        },
        "Headers": {
          "Content-Type": "application/x-www-form-urlencoded"
        },
        "RequestBody": {
          "customer.$": "$.customer_id",
          "description": "Monthly subscription",
          "metadata": {
            "order_details": "monthly report data"
          }
        },
        "Transform": {
          "RequestBodyEncoding": "URL_ENCODED",
          "RequestEncodingOptions": {
            "ArrayFormat": "INDICES"
          }
        }
      },
      "Retry": [
        {
          "ErrorEquals": [
            "States.Http.StatusCode.429",
            "States.Http.StatusCode.503",
            "States.Http.StatusCode.504",
            "States.Http.StatusCode.502"
          ],
          "BackoffRate": 2,
          "IntervalSeconds": 1,
          "MaxAttempts": 3,
          "JitterStrategy": "FULL"
        }
      ],
      "Catch": [
        {
          "ErrorEquals": [
            "States.Http.StatusCode.404",
            "States.Http.StatusCode.400",
            "States.Http.StatusCode.401",
            "States.Http.StatusCode.409",
            "States.Http.StatusCode.500"
          ],
          "Comment": "Handle all non 200 ",
          "Next": "HandleInvoiceFailure"
        }
      ],
      "End": true
    }
  }
}

Untuk menjalankan mesin status ini, berikan ID pelanggan sebagai input seperti yang ditunjukkan pada contoh berikut:

{
    "customer_id": "1234567890"
}

Contoh berikut menunjukkan permintaan HTTP yang Step Functions mengirim ke Stripe API.

POST /v1/invoices HTTP/1.1
Authorization: Basic <base64 of username and password>
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890

Menguji Tugas HTTP

Anda dapat menggunakan TestStateAPI melalui konsol, SDK, atau AWS CLI untuk menguji Tugas HTTP. Prosedur berikut menjelaskan cara menggunakan TestState API di Step Functions konsol. Anda dapat menguji detail permintaan, respons, dan autentikasi API secara berulang hingga Tugas HTTP berfungsi seperti yang diharapkan.

Respons Tugas HTTP yang tidak didukung

Tugas HTTP gagal dengan States.Runtime kesalahan jika salah satu kondisi berikut benar untuk respons yang dikembalikan:

Kesalahan koneksi

Jika EventBridge mengalami masalah saat menyambung ke API yang ditentukan selama eksekusi alur kerja, Step Functions memunculkan kesalahan dalam alur kerja Anda. Kesalahan koneksi diawali denganEvents.ConnectionResource..

Kesalahan ini meliputi: