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

AWS AppSync 解析程式映射範本內容參考

AWS AppSync 定義一組變數和函數，以使用解析程式映射範本。這樣可讓使用 GraphQL 對資料進行邏輯運算更簡單。本文件說明這些函式，並提供範本使用範例。

正在存取 $context

$context 變數是一種映射，保存您的解析程式叫用的所有情境資訊。其結構如下：

{
   "arguments" : { ... },
   "source" : { ... },
   "result" : { ... },
   "identity" : { ... },
   "request" : { ... },
   "info": { ... }
}

$context 映射中每個欄位的定義如下：

$context 欄位

Identity

包含有關發起人資訊的 identity 區段。本節的形狀取決於 AWS AppSync API 的授權類型。

如需 AWS AppSync 安全選項的詳細資訊，請參閱授權和身分驗證。

每個欄位的定義如下：

存取請求標頭

AWS AppSync 支援從用戶端傳遞自訂標頭，並使用 在 GraphQL 解析程式中存取它們$context.request.headers。然後，您可以將 標頭值用於動作，例如將資料插入資料來源或授權檢查。您可以將 與來自命令列的 API 金鑰$curl搭配使用的單一或多個請求標頭，如下列範例所示：

單一標頭範例

假設您設定使用 custom 值的 nadia 標頭，如下所示：

curl -XPOST -H "Content-Type:application/graphql" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql

可使用 $context.request.headers.custom 對此進行存取。例如，它可能位於 DynamoDB 的下列 VTL 中：

"custom": $util.dynamodb.toDynamoDBJson($context.request.headers.custom)

多個標頭範例

您也可以將多個標頭傳遞到單一要求，並在解析程式映射範本中存取這些要求。例如，如果 custom標頭設定為兩個值：

curl -XPOST -H "Content-Type:application/graphql" -H "custom:bailey" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql

然後，您可以將這些存取為陣列，例如 $context.request.headers.custom[1]。

存取請求自訂網域名稱

AWS AppSync 支援設定自訂網域，您可以用來存取 APIs的 GraphQL 和即時端點。使用自訂網域名稱提出請求時，您可以使用 取得網域名稱$context.request.domainName。

使用預設 GraphQL 端點網域名稱時，值為 null。

資訊

info 區段包含有關 GraphQL 請求的資訊。本節的格式如下：

{
    "fieldName": "string",
    "parentTypeName": "string",
    "variables": { ... },
    "selectionSetList": ["string"],
    "selectionSetGraphQL": "string"
}

每個欄位的定義如下：

例如，如果您解析下列查詢的 getPost 欄位：

query {
  getPost(id: $postId) {
    postId
    title
    secondTitle: title
    content
    author(id: $authorId) {
      authorId
      name
    }
    secondAuthor(id: "789") {
      authorId
    }
    ... on Post {
      inlineFrag: comments: {
        id
      }
    }
    ... postFrag
  }
}

fragment postFrag on Post {
  postFrag: comments: {
    id
  }
}

那麼，在處理映射範本時，可用的完整 $context.info 變數可能是：

{
  "fieldName": "getPost",
  "parentTypeName": "Query",
  "variables": {
    "postId": "123",
    "authorId": "456"
  },
  "selectionSetList": [
    "postId",
    "title",
    "secondTitle"
    "content",
    "author",
    "author/authorId",
    "author/name",
    "secondAuthor",
    "secondAuthor/authorId",
    "inlineFragComments",
    "inlineFragComments/id",
    "postFragComments",
    "postFragComments/id"
  ],
  "selectionSetGraphQL": "{\n  getPost(id: $postId) {\n    postId\n    title\n    secondTitle: title\n    content\n    author(id: $authorId) {\n      authorId\n      name\n    }\n    secondAuthor(id: \"789\") {\n      authorId\n    }\n    ... on Post {\n      inlineFrag: comments {\n        id\n      }\n    }\n    ... postFrag\n  }\n}"
}

selectionSetList 只會公開屬於目前類型的欄位。如果目前類型是界面或聯集，則只會公開屬於界面的所選欄位。例如，指定下列結構描述：

type Query {
    node(id: ID!): Node
}

interface Node {
    id: ID
}

type Post implements Node {
    id: ID
    title: String
    author: String
}

type Blog implements Node {
    id: ID
    title: String
    category: String
}

以及下列查詢：

query {
    node(id: "post1") {
        id
        ... on Post {
            title
        }

        ... on Blog {
            title
        }
    }
}

$ctx.info.selectionSetList 以Query.node欄位解析度呼叫 時，只會id公開：

"selectionSetList": [
    "id"
]

處理輸入

應用程式必須處理不受信任的輸入，以防止任何外部方使用其預期用途之外的應用程式。由於 包含 $context.arguments、、$context.info.variables、 $context.identity $context.result和 等屬性中的$context使用者輸入$context.request.headers，因此必須小心在映射範本中淨化其值。

由於對應範本代表 JSON，輸入處理採用從表示使用者輸入的字串逸出 JSON 保留字元的形式。將敏感字串值放入對應範本時，最佳做法是使用 $util.toJson() 公用程式將 JSON 保留字元從敏感字串值逸出。

例如，在下列 Lambda 請求映射範本中，因為我們存取了不安全的客戶輸入字串 ($context.arguments.id)，因此我們使用 包裝它$util.toJson()，以防止未逸出的 JSON 字元破壞 JSON 範本。

{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": $util.toJson($context.arguments.id)
    }
}

與下面的映射範本相反，我們在其中直接插入$context.arguments.id而不進行淨化。這不適用於包含未逸出引號或其他 JSON 預留字元的字串，並且可能會讓您的範本處於開啟失敗狀態。

## DO NOT DO THIS
{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "$context.arguments.id" ## Unsafe! Do not insert $context string values without escaping JSON characters.
    }
}