AWS AppSync
AWS AppSync 開発者ガイド

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

AWS AppSync は GraphQL リゾルバー内で利用できるユーティリティを定義し、データソースとのやり取りを簡素化します。こうしたユーティリティには、ID やタイムスタンプの生成などあらゆるデータソースで使用できる汎用のユーティリティもあれば、データソースのみを対象とする固有のユーティリティもあります。

$util のユーティリティヘルパー

$util 変数には、データの操作を容易にする一般的なユーティリティメソッドが含まれています。

特に指定されていない限り、すべてのユーティリティでは UTF-8 文字セットが使用されます。

$util.qr() および $util.quiet()

VTL ステートメントを実行し、実行時に返された値を抑制します。これは、マップへの項目の追加など、一時的なプレースホルダーを使用せずにメソッドを実行する場合に便利です。以下に例を示します。

#set ($myMap = {}) #set($discard = $myMap.put("id", "first value"))

次のようになります。

#set ($myMap = {}) $util.qr($myMap.put("id", "first value"))
$util.escapeJavaScript(String) : String

入力文字列を JavasScript のエスケープした文字列として返します。

$util.urlEncode(String) : String

入力文字列を application/x-www-form-urlencoded でエンコードされた文字列として返します。

$util.urlDecode(String) : String

application/x-www-form-urlencoded でエンコードされた文字列をデコードして、エンコードされていない形式に戻します。

$util.base64Encode( byte[] ) : String

入力を base64 でエンコードされた文字列にエンコードします。

$util.base64Decode(String) : byte[]

base64 エンコードされた文字列からデータをデコードします。

$util.parseJson(String) : Object

"stringified" JSON を受け取り、結果のオブジェクト表現を返します。

$util.toJson(Object) : String

オブジェクトを受け取り、そのオブジェクトの「文字列化された」JSON 表現を返します。

$util.autoId() : String

ランダムに生成された 128 ビットの UUID を返します。

$util.unauthorized()

解決されるフィールドに対して Unauthorized をスローします。これは、呼び出し元にそのフィールドの解決が許可されるかどうかを判別するために、リクエストまたはレスポンスのマッピングテンプレートで使用できます。

$util.error(String)

カスタムエラーをスローします。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。

$util.error(String, String)

カスタムエラーをスローします。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。また、errorType を指定できます。

$util.error(String, String, Object)

カスタムエラーをスローします。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。また、errorTypedata フィールドを指定できます。data の値は、GraphQL のレスポンスの error 内の該当する errors ブロックに追加されます。注 : data はクエリ選択セットに基づいてフィルタリングされます。

$util.error(String, String, Object, Object)

カスタムエラーをスローします。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。また、errorType フィールド、data フィールド、および errorInfo フィールドを指定できます。data の値は、GraphQL のレスポンスの error 内の該当する errors ブロックに追加されます。注 : data はクエリ選択セットに基づいてフィルタリングされます。errorInfo の値は、GraphQL のレスポンスの error 内の該当する errors ブロックに追加されます。注 : errorInfo はクエリ選択セットに基づいてフィルタリングされません

$util.appendError(String)

カスタムエラーを追加します。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。$util.error(String) とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。

$util.appendError(String, String)

カスタムエラーを追加します。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。また、errorType を指定できます。$util.error(String, String) とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。

$util.appendError(String, String, Object)

カスタムエラーを追加します。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。また、errorTypedata フィールドを指定できます。$util.error(String, String, Object) とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。data の値は、GraphQL のレスポンスの error 内の該当する errors ブロックに追加されます。注 : data はクエリ選択セットに基づいてフィルタリングされます。

$util.appendError(String, String, Object, Object)

カスタムエラーを追加します。これは、リクエストまたはレスポンスのマッピングテンプレートでリクエストまたは呼び出し結果を持つエラーが検出される場合に、そのテンプレートで使用できます。また、errorType フィールド、data フィールド、および errorInfo フィールドを指定できます。$util.error(String, String, Object, Object) とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。data の値は、GraphQL のレスポンスの error 内の該当する errors ブロックに追加されます。注 : data はクエリ選択セットに基づいてフィルタリングされます。errorInfo の値は、GraphQL のレスポンスの error 内の該当する errors ブロックに追加されます。注 : errorInfo はクエリ選択セットに基づいてフィルタリングされません

$util.validate(boolean, String) : void

条件が false の場合、指定されたメッセージ付きで CustomTemplateException がスローされます。

$util.validate(boolean, String, String) : void

条件が false の場合、指定されたメッセージとエラータイプ付きで CustomTemplateException がスローされます。

$util.validate(boolean, String, String, Object) : void

条件が false の場合、指定されたメッセージ、エラータイプ、およびレスポンスで返されたデータ付きで CustomTemplateException がスローされます。

$util.isNull(Object) : boolean

指定されたオブジェクトが null である場合は true を返します。

$util.isNullOrEmpty(String) : boolean

指定されたデータが null または空の文字列である場合は true を返します。それ以外の場合は、false を返します。

$util.isNullOrBlank(String) : boolean

指定されたデータが null または空白文字列である場合は true を返します。それ以外の場合は、false を返します。

$util.defaultIfNull(Object, Object) : Object

最初のオブジェクトが null でない場合は、そのオブジェクトを返します。それ以外の場合は、2 番目のオブジェクトを「デフォルトオブジェクト」として返します。

$util.defaultIfNullOrEmpty(String, String) : String

最初の文字列型が null でも空の文字列でもない場合は、その文字列を返します。それ以外の場合は、2 番目の文字列型を「デフォルト文字列」として返します。

$util.defaultIfNullOrBlank(String, String) : String

最初の文字列型が null でも空白文字列でもない場合は、その文字列型を返します。それ以外の場合は、2 番目の文字列型を「デフォルト文字列」として返します。

$util.isString(Object) : boolean

オブジェクトが文字列型である場合は true を返します。

$util.isNumber(Object) : boolean

オブジェクトが数値型である場合は true を返します。

$util.isBoolean(Object) : boolean

オブジェクトがブール型である場合は true を返します。

$util.isList(Object) : boolean

オブジェクトがリスト型である場合は true を返します。

$util.isMap(Object) : boolean

オブジェクトがマップ型である場合は true を返します。

$util.typeOf(Object) : String

オブジェクトの型を表す文字列型を返します。サポートされている型識別名は "Null"、"Number"、"String"、"Map"、"List"、"Boolean" です。型を識別できない場合は、"Object" を返します。

$util.matches(String, String) : Boolean

最初の引数で指定されたパターンが、2 番目の引数で指定されたデータと一致する場合は true を返します。パターンは正規表現である必要があります (例: $util.matches("a*b", "aaaaab"))。この機能は Java の Pattern に基づいています。詳細については、Pattern を参照してください。

AWS AppSync ディレクティブ

AppSync では、Velocity の記述時に開発者の生産性を高めるディレクティブが公開されています。

#return(Object) マッピングテンプレートから途中で戻る必要がある場合は、#return ディレクティブが便利です。#return は、プログラミング言語の return キーワードに似ています。これは、最も近いスコープのロジックブロックから戻るためです。つまり、リゾルバーのマッピングテンプレート内で #return を使用すると、リゾルバーから戻ることになります。さらに、関数のマッピングテンプレートから #return を使用すると、実行は関数から戻り、パイプライン内の次の関数に、またはリゾルバーのレスポンスマッピングテンプレートに継続されます。

#return #return(Object) と同じですが、代わりに null が返されます。

$util.time の日時ヘルパー

$util.time 変数には、タイムスタンプの生成、日時形式間の変換、および日時文字列の解析に役立つ日時メソッドが含まれています。日時形式の構文は Java の DateTimeFormatter に基づいています。詳細については、DateTimeFormatter を参照してください。いくつかの例、および利用可能なメソッドの一覧と説明を以下に示します。

スタンドアロン関数の例

$util.time.nowISO8601() : 2018-02-06T19:01:35.749Z $util.time.nowEpochSeconds() : 1517943695 $util.time.nowEpochMilliSeconds() : 1517943695750 $util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ") : 2018-02-06 19:01:35+0000 $util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ", "+08:00") : 2018-02-07 03:01:35+0800 $util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ", "Australia/Perth") : 2018-02-07 03:01:35+0800

変換の例

#set( $nowEpochMillis = 1517943695758 ) $util.time.epochMilliSecondsToSeconds($nowEpochMillis) : 1517943695 $util.time.epochMilliSecondsToISO8601($nowEpochMillis) : 2018-02-06T19:01:35.758Z $util.time.epochMilliSecondsToFormatted($nowEpochMillis, "yyyy-MM-dd HH:mm:ssZ") : 2018-02-06 19:01:35+0000 $util.time.epochMilliSecondsToFormatted($nowEpochMillis, "yyyy-MM-dd HH:mm:ssZ", "+08:00") : 2018-02-07 03:01:35+0800

解析の例

$util.time.parseISO8601ToEpochMilliSeconds("2018-02-01T17:21:05.180+08:00") : 1517476865180 $util.time.parseFormattedToEpochMilliSeconds("2018-02-02 01:19:22+0800", "yyyy-MM-dd HH:mm:ssZ") : 1517505562000 $util.time.parseFormattedToEpochMilliSeconds("2018-02-02 01:19:22", "yyyy-MM-dd HH:mm:ss", "+08:00") : 1517505562000

AWS スカラーの使用法

次の形式は、AWSDateAWSDateTime、および AWSTime と互換性があります。

$util.time.nowFormatted("yyyy-MM-dd[XXX]", "-07:00:30") : 2018-07-11-07:00 $util.time.nowFormatted("yyyy-MM-dd'T'HH:mm:ss[XXXXX]", "-07:00:30") : 2018-07-11T15:14:15-07:00:30
$util.time.nowISO8601() : String

ISO 8601 形式の UTC の文字列型表現を返します。

$util.time.nowEpochSeconds() : long

エポック (1970-01-01T00:00:00Z) から現在までの秒数を返します。

$util.time.nowEpochMilliSeconds() : long

エポック (1970-01-01T00:00:00Z) から現在までのミリ秒数を返します。

$util.time.nowFormatted(String) : String

文字列型の入力引数で指定された形式を使用して、UTC での現在のタイムスタンプを返します。

$util.time.nowFormatted(String, String) : String

文字列型の入力引数で指定された形式とタイムゾーンを使用して、そのタイムゾーンでの現在のタイムスタンプを返します。

$util.time.parseFormattedToEpochMilliSeconds(String, String) : Long

文字列型として渡されたタイムスタンプと形式を解析し、エポックからのミリ秒単位のタイムスタンプを返します。

$util.time.parseFormattedToEpochMilliSeconds(String, String, String) : Long

文字列型として渡されたタイムスタンプ、形式、およびタイムゾーンを解析し、エポックからのミリ秒単位のタイムスタンプを返します。

$util.time.parseISO8601ToEpochMilliSeconds(String) : Long

文字列型として渡された ISO8601 形式のタイムスタンプを解析し、エポックからのミリ秒単位のタイムスタンプを返します。

$util.time.epochMilliSecondsToSeconds(long) : long

エポックからのミリ秒単位のタイムスタンプを、エポックからの秒単位のタイムスタンプに変換します。

$util.time.epochMilliSecondsToISO8601(long) : String

エポックからのミリ秒単位のタイムスタンプを、ISO8601 形式のタイムスタンプに変換します。

$util.time.epochMilliSecondsToFormatted(long, String) : String

long として渡されたエポックからのミリ秒単位のタイムスタンプを、文字列型で指定された形式に合わせて UTC でのタイムスタンプに変換します。

$util.time.epochMilliSecondsToFormatted(long, String, String) : String

long として渡されたエポックからのミリ秒単位のタイムスタンプを、文字列型で指定された形式とタイムゾーンに合わせて、そのタイムゾーンでのタイムスタンプに変換します。

$util.list のリストヘルパー

$util.list には、よく使用されるリストオペレーション (フィルタリングのユースケースでのリストの項目の削除や保持など) に役立つメソッドが含まれています。

$util.list.copyAndRetainAll(List, List) : List

最初の引数で指定されたリストのシャローコピーを作成し、2 番目の引数で指定された項目のみを保持します (存在する場合)。他のすべての項目はそのコピーから削除されます。

$util.list.copyAndRemoveAll(List, List) : List

最初の引数で指定されたリストのシャローコピーを作成し、2 番目の引数で指定されたすべての項目を削除します (存在する場合)。他のすべての項目はそのコピーで保持されます。

$util.map のマップヘルパー

$util.map には、よく使用されるマップオペレーション (フィルタリングのユースケースでのマップの項目の削除や保持など) に役立つメソッドが含まれています。

$util.map.copyAndRetainAllKeys(Map, List) : Map

最初の引数で指定されたマップのシャローコピーを作成し、リストで指定されたキーのみを保持します (存在する場合)。他のすべてのキーはそのコピーから削除されます。

$util.map.copyAndRemoveAllKeys(Map, List) : Map

最初の引数で指定されたマップのシャローコピーを作成し、リストで指定されたキーを持つすべてのエントリを削除します (存在する場合)。他のすべてのキーはそのコピーで保持されます。

$util.dynamodb の DynamoDB ヘルパー

$util.dynamodb には、Amazon DynamoDB に対するデータの読み書きを容易にするヘルパーメソッド (自動型マッピングやフォーマットなど) が含まれています。これらのメソッドは、プリミティブ型やリスト型を適切な DynamoDB 入力形式に自動的にマッピングするように設計されていて、そのマッピングは { "TYPE" : VALUE } 形式の Map です。

たとえば、前述の例で、DynamoDB に新しい項目を作成するリクエストマッピングテンプレートは次のようになっていました。

{ "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : { "S" : "${util.autoId()}" } }, "attributeValues" : { "title" : { "S" : "${ctx.args.title}" }, "author" : { "S" : "${ctx.args.author}" }, "version" : { "N", $ctx.args.version } } }

このオブジェクトにフィールドを追加する場合は、スキーマで GraphQL でクエリを更新し、リクエストマッピングテンプレートも更新する必要があります。ただし、スキーマに追加された新しいフィールドが自動的に取得され、正しい型で DynamoDB に追加されるように、リクエストマッピングテンプレートを再構築できるようになりました。

{ "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : $util.dynamodb.toDynamoDBJson($util.autoId()) }, "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args) }

上記の例では、$util.dynamodb.toDynamoDBJson(...) ヘルパーを使用して、生成された ID を自動的に取得し、それを文字列属性の DynamoDB 表現に変換しています。次に、すべての引数を取得して DynamoDB 表現に変換し、それをテンプレートの attributeValues フィールドに出力しています。

各ヘルパーには、オブジェクトを返すバージョン (例 : $util.dynamodb.toString(...)) と、オブジェクトを JSON 文字列として返すバージョン (例 : $util.dynamodb.toStringJson(...)) の 2 つのバージョンがあります。上記の例では、データを JSON 文字列として返すバージョンを使用していました。次に示すように、オブジェクトがテンプレートで使用される前にそのオブジェクトを操作する場合は、代わりにオブジェクトを返すことを選択できます。

{ "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : $util.dynamodb.toDynamoDBJson($util.autoId()) }, #set( $myFoo = $util.dynamodb.toMapValues($ctx.args) ) #set( $myFoo.version = $util.dynamodb.toNumber(1) ) #set( $myFoo.timestamp = $util.dynamodb.toString($util.time.nowISO8601())) "attributeValues" : $util.toJson($myFoo) }

前述の例では、変換された引数を JSON 文字列としてではなくマップとして返し、version フィールドと timestamp フィールドを追加してから、最終的にテンプレートで attributeValues を使用してそれらを $util.toJson(...) フィールドに出力していました。

各ヘルパーの JSON バージョンは、非 JSON バージョンを $util.toJson(...) でラップすることと等価です。たとえば、次の 2 つのステートメントはまったく同じです。

$util.toStringJson("Hello, World!") $util.toJson($util.toString("Hello, World!"))
$util.dynamodb.toDynamoDB(Object) : Map

入力オブジェクトを該当する DynamoDB 表現に変換する、DynamoDB 用の一般的なオブジェクト変換ツール。このツールは、一部の型の表現方法に関して融通が利きません。たとえば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

文字列型の例:

Input: $util.dynamodb.toDynamoDB("foo") Output: { "S" : "foo" }

数値型の例:

Input: $util.dynamodb.toDynamoDB(12345) Output: { "N" : 12345 }

ブール型の例:

Input: $util.dynamodb.toDynamoDB(true) Output: { "BOOL" : true }

リスト型の例:

Input: $util.dynamodb.toDynamoDB([ "foo", 123, { "bar" : "baz" } ]) Output: { "L" : [ { "S" : "foo" }, { "N" : 123 }, { "M" : { "bar" : { "S" : "baz" } } } ] }

マップ型の例:

Input: $util.dynamodb.toDynamoDB({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "M" : { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } }
$util.dynamodb.toDynamoDBJson(Object) : String

$util.dynamodb.toDynamoDB(Object) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toString(String) : String

入力文字列を DynamoDB の文字列形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toString("foo") Output: { "S" : "foo" }
$util.dynamodb.toStringJson(String) : Map

$util.dynamodb.toString(String) : String と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toStringSet(List<String>) : Map

文字列型のリスト型を DynamoDB の文字列セット形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toStringSet([ "foo", "bar", "baz" ]) Output: { "SS" : [ "foo", "bar", "baz" ] }
$util.dynamodb.toStringSetJson(List<String>) : String

$util.dynamodb.toStringSet(List<String>) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toNumber(Number) : Map

数値を DynamoDB の数値形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toNumber(12345) Output: { "N" : 12345 }
$util.dynamodb.toNumberJson(Number) : String

$util.dynamodb.toNumber(Number) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toNumberSet(List<Number>) : Map

数値のリストを DynamoDB の数値セット形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toNumberSet([ 1, 23, 4.56 ]) Output: { "NS" : [ 1, 23, 4.56 ] }
$util.dynamodb.toNumberSetJson(List<Number>) : String

$util.dynamodb.toNumberSet(List<Number>) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toBinary(String) : Map

base64 文字列としてエンコードされたバイナリデータを DynamoDB のバイナリ形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toBinary("foo") Output: { "B" : "foo" }
$util.dynamodb.toBinaryJson(String) : String

$util.dynamodb.toBinary(String) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toBinarySet(List<String>) : Map

base64 文字列としてエンコードされたバイナリデータのリストを DynamoDB のバイナリセット形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toBinarySet([ "foo", "bar", "baz" ]) Output: { "BS" : [ "foo", "bar", "baz" ] }
$util.dynamodb.toBinarySetJson(List<String>) : String

$util.dynamodb.toBinarySet(List<String>) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toBoolean(boolean) : Map

ブール値を DynamoDB の該当するブール形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toBoolean(true) Output: { "BOOL" : true }
$util.dynamodb.toBooleanJson(boolean) : String

$util.dynamodb.toBoolean(boolean) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toNull() : Map

null を DynamoDB の null 形式で返します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toNull() Output: { "NULL" : null }
$util.dynamodb.toNullJson() : String

$util.dynamodb.toNull() : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toList(List) : Map

オブジェクトのリストを DynamoDB のリスト形式に変換します。リスト内の各項目も、該当する DynamoDB 形式に変換されます。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。たとえば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toList([ "foo", 123, { "bar" : "baz" } ]) Output: { "L" : [ { "S" : "foo" }, { "N" : 123 }, { "M" : { "bar" : { "S" : "baz" } } } ] }
$util.dynamodb.toListJson(List) : String

$util.dynamodb.toList(List) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toMap(Map) : Map

マップを DynamoDB のマップ形式に変換します。マップ内の各値も、該当する DynamoDB 形式に変換されます。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。たとえば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toMap({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "M" : { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } }
$util.dynamodb.toMapJson(Map) : String

$util.dynamodb.toMap(Map) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toMapValues(Map) : Map

マップ内の各値を該当する DynamoDB 形式に変換して、マップのコピーを作成します。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。たとえば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。

Input: $util.dynamodb.toMapValues({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } }

注 : このツールは $util.dynamodb.toMap(Map) : Map と少し異なっていて、属性値全体ではなく DynamoDB の属性値の内容のみを返します。たとえば、次の 2 つのステートメントはまったく同じです。

$util.dynamodb.toMapValues($map) $util.dynamodb.toMap($map).get("M")
$util.dynamodb.toMapValuesJson(Map) : String

$util.dynamodb.toMapValues(Map) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toS3Object(String key, String bucket, String region) : Map

キー、バケット、およびリージョンを DynamoDB の S3 オブジェクト表現に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toS3Object("foo", "bar", region = "baz") Output: { "S" : "{ \"s3\" : { \"key\" : \"foo", \"bucket\" : \"bar", \"region\" : \"baz" } }" }
$util.dynamodb.toS3ObjectJson(String key, String bucket, String region) : String

$util.dynamodb.toS3Object(String key, String bucket, String region) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.toS3Object(String key, String bucket, String region, String version) : Map

キー、バケット、リージョン、およびバージョン (省略可) を DynamoDB の S3 オブジェクト表現に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。

Input: $util.dynamodb.toS3Object("foo", "bar", "baz", "beep") Output: { "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" }
$util.dynamodb.toS3ObjectJson(String key, String bucket, String region, String version) : String

$util.dynamodb.toS3Object(String key, String bucket, String region, String version) : Map と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

$util.dynamodb.fromS3ObjectJson(String) : Map

DynamoDB の S3 オブジェクトの文字列値を受け入れて、キー、バケット、リージョン、およびバージョン (省略可) が含まれているマップを返します。

Input: $util.dynamodb.fromS3ObjectJson({ "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" }) Output: { "key" : "foo", "bucket" : "bar", "region" : "baz", "version" : "beep" }

$ util.rds の RDS ヘルパー

$util.rds.toJsonString(String serializedSQLResult): String

文字列化された生の RDS Data API 結果形式をより簡潔な文字列に変換して、String を返します。返される文字列は、結果セットの SQL レコードのリストのシリアル化されたリストです。すべてのレコードはキーと値のペアの集合として表されます。キーは対応する列名です。

入力内の対応するステートメントがミューテーションの実行元の SQL クエリ (INSERT、UPDATE、DELETE など) であった場合は、空のリストが返されます。たとえば、クエリ select * from Books limit 2 では、RDS Data API からの生の結果が返されます。

{ "sqlStatementResults": [ { "numberOfRecordsUpdated": 0, "records": [ [ { "stringValue": "Mark Twain" }, { "stringValue": "Adventures of Huckleberry Finn" }, { "stringValue": "978-1948132817" } ], [ { "stringValue": "Jack London" }, { "stringValue": "The Call of the Wild" }, { "stringValue": "978-1948132275" } ] ], "columnMetadata": [ { "isSigned": false, "isCurrency": false, "label": "author", "precision": 200, "typeName": "VARCHAR", "scale": 0, "isAutoIncrement": false, "isCaseSensitive": false, "schemaName": "", "tableName": "Books", "type": 12, "nullable": 0, "arrayBaseColumnType": 0, "name": "author" }, { "isSigned": false, "isCurrency": false, "label": "title", "precision": 200, "typeName": "VARCHAR", "scale": 0, "isAutoIncrement": false, "isCaseSensitive": false, "schemaName": "", "tableName": "Books", "type": 12, "nullable": 0, "arrayBaseColumnType": 0, "name": "title" }, { "isSigned": false, "isCurrency": false, "label": "ISBN-13", "precision": 15, "typeName": "VARCHAR", "scale": 0, "isAutoIncrement": false, "isCaseSensitive": false, "schemaName": "", "tableName": "Books", "type": 12, "nullable": 0, "arrayBaseColumnType": 0, "name": "ISBN-13" } ] } ] }

utils.rds.toJsonString は以下のようになります。

[ { "author": "Mark Twain", "title": "Adventures of Huckleberry Finn", "ISBN-13": "978-1948132817" }, { "author": "Jack London", "title": "The Call of the Wild", "ISBN-13": "978-1948132275" }, ]

$util.rds.toJsonObject(String serializedSQLResult): Object

utils.rds.toJsonString と同じですが、結果は Json Object になります。

$utils.http の HTTP ヘルパー

$utils.http には、http リクエストパラメーターの処理を容易にするヘルパーメソッドが含まれています。

$utils.http.copyHeaders(Map) : Map

HTTP ヘッダーを制限せずに、マップからヘッダーをコピーします。これは、リクエストヘッダーをダウンストリーム HTTP エンドポイントに転送する場合に役立ちます。

{ ... "params": { ... "headers": $utils.http.copyHeaders($ctx.request.headers), ... }, ... }

$utils.xml の XML ヘルパー

$utils.xml には、XML レスポンスを JSON またはディクショナリに変換しやすくするヘルパーメソッドが含まれています。

$utils.xml.toMap(String) : Map

XML 文字列をディクショナリに変換します。

Input: <?xml version="1.0" encoding="UTF-8"?> <posts> <post> <id>1</id> <title>Getting Started with GraphQL</title> </post> </posts> Output (JSON representation): { "posts":{ "post":{ "id":1, "title":"Getting Started with GraphQL" } } } Input: <?xml version="1.0" encoding="UTF-8"?> <posts> <post> <id>1</id> <title>Getting Started with GraphQL</title> </post> <post> <id>2</id> <title>Getting Started with AWS AppSync</title> </post> </posts> Output (JSON representation): { "posts":{ "post":[ { "id":1, "title":"Getting Started with GraphQL" }, { "id":2, "title":"Getting Started with AWS AppSync" } ] } }

$utils.xml.toJsonString(String) : String

XML 文字列を JSON 文字列に変換します。これは、出力が文字列である点を除き、toMap に似ています。これは、XML レスポンスを HTTP オブジェクトから JSON に直接変換し、返す場合に便利です。

$utils.xml.toJsonString(String, boolean) : String

XML 文字列を JSON 文字列に変換します。オプションのブールパラメーターを使用して、JSON を文字列エンコードするか判断します。

$utils.transform の変換ヘルパー

$utils.transform には、Amazon DynamoDB フィルター処理などの、データソースに対する複雑なオペレーションの実行を容易にするヘルパーメソッドが含まれています。

$util.transform.toDynamoDBFilterExpression(Map) : Map

Amazon DynamoDB で使用するために、入力文字列をフィルター式に変換します。

Input: $util.transform.toDynamoDBFilterExpression({ title:{ contains:"Hello World" } }) Output: { "expression" : "contains(#title, :title_contains)" "expressionNames" : { "#title" : "title", }, "expressionValues" : { ":title_contains" : { "S" : "${context.arguments.filter.title.contains}" } }, }