リゾルバーのマッピングテンプレートのコンテキストリファレンス

AWS AppSync は、リゾルバーマッピングテンプレートを操作するための変数と関数のセットを定義します。これにより、GraphQL を使用してデータの論理的オペレーションが容易になります。このドキュメントでは、それらの関数について説明し、テンプレートの使用例を示します。

`$context` へのアクセス

$context 変数は、リゾルバー呼び出しのすべてのコンテキスト情報が保持されるマップです。この変数の構造は次のとおりです。


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

注記

キーを使用してディクショナリ/マップエントリ (のエントリなどcontext) にアクセスして値を取得しようとする場合、Velocity Template Language (VTL) を使用して表記法を直接使用できます<dictionary-element>.<key-name>。ただし、キー名に特殊文字 (アンダースコア "_" など) が使われている場合など、一部のケースでは機能しない場合があります。常に <dictionary-element>.get("<key-name>") 表記を使用することをお勧めします。

$context マップの各フィールドは次のように定義されます。

`$context` フィールド

arguments: このフィールドのすべての GraphQL 引数を含むマップ。
identity: 呼び出し元に関する情報を含むオブジェクト。このフィールドの構造の詳細については、「ID」を参照してください。
source: 親フィールドの解像度を含むマップ。
stash: stash は、リゾルバーと関数の各マッピングテンプレート内で使用可能になるマップです。同じ stash インスタンスは 1 つのリゾルバーの実行を通して存続します。つまり、stash を使用して、リクエストとレスポンスのマッピングテンプレート間、およびパイプラインリゾルバーの関数間で、任意のデータを渡すことができます。stash は Java Map データ構造と同じメソッドを継承しています。

result

このリゾルバーの結果用のコンテナ。このフィールドは、レスポンスマッピングテンプレートでのみ使用できます。

たとえば、author次のクエリのフィールドを解決するとします。


query {
    getPost(id: 1234) {
        postId
        title
        content
        author {
            id
            name
        }
    }
}

レスポンスマッピングテンプレートを処理する際に使用可能な完全な $context 変数は次のようになります。


{
  "arguments" : {
    id: "1234"
  },
  "source": {},
  "result" : {
      "postId": "1234",
      "title": "Some title",
      "content": "Some content",
      "author": {
        "id": "5678",
        "name": "Author Name"
      }
  },
  "identity" : {
      "sourceIp" : ["x.x.x.x"],
      "userArn" : "arn:aws:iam::123456789012:user/appsync",
      "accountId" : "666666666666",
      "user" : "AIDAAAAAAAAAAAAAAAAAA"
  }
}

prev.result

パイプラインリゾルバーで以前に実行された操作の結果。

前のオペレーションがパイプラインリゾルバーのマッピング前テンプレートであった場合、$ctx.prev.resultはテンプレートの評価の出力を表し、パイプラインの最初の関数に使用可能になります。

前のオペレーションが最初の関数であった場合、$ctx.prev.result は最初の関数の出力を表し、パイプライン内の 2 番目の関数に使用可能になります。

前のオペレーションが最後の関数であった場合、$ctx.prev.resultは最後の関数の出力を表し、パイプラインリゾルバーのマッピング後テンプレートに使用可能になります。

info

GraphQL リクエストに関する情報を含むオブジェクト。このフィールドの構造については、「情報」を参照してください。

アイデンティティ

identity セクションには、呼び出し元に関する情報が含まれています。このセクションのシェイプは、使用する AWS AppSyncAPI の認証タイプによって異なります。

AWS AppSync セキュリティオプションの詳細については、「承認と認証」を参照してください。

API_KEY authorization

identityこのフィールドにはデータが入力されていません。

AWS_LAMBDA authorization

identityには、リクエストを承認する Lambda 関数によって返されるのと同じ resolverContext コンテンツを含む resolverContext キーが含まれています。

AWS_IAM authorization

identityには、以下の形式です。


{
    "accountId" : "string",
    "cognitoIdentityPoolId" : "string",
    "cognitoIdentityId" : "string",
    "sourceIp" : ["string"],
    "username" : "string", // IAM user principal
    "userArn" : "string",
    "cognitoIdentityAuthType" : "string", // authenticated/unauthenticated based on the identity type
    "cognitoIdentityAuthProvider" : "string" // the auth provider that was used to obtain the credentials
}

AMAZON_COGNITO_USER_POOLS authorization

identityには、以下の形式です。


{
    "sub" : "uuid",
    "issuer" : "string",
    "username" : "string"
    "claims" : { ... },
    "sourceIp" : ["x.x.x.x"],
    "defaultAuthStrategy" : "string"
}

各フィールドは次のように定義されています。

accountId: 呼び出し元の AWS アカウント ID。
claims: ユーザーが持っているクレーム。
cognitoIdentityAuthType: ID タイプに基づいて認証済みまたは未認証のいずれか。
cognitoIdentityAuthProvider: リクエストの署名に使用された認証情報の取得先となる外部 ID プロバイダ情報のカンマ区切りリスト。
cognitoIdentityId: リクエストを行う呼び出し元の Amazon Cognito 認証 ID。
cognitoIdentityPoolId: 呼び出し元に関連付けられている Amazon Cognito ID プール。
defaultAuthStrategy: この呼び出し元のデフォルトの認証方法 (ALLOW または DENY)。
issuer: トークン発行者。
sourceIp: AWS AppSync受信者の送信元 IP アドレス。x-forwarded-forリクエストにヘッダーが含まれていない場合、ソース IP 値には TCP 接続の IP アドレスが 1 つだけ含まれます。リクエストに x-forwarded-for ヘッダーが含まれている場合、ソース IP は、TCP 接続からの IP アドレスと x-forwarded-for ヘッダーからの IP アドレスのリストです。
sub: 認証されたユーザーの UUID。
user: IAM ユーザー。
userArn: IAM ユーザーの Amazon リソースネーム (ARN)。
username: 認証されたユーザーのユーザー名です。AMAZON_COGNITO_USER_POOLS 認証の場合、username の値は cognito:username の属性の値です。AWS_IAM 認証の場合、username の値は AWS ユーザープリンシパルの値です。Amazon Cognito アイデンティティプールから発行された認証情報による IAM 認証情報による IAM 認証を使用することをお勧めしますcognitoIdentityId。

リクエストのヘッダーにアクセスする

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)

複数ヘッダーの例

1 つのリクエストで複数のヘッダーを渡して、リゾルバーのマッピングテンプレートでそれらのヘッダーにアクセスすることもできます。たとえば、customヘッダーに次の 2 つの値が設定されているとします。


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のクッキーヘッダーは公開されません$context.request.headers。

リクエストのカスタムドメイン名にアクセスする

AWS AppSyncは、GraphQL と API のリアルタイムエンドポイントへのアクセスに使用できるカスタムドメインの設定をサポートします。カスタムドメイン名を使用してリクエストを行う場合、を使用してドメイン名を取得できます$context.request.domainName。

デフォルトの GraphQL エンドポイントドメイン名を使用する場合、値はですnull。

Info

info セクションには、GraphQL リクエストに関する情報が含まれています。このセクションには、次の形式です。


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

各フィールドは次のように定義されています。

fieldName: 現在解決中のフィールドの名前。
parentTypeName: 現在解決中のフィールドの親タイプの名前。
variables: GraphQLリクエストに渡されるすべての変数を保持するマップ。
selectionSetList: GraphQL 選択セット内のフィールドのリスト表現。エイリアスされたフィールドは、フィールド名ではなくエイリアス名によってのみ参照されます。次の例で詳細を示します。
selectionSetGraphQL: 選択セットの文字列表現。GraphQL スキーマ定義言語 (SDL) としてフォーマットされます。フラグメントは選択セットにマージされませんが、次の例に示すように、インラインフラグメントは保持されます。

注記

$utils.toJson()on を使用する場合context.info、selectionSetGraphQLselectionSetListとが返す値はデフォルトではシリアル化されません。

たとえば、次のクエリの 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.selectionSetListQuery.nodeフィールド解像度でコールすると、id次の情報のみが表示されます。


"selectionSetList": [
    "id"
]

入力のサニタイズ

アプリケーションは、信頼できない入力をサニタイズして、部外者が意図した用途以外でアプリケーションを使用することを防ぐ必要があります。には、$context.arguments、、、$context$context.identityなどのプロパティにユーザ入力が含まれているため$context.result$context.info.variables$context.request.headers、マッピングテンプレートではそれらの値をサニタイズするように注意する必要があります。

マッピングテンプレートは JSON を表すため、入力のサニタイズは、ユーザー入力を表す文字列から JSON 予約文字をエスケープする形式をとります。JSON 予約文字をマッピングテンプレートに配置するときは、$util.toJson() ユーティリティを使用して機密文字列値からエスケープすることをお勧めします。

たとえば、次の Lambda リクエストマッピングテンプレートでは、安全でない顧客入力文字列 ($context.arguments.id) にアクセスしたため、エスケープされていない JSON 文字が JSON$util.toJson() テンプレートを壊さないように、でラップしています。


{
    "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.
    }
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

のリゾルバーのマッピングテンプレートプログラミングテンプレートプログラミングガイド

リゾルバーのマッピングテンプレートユーティリティーリファレンス