本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

AWS AppSync 解析器映射範本概觀

AWS AppSync 可讓您透過對資源執行操作來回應 GraphQL 請求。對於您要在其中執行查詢或突變的每個 GraphQL 欄位，必須連接解析器，才能與資料來源通訊。通訊通常透過資料來源特有的參數或操作進行。

解析程式是 GraphQL 與資料來源之間的連接器。它們 AWS AppSync 說明如何將傳入的 GraphQL 請求轉換為後端資料來源的指示，以及如何將來自該資料來源的回應轉換回 GraphQL 回應。它們以 Apache Velocity 範本語言 （VTL） 編寫，會將您的請求視為輸入，並輸出包含解析器指示JSON的文件。您可以使用映射範本進行簡單指示，例如從 GraphQL 欄位傳入引數，或用於更複雜的指示，例如循環瀏覽引數以建置項目，然後再將項目插入 DynamoDB 。

中的解析程式有兩種類型 AWS AppSync ，會以略有不同的方式利用映射範本：

單位解析程式

單位解析器是獨立的實體，僅包含請求和回應範本。這種類型可以用於簡易、單一的操作，例如列出來自單一資料來源的清單項目。

管道解析程式

管道解析器包含一個或多個按順序執行的函數。每個函數都包含請求範本和回應範本。管道解析程式也具有 預範本和 後範本，其圍繞範本包含的函數序列。後續範本會映射至 GraphQL 欄位輸出類型。管道解析程式與單位解析程式的不同之處在於回應範本對應輸出的方式。管道解析程式可以映射到任何您想要的輸出，包括另一個函數的輸入或管道解析程式的後續範本。

管道解析器函數可讓您撰寫常見邏輯，以便在結構描述中的多個解析器之間重複使用。函數會直接連接至資料來源，而且就像單位解析器一樣，包含相同的請求和回應映射範本格式。

下圖示範左側單元解析器和右側管道解析器的處理流程。

管道解析器包含單元解析器支援的功能超集，以及更多功能，且成本更高。

管道解析程式剖析

管道解析器由映射前範本、映射後範本和函數清單組成。每個函數都有一個請求和回應映射範本，它會根據資料來源執行。由於管道解析程式是將執行委派到一份函數清單，所以不會連結到任何資料來源。單位解析程式和函數是對資料來源執行操作的基本元素。如需詳細資訊，請參閱解析程式映射範本概觀。

映射範本之前

管道解析程式的請求映射範本，或 Before 步驟，可讓您在執行定義的函數之前執行一些準備邏輯。

函數清單

管道解析程式將會依序執行的函數清單。管道解析程式要求映射範本評估的結果，會依 $ctx.prev.result 提供給第一個函數。每個函數輸出都會依 $ctx.prev.result 提供給下一個函數。

After 映射範本

管道解析程式的回應映射範本，或 After step，可讓您從最後一個函數的輸出執行一些最終映射邏輯，以至預期的 GraphQL 欄位類型。在函數清單的最後一個函數的輸出，將依 $ctx.prev.result 或 $ctx.result 提供給管道解析程式映射範本。

執行流程

假設管道解析器由兩個函數組成，則以下清單代表呼叫解析器時的執行流程：

有用的 Apache Velocity 範本語言 （VTL） 公用程式

隨著應用程式的複雜性增加，VTL公用程式和指令會在這裡促進開發生產力。下列公用程式可在您使用管道解析程式時提供協助。

$ctx.stash

堆疊是在每個解析器和函數映射範本內Map提供的 。在單一個解析程式執行期間，則會存在相同的 stash 執行個體。這表示您可以使用 stash 在管道解析程式中的所有要求和回應映射範本、以及全部函數中，傳遞任意資料。堆疊會公開與 Java 地圖資料結構相同的方法。

$ctx.prev.result

$ctx.prev.result 代表在管道解析程式中執行的先前操作的結果。

如果先前的操作是管道解析程式的映射前範本，則 $ctx.prev.result代表範本評估的輸出，並提供給管道中的第一個函數。如果先前操作是第一個函數，則 $ctx.prev.result 會顯示第一個函數的輸出，並將資料提供給管道中的第二個函數。如果先前的操作是最後一個函數，則 $ctx.prev.result代表最後一個函數的輸出，並提供給管道解析程式的映射後範本。

#return(data: Object)

當您需要從任何映射範本提前傳回時，這時使用 #return(data: Object) 指令就能完成。#return(data: Object) 類似於程式設計語言中的 return 關鍵字，因為它會從最靠近範圍的邏輯區塊傳回。這表示在解析程式映射範本中使用 #return 時，將從該解析程式傳回。在解析程式映射範本中使用 #return(data: Object)，將會設定 GraphQL 欄位上的 data。此外，使用函數映射範本的 #return(data: Object) 時會從該函數傳回，且執行將持續到該管道或是解析程式回應映射範本中的下一個函數。

#return

這與 相同#return(data: Object)，但null會改為傳回。

$util.error

$util.error 公用程式非常適合用來擲出欄位錯誤。在函數映射範本內使用 $util.error 會立即擲出錯誤，其可阻止後續函數執行。如需更多詳細資訊和其他$util.error簽章，請造訪解析程式映射範本公用程式參考 。

$util。appendError

$util.appendError 的功能類似於 $util.error()，主要的差別在於前者不會中斷映射範本的評估，而是在欄位出現錯誤時發出訊號，但允許範本的評估，進而將資料傳回。在函數中使用 $util.appendError 並不會中斷管道的執行流程。如需更多詳細資訊和其他$util.error簽章，請造訪解析程式映射範本公用程式參考 。

範例 範本

假設您在名稱為 的欄位上有 DynamoDB 資料來源和單位解析器getPost(id:ID!)，該欄位會傳回具有下列 GraphQL 查詢的Post類型：

getPost(id:1){
    id
    title
    content
}

解析程式範本看起來可能會類似於下列的範例：

     {
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

這將取代 1 的id輸入參數值，${ctx.args.id}並產生下列 JSON：

     {
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : { "S" : "1" }
    }
}

AWS AppSync 使用此範本來產生與 DynamoDB 通訊和取得資料 （或視情況執行其他操作） 的指示。資料傳回後， 會透過選用的回應映射範本 AWS AppSync 執行，您可以使用該範本來執行資料成形或邏輯。例如，當我們從 DynamoDB 取得結果時，它們看起來可能如下所示：

{
        "id" : 1,
        "theTitle" : "AWS AppSync works offline!",
        "theContent-part1" : "It also has realtime functionality",
        "theContent-part2" : "using GraphQL"
}

您可以利用下列的回應映射範本，來選擇將其中兩個欄位合併為單一欄位：

{
        "id" : $util.toJson($context.data.id),
        "title" : $util.toJson($context.data.theTitle),
        "content" : $util.toJson("${context.data.theContent-part1} ${context.data.theContent-part2}")
}

在將範本套用到資料之後，資料的格式如下所示：

{
        "id" : 1,
        "title" : "AWS AppSync works offline!",
        "content" : "It also has realtime functionality using GraphQL"
}

這些資料會再做為回應傳回給用戶端，如下所示：

{
        "data": {
                "getPost":      {
                        "id" : 1,
                        "title" : "AWS AppSync works offline!",
                        "content" : "It also has realtime functionality using GraphQL"
                }
        }
}

請注意，在大部分情況下，回應映射範本是簡單的資料傳遞，主要差別在於您是傳回個別項目或項目清單。若是個別項目，則傳遞是：

$util.toJson($context.result)

若是清單，則傳遞通常是：

$util.toJson($context.result.items)

若要查看單元和管道解析程式的更多範例，請參閱解析程式教學課程 。

評估的映射範本去序列化規則

對於一個字串的對應範本評估。在 中 AWS AppSync，輸出字串必須遵循JSON結構才能有效。

此外，系統會強制執行下列還原序列化規則。

JSON 物件中不允許重複的金鑰

如果評估的映射範本字串代表JSON物件或包含具有重複金鑰的物件，映射範本會傳回下列錯誤訊息：

Duplicate field 'aField' detected on Object. Duplicate JSON keys are not allowed.

已評估要求對應範本中重複金鑰的範例：

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
        "field": "getPost" ## key 'field' has been redefined
    }
}

若要修正此錯誤，請勿重新定義JSON物件中的金鑰。

JSON 物件中不允許追蹤字元

如果評估的映射範本字串代表JSON物件，並包含尾隨外部字元，映射範本會傳回下列錯誤訊息：

Trailing characters at the end of the JSON string are not allowed.

已評估請求映射範本中結尾字元的範例：

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
    }
}extraneouschars

若要修正此錯誤，請確保評估的範本嚴格評估為 JSON。