本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立基本查詢 (VTL)
**注意**
我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)使用 APPSYNC\$1JS 執行期及其指南。
GraphQL 解析程式將類型結構描述中的欄位連接到資料來源。解析程式是滿足請求的機制。 AWS AppSync 可以從結構描述自動建立和連接解析程式，或從現有資料表建立結構描述並連接解析程式，而無需撰寫任何程式碼。
Resolvers in AWS AppSync 使用 JavaScript 將 GraphQL 表達式轉換為資料來源可以使用的格式。或者，映射範本可以用 [Apache Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/2.0/vtl-reference.html) 撰寫，將 GraphQL 表達式轉換為資料來源可以使用的格式。
本節將說明如何使用 VTL 設定解析程式。您可以在[解析程式映射範本程式設計指南中找到編寫解析程式的教學風格程式設計指南](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide)，以及可在[解析程式映射範本內容參考](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference)中找到程式設計時使用的協助程式公用程式。 AWS AppSync 也有內建測試和偵錯流程，可讓您從頭開始編輯或撰寫時使用。如需詳細資訊，請參閱[測試和偵錯解析程式](test-debug-resolvers.md#aws-appsync-test-debug-resolvers)。
我們建議您先遵循本指南，再嘗試使用任何上述教學課程。
在本節中，我們將逐步解說如何建立解析程式、為變動新增解析程式，以及使用進階組態。
## 建立您的第一個解析程式
遵循先前章節的範例，第一個步驟是為您的 `Query` 類型建立解析程式。
------
#### [ Console ]
1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。
1. 在 **APIs儀表板**中，選擇您的 GraphQL API。
1. 在**側邊欄中**，選擇**結構描述**。
1. 在頁面右側，有一個稱為**解析程式**的視窗。此方塊包含頁面左側**結構描述**視窗中定義的類型和欄位清單。您可以將解析程式連接至欄位。例如，在**查詢**類型下，選擇 `getTodos` 欄位旁的**連接**。
1. 在**建立解析程式**頁面上，選擇您在[連接資料來源指南中建立的資料來源](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html)。在**設定映射範本**視窗中，您可以使用右側的下拉式清單選擇一般請求和回應映射範本，或自行撰寫。
**注意**
將請求映射範本與回應映射範本配對稱為單位解析程式。單位解析程式通常用於執行輪換操作；我們建議僅將它們用於具有少量資料來源的單一操作。對於更複雜的操作，我們建議使用管道解析程式，其可以依序使用多個資料來源執行多個操作。
如需請求與回應映射範本之間差異的詳細資訊，請參閱[單位解析程式](https://docs.aws.amazon.com//appsync/latest/devguide/resolver-mapping-template-reference-overview.html#unit-resolvers)。
如需使用管道解析程式的詳細資訊，請參閱[管道解析程式](pipeline-resolvers.md#aws-appsync-pipeline-resolvers)。
1. 對於常見的使用案例， AWS AppSync 主控台具有內建範本，可用於從資料來源取得項目 （例如，所有項目查詢、個別查詢等）。例如，在設計`getTodos`沒有分頁的[結構](designing-your-schema.md#aws-appsync-designing-your-schema)描述的簡單版本上，列出項目的請求映射範本如下所示：
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. 您一律需要回應映射範本來隨附請求。主控台為清單提供具有下列傳遞值的預設值：
```
$util.toJson($ctx.result.items)
```
在這個範例中，項目清單的 `context` 物件 (別名為 `$ctx`) 為 `$context.result.items` 格式。如果您的 GraphQL 操作傳回單一項目，則會是 `$context.result`。 AWS AppSync 提供常見操作的協助程式函數，例如先前列出的`$util.toJson`函數，以正確格式化回應。如需函數的完整清單，請參閱[解析程式映射範本公用程式參考](resolver-util-reference.md#aws-appsync-resolver-mapping-template-util-reference)。
1. 選擇**儲存解析程式**。
------
#### [ API ]
1. 呼叫 [https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_CreateResolver.html) API 來建立解析程式物件。
1. 您可以呼叫 [https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html](https://docs.aws.amazon.com/appsync/latest/APIReference/API_UpdateResolver.html) API 來修改解析程式的欄位。
------
#### [ CLI ]
1. 執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)命令來建立解析程式。
您需要為此特定命令輸入 6 個參數：
1. 您 API `api-id`的 。
1. 您想要在結構描述中修改`type-name`的類型 。在主控台範例中，這是 `Query`。
1. 您要在類型中修改的欄位`field-name`的 。在主控台範例中，這是 `getTodos`。
1. 您在連接資料來源指南中建立`data-source-name`的資料來源的 。 [https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html)
1. `request-mapping-template`，這是請求的內文。在主控台範例中，這是：
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
1. `response-mapping-template`，這是回應的內文。在主控台範例中，這是：
```
$util.toJson($ctx.result.items)
```
範例命令可能如下所示：
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Query --field-name getTodos --data-source-name TodoTable --request-mapping-template "{ "version" : "2017-02-28", "operation" : "Scan", }" --response-mapping-template ""$"util.toJson("$"ctx.result.items)"
```
輸出會在 CLI 中傳回。範例如下：
```
{
"resolver": {
"kind": "UNIT",
"dataSourceName": "TodoTable",
"requestMappingTemplate": "{ version : 2017-02-28, operation : Scan, }",
"resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query/resolvers/getTodos",
"typeName": "Query",
"fieldName": "getTodos",
"responseMappingTemplate": "$util.toJson($ctx.result.items)"
}
}
```
1. 若要修改解析程式的欄位和/或映射範本，請執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-resolver.html)命令。
除了 `api-id` 參數之外，`create-resolver`命令中使用的參數會被`update-resolver`命令中的新值覆寫。
------
## 新增變動的解析程式
下一個步驟是為您的 `Mutation` 類型建立解析程式。
------
#### [ Console ]
1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。
1. 在 **APIs儀表板**中，選擇您的 GraphQL API。
1. 在**側邊欄中**，選擇**結構描述**。
1. 在**變動**類型下，選擇`addTodo`欄位旁的**連接**。
1. 在**建立解析程式**頁面上，選擇您在[連接資料來源指南中建立的資料來源](https://docs.aws.amazon.com/appsync/latest/devguide/attaching-a-data-source.html)。
1. 在**設定映射範本**視窗中，您將需要修改請求範本，因為這是您要將新項目新增至 DynamoDB 的變動。請使用下列要求映射範本：
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
1. AWS AppSync 會自動將 `addTodo` 欄位中定義的引數從 GraphQL 結構描述轉換為 DynamoDB 操作。先前的範例使用 索引鍵將記錄存放在 DynamoDB 中`id`，該索引鍵會從變動引數傳遞為 `$ctx.args.id`。您傳遞的所有其他欄位都會使用 自動映射至 DynamoDB 屬性`$util.dynamodb.toMapValuesJson($ctx.args)`。
在此解析程式中，使用下列的回應映射範本：
```
$util.toJson($ctx.result)
```
AWS AppSync 也支援用於編輯解析程式的測試和偵錯工作流程。您可以使用模擬 `context` 物件，先查看範本轉換後的值，然後再叫用。或者，您可以在執行查詢時以互動方式檢視對資料來源的完整要求執行。如需詳細資訊，請參閱[測試和偵錯解析程式](test-debug-resolvers.md#aws-appsync-test-debug-resolvers)以及[監控和記錄](monitoring.md#aws-appsync-monitoring)。
1. 選擇**儲存解析程式**。
------
#### [ API ]
您也可以使用[建立第一個解析程式](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)區段中的命令和本節中的參數詳細資訊，以 APIs 執行此操作。
------
#### [ CLI ]
您也可以使用[建立第一個解析程式](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)區段中的命令和本節中的參數詳細資訊，在 CLI 中執行此操作。
------
此時，如果您未使用進階解析程式，您可以開始使用 GraphQL API，如[使用 API](using-your-api.md#aws-appsync-using-your-api) 中所述。
## 進階解析程式
如果您遵循進階區段，並在[設計結構描述以執行分頁掃描中建置範例結構描述](designing-your-schema.md#aws-appsync-designing-your-schema)，請改用下列請求範本做為 `getTodos` 欄位：
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"limit": $util.defaultIfNull(${ctx.args.limit}, 20),
"nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}
```
對此分頁使用案例而言，回應映射不只是傳遞，因為其中必須包含*游標* (讓用戶端了解接下來從哪個頁面開始) 和結果集。映射範本如下所示：
```
{
"todos": $util.toJson($context.result.items),
"nextToken": $util.toJson($context.result.nextToken)
}
```
前述回應映射範本的欄位，應符合 `TodoConnection` 類型之中定義的欄位。
對於您擁有`Comments`資料表且正在解析`Todo`類型 （傳回 類型的`[Comment]`) 註解欄位的關係，您可以使用對第二個資料表執行查詢的映射範本。若要這樣做，您必須已經建立`Comments`資料表的資料來源，如[連接資料來源](attaching-a-data-source.md#aws-appsync-getting-started-build-a-schema-from-scratch)中所述。
**注意**
我們針對第二個資料表使用查詢操作，僅供說明之用。您可以改為對 DynamoDB 使用其他操作。此外，您可以從其他資料來源提取資料，例如 AWS Lambda 或 Amazon OpenSearch Service，因為關係是由 GraphQL 結構描述控制。
------
#### [ Console ]
1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。
1. 在 **APIs儀表板**中，選擇您的 GraphQL API。
1. 在**側邊欄中**，選擇**結構描述**。
1. 在**待辦事項**類型下，選擇`comments`欄位旁的**連接**。
1. 在**建立解析程式**頁面上，選擇您的**註解**資料表資料來源。快速入門指南中**註解**資料表的預設名稱為 `AppSyncCommentTable`，但可能會因您提供的名稱而有所不同。
1. 將下列程式碼片段新增至您的請求映射範本：
```
{
"version": "2017-02-28",
"operation": "Query",
"index": "todoid-index",
"query": {
"expression": "todoid = :todoid",
"expressionValues": {
":todoid": {
"S": $util.toJson($context.source.id)
}
}
}
}
```
1. `context.source` 參照目前正在解析之欄位的父物件。在這個範例中，`source.id` 代表個別 `Todo` 物件，這個物件會在稍後用於查詢表達式。
您可使用傳遞回應映射範本，如下所示：
```
$util.toJson($ctx.result.items)
```
1. 選擇**儲存解析程式**。
1. 最後，回到 主控台的**結構描述**頁面，將解析程式連接到 `addComment` 欄位，並指定`Comments`資料表的資料來源。在這種情況下，要求映射範本是簡單的 `PutItem`，其中具有註解為引數的特定 `todoid`，但您需要使用 `$utils.autoId()` 公用程式來為註解建立唯一的排序索引鍵，如下所示：
```
{
"version": "2017-02-28",
"operation": "PutItem",
"key": {
"todoid": { "S": $util.toJson($context.arguments.todoid) },
"commentid": { "S": "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
使用傳遞回應範本，如下所示：
```
$util.toJson($ctx.result)
```
------
#### [ API ]
您也可以使用[建立第一個解析程式](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)區段中的命令和本節中的參數詳細資訊，以 APIs 執行此操作。
------
#### [ CLI ]
您也可以使用[建立第一個解析程式](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html#create-your-first-resolver)區段中的命令和本節中的參數詳細資訊，在 CLI 中執行此操作。
------
# 使用直接 Lambda 解析程式 (VTL) 停用 VTL 映射範本
**注意**
我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)使用 APPSYNC\$1JS 執行期及其指南。
使用直接 Lambda 解析程式時，您可以避免使用 VTL 映射範本 AWS Lambda 。 AWS AppSync 可以為您的 Lambda 函數提供預設承載，以及從 Lambda 函數對 GraphQL 類型的回應進行預設轉譯。您可以選擇提供請求範本、回應範本，或由 and AWS AppSync 處理。
若要進一步了解 AWS AppSync 提供的預設請求承載和回應轉譯，請參閱 [Direct Lambda 解析程式參考](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers)。如需設定 AWS Lambda 資料來源和設定 IAM 信任政策的詳細資訊，請參閱[連接資料來源](attaching-a-data-source.md)。
## 設定直接 Lambda 解析程式
以下各節將說明如何連接 Lambda 資料來源，並將 Lambda 解析程式新增至您的欄位。
### 新增 Lambda 資料來源
您必須先新增 Lambda 資料來源，才能啟用直接 Lambda 解析程式。
------
#### [ Console ]
1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。
1. 在 **APIs儀表板**中，選擇您的 GraphQL API。
1. 在**側邊欄中**，選擇**資料來源**。
1. 選擇 **Create data source (建立資料來源)**。
1. 針對**資料來源名稱**，輸入資料來源的名稱，例如 **myFunction**。
1. 針對**資料來源類型**，選擇 **AWS Lambda 函數**。
1. 針對**區域**，選擇適當的區域。
1. 對於**函數 ARN**，從下拉式清單中選擇 Lambda 函數。您可以搜尋函數名稱，或手動輸入您要使用的函數 ARN。
1. 建立新的 IAM 角色 （建議） 或選擇具有 IAM `lambda:invokeFunction` 許可的現有角色。現有角色需要信任政策，如[連接資料來源](attaching-a-data-source.md)一節所述。
以下是 IAM 政策範例，其具有對資源執行操作所需的許可：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "lambda:invokeFunction" ],
"Resource": [
"arn:aws:lambda:us-west-2:123456789012:function:myFunction",
"arn:aws:lambda:us-west-2:123456789012:function:myFunction:*"
]
}
]
}
```
------
1. 選擇**建立**按鈕。
------
#### [ CLI ]
1. 執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-data-source.html)命令來建立資料來源物件。
您需要為此特定命令輸入 4 個參數：
1. 您 API `api-id`的 。
1. 資料來源`name`的 。在主控台範例中，這是**資料來源名稱**。
1. 資料來源`type`的 。在主控台範例中，這是 **AWS Lambda 函數**。
1. `lambda-config`，這是主控台範例中的**函數 ARN**。
**注意**
還有其他參數，例如 必須設定 `Region` ，但通常會預設為您的 CLI 組態值。
範例命令可能如下所示：
```
aws appsync create-data-source --api-id abcdefghijklmnopqrstuvwxyz --name myFunction --type AWS_LAMBDA --lambda-config lambdaFunctionArn=arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example
```
輸出會在 CLI 中傳回。範例如下：
```
{
"dataSource": {
"dataSourceArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/datasources/myFunction",
"type": "AWS_LAMBDA",
"name": "myFunction",
"lambdaConfig": {
"lambdaFunctionArn": "arn:aws:lambda:us-west-2:102847592837:function:appsync-lambda-example"
}
}
}
```
1. 若要修改資料來源的屬性，請執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/update-data-source.html)命令。
除了 `api-id` 參數之外，`create-data-source`命令中使用的參數將由`update-data-source`命令中的新值覆寫。
------
### 啟用直接 Lambda 解析程式
建立 Lambda 資料來源並設定適當的 IAM 角色以允許 AWS AppSync 叫用函數後，您可以將其連結至解析程式或管道函數。
------
#### [ Console ]
1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。
1. 在 **APIs儀表板**中，選擇您的 GraphQL API。
1. 在**側邊欄中**，選擇**結構描述**。
1. 在**解析程式**視窗中，選擇欄位或操作，然後選取**連接**按鈕。
1. 在**建立新的解析程式**頁面中，從下拉式清單中選擇 Lambda 函數。
1. 為了利用直接 Lambda 解析程式，請確認在**設定映射範本區段中已停用請求和回應映射範本**。
1. 選擇**儲存解析程式**按鈕。
------
#### [ CLI ]
+ 執行 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/appsync/create-resolver.html)命令來建立解析程式。
您需要為此特定命令輸入 6 個參數：
1. 您 API `api-id`的 。
1. 結構描述中 `type-name` 類型的 。
1. 結構描述中 欄位`field-name`的 。
1. `data-source-name`或您的 Lambda 函數名稱。
1. `request-mapping-template`，這是請求的內文。在主控台範例中，已停用：
```
" "
```
1. `response-mapping-template`，這是回應的內文。在主控台範例中，這也已停用：
```
" "
```
範例命令可能如下所示：
```
aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Subscription --field-name onCreateTodo --data-source-name LambdaTest --request-mapping-template " " --response-mapping-template " "
```
輸出會在 CLI 中傳回。範例如下：
```
{
"resolver": {
"resolverArn": "arn:aws:appsync:us-west-2:102847592837:apis/abcdefghijklmnopqrstuvwxyz/types/Subscription/resolvers/onCreateTodo",
"typeName": "Subscription",
"kind": "UNIT",
"fieldName": "onCreateTodo",
"dataSourceName": "LambdaTest"
}
}
```
------
當您停用映射範本時，會在 中發生幾個額外的行為 AWS AppSync：
+ 透過停用映射範本，您要向 發出訊號 AWS AppSync ，表示您接受 [Direct Lambda 解析程式參考](resolver-mapping-template-reference-lambda.md#direct-lambda-resolvers)中指定的預設資料轉譯。
+ 透過停用請求映射範本，您的 Lambda 資料來源將收到包含整個[內容](resolver-context-reference.md)物件的承載。
+ 透過停用回應映射範本，您的 Lambda 調用結果將根據請求映射範本的版本或請求映射範本是否也停用而翻譯。
# 測試和偵錯解析程式 in AWS AppSync (VTL)
**注意**
我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)使用 APPSYNC\$1JS 執行期及其指南。
AWS AppSync 會對資料來源在 GraphQL 欄位上執行解析程式。如[解析程式映射範本概觀](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)中所述，解析程式會使用範本語言與資料來源通訊。這可讓您自訂行為，並在與資料來源通訊前後套用邏輯和條件。如需撰寫解析程式的教學風格程式設計指南簡介，請參閱[解析程式映射範本程式設計指南](resolver-mapping-template-reference-programming-guide.md#aws-appsync-resolver-mapping-template-reference-programming-guide)。
為了協助開發人員寫入、測試和偵錯這些解析程式， AWS AppSync 主控台也提供工具來建立 GraphQL 請求和回應，並將模擬資料縮減至個別欄位解析程式。此外，您可以在 AWS AppSync 主控台中執行查詢、變動和訂閱，並從 Amazon CloudWatch 查看整個請求的詳細日誌串流。其中包括資料來源的結果。
## 使用模擬資料進行測試
叫用 GraphQL 解析程式時，會包含包含請求相關資訊的`context`物件。其中包括用戶端引數、身分資訊，以及父 GraphQL 欄位的資料。它還包含來自資料來源的結果，可用於回應範本。如需詳細資訊來了解此項架構，以及程式設計時可用的各種協助公用程式，請參閱[解析程式映射範本內容參考](resolver-context-reference.md#aws-appsync-resolver-mapping-template-context-reference)。
寫入或編輯解析程式時，您可以將*模擬*或*測試內容*物件傳遞至主控台編輯器。這可讓您在沒有實際依據資料來源執行的情況下，了解這兩者如何請求及回應範本評估。例如您可傳送測試 `firstname: Shaggy` 引數，了解該引數在範本程式碼之中使用 `$ctx.args.firstname` 時如何進行評估。您也可以測試任何公用程式協助程式的評估，例如 `$util.autoId()` 或 `util.time.nowISO8601()`。
### 測試解析程式
此範例將使用 AWS AppSync 主控台來測試解析程式。
1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。
1. 在 **APIs儀表板**中，選擇您的 GraphQL API。
1. 在**側邊欄中**，選擇**結構描述**。
1. 如果您尚未這麼做，請在 類型下和 欄位旁，選擇**連接**以新增您的解析程式。
如需如何建置完整解析程式的詳細資訊，請參閱[設定解析程式](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers.html)。
否則，請選取已在 欄位中的解析程式。
1. 在**編輯解析程式**頁面頂端，選擇**選取測試內容**，然後選擇**建立新內容**。
1. 選取範例內容物件，或在下方的**執行內容**視窗中手動填入 JSON。
1. 在**文字內容名稱**中輸入 。
1. 選擇 **Save (儲存)** 按鈕。
1. 在**編輯解析程式**頁面頂端，選擇**執行測試**。
如需更實際的範例，假設您有一個應用程式存放的 GraphQL 類型`Dog`，該類型使用物件的自動 ID 產生，並將它們存放在 Amazon DynamoDB 中。您也希望寫入 GraphQL 變動引數的值，並且只讓特定使用者看見回應。結構描述看起來類似如下：
```
type Dog {
breed: String
color: String
}
type Mutation {
addDog(firstname: String, age: Int): Dog
}
```
當您為`addDog`變動新增解析程式時，您可以填入內容物件，如下列範例所示。下列引數來自 `name` 及 `age`，以及將 `username` 填入 `identity` 物件之中的用戶端：
```
{
"arguments" : {
"firstname": "Shaggy",
"age": 4
},
"source" : {},
"result" : {
"breed" : "Miniature Schnauzer",
"color" : "black_grey"
},
"identity": {
"sub" : "uuid",
"issuer" : " https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
"username" : "Nadia",
"claims" : { },
"sourceIp" :[ "x.x.x.x" ],
"defaultAuthStrategy" : "ALLOW"
}
}
```
您可利用下列要求及回應映射範本對此進行測試：
**請求範本**
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "$util.autoId()" }
},
"attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
**回應範本**
```
#if ($context.identity.username == "Nadia")
$util.toJson($ctx.result)
#else
$util.unauthorized()
#end
```
經過評估的範本擁有測試內容物件的資料，以及 `$util.autoId()` 產生的值。此外，若您將 `username` 變更為 `Nadia` 以外的值，將不會傳回結果，因為授權檢查將會失敗。如需精細存取控制的詳細資訊，請參閱[授權使用案例](security-authorization-use-cases.md#aws-appsync-security-authorization-use-cases)。
### 使用 AWS AppSync 的 APIs測試映射範本
您可以使用 `EvaluateMappingTemplate` API 命令，以模擬資料遠端測試映射範本。若要開始使用 命令，請確定您已將 `appsync:evaluateMappingTemplate`許可新增至政策。例如：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "appsync:evaluateMappingTemplate",
"Resource": "arn:aws:appsync:us-east-1:111122223333:*"
}
]
}
```
------
您可以使用 [AWS CLI](https://aws.amazon.com/cli/)或 [AWS SDKs](https://aws.amazon.com/tools/) 來利用 命令。例如，從上一節取得`Dog`結構描述及其請求/回應映射範本。在本機工作站上使用 CLI，將請求範本儲存到名為 的檔案`request.vtl`，然後將`context`物件儲存到名為 的檔案`context.json`。從您的 shell 執行下列命令：
```
aws appsync evaluate-mapping-template --template file://request.vtl --context file://context.json
```
該命令會傳回下列回應：
```
{
"evaluationResult": "{\n \"version\" : \"2017-02-28\",\n \"operation\" : \"PutItem\",\n \"key\" : {\n \"id\" : { \"S\" : \"afcb4c85-49f8-40de-8f2b-248949176456\" }\n },\n \"attributeValues\" : {\"firstname\":{\"S\":\"Shaggy\"},\"age\":{\"N\":4}}\n}\n"
}
```
`evaluationResult` 包含使用提供的 測試您提供的範本的結果`context`。您也可以使用 AWS SDKs測試範本。以下是使用適用於 JavaScript V2 的 AWS SDK 的範例：
```
const AWS = require('aws-sdk')
const client = new AWS.AppSync({ region: 'us-east-2' })
const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
client
.evaluateMappingTemplate({ template, context })
.promise()
.then((data) => console.log(data))
```
使用 SDK，您可以輕鬆整合來自您最愛測試套件的測試，以驗證範本的行為。我們建議您使用 [Jest 測試架構](https://jestjs.io/)建立測試，但任何測試套件都可以運作。下列程式碼片段顯示假設性驗證執行。請注意，我們預期評估回應是有效的 JSON，因此我們使用 從字串回應`JSON.parse`擷取 JSON：
```
const AWS = require('aws-sdk')
const fs = require('fs')
const client = new AWS.AppSync({ region: 'us-east-2' })
test('request correctly calls DynamoDB', async () => {
const template = fs.readFileSync('./request.vtl', 'utf8')
const context = fs.readFileSync('./context.json', 'utf8')
const contextJSON = JSON.parse(context)
const response = await client.evaluateMappingTemplate({ template, context }).promise()
const result = JSON.parse(response.evaluationResult)
expect(result.key.id.S).toBeDefined()
expect(result.attributeValues.firstname.S).toEqual(contextJSON.arguments.firstname)
})
```
這會產生下列結果：
```
Ran all test suites.
> jest
PASS ./index.test.js
✓ request correctly calls DynamoDB (543 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.511 s, estimated 2 s
```
## 偵錯即時查詢
end-to-end測試和記錄無法用來偵錯生產應用程式。 AWS AppSync 可讓您使用 Amazon CloudWatch 記錄錯誤和完整請求詳細資訊。此外，您可以使用 AWS AppSync 主控台來測試 GraphQL 查詢、變動和訂閱，以及將每個請求的即時串流日誌資料傳回查詢編輯器以進行即時偵錯。針對訂閱，日誌會顯示連線時間資訊。
若要執行此操作，您需要事先啟用 Amazon CloudWatch logs，如[監控和記錄](monitoring.md#aws-appsync-monitoring)中所述。接著，在 AWS AppSync 主控台中，選擇**查詢**索引標籤，然後輸入有效的 GraphQL 查詢。在右下角區段中，按一下並拖曳**日誌**視窗以開啟日誌檢視。在頁面頂端，選擇執行箭頭圖示來執行您的 GraphQL 查詢。幾分鐘後，操作的完整請求及回應日誌，將串流至此區段，然後您可在主控台中檢視。
# 設定和使用管道解析程式 in AWS AppSync (VTL)
**注意**
我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)使用 APPSYNC\$1JS 執行期及其指南。
AWS AppSync 會在 GraphQL 欄位上執行解析程式。在某些情況下，應用程式需要執行多個操作，才能解析單一 GraphQL 欄位。透過管道解析程式，開發人員現在可以編寫稱為 Functions 的操作，並依序執行這些操作。在像是以需要先執行授權檢查才能擷取欄位資料的情況中，就很適合使用管道解析程式。
管道解析程式包含 **Before** 映射範本和 **After** 映射範本，以及一份函數清單。每個函數都有一個**請求**和**回應**映射範本，它會針對資料來源執行。由於管道解析程式是將執行委派到一份函數清單，所以不會連結到任何資料來源。單位解析程式和函數是對資料來源執行操作的基礎。如需詳細資訊，請參閱[解析程式映射範本概觀](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。
## 步驟 1：建立管道解析程式
在 AWS AppSync 主控台中，前往**結構描述**頁面。
儲存下列結構描述：
```
schema {
query: Query
mutation: Mutation
}
type Mutation {
signUp(input: Signup): User
}
type Query {
getUser(id: ID!): User
}
input Signup {
username: String!
email: String!
}
type User {
id: ID!
username: String
email: AWSEmail
}
```
我們將將管道解析程式連接到 **Mutation** 類型的 **signUp** 欄位。在右側的**變動**類型中，選擇`signUp`變動欄位旁的**連接**。在建立解析程式頁面上，按一下**動作**，然後按一下**更新執行時間**。選擇 `Pipeline Resolver`，然後選擇 `VTL`，然後選擇**更新**。頁面現在應會顯示三個區段：**映射前範本**文字區域、**函數**區段，以及**映射後範本**文字區域。
我們的管道解析程式會註冊使用者，此註冊的第一步是驗證電子郵件地址輸入，然後在系統中儲存此位使用者。我們將在 **validateEmail** 函數中封裝該電子郵件驗證，並在 **saveUser** 函數中封裝使用者儲存步驟。**validateEmail** 函數會先執行，而當電子郵件驗證有效時，**saveUser** 函數就會接著執行。
執行流程將如下所示：
1. Mutation.signUp 解析程式要求映射範本
1. validateEmail 函數
1. saveUser 函數
1. Mutation.signUp 解析程式回應映射範本
由於我們可能會在 API 上的其他解析程式中重複使用 **validateEmail** 函數，因此我們希望避免存取 ，`$ctx.args`因為這些函數會從一個 GraphQL 欄位變更為另一個欄位。反之，我們可以使用 `$ctx.stash` 來存放 `signUp(input: Signup)` 輸入欄位引數所傳遞的電子郵件屬性。
映射範本**之前**：
```
## store email input field into a generic email key
$util.qr($ctx.stash.put("email", $ctx.args.input.email))
{}
```
主控台提供預設的 **AFTER** 映射範本，我們將使用：
```
$util.toJson($ctx.result)
```
選擇**建立**或**儲存**以更新解析程式。
## 步驟 2：建立 函數
在管道解析程式頁面的**函數**區段中，按一下**新增函數**，然後按一下**建立新函數**。您也可以在不經過解析程式頁面的情況下建立函數；若要這樣做，請在 AWS AppSync 主控台中前往**函數**頁面。選擇 **Create function (建立函數)** 按鈕。讓我們來建立可檢查電子郵件是否有效且來源是特定網域的函數。如果電子郵件無效，則該函數會引發錯誤。否則，它會轉送任何獲予的任何輸入。
在新函數頁面上，選擇**動作**，然後選擇**更新執行時間**。選擇 `VTL`，然後選擇**更新**。請確定您已建立 **NONE** 類型的資料來源。在資料來源**名稱清單中選擇此資料來源**。在**函數名稱**中輸入 `validateEmail`。在**函數程式碼**區域中，使用此程式碼片段覆寫所有項目：
```
#set($valid = $util.matches("^[a-zA-Z0-9_.+-]+@(?:(?:[a-zA-Z0-9-]+\.)?[a-zA-Z]+\.)?(myvaliddomain)\.com", $ctx.stash.email))
#if (!$valid)
$util.error("$ctx.stash.email is not a valid email.")
#end
{
"payload": { "email": $util.toJson(${ctx.stash.email}) }
}
```
將此貼到回應映射範本中：
```
$util.toJson($ctx.result)
```
檢閱您的變更，然後選擇**建立**。我們已建立我們 **validateEmail** 函數。重複這些步驟，使用下列請求和回應映射範本建立 **saveUser** 函數 （為了簡單起見，我們使用 **NONE** 資料來源，並在函數執行後假設使用者已儲存在系統中。)：
要求映射範本：
```
## $ctx.prev.result contains the signup input values. We could have also
## used $ctx.args.input.
{
"payload": $util.toJson($ctx.prev.result)
}
```
回應映射範本：
```
## an id is required so let's add a unique random identifier to the output
$util.qr($ctx.result.put("id", $util.autoId()))
$util.toJson($ctx.result)
```
我們剛建立了 **saveUser** 函數。
## 步驟 3：將函數新增至管道解析程式
我們的函數應該會自動新增至我們剛建立的管道解析程式。如果不是這種情況，或者您透過函數頁面建立**函數**，您可以在解析程式頁面上按一下**新增函數**來連接它們。將 **validateEmail** 和 **saveUser** 函數新增至解析程式。**validateEmail** 函數應該放在 **saveUser** 函數之前。當您新增更多函數時，您可以使用**上下****移動**選項來重組函數的執行順序。檢閱您的變更，然後選擇**儲存**。
## 步驟 4：執行查詢
在 AWS AppSync 主控台中，前往**查詢**頁面。在瀏覽器中，請確定您使用的是變動。如果不是，請在下拉式清單`Mutation`中選擇 ，然後選擇 `+`。輸入下列查詢：
```
mutation {
signUp(input: {
email: "nadia@myvaliddomain.com"
username: "nadia"
}) {
id
email
}
}
```
這應該會傳回如下內容：
```
{
"data": {
"signUp": {
"id": "256b6cc2-4694-46f4-a55e-8cb14cc5d7fc",
"email": "nadia@myvaliddomain.com"
}
}
}
```
我們已使用管道解析程式成功註冊我們的使用者，並完成輸入電子郵件的驗證。若要取得更多著重管道解析程式的全面教學課程，您可以移至[教學課程：管道解析程式](tutorial-pipeline-resolvers.md#aws-appsync-tutorial-pipeline-resolvers)