翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Step Functions ワークフローで HTTPS API を呼び出す
HTTP タスクは [Task ワークフロー状態](state-task.md) ステートの一種で、ワークフロー内から HTTPS API を呼び出す際に使用できます。API は、Stripe や Salesforce などのサードパーティ SaaS アプリのようなパブリック API でもかまいません。また、Amazon Virtual Private Cloud 内の HTTPS ベースのアプリケーションなど、プライベート API を呼び出すこともできます。
認可とネットワーク接続のために、HTTP タスクでは EventBridge 接続が必要です。
HTTPS API を呼び出すには、[Task](state-task.md) ステートと `arn:aws:states:::http:invoke` リソースを使用します。次に、API の URL、使用するメソッド、[接続](#http-task-authentication)の詳細など、API エンドポイント設定の詳細を指定します。
[Workflow Studio](workflow-studio.md) を使用して HTTP タスクを含むステートマシンを構築すると、Workflow Studio は HTTP タスクの IAM ポリシーを含む実行ロールを自動的に生成します。詳細については、「[Workflow Studio で HTTP タスクをテストするためのロール](manage-state-machine-permissions.md#test-state-role-http)」を参照してください。
**注記**
HTTP タスクは現在、プライベート API を使用する場合、HTTPS エンドポイントに対しては公開ドメイン名と信頼された証明書のみをサポートしています。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 タスクには、API プロバイダーの認証情報を安全に管理する [EventBridge 接続](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html)が必要です。*接続*は、特定の API に接続する際に使用する認可方法と認証情報を定義します。Amazon Virtual Private Cloud (Amazon VPC) のプライベート API などのプライベート API に接続する場合は、接続を使用して安全な point-to-point ネットワーク接続を定義することもできます。接続を使用すると、API キーなどのシークレットをステートマシン定義にハードコーディングすることを避けることができます。EventBridge 接続は、Basic、OAuth、API キーの各認可スキームをサポートしています。
EventBridge 接続を作成するときは、認可情報とネットワーク接続の詳細を指定します。API での認可に必要なヘッダー、本文、およびクエリパラメータを含めることもできます。HTTP API を呼び出す HTTP タスクには、接続 ARN を含める必要があります。
接続を作成すると、EventBridge は AWS Secrets Managerに[https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)を作成します。このシークレットでは、EventBridge は接続パラメータと認可パラメータを暗号化された形式で保存します。接続を正常に作成または更新するには、Secrets Manager を使用するアクセス許可 AWS アカウント を持つ を使用する必要があります。ステートマシンが EventBridge 接続にアクセスするために必要な IAM アクセス許可の詳細については、「[HTTP タスクを実行するための IAM アクセス許可](#connect-http-task-permissions)」を参照してください。
次の図では、Step Functions が EventBridge 接続を使用して HTTPS API コールの認可を処理する方法を示しています。EventBridge 接続では、HTTPS API プロバイダーの認証情報を管理します。EventBridge は、Secrets Manager に[https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)を作成し、接続と認可のパラメータを暗号化して保存します。プライベート API の場合、EventBridge ではネットワーク接続の設定も保存します。
**接続のタイムアウト**
HTTP タスクのリクエストは 60 秒後にタイムアウトします。
![\[Step Functions は、HTTPS エンドポイントへの呼び出しに EventBridge 接続の認可とネットワーク設定を使用します。\]](http://docs.aws.amazon.com/ja_jp/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` (必須)**
呼び出したい HTTPS API に関する情報を提供する `ApiEndpoint`、`Method`、および `ConnectionArn` フィールドが含まれます。`Parameters` には `Headers` や `QueryParameters` などのオプションフィールドも含まれています。
`Parameters` フィールドの `Parameters` のように、静的 JSON 構文と [JsONPath](https://datatracker.ietf.org/wg/jsonpath/about/) 構文の組み合わせを指定できます。詳細については、「[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 の API のいずれかを呼び出す場合を想定します。次のようなステートの入力を指定したとします。
```
{
"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、OPTIONS、または HEAD。
例えば、GET メソッドを使用するには、`Method` フィールドを次のように指定します。
```
"Method": "GET"
```
[参照パス](amazon-states-language-paths.md#amazon-states-language-reference-paths)を使用して実行時にメソッドを指定することもできます。例えば、**"Method.\$1": "\$1.myHTTPMethod"**。
`Authentication` **(条件付き)**
*パブリックとプライベートの両方の HTTPS API コールに、`Authentication` ではなく `InvocationConfig` を使用することをお勧めします。*
既存の `Authentication` 参照は下位互換性のために保持されています。このフィールド内では、`ApiEndpoint` に接続するための Amazon EventBridge の接続リソースを指定する `ConnectionArn` フィールドを指定する必要があります。
`InvocationConfig` **(条件付き)**
パブリックとプライベートの**両方の** HTTPS API コールの認可とネットワーク接続設定が含まれます。
Step Functions は Amazon EventBridge の接続リソースを使用して、指定された `ApiEndpoint` の接続を処理します。詳細については、「*Amazon EventBridge ユーザーガイド*」の「[プライベート API への接続](https://docs.aws.amazon.com/eventbridge/latest/userguide/connection-private.html)」を参照してください。
`ConnectionArn` **(必須)**
EventBridge 接続 ARN を指定します。
HTTP タスクには、API プロバイダーの認証情報を安全に管理する [EventBridge 接続](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html)が必要です。*接続*には、HTTPS API の認可に使用する認可タイプと認証情報を指定します。プライベート API の場合、接続にはセキュアなポイントツーポイントのネットワーク接続も定義します。接続を使用すると、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` フィールドで指定できます。API プロバイダへの認証情報を `Headers` フィールドに入力しないことをお勧めします。これらの情報は、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` ヘッダーを設定します。Step Functions は呼び出している API に基づいて `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
+ Accept-Encoding
+ Authorization
+ Cache-Control
+ 接続
+ Content-Encoding
+ Content−MD5
+ 日付
+ Expect
+ Forwarded
+ から
+ ホスト
+ HTTP2-Settings
+ If-Match
+ If-Modified-Since
+ If-None-Match
+ If-Range
+ If-Unmodified-Since
+ Max-Forwards
+ オリジン
+ Pragma
+ Proxy-Authorization
+ リファラー
+ サーバー
+ TE
+ Trailer
+ Transfer-Encoding
+ アップグレード
+ Via
+ 警告
+ x-forwarded-\$1
+ x-amz-\$1
+ x-amzn-\$1
`QueryParameters` (オプション)
API URL の末尾にキーと値のペアを挿入します。クエリパラメータは、文字列、JSON 配列、または JSON オブジェクトとして指定できます。Step Functions は HTTPS API を呼び出すとき、クエリパラメータを自動的に 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"
}
```
実行時にこれらの `CardNumber` と `ExpiryDate` の値をリクエスト本文で使用するには、リクエスト本文に次の 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` パラメータが含まれます。Step Functions は、リクエスト本文が文字列で接続本文のパラメータが空でない場合を除き、HTTPS API を呼び出す前に、リクエスト本文と接続本文パラメータをマージします。この場合、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` クエリパラメータ値を使用します。
+ **Body パラメータ**
+ Step Functions は接続で指定されたすべてのリクエスト本文値を HTTP タスクの `RequestBody` フィールドのリクエスト本文に追加します。リクエスト本文のキーが競合する場合は、Step Functions は接続で指定された値をリクエスト本文として使用します。例えば、HTTP タスク定義と EventBridge 接続の両方で `RequestBody` の `Mode` フィールドを指定したとします。Step Functions は接続で指定した `Mode` フィールド値を使用します。
+ リクエスト本文を JSON オブジェクトではなく文字列として指定し、EventBridge 接続にリクエスト本文も含まれている場合、Step Functions はこの 2 つの場所で指定されたリクエスト本文をマージすることはできません。HTTP タスクは `States.Runtime` エラーで失敗します。
リクエスト本文のマージが完了したら、Step Functions はすべての変換を適用してリクエスト本文をシリアル化します。
次の例では、HTTP タスクと EventBridge 接続の両方に `Headers`、`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 エンコードします。
URL エンコードは `Transform` を使用してフィールドを指定します。このフィールドには、リクエスト本文に URL エンコードを適用するかどうかを指定する `RequestBodyEncoding` フィールドが含まれます。`RequestBodyEncoding` フィールドを指定すると、Step Functions は HTTPS API を呼び出す前に JSON リクエスト本文を `form-urlencoded` リクエスト本文に変換します。URL でエンコードされたデータを受け入れる API は `content-type` ヘッダーを必要とするため、`content-type` ヘッダーも `application/x-www-form-urlencoded` として指定する必要があります。
リクエスト本文の配列をエンコードするために、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 APIを呼び出すために必要な最小特権をステートマシンのロールに付与しています。このIAMポリシーは、Secrets Manager に保存されているこの接続のシークレットを含め、特定のEventBridge 接続にアクセスするアクセス許可をステートマシンのロールに付与します。
****
```
{
"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 タスク例
次のステートマシン定義は `Headers`、`QueryParameters`、`Transform`、および `RequestBody` パラメータを含む HTTP タスクを示しています。HTTP タスクは Stripe API (https://api.stripe.com/v1/invoices) を呼び出して請求書を生成します。HTTP タスクでは、`INDICES` エンコーディングオプションを使用してリクエスト本文の URL エンコーディングも指定します。
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"
}
```
次の例は、Stripe API Step Functions に送信する 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 タスクのテスト
[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API は、コンソール、SDK、または を使用して AWS CLI HTTP タスクを[テスト](test-state-isolation.md)できます。次の手順では、Step Functions コンソールを使用してを TestState API 実行する方法について説明します。HTTP タスクが期待どおりに動作するまで、API リクエスト、応答、認証の詳細を繰り返しテストできます。
**HTTP タスクステートを Step Functions コンソールでテストする**
1. [Step Functions コンソール](https://console.aws.amazon.com/states/home?region=us-east-1#/)を開きます。
1. **[ステートマシンの作成]** を選択してステートマシンの作成を開始するか、HTTP タスクを含む既存のステートマシンを選択します。
既存のステートマシンでタスクをテストする場合は、ステップ 4 を参照してください。
1. [デザインモード](workflow-studio.md#wfs-interface-design-mode) の Workflow Studio で、HTTP タスクを視覚的に設定します。または、コードモードを選択して、ローカル開発環境からステートマシン定義をコピーして貼り付けます。
1. デザインモードで、Workflow Studio の [インスペクターパネル](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]** と組み合わせると、API キーなど、EventBridge 接続によって挿入される機密データを確認できます。コンソールへのアクセスに使用する IAM ユーザー ID には、`states:RevealSecrets` アクションを実行するアクセス許可が必要です。このアクセス許可がない場合、Step Functions はテストの開始時にアクセス拒否エラーをスローします。これらの `states:RevealSecrets` アクセス許可を付与する IAM ポリシーの例については、「[TestState API を使用するための IAM アクセス許可](test-state-isolation.md#test-state-permissions)」を参照してください。
次の図は、HTTP タスクが成功するかどうかのテストを示しています。このステートの **[検査レベル]** は **[TRACE]** に設定されています。次の画像の **[HTTP リクエストおよびレスポンス]** タブには、HTTPS API コールの結果が表示されます。
![\[[TRACE] レベルのテストに成功した、選択されたステートの出力。\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/test-state-trace-success.png)
1. **[テストを開始]** を選択します。
1. テストが成功すると、**[HTTP リクエストおよびレスポンス]** タブに HTTP の詳細が表示されます。
## サポートされていない HTTP タスクレスポンス
返された応答が次のいずれかの条件に当てはまる場合、HTTP タスクは `States.Runtime` エラーで失敗します。
+ レスポンスには、`application/octet-stream`、`image/*`、`video/*`、または `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`