リゾルバーのマッピングテンプレートのコンテキストリファレンス - 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は最初の関数の出力を表し、パイプライン内の 2 番目の関数に使用可能になります。前の操作が最後の関数だった場合、$ctx.prev.resultは最後の関数の出力を表し、パイプラインリゾルバーのレスポンスマッピングテンプレートに使用可能になります。

info

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

ID

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

の詳細AWSAppSync セキュリティオプション、を参照してください。認証と認可

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 プロバイダ情報の取得先となる外部 ID プロバイダ情報のカンマ区切りリスト。

cognitoIdentityId

リクエストを行う呼び出し元の Amazon Cognito 認証 ID。

cognitoIdentityPoolId

呼び出し元に関連付けられている Amazon Cognito 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 ユーザーの Amazon リソースネーム (ARN)。

username

認証されたユーザーのユーザー名です。AMAZON_COGNITO_USER_POOLS 認証の場合、username の値は cognito:username の属性の値です。AWS_IAM 認証の場合、username の値は AWS ユーザープリンシパルの値です。Amazon Cognito アイデンティティプールから発行された認証情報による IAM 認証を使用している場合は、以下を使用することをお勧めします。cognitoIdentityId

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

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

単一ヘッダーの例

次のように、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 AppSyncGraphQL とリアルタイムへのアクセスに使用できるカスタムドメインの構成をサポートします。エンドポイント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()オンcontext.infoとすると、その値selectionSetGraphQLそしてselectionSetListreturn はデフォルトではシリアル化されません。

たとえば、次のクエリの 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) で包んだ$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. } }