本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Step Functions 工作流程中呼叫 HTTPS APIs
HTTP 任務是一種[任務工作流程狀態](state-task.md)狀態，可用來在工作流程中呼叫 HTTPS APIs。API 可以是公有的，例如第三方 SaaS 應用程式，例如 Stripe 或 Salesforce。您也可以呼叫私有 API，例如 Amazon Virtual Private Cloud 中的 HTTPS 應用程式。
針對授權和網路連線，HTTP 任務需要 EventBridge 連線。
若要呼叫 HTTPS API，請將[任務](state-task.md)狀態與 `arn:aws:states:::http:invoke` 資源搭配使用。然後，提供 API 端點組態詳細資訊，例如 API URL、您要使用的方法，以及[連線](#http-task-authentication)詳細資訊。
如果您使用 [Workflow Studio](workflow-studio.md) 建置包含 HTTP 任務的狀態機器，Workflow Studio 會自動產生具有 HTTP 任務IAM政策的執行角色。如需詳細資訊，請參閱[在 Workflow Studio 中測試 HTTP 任務的角色](manage-state-machine-permissions.md#test-state-role-http)。
**注意**
HTTP 任務目前僅支援使用私有 APIs公有網域名稱。HTTP 任務不支援交互 TLS (mTLS)。
**Topics**
+ [HTTP 任務的連線能力](#http-task-authentication)
+ [HTTP 任務定義](#connect-http-task-definition)
+ [HTTP 任務欄位](#connect-http-task-fields)
+ [合併EventBridge連線和 HTTP 任務定義資料](#http-task-data-merge)
+ [對請求內文套用 URL 編碼](#url-encode-request-body)
+ [執行 HTTP 任務的 IAM 許可](#connect-http-task-permissions)
+ [HTTP 任務範例](#connect-http-task-example)
+ [測試 HTTP 任務](#http-task-test)
+ [不支援的 HTTP 任務回應](#unsupported-http-task-responses)
+ [連線錯誤](#connect-http-task-errors)
## HTTP 任務的連線能力
HTTP 任務需要 [EventBridge 連線](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html)，可安全地管理 API 提供者的身分驗證憑證。*連線*定義用於連線至指定 API 的授權方法和登入資料。如果您要連線到私有 API，例如 Amazon Virtual Private Cloud (Amazon VPC) 中的私有 API，您也可以使用連線來定義安全的point-to-point網路連線。使用連線有助於避免將機密 (例如 API 金鑰) 硬式編碼至狀態機器定義中。EventBridge 連線支援基本、OAuth 和 API 金鑰授權機制。
當您建立 EventBridge 連線時，請提供授權和網路連線詳細資訊。您也可以包含使用 API 授權所需的標頭、內文和查詢參數。您必須在呼叫 HTTPS API 的任何 HTTP 任務中包含連線 ARN。
當您建立連線時，EventBridge 會在其中建立[https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) AWS Secrets Manager。在此秘密中，EventBridge 會以加密形式存放連線和授權參數。若要成功建立或更新連線，您必須使用具有使用 Secrets Manager AWS 帳戶 許可的 。如需狀態機器存取 EventBridge 連線所需IAM許可的詳細資訊，請參閱 [執行 HTTP 任務的 IAM 許可](#connect-http-task-permissions)。
下圖顯示 如何使用 EventBridge連線Step Functions處理 HTTPS API 呼叫的授權。EventBridge 連線會管理 HTTPS API 提供者的登入資料。 會在 中EventBridge建立[https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)Secrets Manager，以加密形式存放連線和授權參數。如果是私有 APIs，EventBridge 也會存放網路連線組態。
**連線逾時**
HTTP 任務請求會在 60 秒後逾時。
![\[Step Functions 在 EventBridge 連線中使用授權和網路組態來呼叫 HTTPS 端點。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/connections-overview_step-functions_conceptual.png)
## HTTP 任務定義
[ASL 定義](concepts-amazon-states-language.md)代表具有`http:invoke`資源的 HTTP 任務。下列 HTTP 任務定義會叫用公有 Stripe API，傳回所有客戶的清單。
```
"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
}
```
## HTTP 任務欄位
HTTP 任務的定義中包含下列欄位。
**`Resource` (必要)**
若要指定[任務類型](state-task.md#task-types)，請在 `Resource` 欄位中提供其 ARN。對於 HTTP 任務，您可以指定 `Resource` 欄位，如下所示。
```
"Resource": "arn:aws:states:::http:invoke"
```
**`Parameters` (必要)**
包含 `ApiEndpoint`、 `Method`和 `ConnectionArn` 欄位，提供您要呼叫之 HTTPS API 的相關資訊。 `Parameters`也包含選用欄位，例如 `Headers`和 `QueryParameters`。
您可以指定靜態 JSON 和 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法的組合，如 `Parameters` 欄位`Parameters`所示。如需詳細資訊，請參閱[在 Step Functions 中將參數傳遞至服務 API](connect-parameters.md)。
若要指定 EventBridge 連線，請使用 `Authentication`*或* `InvocationConfig` 欄位。
`ApiEndpoint` **（必要）**
指定您要呼叫的 HTTPS API URL。若要將查詢參數附加至 URL，請使用 `QueryParameters` 欄位。下列範例示範如何呼叫 Stripe API 來擷取所有客戶的清單。
```
"ApiEndpoint":"https://api.stripe.com/v1/customers"
```
您也可以使用 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法指定[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，以選取包含 HTTPS API URL 的 JSON 節點。例如，假設您想要使用特定客戶 ID 呼叫 Stripe 的其中一個 APIs。假設您已提供下列狀態輸入。
```
{
"customer_id": "1234567890",
"name": "John Doe"
}
```
若要使用 Stripe API 擷取此客戶 ID 的詳細資訊，請指定 `ApiEndpoint`，如下列範例所示。此範例使用[內部 函數](intrinsic-functions.md)和參考路徑。
```
"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"
```
在執行時間，Step Functions 會解析 的值`ApiEndpoint`，如下所示。
```
https://api.stripe.com/v1/customers/1234567890
```
`Method` **（必要）**
指定您要用於呼叫 HTTPS API 的 HTTP 方法。您可以在 HTTP 任務中指定下列其中一種方法：GET、POST、PUT、DELETE、PATCH、OPONS 或 HEAD。
例如，若要使用 GET 方法，請指定 `Method` 欄位，如下所示。
```
"Method": "GET"
```
您也可以使用[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，在執行時間指定 方法。例如 **"Method.\$1": "\$1.myHTTPMethod"**。
`Authentication` **（條件式）**
*我們建議您在公`Authentication`有和私有 HTTPS API 呼叫中使用 `InvocationConfig` 。*
為了回溯相容性，會維護現有的`Authentication`參考。在 欄位中，您必須指定 `ConnectionArn` 欄位，指定 的連線資源Amazon EventBridge以連線至 `ApiEndpoint`。
`InvocationConfig` **（條件式）**
包含公**有**和私有 HTTPS API 呼叫的授權和網路連線組態。
Step Functions `ApiEndpoint`使用 的連線資源來處理指定 的連線Amazon EventBridge。如需詳細資訊，請參閱《*Amazon EventBridge 使用者指南*》中的[連線至私有 APIs](https://docs.aws.amazon.com/eventbridge/latest/userguide/connection-private.html)。
`ConnectionArn` **（必要）**
指定EventBridge連線 ARN。
HTTP 任務需要 [EventBridge 連線](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html)，可安全地管理 API 提供者的授權憑證。*連線*指定用於授權 HTTPS API 的授權類型和憑證。對於私有 APIs，連線也會定義安全的point-to-point網路連線。使用連線有助於避免將機密 (例如 API 金鑰) 硬式編碼至狀態機器定義中。在連線中，您也可以指定 `Headers`、 `QueryParameters`和 `RequestBody` 參數。
如需詳細資訊，請參閱[HTTP 任務的連線能力](#http-task-authentication)。
下列範例顯示 HTTP 任務`InvocationConfig`中的 格式：
```
"InvocationConfig": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/connection-id"
}
```
`Headers` (選用)
為 API 端點提供額外的內容和中繼資料。您可以將標頭指定為字串或 JSON 陣列。
您可以在EventBridge連線中指定標頭，並在 HTTP 任務中指定 `Headers` 欄位。建議您不要在 `Headers` 欄位中包含 API 供應商的身分驗證詳細資訊。我們建議您將這些詳細資訊包含在EventBridge連線中。
Step Functions 會將您在EventBridge連線中指定的標頭新增至您在 HTTP 任務定義中指定的標頭。如果定義和連線中存在相同的標頭索引鍵， Step Functions會將EventBridge連線中指定的對應值用於這些標頭。如需 如何Step Functions執行資料合併的詳細資訊，請參閱 [合併EventBridge連線和 HTTP 任務定義資料](#http-task-data-merge)。
下列範例會指定要包含在 HTTPS API 呼叫中的標頭：`content-type`。
```
"Headers": {
"content-type": "application/json"
}
```
您也可以使用[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，在執行時間指定標頭。例如 **"Headers.\$1": "\$1.myHTTPHeaders"**。
Step Functions 會設定 `User-Agent`、 `Range`和 `Host`標頭。 會根據您呼叫的 API 來Step Functions設定 `Host` 標頭的值。以下是這些標頭的範例。
```
User-Agent: Amazon|StepFunctions|HttpInvoke|region,
Range: bytes=0-262144,
Host: api.stripe.com
```
您無法在 HTTP 任務定義中使用下列標頭。如果您使用這些標頭，HTTP 任務會失敗並顯示`States.Runtime`錯誤。
+ A-IM
+ Accept-Charset
+ Accept-Datetime
+ 接受編碼
+ Authorization
+ 快取控制
+ 連線
+ Content-Encoding
+ Content-MD5
+ Date
+ Expect
+ Forwarded
+ 從
+ 主機
+ HTTP2-Settings
+ If-Match
+ If-Modified-Since
+ If-None-Match
+ If-Range
+ If-Unmodified-Since
+ Max-Forwards
+ Origin
+ Pragma
+ Proxy-Authorization
+ Referer
+ Server
+ TE
+ 預告片
+ Transfer-Encoding
+ Upgrade
+ Via
+ 警告
+ x-forwarded-\$1
+ x-amz-\$1
+ x-amzn-\$1
`QueryParameters` (選用)
在 API URL 結尾插入鍵/值對。您可以將查詢參數指定為字串、JSON 陣列或 JSON 物件。 會在呼叫 HTTPS API 時Step Functions自動將查詢參數進行 URL 編碼。
例如，假設您想要呼叫 Stripe API 來搜尋以美元 (USD) 進行交易的客戶。假設您已提供下列項目`QueryParameters`做為狀態輸入。
```
"QueryParameters": {
"currency": "usd"
}
```
在執行時間，Step Functions 會將 附加`QueryParameters`至 API URL，如下所示。
```
https://api.stripe.com/v1/customers/search?currency=usd
```
您也可以使用[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，在執行時間指定查詢參數。例如 **"QueryParameters.\$1": "\$1.myQueryParameters"**。
如果您已在EventBridge連線中指定查詢參數， 會將這些查詢參數Step Functions新增至您在 HTTP 任務定義中指定的查詢參數。如果定義和連線中有相同的查詢參數索引鍵， 會針對這些標頭Step Functions使用EventBridge連線中指定的對應值。如需 如何Step Functions執行資料合併的詳細資訊，請參閱 [合併EventBridge連線和 HTTP 任務定義資料](#http-task-data-merge)。
`Transform` (選用)
包含 `RequestBodyEncoding`和 `RequestEncodingOptions` 欄位。根據預設， Step Functions會將請求內文做為 JSON 資料傳送至 API 端點。
如果您的 API 提供者接受`form-urlencoded`請求內文，請使用 `Transform` 欄位來指定請求內文的 URL 編碼。您還必須將 `content-type` 標頭指定為 `application/x-www-form-urlencoded`。Step Functions然後， 會自動對您的請求內文進行 URL 編碼。
`RequestBodyEncoding`
指定請求內文的 URL 編碼。您可以指定下列其中一個值： `NONE`或 `URL_ENCODED`。
+ `NONE` – HTTP 請求內文將是 `RequestBody` 欄位的序列化 JSON。這是預設值。
+ `URL_ENCODED` – HTTP 請求內文將是 `RequestBody` 欄位的 URL 編碼形式資料。
`RequestEncodingOptions`
如果您將 `RequestBodyEncoding`設定為 ，則決定要用於請求內文中陣列的編碼選項`URL_ENCODED`。
Step Functions 支援下列陣列編碼選項。如需這些選項及其範例的詳細資訊，請參閱 [對請求內文套用 URL 編碼](#url-encode-request-body)。
+ `INDICES` – 使用陣列元素的索引值來編碼陣列。根據預設， Step Functions會使用此編碼選項。
+ `REPEAT` – 為陣列中的每個項目重複一個索引鍵。
+ `COMMAS` – 將金鑰中的所有值編碼為以逗號分隔的值清單。
+ `BRACKETS` – 為陣列中的每個項目重複一個索引鍵，並將括號 【】 附加到索引鍵，以表示它是陣列。
下列範例會設定請求內文資料的 URL 編碼。它還指定在請求內文中使用陣列的`COMMAS`編碼選項。
```
"Transform": {
"RequestBodyEncoding": "URL_ENCODED",
"RequestEncodingOptions": {
"ArrayFormat": "COMMAS"
}
}
```
`RequestBody` (選用)
接受您在狀態輸入中提供的 JSON 資料。在 中`RequestBody`，您可以指定靜態 JSON 和 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法的組合。例如，假設您提供下列狀態輸入：
```
{
"CardNumber": "1234567890",
"ExpiryDate": "09/25"
}
```
若要在執行時間於請求內文`ExpiryDate`中使用這些 `CardNumber`和 的值，您可以在請求內文中指定下列 JSON 資料。
```
"RequestBody": {
"Card": {
"Number.$": "$.CardNumber",
"Expiry.$": "$.ExpiryDate",
"Name": "John Doe",
"Address": "123 Any Street, Any Town, USA"
}
}
```
如果您想要呼叫的 HTTPS API 需要`form-urlencoded`請求內文，您必須為請求內文資料指定 URL 編碼。如需詳細資訊，請參閱[對請求內文套用 URL 編碼](#url-encode-request-body)。
## 合併EventBridge連線和 HTTP 任務定義資料
當您叫用 HTTP 任務時，您可以在EventBridge連線和 HTTP 任務定義中指定資料。此資料包含 `Headers`、 `QueryParameters`和 `RequestBody` 參數。呼叫 HTTPS API 之前，Step Functions 會在所有情況下將請求內文與連線內文參數合併，除非您的請求內文是字串且連線內文參數不是空的。在此情況下，HTTP 任務會失敗並顯示`States.Runtime`錯誤。
如果 HTTP 任務定義和EventBridge連線中指定了任何重複的金鑰， 會以連線中的值Step Functions覆寫 HTTP 任務中的值。
下列清單說明 如何在呼叫 HTTPS API Step Functions 之前合併資料：
+ **標頭** – 將您在連線中指定的任何標頭Step Functions新增至 HTTP 任務 `Headers` 欄位中的標頭。如果標頭索引鍵之間發生衝突， Step Functions會使用這些標頭連線中指定的值。例如，如果您同時在 HTTP 任務定義和EventBridge連線中指定 `content-type` 標頭， Step Functions會使用連線中指定的`content-type`標頭值。
+ **查詢參數** – 將您在連線中指定的任何查詢參數Step Functions新增至 HTTP 任務 `QueryParameters` 欄位中的查詢參數。如果查詢參數索引鍵之間發生衝突， Step Functions會將連線中指定的值用於這些查詢參數。例如，如果您同時在 HTTP 任務定義和EventBridge連線中指定`maxItems`查詢參數， Step Functions會使用連線中指定的`maxItems`查詢參數值。
+ **主體參數**
+ Step Functions 在 HTTP 任務的 `RequestBody` 欄位中，將連線中指定的任何請求內文值新增至請求內文。如果請求內文金鑰之間發生衝突， Step Functions會使用請求內文連線中指定的值。例如，假設您已在 HTTP 任務定義和EventBridge連線`RequestBody`的 中指定`Mode`欄位。 Step Functions會使用您在連線中指定的`Mode`欄位值。
+ 如果您將請求內文指定為字串而非 JSON 物件，且EventBridge連線也包含請求內文，則 Step Functions無法合併這兩個位置指定的請求內文。它會失敗 HTTP 任務並顯示`States.Runtime`錯誤。
Step Functions 會套用所有轉換，並在完成合併請求內文後序列化請求內文。
下列範例會設定 HTTP `Headers`任務和EventBridge連線中的 `QueryParameters`、 和 `RequestBody` 欄位。
**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 連線**
```
{
"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"
}
]
}
}
}
```
在此範例中，會在 HTTP 任務和EventBridge連線中指定重複的金鑰。因此， 會以連線中的值Step Functions覆寫 HTTP 任務中的值。下列程式碼片段顯示Step Functions傳送至 HTTPS API 的 HTTP 請求。
```
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"}
```
## 對請求內文套用 URL 編碼
根據預設， Step Functions會將請求內文做為 JSON 資料傳送至 API 端點。如果您的 HTTPS API 提供者需要`form-urlencoded`請求內文，您必須為請求內文指定 URL 編碼。Step Functions然後， 會根據您選取的 URL 編碼選項，自動對請求內文進行 URL 編碼。
您可以使用 `Transform` 欄位指定 URL 編碼。此欄位包含 `RequestBodyEncoding` 欄位，指定您是否要為請求內文套用 URL 編碼。當您指定 `RequestBodyEncoding` 欄位時， 會將您的 JSON 請求內文Step Functions轉換為`form-urlencoded`請求內文，然後再呼叫 HTTPS API。您也必須將 `content-type` 標頭指定為 ，`application/x-www-form-urlencoded`因為APIs 需要 `content-type`標頭。
若要在您的請求內文中編碼陣列， Step Functions提供下列陣列編碼選項。
+ `INDICES` – 為陣列中的每個項目重複一個索引鍵，並將括號 【】 附加到索引鍵，以表示它是陣列。此括號包含陣列元素的索引。新增索引有助於指定陣列元素的順序。根據預設， Step Functions會使用此編碼選項。
例如，如果您的請求內文包含下列陣列。
```
{"array": ["a","b","c","d"]}
```
Step Functions 會將此陣列編碼為下列字串。
```
array[0]=a&array[1]=b&array[2]=c&array[3]=d
```
+ `REPEAT` – 為陣列中的每個項目重複一個索引鍵。
例如，如果您的請求內文包含下列陣列。
```
{"array": ["a","b","c","d"]}
```
Step Functions 會將此陣列編碼為下列字串。
```
array=a&array=b&array=c&array=d
```
+ `COMMAS` – 將金鑰中的所有值編碼為以逗號分隔的值清單。
例如，如果您的請求內文包含下列陣列。
```
{"array": ["a","b","c","d"]}
```
Step Functions 會將此陣列編碼為下列字串。
```
array=a,b,c,d
```
+ `BRACKETS` – 為陣列中的每個項目重複一個索引鍵，並將括號 【】 附加到索引鍵，以表示它是陣列。
例如，如果您的請求內文包含下列陣列。
```
{"array": ["a","b","c","d"]}
```
Step Functions 會將此陣列編碼為下列字串。
```
array[]=a&array[]=b&array[]=c&array[]=d
```
## 執行 HTTP 任務的 IAM 許可
您的狀態機器執行角色必須具有下列許可，HTTP 任務才能呼叫 HTTPS API：
+ `states:InvokeHTTPEndpoint`
+ `events:RetrieveConnectionCredentials`
+ `secretsmanager:GetSecretValue`
+ `secretsmanager:DescribeSecret`
下列 IAM 政策範例會將呼叫 Stripe APIs 所需的最低權限授予狀態機器角色。此 IAM 政策也會授予 狀態機器角色存取特定 EventBridge 連線的許可，包括存放在 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/*"
}
]
}
```
## HTTP 任務範例
下列狀態機器定義顯示 HTTP 任務，其中包含 `Headers`、`Transform`、 `QueryParameters`和 `RequestBody` 參數。HTTP 任務會呼叫 Stripe API https：//https://api.stripe.com/v1/invoices 來產生發票。HTTP 任務也會使用編碼選項指定請求內文的 URL `INDICES`編碼。
請確定您已建立 EventBridge 連線。下列範例顯示使用 BASIC 驗證類型建立的連線。
```
{
"Type": "BASIC",
"AuthParameters": {
"BasicAuthParameters": {
"Password": "myPassword",
"Username": "myUsername"
},
}
}
```
請以資源特定資訊取代*斜體*文字。
```
{
"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
}
}
}
```
若要執行此狀態機器，請提供客戶 ID 做為輸入，如下列範例所示：
```
{
"customer_id": "1234567890"
}
```
下列範例顯示Step Functions傳送至 Stripe API 的 HTTP 請求。
```
POST /v1/invoices HTTP/1.1
Authorization: Basic
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
```
## 測試 HTTP 任務
您可以透過主控台、 SDK 或 使用 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API AWS CLI 來[測試](test-state-isolation.md) HTTP 任務。下列程序說明如何在 Step Functions主控台中使用 TestState API。您可以反覆測試 API 請求、回應和身分驗證詳細資訊，直到 HTTP 任務如預期般運作為止。
**在Step Functions主控台中測試 HTTP 任務狀態**
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)。
1. 選擇**建立狀態機器**以開始建立狀態機器，或選擇包含 HTTP 任務的現有狀態機器。
如果您在現有狀態機器中測試任務，請參閱步驟 4。
1. 在 Workflow Studio [設計模式](workflow-studio.md#wfs-interface-design-mode)的 中，以視覺化方式設定 HTTP 任務。或者，選擇程式碼模式，從本機開發環境複製貼上狀態機器定義。
1. 在設計模式中，選擇 Workflow Studio [Inspector 面板](workflow-studio.md#workflow-studio-components-formdefinition)面板中的**測試狀態**。
1. 在**測試狀態**對話方塊中，執行下列動作：
1. 針對**執行角色**，選擇要測試狀態的執行角色。如果您沒有具有[足夠 HTTP 任務許可](#connect-http-task-permissions)的角色，請參閱 [在 Workflow Studio 中測試 HTTP 任務的角色](manage-state-machine-permissions.md#test-state-role-http) 以建立角色。
1. （選用） 提供您選擇的測試狀態所需的任何 JSON 輸入。
1. 對於**檢測層級**，請保留 **INFO** 的預設選擇。此層級會顯示 API 呼叫的狀態和狀態輸出。這有助於快速檢查 API 回應。
1. 選擇**開始測試**。
1. 如果測試成功，狀態輸出會出現在**測試狀態**對話方塊的右側。如果測試失敗，則會顯示錯誤。
在對話方塊**的狀態詳細資訊**索引標籤中，您可以看到狀態定義和[EventBridge連線](#http-task-authentication)的連結。
1. 將**檢測層級**變更為 **TRACE**。此層級會顯示原始 HTTP 請求和回應，對於驗證標頭、查詢參數和其他 API 特定詳細資訊很有用。
1. 選擇**顯示秘密**核取方塊。結合 **TRACE**，此設定可讓您查看EventBridge連線插入的敏感資料，例如 API 金鑰。您用來存取主控台IAM的使用者身分必須具有執行 `states:RevealSecrets`動作的許可。如果沒有此許可， 會在您開始測試時Step Functions擲出存取遭拒錯誤。如需IAM設定 `states:RevealSecrets`許可的政策範例，請參閱 [IAM 使用 TestState API 的許可](test-state-isolation.md#test-state-permissions)。
下圖顯示成功 HTTP 任務的測試。此狀態的**檢查層級**設定為 **TRACE**。下圖中的 **HTTP 請求和回應**索引標籤會顯示 HTTPS API 呼叫的結果。
![\[所選狀態的輸出，可成功測試 TRACE 層級。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/test-state-trace-success.png)
1. 選擇**開始測試**。
1. 如果測試成功，您可以在 HTTP **請求和回應索引標籤下查看您的 HTTP** 詳細資訊。
## 不支援的 HTTP 任務回應
如果傳回的回應符合下列其中一個條件，HTTP 任務會失敗並顯示`States.Runtime`錯誤：
+ 回應包含 `application/octet-stream`、`video/*`、 `image/*`或 的內容類型標頭`audio/*`。
+ 無法將回應讀取為有效的字串。例如，二進位或映像資料。
## 連線錯誤
如果在工作流程執行期間連線至指定的 API 時 EventBridge 遇到問題，Step Functions 會在工作流程中引發錯誤。連線錯誤字首為 `Events.ConnectionResource.`。
這些錯誤包括：
+ `Events.ConnectionResource.InvalidConnectionState`
+ `Events.ConnectionResource.InvalidPrivateConnectionState`
+ `Events.ConnectionResource.AccessDenied`
+ `Events.ConnectionResource.ResourceNotFound`
+ `Events.ConnectionResource.AuthInProgress`
+ `Events.ConnectionResource.ConcurrentModification`
+ `Events.ConnectionResource.InternalError`