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

注記

現在、主に APPSYNC_JS ランタイムとそのドキュメントをサポートしています。APPSYNC_JS ランタイムとそのガイドをここで使用することを検討してください。

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 AppSync API。

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接続からの 1 つの IP アドレスのみが含まれます。リクエストに 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 認証の場合、ユーザー名の値は AWS ユーザープリンシパルの値です。Amazon Cognito ID プールから提供された認証情報で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 はの Cookie ヘッダーを公開しません$context.request.headers。

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

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

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

情報

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


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

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

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

注記

context.info を $utils.toJson() で使用する場合，selectionSetList および selectionSetGraphQL によって返される値はデフォルトでシリアル化されません。

たとえば、次のクエリの 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
        }
    }
}

Query.node フィールド解決で $ctx.info.selectionSetList が呼び出されると、id のみが公開されます。


"selectionSetList": [
    "id"
]

入力のサニタイズ

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

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

例えば、次の 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 を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

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

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