AWS AppSync JavaScript リゾルバーコンテキストオブジェクトリファレンス

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

context へのアクセス

リクエスト&レスポンスハンドラーの context 引数は、リゾルバー呼び出しのコンテキスト情報をすべて保持するオブジェクトです。この変数の構造は次のとおりです。

type Context = {
  arguments: any;
  args: any;
  identity: Identity;
  source: any;
  error?: {
    message: string;
    type: string;
  };
  stash: any;
  result: any;
  prev: any;
  request: Request;
  info: Info;
};

注記

context オブジェクトは ctx と呼ばれることがよくあります。

context オブジェクトの各フィールドは次のように定義されます。

context フィールド

arguments

このフィールドのすべての GraphQL 引数を含むマップ。

identity

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

source

親フィールドの解像度を含むマップ。

stash

stash は、リゾルバーと関数ハンドラー内部で使用可能になるオブジェクトです。リゾルバーを 1 回実行すると、同じ stash オブジェクトが存続します。つまり、stash を使用して、リクエストとレスポンスのハンドラー間、およびパイプラインリゾルバーの関数間で、任意のデータを渡すことができます。

注記

stash 全体を削除または置換することはできませんが、スタッシュのプロパティを追加、更新、削除、および読み取ることはできます。

以下のコード例のいずれかを変更することで、stash にアイテムを追加できます。

//Example 1
ctx.stash.newItem = { key: "something" }

//Example 2
Object.assign(ctx.stash, {key1: value1, key2: value})

以下のコードを変更することで、stashからアイテムを削除できます。

delete ctx.stash.key

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 の形式は次のとおりです。

type AppSyncIdentityLambda = {
  resolverContext: any;
};

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

AWS_IAM authorization

identity の形式は次のとおりです。

type AppSyncIdentityIAM = {
  accountId: string;
  cognitoIdentityPoolId: string;
  cognitoIdentityId: string;
  sourceIp: string[];
  username: string;
  userArn: string;
  cognitoIdentityAuthType: string;
  cognitoIdentityAuthProvider: string;
};

AMAZON_COGNITO_USER_POOLS authorization

identity の形式は次のとおりです。

type AppSyncIdentityCognito = {
  sourceIp: string[];
  username: string;
  groups: string[] | null;
  sub: string;
  issuer: string;
  claims: any;
  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 認可の場合、username の値は AWS ユーザープリンシパルの値です。Amazon Cognito アイデンティティプールから発行された認証情報による IAM 認可を使用されている場合は、cognitoIdentityIdの使用をお勧めします。

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

AWS AppSync では、クライアントからカスタムヘッダーを渡して、GraphQL リゾルバーで ctx.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

この値には ctx.request.headers.custom を使用してアクセスできます。たとえば、DynamoDB に対する VTL は次のようになります。

"custom": util.dynamodb.toDynamoDB(ctx.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

それらのヘッダーに配列としてアクセスできます (例: ctx.request.headers.custom[1])。

注記

AWS AppSync では、ctx.request.headers に Cookie ヘッダーが公開されません。

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

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

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

情報

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

type Info = {
  fieldName: string;
  parentTypeName: string;
  variables: any;
  selectionSetList: string[];
  selectionSetGraphQL: string;
};

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

fieldName

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

parentTypeName

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

variables

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

selectionSetList

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

selectionSetGraphQL

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

注記

JSON.stringify では文字列のシリアル化には 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
  }
}

ハンドラーを処理する際に使用可能な完全な ctx.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"
]