# チュートリアル: REST API を Amazon S3 のプロキシとして作成する
このセクションでは、API Gateway で REST API を Amazon S3 のプロキシとして使用する例として、Amazon S3 の以下のオペレーションを公開するために REST API を作成して設定する方法について説明します。
+ API のルートリソースに対するメソッドとして、[呼び出し元のすべての Amazon S3 バケットを一覧表示する](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) GET を公開する。
+ Folder リソースに対するメソッドとして、[Amazon S3 バケット内のすべてのオブジェクトを一覧表示する](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) GET を公開する。
+ Folder/Item リソースに対するメソッドとして、[Amazon S3 バケットからオブジェクトをダウンロードする](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) GET を公開する。
Amazon S3 のプロキシとして、「[Amazon S3 のプロキシとしてのサンプル API の OpenAPI 定義](api-as-s3-proxy-export-swagger-with-extensions.md)」に示すように、サンプル API をインポートすることもできます。このサンプルには、より多くの公開メソッドが含まれています。OpenAPI 定義を使用して API をインポートする方法については、「[API Gateway で OpenAPI を使用して REST API を開発する](api-gateway-import-api.md)」を参照してください。
**注記**
API Gateway の API を Amazon S3 と統合するには、API Gateway と Amazon S3 の両方のサービスが利用できるリージョンを選択する必要があります。利用できるリージョンについては、「[Amazon API Gateway エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/apigateway.html)」を参照してください。
**Topics**
+ [API で Amazon S3 のアクションを呼び出すための IAM アクセス許可を設定する](#api-as-s3-proxy-iam-permissions)
+ [Amazon S3 のリソースを表す API のリソースを作成する](#api-as-s3-proxy-create-resources)
+ [呼び出し元の Amazon S3 バケットを一覧表示する API のメソッドを公開する](#api-root-get-as-s3-get-service)
+ [Amazon S3 バケットにアクセスする API のメソッドを公開する](#api-folder-operations-as-s3-bucket-actions)
+ [バケット内の Amazon S3 オブジェクトにアクセスする API のメソッドを公開する](#api-items-in-folder-as-s3-objects-in-bucket)
+ [Amazon S3 のプロキシとしてのサンプル API の OpenAPI 定義](api-as-s3-proxy-export-swagger-with-extensions.md)
+ [REST API クライアントを使用して API を呼び出す](api-as-s3-proxy-test-using-postman.md)
## API で Amazon S3 のアクションを呼び出すための IAM アクセス許可を設定する
Amazon S3 のアクションを呼び出すことを API に許可するには、IAM ロールに適切な IAM ポリシーをアタッチする必要があります。このステップでは、新しい IAM ロールを作成します。
**AWS のサービスプロキシの実行ロールを作成するには**
1. AWS マネジメントコンソール にサインインして、IAM コンソール [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) を開きます。
1. **[ロール]** を選択します。
1. [**ロールの作成**] を選択してください。
1. **[信頼されたエンティティの種類を選択]** で **[AWS のサービス]** を選択し、**[API Gateway]**、**[API Gateway が CloudWatch Logs にログをプッシュすることを許可]** の順に選択します。
1. **[次へ]** を選択し、さらに **[次へ]** を選択します。
1. [**ロール名**] に「**APIGatewayS3ProxyPolicy**」と入力し、[**ロールの作成**] を選択します。
1. [**ロール**] リストで、作成したロールを選択します。ロールを検索するには、必要に応じてスクロールするか、検索バーを使用します。
1. 選択したロールの **[アクセス許可を追加]** タブを選択します。
1. ドロップダウンリストから **[ポリシーをアタッチ]** を選択します。
1. 検索バーに「**AmazonS3FullAccess**」と入力し、**[アクセス許可を追加]** を選択します。
**注記**
このチュートリアルでは、わかりやすくするために管理ポリシーを使用しますが、独自の IAM ポリシーを作成して、必要な最小限のアクセス許可を付与するのがベストプラクティスです。
1. 新しく作成した**ロール ARN** をメモしておきます。これは後で使用します。
## Amazon S3 のリソースを表す API のリソースを作成する
API のルート (`/`) リソースを、認証された呼び出し元の Amazon S3 バケットのコンテナとして使用します。また、特定の Amazon S3 バケットと特定の Amazon S3 オブジェクトを表す `Folder` リソースと `Item` リソースもそれぞれ作成します。フォルダ名とオブジェクトキーは、発信者により、リクエスト URL の一部としてパスパラメータの形式で指定されます。
**注記**
オブジェクトキーに `/` やその他の特殊文字が含まれているオブジェクトにアクセスする場合は、文字を URL エンコードする必要があります。たとえば、`test/test.txt` は `test%2Ftest.txt` にエンコードする必要があります。
**Amazon S3 サービスの機能を公開する API のリソースを作成するには**
1. Amazon S3 バケットを作成したのと同じ AWS リージョンで、**MyS3** という名前の API を作成します。この API のルートリソース (**/**) は Amazon S3 サービスを表します。このステップでは、**/{folder}** と **/{item}** という 2 つの追加のリソースを作成します。
1. **[リソースの作成]** を選択します。
1. **[プロキシのリソース]** はオフのままにします。
1. **[リソースパス]** で、`/` を選択します。
1. **[リソース名]** に **{folder}** と入力します。
1. **[CORS (Cross Origin Resource Sharing)]** はオフのままにします。
1. **[リソースの作成]** を選択します。
1. **/{folder}** リソースを選択し、**[リソースを作成]** を選択します。
1. 前のステップを使用して、**/{folder}** の子リソースを **{item}** という名前で作成します。
最終的な API は次のようになります。
## 呼び出し元の Amazon S3 バケットを一覧表示する API のメソッドを公開する
呼び出し元の Amazon S3 バケットの一覧を取得するには、Amazon S3 に対して [GET サービス](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html)アクションを呼び出す必要があります。API のルートリソース (**/**) で、GET メソッドを作成します。GET メソッドを設定して Amazon S3 と統合するには、以下の手順に従います。
**API の `GET /` メソッドを作成し、初期化するには**
1. **/** リソースを選択し、**[メソッドを作成]** を選択します。
1. メソッドタイプとして、**[GET]** を選択します。
1. **[統合タイプ]** で、**[AWS のサービス]** を選択します。
1. **[AWS リージョン]** で、Amazon S3 バケットを作成した AWS リージョンを選択します。
1. **[AWS のサービス]** で、**[Amazon Simple Storage Service]** を選択します。
1. **[AWS サブドメイン]** は空白のままにします。
1. **[HTTP メソッド]** で、**[GET]** を選択します。
1. **[アクションタイプ]** で、**[パスオーバーライドを使用]** を選択します。
パスの上書きを使用すると、API Gateway はクライアントのリクエストを対応する [Amazon S3 の REST API のパス形式のリクエスト](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html)として Amazon S3 に転送します。このリクエストでは、Amazon S3 のリソースは `s3-host-name/bucket/key` 形式のリソースパスで表されます。API Gateway は `s3-host-name` を設定し、クライアントが指定した `bucket` と `key` をクライアントから Amazon S3 に渡します。
1. **[パスオーバーライド]**] に「**/**」と入力します。
1. **[実行ロール]** に、**APIGatewayS3ProxyPolicy** のロール ARN を入力します。
1. **[メソッドリクエストの設定]** を選択します。
メソッドリクエストの設定を使用して、この API メソッドを誰が呼び出せるかを制御します。
1. **[認可]** で、ドロップダウンメニューから [`AWS_IAM`] を選択します。
1. **[メソッドの作成]** を選択します。
この設定には、フロントエンドの `GET https://{{your-api-host}}/{{stage}}/` リクエストとバックエンドの `GET https://{{your-s3-host}}/` が含まれます。
API から呼び出し元に正常なレスポンスと例外を適切に返すようにするには、**[メソッドレスポンス]** で 200、400、500 のレスポンスを宣言します。200 レスポンスのデフォルトのマッピングを使用すると、ここで宣言されていないステータスコードのバックエンドレスポンスが 200 レスポンスとして呼び出し元に返されます。
**`GET /` メソッドのレスポンスタイプを宣言するには**
1. **[メソッドレスポンス]** タブの **[レスポンス 200]** で、**[編集]** を選択します。
1. **[ヘッダーを追加]** を選択し、次の操作を行います。
1. **[ヘッダー名]** に「**Content-Type**」と入力します。
1. [**ヘッダーの追加**] を選択します。
次の手順を繰り返して、**Timestamp** ヘッダーと **Content-Length** ヘッダーを作成します。
1. **[保存]** を選択します。
1. **[メソッドレスポンス]** タブの **[メソッドレスポンス]** で、**[レスポンスを作成]** を選択します。
1. **[HTTP ステータスコード]** に「**400**」と入力します。
このレスポンスにはヘッダーを設定しません。
1. **[保存]** を選択します。
1. 次の手順を繰り返して 500 レスポンスを作成します。
このレスポンスにはヘッダーを設定しません。
Amazon S3 からの正常な統合レスポンスはバケットのリストを XML ペイロードとして返し、API Gateway からのデフォルトのメソッドレスポンスは JSON ペイロードを返すため、バックエンドの Content-Type ヘッダーパラメータ値をフロントエンドの対応する値にマッピングする必要があります。そうしないと、クライアントは、レスポンスの本文が実際には XML 文字列である場合に `application/json` のコンテンツタイプを受け取ってしまいます。以下に、設定の手順を示します。また、Date や Content-Length などの他のヘッダーパラメータをクライアントに表示することもできます。
**GET / メソッドのレスポンスヘッダーのマッピングを設定する**
1. **[統合レスポンス]** タブの **[デフォルト - レスポンス]** で、**[編集]** を選択します。
1. **Content-Length** ヘッダーに、マッピング値として「**integration.response.header.Content-Length**」と入力します。
1. **Content-Type** ヘッダーに、マッピング値として「**integration.response.header.Content-Type**」と入力します。
1. **Timestamp** ヘッダーに、マッピング値として「**integration.response.header.Date**」と入力します。
1. **[保存]** を選択します。結果は次のようになります。
1. **[統合レスポンス]** タブの **[統合レスポンス]** で、**[レスポンスを作成]** を選択します。
1. [**HTTP status regex (HTTP ステータスの正規表現)**]に「**4\\d{2}**」と入力します。これにより、すべての 4xx HTTP レスポンスのステータスコードがメソッドレスポンスにマッピングされます。
1. **[メソッドレスポンスのステータスコード]** で [**400**] を選択します。
1. **[作成]** を選択します。
1. 次の手順を繰り返して、500 メソッドレスポンスの統合レスポンスを作成します。[**HTTP status regex (HTTP ステータスの正規表現)**]に「**5\\d{2}**」と入力します。
作業を適切に進めるために、ここまで設定した API をテストできます。
**`GET /` メソッドをテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[テスト]** を選択します。結果は次の図のようになります。
## Amazon S3 バケットにアクセスする API のメソッドを公開する
Amazon S3 バケットを使用するには、/{folder} リソースの `GET` メソッドを公開して、バケット内のオブジェクトを一覧表示します。手順は、[呼び出し元の Amazon S3 バケットを一覧表示する API のメソッドを公開する](#api-root-get-as-s3-get-service) で説明されている手順と同様です。その他のメソッドについては、サンプル API をこちら ([Amazon S3 のプロキシとしてのサンプル API の OpenAPI 定義](api-as-s3-proxy-export-swagger-with-extensions.md)) でインポートできます。
**フォルダリソースで GET メソッドを公開するには**
1. **/{folder}** リソースを選択し、**[メソッドを作成]** を選択します。
1. メソッドタイプとして、**[GET]** を選択します。
1. **[統合タイプ]** で、**[AWS のサービス]** を選択します。
1. **[AWS リージョン]** で、Amazon S3 バケットを作成した AWS リージョンを選択します。
1. **[AWS のサービス]** で、**[Amazon Simple Storage Service]** を選択します。
1. **[AWS サブドメイン]** は空白のままにします。
1. **[HTTP メソッド]** で、**[GET]** を選択します。
1. **[アクションタイプ]** で、**[パスオーバーライドを使用]** を選択します。
1. **[パスオーバーライド]** に「**{bucket}**」と入力します。
1. **[実行ロール]** に、**APIGatewayS3ProxyPolicy** のロール ARN を入力します。
1. **[メソッドの作成]** を選択します。
Amazon S3 エンドポイントの URL で `{folder}` パスパラメータを設定します。メソッドリクエストの `{folder}` パスパラメータを統合リクエストの `{bucket}` パスパラメータにマッピングする必要があります。
**`{folder}` を `{bucket}` にマッピングするには**
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で **[編集]** を選択します。
1. **[URL パスパラメータ]**、**[パスパラメータを追加]** を選択します。
1. **[Name]** (名前) には **bucket** を入力します。
1. **[マッピング元]** として「**method.request.path.folder**」と入力します。
1. **[保存]** を選択します。
次に API をテストします。
**`/{folder} GET` メソッドをテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[パス]** の **[folder]** に、バケットの名前を入力します。
1. **[テスト]** を選択します。
テスト結果には、バケット内のオブジェクトのリストが含まれます。
## バケット内の Amazon S3 オブジェクトにアクセスする API のメソッドを公開する
Amazon S3 では、GET、DELETE、HEAD、OPTIONS、POST、PUT の各アクションで特定のバケット内のオブジェクトにアクセスし、管理することができます。このチュートリアルでは、`{folder}/{item}` リソースでバケットから画像を取得する `GET` メソッドを公開します。`{folder}/{item}` リソースのその他の用途については、サンプル API ([Amazon S3 のプロキシとしてのサンプル API の OpenAPI 定義](api-as-s3-proxy-export-swagger-with-extensions.md)) を参照してください。
**項目リソースで GET メソッドを公開するには**
1. **/{item}** リソースを選択し、**[メソッドを作成]** を選択します。
1. メソッドタイプとして、**[GET]** を選択します。
1. **[統合タイプ]** で、**[AWS のサービス]** を選択します。
1. **[AWS リージョン]** で、Amazon S3 バケットを作成した AWS リージョンを選択します。
1. **[AWS のサービス]** で、**[Amazon Simple Storage Service]** を選択します。
1. **[AWS サブドメイン]** は空白のままにします。
1. **[HTTP メソッド]** で、**[GET]** を選択します。
1. **[アクションタイプ]** で、**[パスオーバーライドを使用]** を選択します。
1. **[パスオーバーライド]** に、「**{bucket}/{object}**」と入力します。
1. **[実行ロール]** に、**APIGatewayS3ProxyPolicy** のロール ARN を入力します。
1. **[メソッドの作成]** を選択します。
Amazon S3 エンドポイント URL で `{folder}` パスパラメータと `{item}` パスパラメータを設定します。メソッドリクエストの パスパラメータを統合リクエストの パスパラメータにマッピングする必要があります。
このステップでは、次の作業を行います。
+ メソッドリクエストの `{folder}` パスパラメータを統合リクエストの `{bucket}` パスパラメータにマッピングします。
+ メソッドリクエストの `{item}` パスパラメータを統合リクエストの `{object}` パスパラメータにマッピングします。
**`{folder}` を `{bucket}` に、`{item}` を `{object}` にマッピングするには**
1. **[統合リクエスト]** タブの **[統合リクエストの設定]** で、**[編集]** を選択します。
1. **[URL パスパラメータ]** を選択します。
1. **[パスパラメータを追加]** を選択します。
1. **[Name]** (名前) には **bucket** を入力します。
1. **[マッピング元]** として「**method.request.path.folder**」と入力します。
1. **[パスパラメータを追加]** を選択します。
1. **[Name]** (名前) には **object** を入力します。
1. **[マッピング元]** として「**method.request.path.item**」と入力します。
1. **[保存]** を選択します。
**`/{folder}/{object} GET` メソッドをテストするには**
1. **[テスト]** タブを選択します。タブを表示するには、右矢印ボタンを選択する必要がある場合があります。
1. **[パス]** の **[folder]** に、バケットの名前を入力します。
1. **[パス]** の **[item]** に、項目の名前を入力します。
1. **[テスト]** を選択します。
レスポンス本文に項目の内容が含まれます。
リクエストは、指定した Amazon S3 バケット (amzn-s3-demo-bucket) の指定したファイル (test.txt) のコンテンツとして、プレーンテキストの (「Hello world」) を正しく返します。
API Gateway で UTF-8 でエンコードされた JSON 以外のコンテンツとみなされるバイナリファイルをダウンロードまたはアップロードするには、API に追加の設定が必要です。次のように説明されています。
**S3 からバイナリファイルをダウンロードまたは S3 にアップロードするには**
1. 影響を受けるファイルのメディアの種類を API の binaryMediaTypes に登録します。これは、コンソールで登録できます。
1. API の **[API 設定]** を選択します。
1. **[バイナリメディアタイプ]** で、**[メディアタイプを管理]** を選択します。
1. **[バイナリメディアタイプを追加]** を選択し、必要なメディアタイプ (例: `image/png`) を入力します。
1. **[Save changes]** (変更の保存) を選択して設定を保存します。
1. `Content-Type` ヘッダー (アップロードの場合) と `Accept` ヘッダー (ダウンロードの場合) をメソッドリクエストに追加し、必要なバイナリメディアタイプを指定するようにクライアントに要求して、統合リクエストにマッピングします。
1. 登録リクエスト (アップロードの場合) および 統合レスポンス (ダウンロードの場合) で、[**コンテンツの処理**] を [`Passthrough`] に設定します。影響のあるコンテンツタイプで定義されているマッピングテンプレートがないことを確認します。詳細については、「[API Gateway での REST API のデータ変換](rest-api-data-transformations.md)」を参照してください。
ペイロードサイズの上限は 10 MB です。「[API Gateway での REST API の設定および実行に関するクォータ](api-gateway-execution-service-limits-table.md)」を参照してください。
Amazon S3 のファイルのメタデータに正しいコンテンツタイプが追加されていることを確認してください。ストリーミング可能なメディアコンテンツの場合も、`Content-Disposition:inline` をメタデータに追加する必要がある場合があります。
API Gateway でのバイナリのサポートの詳細については、「[API Gateway でのコンテンツタイプの変換](api-gateway-payload-encodings-workflow.md)」を参照してください。