AWS AppSync
AWS AppSync 開発者ガイド

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

AWS AppSync は、リゾルバーのマッピングテンプレートを使用するための一連の変数と関数を定義して、データへのロジックフルオペレーションを GraphQL を使用して容易にします。このドキュメントでは、それらの関数について説明し、テンプレートの使用例を示します。

$context へのアクセス

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

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

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

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

arguments

このフィールドに対するすべての GraphQL 引数が含まれているマップ。

identity

呼び出し元に関する情報が含まれているオブジェクト。このフィールドの構造の詳細については、「ID」を参照してください。

source

親フィールドの解決が含まれているマップ。

stash

stash は、リゾルバーと関数の各マッピングテンプレート内で使用可能になる Map です。同じ 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" : "123456789012", "user" : "AIDAAAAAAAAAAAAAAAAAA" } }
prev.result

これは、パイプラインリゾルバーで実行された前回のオペレーションの結果を表します。前のオペレーションがパイプラインリゾルバーのリクエストマッピングテンプレートであった場合、$ctx.prev.result はテンプレートの評価の出力を表し、パイプライン内の最初の関数に使用可能になります。前のオペレーションが最初の関数であった場合、$ctx.prev.result は最初の関数の出力を表し、パイプライン内の 2 番目の関数に使用可能になります。前のオペレーションが最後の関数であった場合、$ctx.prev.result は最初の関数の出力を表し、パイプラインリゾルバーのレスポンスマッピングテンプレートに使用可能になります。

ID

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

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

API_KEY authorization

identity フィールドには値が入っていません。

AWS_IAM authorization

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

{ "accountId" = "string", "cognitoIdentityPoolId" = "string", "cognitoIdentityId" = "string", "sourceIp" = ["string"], "username" = "string", // IAM user principal "userArn" = "string" }
AMAZON_COGNITO_USER_POOLS authorization

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

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

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

accountId

呼び出し元の AWS アカウント ID。

claims

ユーザーが持つクレーム。

cognitoIdentityId

呼び出し元の Amazon Cognito ID。

cognitoIdentityPoolId

呼び出し元に関連付けられている Amazon Cognito ID プール。

defaultAuthStrategy

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

issuer

トークン発行者。

sourceIp

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 ユーザーの ARN。

username

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

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

AWS AppSync では、クライアントからカスタムヘッダーを渡して、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": { "S": "$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]")。

このページの内容: