翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Step Functions を使用して API Gateway REST API を作成する
<a name="connect-api-gateway"></a>

Amazon API Gateway を使用して、Step Functions で HTTP と REST API を作成、発行、管理、モニタリングする方法について説明します。API Gateway と統合するには、コードを記述したり、他のインフラストラクチャに依存したりすることなく、API Gateway HTTP または API Gateway REST エンドポイントを直接呼び出す Step Functions 内の `Task` 状態を定義します。`Task` 状態定義には、API コールに必要なすべての情報が含まれます。別の認可方法を選択することもできます。

Step Functions での AWS サービスとの統合については、[ サービスとの統合](integrate-services.md)「」および「」を参照してください[Step Functions でサービス API にパラメータを渡す](connect-parameters.md)。

**最適化された API Gateway 統合の主な機能**  
`apigateway:invoke:` には、 AWS SDK サービス統合で同等のものはありません。代わりに、最適化 API Gateway サービスは API Gateway エンドポイントを直接呼び出します。

## API Gateway 特徴のサポート
<a name="connect-api-gateway-support"></a>

Step Functions API Gateway 統合は、一部の API Gateway 機能をサポートしますが、すべてはサポートしていません。サポートされている特徴の詳細なリストについては、以下を参照してください。
+ 以下は、Step Functions API Gateway REST API と API Gateway HTTP API 統合の両方でサポートされています。
  + **オーソライザー**: IAM ([署名バージョン 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)を使用)、認証なし、Lambda Authorizers (カスタムヘッダーを使用したリクエストパラメータベースおよびトークンベース)
  + **API タイプ**: リージョン
  + **API 管理**: API Gateway API ドメイン名、API ステージ、パス、クエリパラメータ、リクエストボディ
+ Step Functions API Gateway HTTP API 統合でサポートされています。エッジ最適化 API のオプションを提供する Step Functions API Gateway REST API 統合はサポートされていません。
+ Step Functions API Gateway 統合ではサポートされていません。
  +  **オーソライザー**: Amazon Cognito、ネイティブオープン ID Connect/OAuth 2.0、トークンベースの Lambda オーソライザーの認可ヘッダー 
  +  **API タイプ**: プライベート 
  +  **API 管理**: カスタムドメイン名 

API Gateway と HTTP および REST API の詳細については、以下を参照してください。
+  [Amazon API Gateway の概念](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html)ページ。
+  API Gateway デベロッパーガイドの [HTTP API と REST API 間で選択します](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html)。

## リクエストの形式
<a name="connect-api-gateway-requests"></a>

`Task` 状態定義を作成するとき、Step Functions はパラメータを検証し、呼び出しを実行するのに必要な URL を構築し、API を呼び出します。レスポンスには、HTTP ステータスコード、ヘッダー、およびレスポンス本文が含まれます。リクエスト形式には、必須およびオプションのパラメータがあります。

### 必須リクエストパラメータ
<a name="connect-api-gateway-requests-required"></a>
+ `ApiEndpoint`
  + 型: `String`
  + API Gateway URL のホスト名。形式は `{{<API ID>}}.execute-api.{{region}}.amazonaws.com` です。

    API ID には、次の英数字の組み合わせのみを使用できます: `0123456789abcdefghijklmnopqrstuvwxyz`
+ `Method`
  + 型: `Enum`
  + HTTP メソッド。次のいずれかとなる必要があります。
    + `GET`
    + `POST`
    + `PUT`
    + `DELETE`
    + `PATCH`
    + `HEAD`
    + `OPTIONS`

### オプションのリクエストパラメータ
<a name="connect-api-gateway-requests-optional"></a>
+ `Headers`
  + 型: `JSON`
  + HTTP ヘッダーは、同じキーに関連付けられた値のリストを許可します。
+ `Stage`
  + 型: `String`
  + API Gateway で API がデプロイされるステージの名前。`$default` ステージを使用する HTTP API のオプションとなっています。
+ `Path`
  + 型: `String`
  + API エンドポイントの後に追加されるパスパラメータ。
+ `QueryParameters`
  + 型: `JSON`
  + クエリ文字列では、同じキーに関連付けられた値のリストのみが許可されます。
+ `RequestBody`
  + タイプ: `JSON` または `String`
  + HTTP リクエストボディ。そのタイプは、`JSON` オブジェクトまたは `String` です。`RequestBody` は、`PATCH`、`POST`、および `PUT` HTTP メソッドに対してのみサポートされています。
+ `AllowNullValues`
  + タイプ: `BOOLEAN` - デフォルト値: `false`
  + デフォルト設定では、リクエスト入力状態の **null** 値は API に送信**されません**。次の例では、ステートマシン定義で `AllowNullValues` が `true` に設定されていない限り、`category` フィールドはリクエストに**含まれません**。

    ```
    {
        "NewPet": {
            "type": "turtle",
            "price": 123,
            "category": null
        }
    }
    ```
**注記**  
デフォルトでは、リクエスト入力状態の **null** 値を持つフィールドは API に送信**されません**。ステートマシン定義で `AllowNullValues` を `true` に設定することで、null 値を強制的に API に送信できます。
+ `AuthType`
  + 型: `JSON`
  + 認証方法。デフォルトの方法は `NO_AUTH` です。指定できる値は次のとおりです。
    + `NO_AUTH`
    + `IAM_ROLE`
    + `RESOURCE_POLICY`

    詳細については、「**認証および認可**」を参照してください。

**注記**  
セキュリティを考慮して、以下の HTTP ヘッダーキーは現在、許可されていません。  
プレフィックスに `X-Forwarded`、`X-Amz`、または `X-Amzn` (大文字と小文字を区別しない) が付いているもの。
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`

次のコード例は、Step Functions を使用して API Gateway を呼び出す方法を示しています。

```
{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke", 
    "Arguments": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "GET", 
        "Headers": { 
            "key": ["value1", "value2"] 
        },
        "Stage": "prod",
        "Path": "bills",
        "QueryParameters": {
            "billId": ["123456"]
        },
        "RequestBody": {},
        "AuthType": "NO_AUTH"
    } 
}
```

## 認証と認可
<a name="connect-api-gateway-auth"></a>

次の認証方法を使用できます。
+ **認可なし**: 認可メソッドなしで API を直接呼び出します。
+ **IAM ロール**: この方法では、Step Functions はステートマシンのロールを引き受けて、[署名バージョン 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (SigV4) を使ってリクエストに署名した後、API を呼び出します。
+ **リソースポリシー**: Step Functions はリクエストを認証し、API を呼び出します。API に以下を指定するリソースポリシーをアタッチする必要があります。

  1. API Gateway を呼び出すステートマシン。
**重要**  
アクセスを制限するため、ステートマシンを指定する必要があります。そうしない場合は、API への**リソースポリシー**認証を使って API Gateway リクエストを認証するステートマシンにアクセスが付与されます。

  1. そのStep Functions は、API Gateway を呼び出すサービスです: `"Service": "states.amazonaws.com"`。

  1. アクセス対象のリソースには、以下が含まれます。
     + {{region}}。
     + 指定されたリージョンの {{account-id}}。
     + {{api-id}}。
     + {{stage-name}}。
     + {{HTTP-VERB}} (メソッド)。
     + {{resource-path-specifier}}。

  リソースポリシーの例については、[Step Functions と API Gateway 用 IAM ポリシー](#api-gateway-iam)を参照してください。

  リソース形式の詳細については、API Gateway デベロッパーガイドの [API Gateway における API 実行許可のリソース形式](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api)を参照してください。
**注記**  
リソースポリシーは REST API の場合に限り、サポートされます。

## サービス統合パターン
<a name="connect-api-gateway-patterns"></a>

API Gateway 統合では、次の 2 つのサービス統合パターンがサポートされています。
+ [レスポンスのリクエスト](connect-to-resource.md#connect-default)。デフォルトの統合パターンです。このおかげで、TTP レスポンスを受信した直後に Step Functions が H次のステップに進むことができます。
+ [タスクトークンのコールバックまで待機する](connect-to-resource.md#connect-wait-token) (`.waitForTaskToken`) は、タスクトークンがペイロードとともに返されるまで待機します。以下の例に示す通り、`.waitForTaskToken` パターンを使うため、タスク定義の **[Resource]** (リソース) フィールドの末尾に .waitForTaskToken を追加します。

  ```
  {
      "Type": "Task", 
      "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", 
      "Arguments": {
          "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
          "Method": "POST", 
          "Headers": { 
              "TaskToken": "{% $states.context.Task.Token %}"
          },
          "Stage": "prod",
          "Path": "bills/add",
          "QueryParameters": {},
          "RequestBody": {
              "billId": "my-new-bill"
          },
          "AuthType": "IAM_ROLE"
      } 
  }
  ```

## 出力形式
<a name="connect-api-gateway-output"></a>

次の出力パラメータが提供されます。


| 名前 | 型 | 説明 | 
| --- | --- | --- | 
| ResponseBody | JSON または String | API コールのレスポンスの本文。 | 
| Headers | JSON | レスポンスヘッダー | 
| StatusCode | Integer | レスポンスの HTTP ステータスコード。 | 
| StatusText | String | レスポンスのステータステキスト。 | 

レスポンスの例:

```
{
    "ResponseBody": {
        "myBills": []
    },
    "Headers": { 
        "key": ["value1", "value2"]
    }, 
    "StatusCode": 200,
    "StatusText": "OK" 
}
```

## エラー処理
<a name="connect-api-gateway-errors"></a>

エラーが発生した場合、`error` そして `cause` は次のように返されます。
+ HTTP ステータスコードが使用可能な場合、エラーは `ApiGateway.{{<HTTP Status Code>}}` 形式で返されます。
+ HTTP ステータスコードが使用できない場合、エラーは `ApiGateway.{{<Exception>}}` 形式で返されます。

いずれの場合も、`cause` は文字列として返されます。

以下は、エラーが発生したレスポンスの例です。

```
{
    "error": "ApiGateway.403", 
    "cause": "{\"message\":\"Missing Authentication Token\"}"
}
```

**注記**  
`2XX` のステータスコードは成功を示し、エラーは返されません。他のすべてのステータスコードまたはスローされた例外は、エラーになります。

## Amazon API Gateway への呼び出しの IAM ポリシー
<a name="api-gateway-iam"></a>

次のサンプルテンプレートは、 がステートマシン定義のリソースに基づいて IAM ポリシー AWS Step Functions を生成する方法を示しています。詳細については、「[Step Functions が統合サービスの IAM ポリシーを生成する方法](service-integration-iam-templates.md)」および「[Step Functions でサービス統合パターンを検出する](connect-to-resource.md)」を参照してください。

*リソース*:

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/GET/pets",
                "arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/POST/pets"
            ],
            "Effect": "Allow"
        }
    ]
}
```

次のコード例では、API Gateway を呼び出すためのリソースポリシーを示しています。

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "states.amazonaws.com"
            },
            "Action": "execute-api:Invoke",
            "Resource": "arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:myApi-id/{{stage-name}}/{{HTTP-VERB}}/{{resource-path-specifier}}",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": [
                        "{{<SourceStateMachineArn>}}"
                    ]
                }
            }
        }
    ]
}
```