Panggil API HTTPS di alur kerja Fungsi Langkah

Tugas HTTP adalah jenis Status alur kerja tugas menyatakan bahwa Anda dapat menggunakan untuk memanggil API HTTPS di alur kerja Anda. API dapat bersifat publik, seperti aplikasi SaaS pihak ketiga seperti Stripe atau Salesforce. Anda juga dapat memanggil API pribadi, seperti HTTPS-based aplikasi di Amazon Virtual Private Cloud.

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

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

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

Konektivitas untuk Tugas HTTP

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

Ketika 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 koneksi ARN dalam Tugas HTTP apa pun yang memanggil API HTTPS.

Ketika Anda membuat koneksi, EventBridge menciptakan sebuah 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 Akun AWS yang memiliki izin untuk menggunakan Manajer Rahasia. Untuk informasi lebih lanjut tentang IAM izin yang dibutuhkan mesin status Anda untuk mengakses EventBridge koneksi, lihat Izin IAM untuk menjalankan Tugas HTTP.

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

Definisi Tugas HTTP

Definisi ASL mewakili Tugas HTTP dengan http:invoke sumber daya. Definisi Tugas HTTP berikut memanggil API Stripe 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:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

Bidang Tugas HTTP

Tugas HTTP menyertakan 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 meliputi Headers, 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 mengganti nilai-nilai dalam Tugas HTTP dengan nilai-nilai dalam koneksi.

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

Contoh berikut menetapkan Headers, QueryParameters, dan RequestBody bidang di 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:region:account-id: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 hubungan

{
  "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 mengganti nilai-nilai dalam Tugas HTTP dengan nilai-nilai dalam koneksi. Cuplikan kode berikut menunjukkan permintaan HTTP yang Step Functions mengirim ke API HTTPS.

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|region

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

Menerapkan URL-encoding sesuai permintaan badan

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

Anda tentukan URL-encoding menggunakan Transform bidang. Bidang ini berisi RequestBodyEncoding bidang yang menentukan apakah Anda ingin mendaftar atau tidak URL-encoding untuk badan permintaan Anda. Ketika Anda menentukan RequestBodyEncoding lapangan, Step Functions mengonversi badan permintaan JSON Anda menjadi form-urlencoded isi permintaan sebelum memanggil HTTPS API. Anda juga harus menentukan content-type header sebagai application/x-www-form-urlencoded karena API yang menerima URL-encoded Data mengharapkan content-type tajuk.

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 API Stripe. Kebijakan IAM ini juga memberikan izin ke peran mesin status untuk mengakses suatu hal tertentu EventBridge koneksi, termasuk rahasia untuk koneksi ini yang disimpan di Secrets Manager.

Contoh Tugas HTTP

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

Pastikan bahwa Anda telah membuat EventBridge koneksi. Contoh berikut menunjukkan koneksi yang dibuat menggunakan tipe 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:region:account-id: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 API Stripe.

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|region

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

Menguji Tugas HTTP

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

Tanggapan 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 menghubungkan ke API yang ditentukan selama eksekusi alur kerja, Fungsi Langkah memunculkan kesalahan dalam alur kerja Anda. Kesalahan koneksi diawali dengan Events.ConnectionResource..

Kesalahan ini meliputi: