# HTTP 統合を選択するチュートリアル
HTTP 統合で API をビルドするには、HTTP プロキシ統合または HTTP カスタム統合のどちらかを使用できます。
HTTP プロキシ統合では、バックエンドの要件に従って HTTP メソッドと HTTP エンドポイント URI を設定するだけで済みます。合理化された API セットアップを利用するには、可能な限り、HTTP プロキシ統合を使用することをお勧めします。
HTTP カスタム統合は、バックエンドのクライアントリクエストデータを変換するか、クライアントのためにバックエンドレスポンスデータを変換する必要がある場合に使用できます。
**Topics**
+ [チュートリアル: HTTP プロキシ統合を使用して REST API を作成する](api-gateway-create-api-as-simple-proxy-for-http.md)
+ [チュートリアル: HTTP 非プロキシ統合を使用して REST API を作成する](api-gateway-create-api-step-by-step.md)
# チュートリアル: HTTP プロキシ統合を使用して REST API を作成する
HTTP プロキシ統合は、API を構築するシンプルかつパワフルで、汎用性のあるメカニズムです。これにより、単一の API メソッドのセットアップを合理化することで、ウェブアプリケーションから、統合された HTTP エンドポイントの複数のリソースや機能 (例: ウェブサイト全体) にアクセスすることができます。HTTP プロキシ統合で、API Gateway はクライアントが送信したメソッドリクエストをバックエンドに渡します。渡されるリクエストデータには、リクエストヘッダー、クエリ文字列パラメータ、URL パス変数、ペイロードなどが含まれます。バックエンド HTTP エンドポイントまたはウェブサーバーでは、受信リクエストデータを解析して、返すレスポンスを決定します。HTTP プロキシ統合では、API メソッドの設定後に API Gateway からの介入なしで、クライアントとバックエンドが直接やり取りできます (「[Amazon API Gateway に関する重要な注意点](api-gateway-known-issues.md)」に示されているサポートされない文字など、既知の問題が発生した場合を除く)。
また、網羅的なプロキシリソース (`{proxy+}`) と、多様な状況に対応できる HTTP メソッドの `ANY` 動詞を使用すれば、HTTP プロキシ統合を使用して、単一の API メソッドの API を作成することができます。このメソッドでは、ウェブサイトのパブリックにアクセス可能な HTTP リソースとオペレーションのセット全体を公開します。バックエンドのウェブサーバーでパブリックアクセス用のリソースが他にも開かれると、クライアントは、同じ API をセットアップしてこれらの新しいリソースを使用できます。このようにするために、ウェブサイトデベロッパーは、適用可能な新しいリソースやオペレーションについて、クライアントデベロッパーに明確に伝える必要があります。
以下のチュートリアルでは、HTTP プロキシ統合の概要について説明します。このチュートリアルでは、API Gateway コンソールを使用して API を作成し、汎用的なプロキシリソース `{proxy+}` から PetStore ウェブサイトと統合し、`ANY` の HTTP メソッドのプレースホルダーを作成します。
**Topics**
+ [API Gateway コンソールを使用して HTTP プロキシ統合で API を作成する](#api-gateway-create-api-as-simple-proxy-for-http-build)
+ [HTTP プロキシ統合を使用して API をテストする](#api-gateway-create-api-as-simple-proxy-for-http-test)
## API Gateway コンソールを使用して HTTP プロキシ統合で API を作成する
次の手順では、API Gateway コンソールを使用して、HTTP バックエンド用のプロキシリソースで API を作成してテストする方法を説明します。HTTP バックエンドは、`PetStore` の `http://petstore-demo-endpoint.execute-api.com/petstore/pets` ウェブサイト ([チュートリアル: HTTP 非プロキシ統合を使用して REST API を作成する](api-gateway-create-api-step-by-step.md)) です。ここでは、スクリーンショットを視覚的な補助として使用し、API Gateway UI 要素を示します。はじめて API Gateway コンソールを使用して API を作成する場合は、まず該当セクションに従って行います。
**API を作成する方法**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API Gateway を初めて使用する場合は、サービスの特徴を紹介するページが表示されます。[**REST API**] で、[**構築**] を選択します。[**Create Example API (サンプル API の作成)**] がポップアップ表示されたら、[**OK**] を選択します。
API Gateway を使用するのが初めてではない場合、[**Create API**] (API を作成)を選択します。[**REST API**] で、[**構築**] を選択します。
1. [**API 名**] に「**HTTPProxyAPI**」と入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[API エンドポイントタイプ]** を **[リージョン別]** に設定したままにします。
1. **[IP アドレスの種類]** には **[IPv4]** を選択します。
1. **API の作成** を選択します。
このステップでは、`{proxy+}` のプロキシリソースパスを作成します。これは、`http://petstore-demo-endpoint.execute-api.com/` のいずれかのバックエンドエンドポイントのプレースホルダーです。たとえば、`petstore`、`petstore/pets`、`petstore/pets/{petId}` のようになります。API Gateway は、`{proxy+}` リソースの作成時に `ANY` メソッドを作成し、ランタイムに、サポートされている HTTP 動詞のいずれかのプレースホルダーとして機能します。
****/\$1proxy\$1\$1** リソースを作成するには**
1. API を選択します。
1. メインナビゲーションペインで、**[リソース]** を選択します。
1. **[リソースの作成]** を選択します。
1. **[プロキシのリソース]** を有効にします。
1. **[リソースパス]** は `/` のままにします。
1. **[リソース名]** に「**\$1proxy\$1\$1**」と入力します。
1. **[CORS (Cross Origin Resource Sharing)]** はオフのままにします。
1. **[リソースの作成]** を選択します。
![\[子リソースを作成します。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-simple-proxy-create-proxy-resource-new-console.png)
このステップでは、プロキシ統合を使用して、`ANY` メソッドをバックエンド HTTP エンドポイントと統合します。プロキシ統合の場合、API Gateway はクライアントから送信されたメソッドリクエストを API Gateway の介入なしでバックエンドに渡します。
**`ANY` メソッドを作成するには**
1. **/\$1proxy\$1\$1** リソースを選択します。
1. **ANY** メソッドを選択します。
1. 警告シンボルの下にある **[統合を編集]** を選択します。統合のないメソッドを含む API はデプロイできません。
1. **[統合タイプ]** で、**[HTTP]** を選択します。
1. **[HTTP プロキシ統合]** を有効にします。
1. **[HTTP メソッド]** で、**[ANY]** を選択します。
1. **[エンドポイント URL]** に「**http://petstore-demo-endpoint.execute-api.com/\$1proxy\$1**」と入力します。
1. **[保存]** を選択します。
## HTTP プロキシ統合を使用して API をテストする
特定のクライアントリクエストが成功するかは次に応じて異なります。
+ バックエンドで、対応するバックエンドポイントエンドポイントが利用可能になった場合、または利用可能である場合は、必要なアクセス許可が付与されます。
+ クライアントから適切に入力が行われる場合。
たとえば、ここで使用した PetStore API には、`/petstore` リソースは表示されません。そのため、取得するレスポンス (`404 Resource Not Found`) には、エラーメッセージ (`Cannot GET /petstore`) が含まれます。
さらに、クライアントは、結果を正しく処理するために、バックエンドの出力形式を処理できるようにする必要があります。クライアントとバックエンドの間のやり取りを容易にするために API Gateway が仲介することはありません。
**プロキシリソースを通じた HTTP プロキシ統合を使用して PetStore ウェブサイトと統合された API をテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[メソッドタイプ]** では、`GET` を選択します。
1. **[パス]** の **[プロキシ]** に、「**petstore/pets**」と入力します。
1. **[クエリ文字列]** に「**type=fish**」と入力します。
1. **[テスト]** を選択します。
![\[テスト機能を使用してメソッドをテストします。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-simple-proxy-petstore-call-proxy-resource-new-console.png)
バックエンドのウェブサイトは、`GET /petstore/pets?type=fish` リクエストをサポートするため、次のような成功のレスポンスを返します。
```
[
{
"id": 1,
"type": "fish",
"price": 249.99
},
{
"id": 2,
"type": "fish",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
`GET /petstore` を呼び出そうとすると、`404` レスポンスとエラーメッセージ `Cannot GET /petstore` が返されます。これは、指定したオペレーションがバックエンドでサポートされていないためです。`GET /petstore/pets/1` を呼び出すと、リクエストは PetStore ウェブサイトでサポートされているため、`200 OK` レスポンスと次のペイロードが返されます。
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
ブラウザを使用して API をテストすることもできます。API をデプロイし、それをステージに関連付けて API の呼び出し URL を作成します。
**API をデプロイするには**
1. [**API のデプロイ**] を選択します。
1. **[ステージ]** で **[新規ステージ]** を選択します。
1. [**Stage name (ステージ名)**] に **test** と入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[デプロイ]** を選択します。
これで、クライアントは API を呼び出すことができます。
**API を呼び出すには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択します。
1. **[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーします。
API の呼び出し URL をウェブブラウザに入力します。
URL は次のようになります。`https://abcdef123.execute-api.us-east-2.amazonaws.com/test/petstore/pets?type=fish`
ブラウザが API に`GET`リクエストを送信します。
1. この結果は、API Gateway コンソールで **[テスト]** を使用したときに返される結果と同じであることが必要です。
# チュートリアル: HTTP 非プロキシ統合を使用して REST API を作成する
このチュートリアルでは、Amazon API Gateway コンソールを使用して、API をゼロから作成します。コンソールを API デザインスタジオとして使用して API 機能を絞り込み、その動作を確認して API を作成し、API をステージにデプロイします。
**Topics**
+ [HTTP カスタム統合を使用して API を作成する](#api-gateway-create-resource-and-methods)
+ [(オプション) リクエストパラメータをマッピングする](#api-gateway-create-resources-and-methods-next-steps)
## HTTP カスタム統合を使用して API を作成する
このセクションでは、リソースの作成、リソースでのメソッドの公開、目的の API 動作を達成するためのメソッドの設定、および API のテストとデプロイのステップを説明します。
このステップでは、空の API を作成します。次の手順では、非プロキシ HTTP 統合を使用して API を `http://petstore-demo-endpoint.execute-api.com/petstore/pets` エンドポイントに接続するためのリソースとメソッドを作成します。
**API を作成する方法**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. API Gateway を初めて使用する場合は、サービスの特徴を紹介するページが表示されます。[**REST API**] で、[**構築**] を選択します。[**Create Example API (サンプル API の作成)**] がポップアップ表示されたら、[**OK**] を選択します。
API Gateway を使用するのが初めてではない場合、[**Create API**] (API を作成)を選択します。[**REST API**] で、[**構築**] を選択します。
1. [**API 名**] に「**HTTPNonProxyAPI**」と入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[API エンドポイントタイプ]** を **[リージョン別]** に設定したままにします。
1. **[IP アドレスの種類]** には **[IPv4]** を選択します。
1. **API の作成** を選択します。
[**リソース**] ツリーには、メソッドのないルートリソース (`/`) が表示されます。この演習では、PetStore ウェブサイト (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) の HTTP カスタム統合を使用して API を作成します。わかりやすくするため、ルートの子として `/pets` リソースを作成し、クライアントが PetStore ウェブサイトから利用できる Pets 項目のリストを取得するために、このリソースで GET メソッドを公開します。
**/pets リソースを作成するには**
1. **[リソースの作成]** を選択します。
1. **[プロキシのリソース]** はオフのままにします。
1. **[リソースパス]** は `/` のままにします。
1. **[リソース名]** に「**pets**」と入力します。
1. **[CORS (Cross Origin Resource Sharing)]** はオフのままにします。
1. **[リソースの作成]** を選択します。
このステップでは、**/pets** リソースで `GET` メソッドを作成します。`GET` メソッドは `http://petstore-demo-endpoint.execute-api.com/petstore/pets` ウェブサイトと統合されています。API メソッドの他のオプションには、以下があります。
+ [**POST**]: 主に子リソースの作成に使用されます。
+ **PUT**。既存のリソースを更新するために主に使用します (推奨はされませんが、子リソースの作成にも使用できます)。
+ **DELETE**: リソースの削除に使用されます。
+ [**PATCH**]; リソースの更新に使用されます。
+ [**HEAD**]: テストシナリオで主に使用します。GET と同じですが、リソースの表現を返しません。
+ [**OPTIONS**]: 対象サービスに使用できる通信オプションに関する情報を取得するために呼び出し元が使用できます。
統合リクエストの [**HTTP メソッド**] で、バックエンドによってサポートされているメソッドを選択する必要があります。`HTTP` または `Mock integration` の場合、メソッドリクエストと統合リクエストが同じ HTTP 動詞を使用すると意味があります。他の統合タイプの場合、メソッドリクエストでは、おそらく統合リクエストとは異なる HTTP 動詞を使用します。たとえば、Lambda 関数を呼び出すには、統合リクエストでは `POST` を使用して関数を呼び出す必要がありますが、Lambda; 関数のロジックに応じて、メソッドリクエストでは任意の HTTP 動詞を使用できます。
****/pets** リソースで `GET` メソッドを作成するには**
1. **/pets** リソースを選択します。
1. **[メソッドの作成]** を選択します。
1. **[メソッドタイプ]** には、**GET** を選択します。
1. **[統合タイプ]** で、**[HTTP 統合]** を選択します。
1. **[HTTP プロキシ統合]** はオフのままにします。
1. **[HTTP メソッド]** で、**[GET]** を選択します。
1. **[エンドポイント URL]** に「**http://petstore-demo-endpoint.execute-api.com/petstore/pets**」と入力します。
PetStore ウェブサイトでは、特定のページでペットの種類 (「Dog」や「Cat」など) ごとに、`Pet` 項目のリストを取得できます。
1. **[コンテンツの処理]** で、**[パススルー]** を選択します。
1. **[URL クエリ文字列パラメータ]** を選択します。
PetStore ウェブサイトでは、`type` および `page` クエリ文字列パラメータを使用して入力を受け取ります。メソッドリクエストにクエリ文字列パラメータを追加して、統合リクエストの対応するクエリ文字列パラメータにマッピングします。
1. クエリ文字列パラメータを追加するには、次の操作を行います。
1. [**クエリ文字列の追加**] を選択します。
1. **[名前]** に「**type**」と入力します。
1. **[必須]** と **[キャッシュ]** はオフのままにしておきます。
前の手順を繰り返し、**page** という名前で追加のクエリ文字列を作成します。
1. **[メソッドの作成]** を選択します。
これで、クライアントはリクエストを送信するときに、ペットのタイプとページ番号をクエリ文字列パラメータとして指定できます。これらの入力パラメータは、バックエンドの PetStore ウェブサイトに入力値を転送するために、統合クエリ文字列パラメータにマッピングする必要があります。
**入力パラメータを統合リクエストにマッピングするには**
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[URL クエリ文字列パラメータ]** を選択し、次の操作を行います。
1. **[クエリ文字列パラメータを追加]** を選択します。
1. [**名前**] に**type**と入力してください。
1. **[マッピング元]** として「**method.request.querystring.type**」と入力します。
1. **[キャッシュ]** はオフのままにします。
1. **[クエリ文字列パラメータを追加]** を選択します。
1. [**名前**] に**page**と入力してください。
1. **[マッピング元]** として「**method.request.querystring.page**」と入力します。
1. **[キャッシュ]** はオフのままにします。
1. **[保存]** を選択します。
**API をテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[クエリ文字列]** に「**type=Dog&page=2**」と入力します
1. **[テスト]** を選択します。
結果は次の例のようになります。
![\[GET on Pets メソッドのテスト呼び出しの結果\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-gateway-create-api-step-by-step-test-invoke-get-on-pets-result-new-console.png)
これでテストが成功したので、API をデプロイし、公開することができます。
1. [**API のデプロイ**] を選択します。
1. **[ステージ]** で **[新規ステージ]** を選択します。
1. [**Stage name (ステージ名)**] に **Prod** と入力します。
1. (オプション) **[説明]** に説明を入力します。
1. **[デプロイ]** を選択します。
1. (オプション) **[ステージの詳細]** の **[呼び出し URL]** で、コピーアイコンを選択して API の呼び出し URL をコピーします。[Postman](https://www.postman.com) や [cURL](https://curl.se/) のようなツールでこれを使用して API をテストできます。
SDK を使用してクライアントを作成する場合は、SDK で公開されたメソッドを呼び出して、リクエストに署名できます。実装の詳細については、選択する [AWS SDK](https://aws.amazon.com/developer/tools/) を参照してください。
**注記**
API が変更された場合、再度リクエスト URL を呼び出す前に、API を再デプロイして、新機能または更新された機能を使用できるようにする必要があります。
## (オプション) リクエストパラメータをマッピングする
### API Gateway API のリクエストパラメータをマッピングする
このチュートリアルでは、API のメソッドリクエスト の `{petId}` のパスパラメータを作成し、項目 ID を指定します。次に、これを統合リクエスト URL で `{id}` パスパラメータにマッピングし、リクエストを HTTP エンドポイントに送信します。
**注記**
大文字の代わりに小文字を使用するなど、大文字と小文字を間違えて入力すると、チュートリアルの後半でエラーが発生します。
#### ステップ 1: リソースを作成する
このステップでは、パスパラメータ \$1petId\$1 を使用してリソースを作成します。
**\$1petId\$1 リソースを作成するには**
1. **/pets** リソースを選択し、**[リソースを作成]** を選択します。
1. **[プロキシのリソース]** はオフのままにします。
1. **[リソースパス]** として、**[/pets/]**を選択します。
1. **[リソース名]** に **\$1petId\$1** と入力します。
`petId` の周りに波括弧 (`{ }`) を使用し、**/pets/\$1petId\$1** と表示されるようにします。
1. **[CORS (Cross Origin Resource Sharing)]** はオフのままにします。
1. **[リソースの作成]** を選択します。
#### ステップ 2: メソッドを作成してテストする
このステップでは、`{petId}` パスパラメータを使用して `GET` メソッドを作成します。
**GET メソッドをセットアップするには**
1. **/\$1petId\$1** リソースを選択し、**[メソッドを作成]** を選択します。
1. **[メソッドタイプ]** には、**GET** を選択します。
1. **[統合タイプ]** で、**[HTTP 統合]** を選択します。
1. **[HTTP プロキシ統合]** はオフのままにします。
1. **[HTTP メソッド]** で、**[GET]** を選択します。
1. **[エンドポイント URL]** に「**http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**」と入力します。
1. **[コンテンツの処理]** で、**[パススルー]** を選択します。
1. **[デフォルトタイムアウト]** はオンのままにします。
1. **[メソッドの作成]** を選択します。
次に、先ほど作成した `{petId}` パスパラメータを、統合リクエストの HTTP エンドポイント URL の `{id}` パスパラメータにマッピングします。HTTP エンドポイント URL は **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1** でした。
**`{petId}` パスパラメータをマッピングするには**
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[URL パスパラメータ]** を選択します。
1. API Gateway は **petId** という名前の統合リクエストのパスパラメータを作成しますが、このパスパラメータはバックエンド統合として設定した HTTP エンドポイント URL には無効です。HTTP エンドポイントはパスパラメータとして `{id}` を使用します。**[名前]** で、**petId** を削除し、**id** を入力します。
これは `petId` のメソッドリクエストのパスパラメータを、`id` の統合リクエストのパスパラメータにマッピングします。
1. **[保存]** を選択します。
次にメソッドをテストします。
**メソッドをテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **petId** の **[パス]** に、「**4**」と入力します。
1. [**Test (テスト)**] を選択します。
成功すると、**[レスポンス本文]** に次の内容が表示されます。
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### ステップ 3: API をデプロイする
このステップでは、API をデプロイして、以降 API Gateway コンソール外で呼び出せるようにします。
**API をデプロイする**
1. [**API のデプロイ**] を選択します。
1. **[ステージ]** で **[実稼働]** を選択します。
1. (オプション) **[説明]** に説明を入力します。
1. [**デプロイ**] を選択します。
#### ステップ 4: API をテストする
このステップでは、API Gateway コンソール外に移動し、API を使用して HTTP エンドポイントにアクセスします。
1. メインナビゲーションペインで、**[ステージ]** を選択します。
1. **[ステージの詳細]** で、コピーアイコンを選択して API の呼び出し URL をコピーします。
次のように表示されます。
```
https://my-api-id.execute-api.region-id.amazonaws.com/prod
```
1. リクエストを送信する前に、この URL をブラウザの新しいタブのアドレスボックスに入力し、`/pets/4` を URL に付加します。
1. ブラウザは以下を返します。
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### 次のステップ
リクエストの検証の有効化、データの変換、カスタムゲートウェイレスポンスの作成により、API をさらにカスタマイズできます。
API をカスタマイズするその他の方法については、以下のチュートリアルを参照してください。
+ リクエスト検証の詳細については、「[API Gateway で基本的なリクエストの検証を設定する](api-gateway-request-validation-set-up.md)」を参照してください。
+ リクエストとレスポンスのペイロードを変換する方法の詳細については、「[チュートリアル: AWS サービスへの統合のための統合リクエストとレスポンスを変更する](set-up-data-transformations-in-api-gateway.md)」を参照してください。
+ カスタムゲートウェイレスポンスの作成方法については、「[API Gateway コンソールを使用して REST API のゲートウェイレスポンスをセットアップする](set-up-gateway-response-using-the-console.md)」を参照してください。