Hubungi pihak ketiga APIs dalam alur kerja Step Functions

HTTPTugas adalah jenis Status alur kerja tugas status yang memungkinkan Anda memanggil publik, pihak ketigaAPI, seperti Salesforce dan Stripe, dalam alur kerja Anda. Untuk memanggil pihak ketigaAPI, gunakan status Tugas dengan arn:aws:states:::http:invoke sumber daya. Kemudian, berikan detail konfigurasi API titik akhir, seperti, metode yang ingin Anda gunakan APIURL, dan detail otentikasi.

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

HTTPDefinisi tugas

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

"Call third-party 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
}

HTTPBidang tugas

HTTPTugas mencakup bidang-bidang berikut dalam definisinya.

Otentikasi untuk Tugas HTTP

HTTPTugas memerlukan EventBridge koneksi, yang mengelola kredensi otentikasi penyedia dengan aman. API Koneksi menentukan jenis otorisasi dan kredensi yang akan digunakan untuk mengotorisasi pihak ketiga. API Menggunakan koneksi membantu Anda menghindari rahasia hard-coding, seperti API kunci, ke dalam definisi mesin negara Anda. EventBridge Koneksi mendukung skema otorisasi DasarOAuth,, dan API Kunci.

Saat Anda membuat EventBridge koneksi, Anda memberikan detail otentikasi Anda. Anda juga dapat menyertakan parameter header, body, dan query yang diperlukan untuk otorisasi dengan fileAPI. Anda harus menyertakan koneksi ARN dalam HTTP Tugas apa pun yang memanggil pihak ketigaAPI.

Saat Anda membuat koneksi dan menambahkan parameter otorisasi, EventBridge buat rahasia AWS Secrets Manager. Dalam rahasia ini, EventBridge menyimpan parameter koneksi dan otorisasi dalam bentuk terenkripsi. Agar berhasil membuat atau memperbarui koneksi, Anda harus menggunakan 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, lihatIAMizin untuk menjalankan Tugas HTTP.

Gambar berikut menunjukkan bagaimana Step Functions menangani otentikasi untuk API panggilan pihak ketiga menggunakan EventBridge koneksi. Bagian EventBridge koneksi yang mengelola kredensyal penyedia pihak ketigaAPI. EventBridge Menciptakan sebuah rahasia di Secrets Manager untuk menyimpan parameter koneksi dan otorisasi dalam bentuk terenkripsi.

Penggabungan EventBridge koneksi dan data definisi HTTP Tugas

Saat Anda memanggil HTTP Tugas, Anda dapat menentukan data di EventBridge koneksi dan definisi HTTP Tugas Anda. Data ini mencakupHeaders,QueryParameters, dan RequestBody parameter. Sebelum memanggil pihak ketigaAPI, 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, HTTP Tugas gagal dengan States.Runtime kesalahan.

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

Daftar berikut menjelaskan bagaimana Step Functions menggabungkan data sebelum memanggil pihak ketigaAPI:

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

HTTPDefinisi tugas

{
  "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 HTTP Tugas dan EventBridge koneksi. Oleh karena itu, Step Functions menimpa nilai-nilai dalam HTTP Tugas dengan nilai-nilai dalam koneksi. Cuplikan kode berikut menunjukkan permintaan yang HTTP Step Functions mengirim ke pihak ketigaAPI.

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 URL -encoding pada badan permintaan

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

Anda menentukan URL -encoding menggunakan bidang. Transform Bidang ini berisi RequestBodyEncoding bidang yang menentukan apakah Anda ingin menerapkan URL -encoding untuk badan permintaan Anda atau tidak. Saat Anda menentukan RequestBodyEncoding bidang, Step Functions mengonversi badan JSON permintaan Anda ke badan form-urlencoded permintaan sebelum memanggil pihak ketigaAPI. Anda juga harus menentukan content-type header sebagai application/x-www-form-urlencoded karena APIs itu menerima URL -encoded data mengharapkan header. content-type

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

IAMizin untuk menjalankan Tugas HTTP

Peran eksekusi mesin status Anda harus memiliki states:InvokeHTTPEndpointevents:RetrieveConnectionCredentials,secretsmanager:GetSecretValue,, dan secretsmanager:DescribeSecret izin untuk HTTP Tugas memanggil pihak ketigaAPI. Contoh IAM kebijakan berikut memberikan hak istimewa paling sedikit yang diperlukan untuk peran mesin status Anda untuk memanggil Stripe. APIs IAMKebijakan 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/*"
        }
    ]
}

HTTPContoh tugas

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

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

{
    "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 HTTP permintaan bahwa Step Functions mengirim ke StripeAPI.

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 HTTP Tugas

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

Tanggapan HTTP Tugas yang Tidak Didukung

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