

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

# AWS AppSync リゾルバーマッピングテンプレートの変更ログ

**注記**  
現在、主に APPSYNC\_JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\_JS ランタイムとそのガイドの使用をご検討ください。

リゾルバーと関数のマッピングテンプレートはバージョニングされています。`2018-05-29` などのマッピングテンプレートバージョンは、以下を決定します。
+ リクエストテンプレートによって提供されるデータソースリクエスト設定の想定される形式
+ リクエストマッピングテンプレートとレスポンスマッピングテンプレートの実行動作

バージョンは YYYY-MM-DD 形式を使用して表され、より後の日付はより新しいバージョンに対応します。このページには、 AWS AppSyncで現在サポートされているマッピングテンプレートのバージョン間の違いが一覧表示されます。

**Topics**
+ [バージョンごとのデータソースオペレーションの可用性一覧](#aws-appsync-resolver-mapping-template-operation-availability-per-version)
+ [ユニットリゾルバーのマッピングテンプレートのバージョンの変更](#changing-the-version-on-a-unit-resolver-mapping-template)
+ [関数のバージョンの変更](#changing-the-version-on-a-function)
+ [2018-05-29](#aws-appsync-resolver-mapping-template-version-2018-05-29)
+ [2017-02-28](#aws-appsync-resolver-mapping-template-version-2017-02-28)

## バージョンごとのデータソースオペレーションの可用性一覧
<a name="aws-appsync-resolver-mapping-template-operation-availability-per-version"></a>


| オペレーション/サポートされているバージョン | 2017-02-28 | 2018-05-29 | 
| --- | --- | --- | 
| AWS Lambda 呼び出し | はい  | はい | 
| AWS Lambda BatchInvoke | はい  | はい | 
| none データソース | はい  | はい | 
| Amazon OpenSearch GET | はい  | はい | 
| Amazon OpenSearch POST | はい  | はい | 
| Amazon OpenSearch PUT | はい  | はい | 
| Amazon OpenSearch DELE | はい  | はい | 
| Amazon OpenSearch GET | はい  | はい | 
| DynamoDB GetItem | はい  | はい | 
| DynamoDB Scan | はい  | はい | 
| DynamoDB Query | はい  | はい | 
| DynamoDB DeleteItem | はい  | はい | 
| DynamoDB PutItem | はい  | はい | 
| DynamoDB BatchGetItem | いいえ | はい | 
| DynamoDB BatchPutItem | いいえ | はい | 
| DynamoDB BatchDeleteItem | いいえ | はい | 
| HTTP | いいえ | はい | 
| Amazon RDS | いいえ | はい | 

 **注意**: 関数で現在サポートされているのは **2018-05-29** バージョンのみです。

## ユニットリゾルバーのマッピングテンプレートのバージョンの変更
<a name="changing-the-version-on-a-unit-resolver-mapping-template"></a>

ユニットリゾルバーの場合、バージョンはリクエストマッピングテンプレートの本文の一部として指定されています。バージョンを更新するには、`version` フィールドを新しいバージョンに更新するだけです。

たとえば、 AWS Lambda テンプレートのバージョンを更新するには:

```velocity
{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}
```

以下のように version フィールドを `2017-02-28` から `2018-05-29` に更新する必要があります。

```velocity
{
    "version": "2018-05-29", ## Note the version
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}
```

## 関数のバージョンの変更
<a name="changing-the-version-on-a-function"></a>

関数の場合、バージョンは function オブジェクトの `functionVersion` フィールドとして指定されています。バージョンを更新するには、`functionVersion` を更新するだけです。*注意:* 現在、関数では `2018-05-29` のみがサポートされています。

以下に示しているのは、既存の関数バージョンを更新する CLI コマンドの例です。

```
aws appsync update-function \
--api-id REPLACE_WITH_API_ID \
--function-id REPLACE_WITH_FUNCTION_ID \
--data-source-name "PostTable" \
--function-version "2018-05-29" \
--request-mapping-template "{...}" \
--response-mapping-template "\$util.toJson(\$ctx.result)"
```

 **注意:** 関数のリクエストマッピングテンプレートから version フィールドを省略することをお勧めします。それにより、このフィールドが優先されなくなります。関数のリクエストマッピングテンプレート内でバージョンを指定した場合、version の値は `functionVersion` フィールドの値によって書き換えられます。

## 2018-05-29
<a name="aws-appsync-resolver-mapping-template-version-2018-05-29"></a>

### 動作の変更
<a name="behavior-change"></a>
+ データソースの呼び出しの結果が `null` の場合は、レスポンスマッピングテンプレートが実行されます。
+ データソースの呼び出しでエラーが発生した場合、エラーを処理するのはお客様です。レスポンスマッピングテンプレートの評価結果は**常に** GraphQL レスポンスの `data` ブロック内に挿入されます。

### 理由
<a name="reasoning"></a>
+ `null` の呼び出し結果には意味があり、アプリケーションのユースケースによっては、`null` の結果を独自の方法で処理することが必要になる場合があります。たとえば、アプリケーションで承認チェックを実行するために、Amazon DynamoDB テーブルにレコードが存在するかどうかを確認するとします。この場合、`null` の呼び出し結果は、ユーザーが承認されていない可能性があることを意味します。レスポンスマッピングテンプレートを実行することで、承認エラーを発生させることが可能になりました。この動作により、API 設計者はより強力な制御機能を得られます。

以下のレスポンスマッピングテンプレートがあるとします。

```velocity
$util.toJson($ctx.result)
```

以前、`2017-02-28` では、`$ctx.result` から null が返された場合、レスポンスマッピングテンプレートは実行されませんでした。`2018-05-29` では、このシナリオを処理できるようになりました。たとえば、以下のように承認エラーを発生させることが可能です。

```velocity
# throw an unauthorized error if the result is null
#if ( $util.isNull($ctx.result) )
    $util.unauthorized()
#end
$util.toJson($ctx.result)
```

 **注意:** データソースから返されるエラーの中には、致命的でないものがあり、予期できないものもあります。そのため、レスポンスマッピングテンプレートには、呼び出しエラーを処理して、無視するか、再発生させるか、別のエラーをスローするかを判断する柔軟性が必要になります。

以下のレスポンスマッピングテンプレートがあるとします。

```velocity
$util.toJson($ctx.result)
```

以前、`2017-02-28` では、呼び出しエラーが発生した場合にレスポンスマッピングテンプレートが評価され、結果は GraphQL レスポンスの `errors` ブロックに自動的に挿入されていました。`2018-05-29` では、エラーをどう処理するか、再発生させるか、別のエラーを発生させるか、またはデータを返すときにエラーを付加するかを選択できるようになりました。

### 呼び出しエラーを再発生させる
<a name="re-raise-an-invocation-error"></a>

以下のレスポンステンプレートでは、データソースから返されたものと同じエラーを発生させます。

```velocity
#if ( $ctx.error )
    $util.error($ctx.error.message, $ctx.error.type)
#end
$util.toJson($ctx.result)
```

呼び出しエラー (`$ctx.error` など) の場合、レスポンスは以下のようになります。

```json
{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "DynamoDB:ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}
```

### 別のエラーを発生させる
<a name="raise-a-different-error"></a>

以下のレスポンステンプレートでは、データソースから返されたエラーを処理した後で、カスタムエラーを発生させます。

```velocity
#if ( $ctx.error )
    #if ( $ctx.error.type.equals("ConditionalCheckFailedException") )
        ## we choose here to change the type and message of the error for ConditionalCheckFailedExceptions
        $util.error("Error while updating the post, try again. Error: $ctx.error.message", "UpdateError")
    #else
        $util.error($ctx.error.message, $ctx.error.type)
    #end
#end
$util.toJson($ctx.result)
```

呼び出しエラー (`$ctx.error` など) の場合、レスポンスは以下のようになります。

```json
{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "UpdateError",
            "message": "Error while updating the post, try again. Error: Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}
```

### データを返すときにエラーを付加する
<a name="append-an-error-to-return-data"></a>

以下のレスポンステンプレートでは、レスポンス内でデータを返すときに、データソースから返されたものと同じエラーを追加します。これは、部分レスポンスとも呼ばれます。

```velocity
#if ( $ctx.error )
    $util.appendError($ctx.error.message, $ctx.error.type)
    #set($defaultPost = {id: "1", title: 'default post'})
    $util.toJson($defaultPost)
#else
    $util.toJson($ctx.result)
#end
```

呼び出しエラー (`$ctx.error` など) の場合、レスポンスは以下のようになります。

```json
{
    "data": {
        "getPost": {
            "id": "1",
            "title: "A post"
        }
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}
```

#### *2017-02-28* から *2018-05-29* への移行
<a name="migrating-from-2017-02-28-to-2018-05-29"></a>

**2017-02-28** から **2018-05-29** への移行は簡単です。リゾルバーのリクエストマッピングテンプレートの version フィールドまたは関数の version オブジェクトを変更します。ただし、**2018-05-29** と **2017-02-28** では実行動作が異なるため、変更点について[こちら](#aws-appsync-resolver-mapping-template-version-2018-05-29)で概要を説明しています。

#### *2017-02-28* から *2018-05-29* への同じ実行動作の保持
<a name="preserving-the-same-execution-behavior-from-2017-02-28-to-2018-05-29"></a>

場合によっては、同じ実行動作を保持できる場合もあります。tたとえば**2018-05-29**バージョン管理されたテンプレートを実行しながら**2017-02-28**を実行することが可能です。

### 例: DynamoDB PutItem
<a name="example-dynamodb-putitem"></a>

以下の **2017-02-28** DynamoDB PutItem リクエストテンプレートがあるとします。

```velocity
{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}
```

また、以下のレスポンステンプレートがあるとします。

```velocity
$util.toJson($ctx.result)
```

**2018-05-29** に移行すると、これらのテンプレートは以下のように変更されます。

```velocity
{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}
```

また、レスポンステンプレートは以下のように変更されます。

```velocity
## If there is a datasource invocation error, we choose to raise the same error
## the field data will be set to null.
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

$util.toJson($ctx.result)
```

エラーを処理するのはお客様であるため、DynamoDB から返された `$util.error()` を使用して同じエラーが発生するようにしました。マッピングテンプレートを **2018-05-29** に変換するようにこのスニペットを調整できます。レスポンステンプレートが異なる場合は、実行動作が変わることを考慮する必要があります。

### 例: DynamoDB GetItem
<a name="example-dynamodb-getitem"></a>

以下の **2017-02-28** DynamoDB GetItem リクエストテンプレートがあるとします。

```velocity
{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}
```

また、以下のレスポンステンプレートがあるとします。

```velocity
## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)
```

**2018-05-29** に移行すると、これらのテンプレートは以下のように変更されます。

```velocity
{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}
```

また、レスポンステンプレートは以下のように変更されます。

```velocity
## If there is a datasource invocation error, we choose to raise the same error
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)
```

**2017-02-28** バージョンでは、データソースの呼び出しが `null` の場合は、DynamoDB テーブルにキーと一致する項目がないことを意味します。そのため、レスポンスマッピングテンプレートは実行されません。ほとんどの場合は問題ありませんが、`$ctx.result` が `null` ではないと想定される場合は、そのシナリオを処理する必要があります。

## 2017-02-28
<a name="aws-appsync-resolver-mapping-template-version-2017-02-28"></a>

### 特性
<a name="characteristics"></a>
+ データソースの呼び出し結果が `null` の場合、レスポンスマッピングテンプレートは実行**されません**。
+ データソースの呼び出しでエラーが発生した場合、レスポンスマッピングテンプレートは実行され、評価結果は GraphQL レスポンスの `errors.data` ブロック内に挿入されます。