本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立基本查詢 (VTL)
**注意**
我們現在主要支援 APPSYNC\_JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/configuring-resolvers-js.html)使用 APPSYNC\_JS 執行期及其指南。
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 中執行此操作。
------