# API Gatewayのリクエスト変換マッピングテンプレートの使い方

## 目次
1. はじめに
2. マッピングテンプレートとは
3. マッピングテンプレートの設定方法
   - 3.1 コンソールでの設定手順
   - 3.2 テンプレートの記述方法
4. リクエストデータの変換
   - 4.1 JSONから別の形式への変換
   - 4.2 Query StringsとHeadersの追加
5. ベストプラクティス
6. よくある問題とその対策
7. まとめ

## 1. はじめに
API Gatewayを利用する際、クライアントから受け取ったデータをLambdaまたはHTTPエンドポイントに渡す前に、データ形式を変換する必要がある場合があります。このような場面で役立つのがマッピングテンプレートです。このテンプレートを用いることで、リクエストデータを自由に加工・変換することができます。

## 2. マッピングテンプレートとは
マッピングテンプレートは、API Gatewayが受け取るリクエストデータを別の形式に変換するための手段です。通常、テンプレートを記述するためにVelocity Template Language (VTL)を使用します。VTLは、シンプルな構文でパターンマッチングと変数挿入をサポートします。

## 3. マッピングテンプレートの設定方法

### 3.1 コンソールでの設定手順
1. AWSコンソールにログインし、API Gatewayのダッシュボードにアクセスします。
2. 使用中のAPIを選択し、「リソース」タブをクリックします。
3. 対象エンドポイント（メソッド）を選び、「統合リクエスト」セクションに移動します。
4. 「リクエスト本文のパススルー: マッピングテンプレートを追加」を選択し、内容を記述します。

### 3.2 テンプレートの記述方法
テンプレートを記述する際は、VTLの構文に従って変数などを使用します。例えば、以下のようにJSONデータを加工するテンプレートを書くことができます。

![img](/mosaic-code.jpg)

## 4. リクエストデータの変換

### 4.1 JSONから別の形式への変換
VTLを使用して、受信したJSONデータをXML、CSVなど、ほかのデータ形式に変換することができます。

### 4.2 Query StringsとHeadersの追加
テンプレートを活用して、リクエストに特定のクエリパラメータやヘッダーを動的に追加できます。例えば、特定のリクエストIDをヘッダーに付加する場合:

![img](/mosaic-code.jpg)
また、
![img](/mosaic-code.jpg)

## 5. ベストプラクティス
- **エラーハンドリング** : マッピングテンプレートでエラーが発生すると、そのままエラーが返されるため、エラーチェックは特に重点を置くことが重要です。
- **デバッグログの使用**: 開発中は `$context.xraySampling` や `$util.error` などのデバッグを利用して、テンプレートの動作を確認します。

## 6. よくある問題とその対策
- **テンプレートエラー** : 意図しない結果を避けるために、必ずテンプレートをテストし、正しい結果を生成することを確認しましょう。
- **データ型の不一致** : データ形式を正しく設定することが不可欠です。想定されるデータ型によって処理が異なる場合がありますので注意してください。

## 7. まとめ
API Gatewayのリクエスト変換マッピングテンプレートは、エンドポイントに適したデータ形式でリクエストを送信するために非常に有効です。適切に用いることで、効率的なデータ処理とエンドポイント間の疎結合を実現できます。テンプレートの設定は手間がかかる反面、大きな柔軟性と制御を提供します。

API Gatewayを用いた開発の知識を深め、さらなる効率化と柔軟性を追及するために、ぜひこの機能を活用してください。 [cv:issue_marketplace_engineer]

# API Gatewayのリクエスト変換マッピングテンプレートの使い方

## 目次
1. はじめに
2. マッピングテンプレートとは
3. マッピングテンプレートの設定方法
   - 3.1 コンソールでの設定手順
   - 3.2 テンプレートの記述方法
4. リクエストデータの変換
   - 4.1 JSONから別の形式への変換
   - 4.2 Query StringsとHeadersの追加
5. ベストプラクティス
6. よくある問題とその対策
7. まとめ

## 1. はじめに
API Gatewayを利用する際、クライアントから受け取ったデータをLambdaまたはHTTPエンドポイントに渡す前に、データ形式を変換する必要がある場合があります。このような場面で役立つのがマッピングテンプレートです。このテンプレートを用いることで、リクエストデータを自由に加工・変換することができます。

## 2. マッピングテンプレートとは
マッピングテンプレートは、API Gatewayが受け取るリクエストデータを別の形式に変換するための手段です。通常、テンプレートを記述するためにVelocity Template Language (VTL)を使用します。VTLは、シンプルな構文でパターンマッチングと変数挿入をサポートします。

## 3. マッピングテンプレートの設定方法

### 3.1 コンソールでの設定手順
1. AWSコンソールにログインし、API Gatewayのダッシュボードにアクセスします。
2. 使用中のAPIを選択し、「リソース」タブをクリックします。
3. 対象エンドポイント（メソッド）を選び、「統合リクエスト」セクションに移動します。
4. 「リクエスト本文のパススルー: マッピングテンプレートを追加」を選択し、内容を記述します。

### 3.2 テンプレートの記述方法
テンプレートを記述する際は、VTLの構文に従って変数などを使用します。例えば、以下のようにJSONデータを加工するテンプレートを書くことができます。

```json
#set($inputRoot = $input.path('$'))
{
    "orderId" : "$inputRoot.orderId",
    "customerName": "$inputRoot.customer.name",
    "orderTotal": $inputRoot.total
}
```

## 4. リクエストデータの変換

### 4.1 JSONから別の形式への変換
VTLを使用して、受信したJSONデータをXML、CSVなど、ほかのデータ形式に変換することができます。

### 4.2 Query StringsとHeadersの追加
テンプレートを活用して、リクエストに特定のクエリパラメータやヘッダーを動的に追加できます。例えば、特定のリクエストIDをヘッダーに付加する場合:

```plaintext
#set($request.querystring.newParam = "newValue")
```
また、
```velocity
#set($context.requestOverride.header.MyHeader = "myHeaderValue")
```

## 5. ベストプラクティス
- **エラーハンドリング** : マッピングテンプレートでエラーが発生すると、そのままエラーが返されるため、エラーチェックは特に重点を置くことが重要です。
- **デバッグログの使用**: 開発中は `$context.xraySampling` や `$util.error` などのデバッグを利用して、テンプレートの動作を確認します。

## 6. よくある問題とその対策
- **テンプレートエラー** : 意図しない結果を避けるために、必ずテンプレートをテストし、正しい結果を生成することを確認しましょう。
- **データ型の不一致** : データ形式を正しく設定することが不可欠です。想定されるデータ型によって処理が異なる場合がありますので注意してください。

## 7. まとめ
API Gatewayのリクエスト変換マッピングテンプレートは、エンドポイントに適したデータ形式でリクエストを送信するために非常に有効です。適切に用いることで、効率的なデータ処理とエンドポイント間の疎結合を実現できます。テンプレートの設定は手間がかかる反面、大きな柔軟性と制御を提供します。

API Gatewayを用いた開発の知識を深め、さらなる効率化と柔軟性を追及するために、ぜひこの機能を活用してください。 

API Gatewayのリクエスト変換マッピングテンプレートの使い方

目次

続きを読むには単価診断を受けてください（30秒）