Panggil API pihak ketiga - AWS Step Functions
Definisi Tugas HTTPBidang Tugas HTTPOtentikasi untuk Tugas HTTPMenggabungkan EventBridge koneksi dan data definisi Tugas HTTPMenerapkan pengkodean URL pada badan permintaanIzin IAM untuk menjalankan Tugas HTTPContoh Tugas HTTPMenguji Tugas HTTPRespons HTTP Task yang tidak didukung

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Panggil API pihak ketiga

Tugas HTTP adalah jenis Tugas status yang memungkinkan Anda memanggil API publik, pihak ketiga, seperti Salesforce dan Stripe, dalam alur kerja Anda. Untuk memanggil API pihak ketiga, 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 otentikasi.

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

Definisi Tugas HTTP

Definisi ASL mewakili Tugas HTTP dengan http:invoke sumber daya. Definisi HTTP Task 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
}

Bidang Tugas HTTP

Tugas HTTP mencakup bidang-bidang berikut dalam definisinya.

Resource (Wajib)

Untuk menentukan jenis tugas, berikan ARN di lapangan. Resource Untuk Tugas HTTP, Anda menentukan Resource bidang sebagai berikut.

"Resource": "arn:aws:states:::http:invoke"
Parameters (Wajib)

BerisiApiEndpoint,Method, dan ConnectionArn bidang yang menyediakan informasi tentang API pihak ketiga yang ingin Anda panggil. Parametersjuga berisi bidang opsional, seperti Headers danQueryParameters.

Anda dapat menentukan kombinasi JSON statis dan JsonPathsintaks seperti Parameters di lapangan. Parameters Untuk informasi selengkapnya, lihat Meneruskan parameter ke API layanan.

ApiEndpoint(Diperlukan)

Menentukan URL API pihak ketiga yang ingin Anda panggil. Untuk menambahkan parameter kueri ke URL, gunakan bidang. QueryParameters Contoh berikut menunjukkan bagaimana Anda dapat memanggil Stripe API untuk mengambil daftar semua pelanggan.

"ApiEndpoint":"https://api.stripe.com/v1/customers"

Anda juga dapat menentukan jalur referensi menggunakan JsonPathsintaks untuk memilih node JSON yang berisi URL API pihak ketiga. Misalnya, Anda ingin memanggil salah satu API Stripe menggunakan ID pelanggan tertentu. Bayangkan Anda telah memberikan masukan status berikut.

{
    "customer_id": "1234567890",
    "name": "John Doe"
}

Untuk mengambil detail ID pelanggan ini menggunakan Stripe API, tentukan ApiEndpoint seperti yang ditunjukkan pada contoh berikut. Contoh ini menggunakan fungsi intrinsik dan jalur referensi.

"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"

Saat runtime, Step Functions menyelesaikan nilai sebagai berikut. ApiEndpoint

https://api.stripe.com/v1/customers/1234567890
Method(Diperlukan)

Menentukan metode HTTP yang ingin Anda gunakan untuk memanggil API pihak ketiga. Anda dapat menentukan salah satu metode ini dalam Tugas HTTP Anda: GET, POST, PUT, DELETE, PATCH, OPTIONS, atau HEAD.

Misalnya, untuk menggunakan metode GET, tentukan Method bidang sebagai berikut.

"Method": "GET"

Anda juga dapat menggunakan jalur referensi untuk menentukan metode saat runtime. Misalnya, "Method.$": "$.myHTTPMethod".

Authentication(Diperlukan)

Berisi ConnectionArn bidang yang menentukan cara mengautentikasi panggilan API pihak ketiga. Step Functionsmendukung otentikasi untuk yang ditentukan ApiEndpoint menggunakan sumber daya koneksi dari. Amazon EventBridge

ConnectionArn(Diperlukan)

Menentukan EventBridge koneksi ARN.

Tugas HTTP memerlukan EventBridge koneksi, yang mengelola kredensi otentikasi penyedia API dengan aman. Koneksi menentukan jenis otorisasi dan kredensi yang akan digunakan untuk mengotorisasi API pihak ketiga. Menggunakan koneksi membantu Anda menghindari rahasia hard-coding, seperti kunci API, ke dalam definisi mesin status Anda. Dalam koneksi, Anda juga dapat menentukanHeaders,QueryParameters, dan RequestBody parameter.

Saat Anda membuat EventBridge koneksi, Anda memberikan detail otentikasi Anda. Untuk informasi selengkapnya tentang cara kerja otentikasi untuk Tugas HTTP, lihatOtentikasi untuk Tugas HTTP.

Contoh berikut menunjukkan bagaimana Anda dapat menentukan Authentication bidang dalam definisi Tugas HTTP Anda.

"Authentication": {
  "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
}
Headers (Opsional)

Menyediakan konteks dan metadata tambahan ke titik akhir API. Anda dapat menentukan header sebagai string atau array JSON.

Anda dapat menentukan header dalam EventBridge koneksi dan Headers bidang dalam Tugas HTTP. Kami menyarankan agar Anda tidak menyertakan detail otentikasi ke penyedia API Anda di Headers bidang ini. Kami menyarankan Anda memasukkan detail ini ke dalam EventBridge koneksi Anda.

Step Functionsmenambahkan header yang Anda tentukan dalam EventBridge koneksi ke header yang Anda tentukan dalam definisi Tugas HTTP. Jika tombol header yang sama hadir dalam definisi dan koneksi, Step Functions gunakan nilai yang sesuai yang ditentukan dalam EventBridge koneksi untuk header tersebut. Untuk informasi selengkapnya tentang cara Step Functions melakukan penggabungan data, lihatMenggabungkan EventBridge koneksi dan data definisi Tugas HTTP.

Contoh berikut menentukan header yang akan disertakan dalam panggilan API pihak ketiga:content-type.

"Headers": {
  "content-type": "application/json"
}

Anda juga dapat menggunakan jalur referensi untuk menentukan header saat runtime. Misalnya, "Headers.$": "$.myHTTPHeaders".

Step FunctionsmenetapkanUser-Agent,Range, dan Host header. Step Functionsmenetapkan nilai Host header berdasarkan API yang Anda panggil. Berikut ini adalah contoh dari header ini.

User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1,
Range: bytes=0-262144,
Host: api.stripe.com

Anda tidak dapat menggunakan header berikut dalam definisi Tugas HTTP Anda. Jika Anda menggunakan header ini, Tugas HTTP gagal dengan States.Runtime kesalahan.

  • A-IM

  • Terima-Charset

  • Terima-Datetime

  • Terima-Pengenkodean

  • Cache-Control

  • Koneksi

  • Pengkodean Konten

  • Content-MD5

  • Tanggal

  • Harapkan

  • Diteruskan

  • Dari

  • Host

  • HTTP2-pengaturan

  • Jika-Pertandingan

  • Jika-Modifikasi-Sejak

  • Jika-Tidak Pertandingan

  • Jika-Rentang

  • Jika-Tidak Dimodifikasi-Sejak

  • Max-Maju

  • Asal

  • Pragma

  • Otorisasi Proksi

  • Perujuk

  • Server

  • TE

  • Trailer

  • Transfer-Encoding

  • Peningkatan

  • Melalui

  • Peringatan

  • x-diteruskan-*

  • x-amz-*

  • x-amzn-*

QueryParameters (Opsional)

Menyisipkan pasangan nilai kunci di akhir URL API. Anda dapat menentukan parameter kueri sebagai string, array JSON, atau objek JSON. Step Functionssecara otomatis mengkodekan parameter kueri URL saat memanggil API pihak ketiga.

Misalnya, katakan bahwa Anda ingin memanggil Stripe API untuk mencari pelanggan yang melakukan transaksi mereka dalam dolar AS (USD). Bayangkan Anda telah memberikan yang berikut ini QueryParameters sebagai input status.

"QueryParameters": {
  "currency": "usd"
}

Saat runtime, Step Functions menambahkan QueryParameters ke URL API sebagai berikut.

https://api.stripe.com/v1/customers/search?currency=usd

Anda juga dapat menggunakan jalur referensi untuk menentukan parameter kueri saat runtime. Misalnya, "QueryParameters.$": "$.myQueryParameters".

Jika Anda telah menentukan parameter kueri dalam EventBridge koneksi Anda, Step Functions tambahkan parameter kueri ini ke parameter kueri yang Anda tentukan dalam definisi Tugas HTTP. Jika kunci parameter kueri yang sama ada dalam definisi dan koneksi, Step Functions gunakan nilai yang sesuai yang ditentukan dalam EventBridge koneksi untuk header tersebut. Untuk informasi selengkapnya tentang cara Step Functions melakukan penggabungan data, lihatMenggabungkan EventBridge koneksi dan data definisi Tugas HTTP.

Transform (Opsional)

Berisi RequestBodyEncoding dan RequestEncodingOptions bidang. Secara default, Step Functions mengirimkan badan permintaan sebagai data JSON ke titik akhir API.

Jika penyedia API Anda menerima badan form-urlencoded permintaan, gunakan Transform bidang untuk menentukan pengkodean URL untuk badan permintaan. Anda juga harus menentukan content-type header sebagaiapplication/x-www-form-urlencoded. Step Functionskemudian secara otomatis URL-menyandikan badan permintaan Anda.

RequestBodyEncoding

Menentukan URL-encoding dari badan permintaan Anda. Anda dapat menentukan satu nilai ini: NONE atauURL_ENCODED.

  • NONE— Badan permintaan HTTP akan menjadi JSON serialisasi lapangan. RequestBody Ini adalah nilai default.

  • URL_ENCODED— Badan permintaan HTTP akan menjadi data formulir yang dikodekan URL dari bidang tersebut. RequestBody

RequestEncodingOptions

Menentukan opsi pengkodean yang akan digunakan untuk array di badan permintaan Anda jika Anda menyetel RequestBodyEncoding ke. URL_ENCODED

Step Functionsmendukung opsi pengkodean array berikut. Untuk informasi lebih lanjut tentang opsi ini dan contohnya, lihatMenerapkan pengkodean URL pada badan permintaan.

  • INDICES— Mengkodekan array menggunakan nilai indeks elemen array. Secara default, Step Functions gunakan opsi pengkodean ini.

  • REPEAT— Mengulangi kunci untuk setiap item dalam array.

  • COMMAS— Mengkodekan semua nilai dalam kunci sebagai daftar nilai yang dibatasi koma.

  • BRACKETS— Mengulangi kunci untuk setiap item dalam array dan menambahkan braket, [], ke kunci untuk menunjukkan bahwa itu adalah array.

Contoh berikut menetapkan URL-encoding untuk data badan permintaan. Ini juga menentukan untuk menggunakan opsi COMMAS pengkodean untuk array di badan permintaan.

"Transform": {
  "RequestBodyEncoding": "URL_ENCODED",
  "RequestEncodingOptions": {
    "ArrayFormat": "COMMAS"
  }
}
RequestBody (Opsional)

Menerima data JSON yang Anda berikan dalam input status. DiRequestBody, Anda dapat menentukan kombinasi JSON statis dan JsonPathsintaks. Misalnya, katakan bahwa Anda memberikan masukan status berikut:

{
    "CardNumber": "1234567890",
    "ExpiryDate": "09/25"
}

Untuk menggunakan nilai-nilai ini dari CardNumber dan ExpiryDate dalam badan permintaan Anda saat runtime, Anda dapat menentukan data JSON berikut di badan permintaan Anda.

"RequestBody": {
  "Card": {
    "Number.$": "$.CardNumber",
    "Expiry.$": "$.ExpiryDate",
    "Name": "John Doe",
    "Address": "123 Any Street, Any Town, USA"
  }
}

Jika API pihak ketiga yang ingin Anda panggil memerlukan badan form-urlencoded permintaan, Anda harus menentukan pengkodean URL untuk data isi permintaan Anda. Untuk informasi selengkapnya, lihat Menerapkan pengkodean URL pada badan permintaan.

Otentikasi untuk Tugas HTTP

Tugas HTTP memerlukan EventBridge koneksi, yang mengelola kredensi otentikasi penyedia API dengan aman. Koneksi menentukan jenis otorisasi dan kredensi yang akan digunakan untuk mengotorisasi API pihak ketiga. 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 detail otentikasi 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 pihak ketiga.

Saat Anda membuat koneksi dan menambahkan parameter otorisasi, 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 selengkapnya tentang IAM izin yang dibutuhkan mesin status Anda untuk mengakses EventBridge sambungan, lihatIzin IAM untuk menjalankan Tugas HTTP.

Gambar berikut menunjukkan cara Step Functions menangani otentikasi untuk panggilan API pihak ketiga menggunakan EventBridge koneksi.

Process Step Functions menggunakan EventBridge koneksi yang mengelola kredensi otentikasi penyedia API pihak ketiga. EventBridgemembuat rahasia Secrets Manager untuk menyimpan koneksi dan parameter otorisasi dalam bentuk terenkripsi.

Menggabungkan EventBridge koneksi dan data definisi Tugas HTTP

Saat Anda menjalankan Tugas HTTP, Anda dapat menentukan data dalam EventBridge koneksi dan definisi Tugas HTTP Anda. Data ini mencakupHeaders,QueryParameters, dan RequestBody parameter. Sebelum memanggil API pihak ketiga, 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 timpa nilai dalam Tugas HTTP dengan nilai-nilai dalam koneksi.

Daftar berikut menjelaskan cara Step Functions menggabungkan data sebelum memanggil API pihak ketiga:

  • Header - Step Functions menambahkan header apa pun yang Anda tentukan dalam koneksi ke header di Headers bidang Tugas HTTP. Jika ada konflik antara tombol header, Step Functions gunakan nilai yang ditentukan dalam koneksi untuk header tersebut. Misalnya, jika Anda menentukan content-type header dalam definisi HTTP Task dan EventBridge koneksi, Step Functions menggunakan nilai content-type header yang ditentukan dalam koneksi.

  • Parameter kueri - Step Functions menambahkan parameter kueri apa pun yang Anda tentukan dalam koneksi ke parameter kueri di QueryParameters bidang Tugas HTTP. Jika ada konflik antara kunci parameter kueri, Step Functions gunakan nilai yang ditentukan dalam koneksi untuk parameter kueri tersebut. Misalnya, jika Anda menentukan parameter maxItems kueri dalam definisi HTTP Task dan EventBridge koneksi, Step Functions menggunakan nilai parameter maxItems kueri yang ditentukan dalam koneksi.

  • Parameter tubuh

    • Step Functionsmenambahkan nilai badan permintaan apa pun yang ditentukan dalam koneksi ke badan permintaan di RequestBody bidang Tugas HTTP. Jika ada konflik antara kunci badan permintaan, Step Functions gunakan nilai yang ditentukan dalam koneksi untuk badan permintaan. Misalnya, katakan bahwa Anda menentukan Mode bidang dalam RequestBody definisi HTTP Task dan EventBridge koneksi. Step Functionsmenggunakan nilai Mode bidang yang Anda tentukan dalam koneksi.

    • Jika Anda menentukan badan permintaan sebagai string alih-alih objek JSON, dan EventBridge koneksi juga berisi badan permintaan, tidak Step Functions dapat menggabungkan badan permintaan yang ditentukan di kedua tempat ini. Gagal Tugas HTTP dengan States.Runtime kesalahan.

    Step Functionsmenerapkan semua transformasi dan membuat serial badan permintaan setelah menyelesaikan penggabungan badan permintaan.

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"
        }
      }
    }
  }
}

EventBridgekoneksi

{
  "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 dikirim ke API pihak ketiga.

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 pihak ketiga Anda memerlukan badan form-urlencoded permintaan, Anda harus menentukan pengkodean URL untuk badan permintaan. Step Functionskemudian 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 API pihak ketiga. Anda juga harus menentukan content-type header sebagai application/x-www-form-urlencoded karena API yang menerima data yang disandikan URL mengharapkan header. content-type

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

  • INDICES— Mengulangi kunci untuk setiap item dalam array dan menambahkan braket, [], ke kunci untuk menunjukkan bahwa itu adalah array. Braket ini berisi indeks elemen array. Menambahkan indeks membantu Anda menentukan urutan elemen array. Secara default, Step Functions gunakan opsi pengkodean ini.

    Misalnya, jika badan permintaan Anda berisi array berikut.

    {"array": ["a","b","c","d"]}

    Step Functionsmengkodekan array ini ke string berikut.

    array[0]=a&array[1]=b&array[2]=c&array[3]=d

  • REPEAT— Mengulangi kunci untuk setiap item dalam array.

    Misalnya, jika badan permintaan Anda berisi array berikut.

    {"array": ["a","b","c","d"]}

    Step Functionsmengkodekan array ini ke string berikut.

    array=a&array=b&array=c&array=d

  • COMMAS— Mengkodekan semua nilai dalam kunci sebagai daftar nilai yang dibatasi koma.

    Misalnya, jika badan permintaan Anda berisi array berikut.

    {"array": ["a","b","c","d"]}

    Step Functionsmengkodekan array ini ke string berikut.

    array=a,b,c,d

  • BRACKETS— Mengulangi kunci untuk setiap item dalam array dan menambahkan braket, [], ke kunci untuk menunjukkan bahwa itu adalah array.

    Misalnya, jika badan permintaan Anda berisi array berikut.

    {"array": ["a","b","c","d"]}

    Step Functionsmengkodekan array ini ke string berikut.

    array[]=a&array[]=b&array[]=c&array[]=d

Izin IAM untuk menjalankan Tugas HTTP

Peran eksekusi mesin status Anda harus memilikistates:InvokeHTTPEndpoint,events:RetrieveConnectionCredentials,secretsmanager:GetSecretValue, dan secretsmanager:DescribeSecret izin untuk Tugas HTTP untuk memanggil API pihak ketiga. Contoh kebijakan IAM berikut memberikan hak istimewa paling sedikit yang diperlukan untuk peran mesin status Anda untuk memanggil Stripe API. 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/invoices, untuk menghasilkan faktur. Tugas HTTP juga menentukan URL-encoding untuk badan permintaan menggunakan opsi encoding. INDICES

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

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

Ingatlah untuk mengganti teks yang dicetak miring 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.

Uji status Tugas HTTP di Step Functions konsol

  1. Buka Konsol Step Functions.

  2. Pilih Buat mesin status untuk mulai membuat mesin status atau pilih mesin status yang ada yang berisi Tugas HTTP.

    Lihat Langkah 4 jika Anda menguji tugas di mesin status yang ada.

  3. Di Mode desain Workflow Studio, konfigurasikan Tugas HTTP secara visual. Atau pilih mode Kode untuk menyalin-menempelkan definisi mesin status dari lingkungan pengembangan lokal Anda.

  4. Dalam mode Desain, pilih Status uji di Inspector panel Workflow Studio.

  5. Dalam kotak dialog Test state, lakukan hal berikut:

    1. Untuk peran Eksekusi, pilih peran eksekusi untuk menguji status. Jika Anda tidak memiliki peran dengan izin yang cukup untuk Tugas HTTP, lihat Peran untuk menguji Tugas HTTP di Workflow Studio untuk membuat peran.

    2. (Opsional) Berikan masukan JSON apa pun yang dibutuhkan status yang Anda pilih untuk pengujian.

    3. Untuk tingkat Inspeksi, pertahankan pilihan default INFO. Level ini menunjukkan status panggilan API dan output status. Ini berguna untuk memeriksa respons API dengan cepat.

    4. Pilih Mulai tes.

    5. Jika tes berhasil, output status muncul di sisi kanan kotak dialog status Uji. Jika tes gagal, kesalahan muncul.

      Di tab Detail negara pada kotak dialog, Anda dapat melihat definisi status dan tautan ke EventBridgekoneksi Anda.

    6. Ubah level Inspeksi menjadi TRACE. Level ini menunjukkan permintaan dan respons HTTP mentah, dan berguna untuk memverifikasi header, parameter kueri, dan detail spesifik API lainnya.

    7. Pilih kotak centang Reveal Secrets. Dalam kombinasi dengan TRACE, pengaturan ini memungkinkan Anda melihat data sensitif yang disisipkan EventBridge koneksi, seperti kunci API. Identitas IAM pengguna yang Anda gunakan untuk mengakses konsol harus memiliki izin untuk melakukan states:RevealSecrets tindakan. Tanpa izin ini, Step Functions melempar kesalahan akses ditolak saat Anda memulai pengujian. Untuk contoh IAM kebijakan yang menetapkan states:RevealSecrets izin, lihatIAMizin untuk menggunakan API TestState .

      Gambar berikut menunjukkan tes untuk Tugas HTTP yang berhasil. Tingkat Inspeksi untuk status ini diatur ke TRACE. Tab permintaan & respons HTTP pada gambar berikut menunjukkan hasil panggilan API pihak ketiga.

      Output dari status yang dipilih yang berhasil pengujian untuk tingkat TRACE.

    8. Pilih Mulai tes.

    9. Jika pengujian berhasil, Anda dapat melihat detail HTTP Anda di bawah tab permintaan & respons HTTP.

Respons HTTP Task yang tidak didukung

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

  • Respons berisi header tipe kontenapplication/octet-stream,, image/*video/*, atau. audio/*

  • Respons tidak dapat dibaca sebagai string yang valid. Misalnya, data biner atau gambar.