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

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

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 マップの各フィールドは次のように定義されます。

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

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

このセクションおよび使用方法の詳細については、「セキュリティ」を参照してください。

API_KEY authorization

identity フィールドは入力されていません。

AWS_LAMBDA authorization

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

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 プール ID プール ID プール。

defaultAuthStrategy

この呼び出し元のデフォルトの認証方法 (ALLOW または DENY)。

issuer

トークン発行者。

sourceIp

によって受信された発信者の送信元 IP アドレス。AWS AppSync。リクエストに x-forwarded-for ヘッダーが含まれていない場合、ソース IP の値には TCP 接続からの 1 つの IP アドレスのみが含まれます。リクエストに x-forwarded-for ヘッダーが含まれている場合、ソース IP は、TCP 接続からの IP アドレスと x-forwarded-for ヘッダーからの IP アドレスのリストです。

sub

認証されたユーザーの UUID。

user

IAM ユーザー。

userArn

IAM ユーザーの ARN。

username

認証されたユーザーのユーザー名です。AMAZON_COGNITO_USER_POOLS 認証の場合、username の値は cognito:username の属性の値です。の場合AWS_IAM認可、次の値usernameの価値はAWSユーザープリンシパル。を使用することをお勧めします。cognitoIdentityIdあなたが使っている場合IAMAmazon Cognito アイデンティティプールからベンディングされた認証情報を使用した認証。

リクエストヘッダーへのアクセス

AWSAppSync では、クライアントからカスタムヘッダーを渡して、GraphQL リゾルバーでを使用してそのヘッダーにアクセスすることがサポートされています。$context.request.headers。データソースへデータの挿入や認証チェックなどのアクションでそのヘッダーの値を使用できます。次の例のようにコマンドラインから API キーで $curl を使用して、1 つまたは複数のリクエストヘッダーを使用できます。

単一ヘッダーの例

次のように、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

Info

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

info のシェイプは次のとおりです。

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

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

fieldName

現在解決中のフィールドの名前。

parentTypeName

現在解決中のフィールドの親タイプの名前。

variables

GraphQLリクエストに渡されるすべての変数を保持するマップ。

selectionSetList

GraphQL 選択セット内のフィールドのリスト表現。エイリアスされたフィールドは、フィールド名ではなく、エイリアス名によってのみ参照されます。次の例で詳細を示します。

selectionSetGraphQL

選択セットの文字列表現。GraphQL スキーマ定義言語 (SDL) としてフォーマットされます。フラグメントは選択セットにマージされませんが、次の例に示すように、インラインフラグメントは保持されます。

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

たとえば、次のクエリの 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 には、$context.arguments$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. } }