翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS AppSync リゾルバーマッピングテンプレートユーティリティリファレンス **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 AWS AppSync は、データソースとのやり取りを簡素化するために GraphQL リゾルバー内で使用できる一連のユーティリティを定義します。これらのユーティリティの中には、ID やタイムスタンプの生成など、あらゆるデータソースで一般的に使用されるものもあります。その他には、データソースの種類に固有のものもあります。次のユーティリティを使用できます。 + [\$1util のユーティリティヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/utility-helpers-in-util.html) - \$1util変数には、データの操作を容易にする一般的なユーティリティメソッドが含まれています。特に指定されていない限り、すべてのユーティリティでは UTF-8 文字セットが使用されます。 + [AppSync ディレクティブ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-directives.html) - AppSync では、VTL の記述時に開発者の生産性を高めるディレクティブが公開されています。 + [\$1util.time のタイムヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/time-helpers-in-util-time.html) - \$1util.time 変数には、タイムスタンプの生成、日時形式間の変換、および日時文字列の解析に役立つ日時メソッドが含まれています。日時形式の構文は DateTimeFormatter に基づいています。詳細については、[DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) を参照してください。 + [\$1util.list のリストヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/list-helpers-in-util-list.html) - \$1util.list には、よく使用されるリストオペレーション (フィルタリングのユースケースでのリストの項目の削除や保持など) に役立つメソッドが含まれています。 + [\$1util.map のマップヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/utility-helpers-in-map.html) - \$1util.map には、よく使用されるマップオペレーション (フィルタリングのユースケースでのマップの項目の削除や保持など) に役立つメソッドが含まれています。 + [\$1util.dynamodb のDynamoDB ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb.html) - \$1util.dynamodb には、Amazon DynamoDB に対するデータの読み書きを容易にするヘルパーメソッド (自動型マッピングやフォーマットなど) が含まれています。 + [\$1util.rds の Amazon RDS ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/rds-helpers-in-util-rds.html) - \$1util.rds には、結果出力から不要なデータを削除して RDS オペレーションをフォーマットするヘルパーメソッドが含まれています。 + [\$1util.http の HTTP ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/http-helpers-in-utils-http.html) - \$1util.http ユーティリティには、HTTP リクエストパラメータの管理やレスポンスヘッダーの追加に使用できるヘルパーメソッドが用意されています。 + [\$1util.xml の XML ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/xml-helpers-in-utils-xml.html) - \$1util.xml には、XML レスポンスを JSON またはディクショナリに変換しやすくするヘルパーメソッドが含まれています。 + [\$1util.transform の変換ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/transformation-helpers-in-utils-transform.html) - \$1util.transform には、DynamoDB フィルターオペレーションのような、データソースに対して複雑な操作を簡単に実行できるヘルパーメソッドが含まれています。 + [\$1util.math の数学ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/math-helpers-in-util-math.html) - \$1util.math には、一般的な数学オペレーションに役立つメソッドが含まれています。 + [\$1util.str の文字列ヘルパー](https://docs.aws.amazon.com/appsync/latest/devguide/str-helpers-in-util-str.html) - \$1util.str には、一般的な文字列オペレーションに役立つメソッドが含まれています。 + [拡張機能](https://docs.aws.amazon.com/appsync/latest/devguide/extensions.html) - \$1extensions には、リゾルバー内で追加のアクションを行うためのメソッドのセットが含まれています。 # \$1util のユーティリティヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util` 変数には、データの操作を容易にする一般的なユーティリティメソッドが含まれています。特に指定されていない限り、すべてのユーティリティでは UTF-8 文字セットが使用されます。 ## JSON パーシング utils ### JSON パーシング utils リスト ** **`$util.parseJson(String) : Object`** ** "stringified" JSON を受け取り、結果のオブジェクト表現を返します。 ** **`$util.toJson(Object) : String`** ** オブジェクトを受け取り、そのオブジェクトの「文字列化された」JSON 表現を返します。 ## エンコーディング utils ### エンコーディング utils リスト ** **`$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 エンコードされた文字列からデータをデコードします。 ## ID 生成 utils ### ID 生成 utils リスト ** **`$util.autoId() : String`** ** ランダムに生成された 128 ビットの UUID を返します。 ****`$util.autoUlid() : String`**** ランダムに生成された 128 ビットの ULID (辞書的にソート可能なユニバーサルユニーク識別子) を返します。 ****`$util.autoKsuid() : String`**** 長さ 27 の文字列としてエンコードされた、ランダムに生成された 128 ビットの KSUID (K ソート可能な固有識別子) base62 を返します。 ## エラー utils ### エラー utils リスト ** `$util.error(String)` ** カスタムエラーをスローします。リクエストや呼び出し結果のエラーを検出するために、リクエストやレスポンスのマッピングテンプレートでこれを使用します。 ** `$util.error(String, String)` ** カスタムエラーをスローします。リクエストや呼び出し結果のエラーを検出するために、リクエストやレスポンスのマッピングテンプレートでこれを使用します。`errorType` を指定することもできます。 ** `$util.error(String, String, Object)` ** カスタムエラーをスローします。リクエストや呼び出し結果のエラーを検出するために、リクエストやレスポンスのマッピングテンプレートでこれを使用します。`errorType` と `data` フィールドを指定することもできます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `data` はクエリ選択セットに基づいてフィルタリングされます。 ** `$util.error(String, String, Object, Object)` ** カスタムエラーをスローします。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` フィールド、`data` フィールド、および `errorInfo` フィールドを指定できます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `data` はクエリ選択セットに基づいてフィルタリングされます。`errorInfo` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `errorInfo` はクエリ選択セットに基づいてフィルタリング**されません**。 ** `$util.appendError(String)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。`$util.error(String)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。 ** `$util.appendError(String, String)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` を指定できます。`$util.error(String, String)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。 ** `$util.appendError(String, String, Object)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` と `data` フィールドを指定できます。`$util.error(String, String, Object)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `data` はクエリ選択セットに基づいてフィルタリングされます。 ** `$util.appendError(String, String, Object, Object)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` フィールド、`data` フィールド、および `errorInfo` フィールドを指定できます。`$util.error(String, String, Object, Object)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `data` はクエリ選択セットに基づいてフィルタリングされます。`errorInfo` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。 `errorInfo` はクエリ選択セットに基づいてフィルタリング**されません**。 ## 条件検証 utils ### 条件検証 utils リスト ** `$util.validate(Boolean, String) : void` ** 条件が false の場合、指定されたメッセージ付きで CustomTemplateException がスローされます。 ** `$util.validate(Boolean, String, String) : void` ** 条件が false の場合、指定されたメッセージとエラータイプ付きで CustomTemplateException がスローされます。 ** `$util.validate(Boolean, String, String, Object) : void` ** 条件が false の場合、指定されたメッセージ、エラータイプ、およびレスポンスで返されたデータ付きで CustomTemplateException がスローされます。 ## Null 動作 utils ### Null 動作 utils リスト ** `$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 番目の文字列型を「デフォルト文字列」として返します。 ## パターンのマッチング utils ### タイプとパターンの一致 utils リスト ** `$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](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html) を参照してください。 ** `$util.authType() : String` ** リクエストで使用されているマルチ認可タイプを表す文字列型 (String) の値を返します。「IAM 認可」、「ユーザープールの認可」、「オープン ID Connect 認可」、または「API キー認可」のいずれかを返します。 ## Object validation utils ### Object validation utils リスト ** `$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 を返します。 ## CloudWatch ログ記録 Utils ### CloudWatch ログ記録 Utils リスト **`$util.log.info(Object) : Void`** API のログレベル `ALL`、`INFO`、または `DEBUG` でリクエストレベルとフィールドレベルの CloudWatch ロギングが有効になっている場合、提供されたオブジェクトの文字列表現をリクエストされたログストリームに記録します。 **`$util.log.info(String, Object...) : Void`** API のログレベル `ALL` でリクエストレベルとフィールドレベルの CloudWatch ロギングが有効になっている場合、提供されたオブジェクトの String 表現をリクエストされたログストリームに記録します。このユーティリティは、最初の入力フォーマット String の「\$1\$1」で示されるすべての変数を、指定されたオブジェクトの文字列表現に順番に置き換えます。 **`$util.log.debug(Object) : Void`** API のログレベル `ALL` または `DEBUG` でリクエストレベルとフィールドレベルの CloudWatch ロギングが有効になっている場合、提供されたオブジェクトの文字列表現をリクエストされたログストリームに記録します。 **`$util.log.debug(String, Object...) : Void`** ログレベル `DEBUG` または API のログレベル `ALL` でフィールドレベルの CloudWatch ロギングが有効になっている場合、要求されたログストリームに提供されたオブジェクトの文字列表現を記録します。このユーティリティは、最初の入力フォーマット String の「\$1\$1」で示されるすべての変数を、指定されたオブジェクトの文字列表現に順番に置き換えます。 **`$util.log.error(Object) : Void`** API の**任意の**ログレベル (`ALL`、`INFO`、`DEBUG` など) でフィールドレベルの CloudWatch ロギングが有効になっている場合、提供されたオブジェクトの文字列表現をリクエストされたログストリームに記録します。 **`$util.log.error(String, Object...) : Void`** ログレベル `ERROR` または API のログレベル `ALL` でフィールドレベルの CloudWatch ロギングが有効になっている場合、要求されたログストリームに提供されたオブジェクトの文字列表現を記録します。このユーティリティは、最初の入力フォーマット String の「\$1\$1」で示されるすべての変数を、指定されたオブジェクトの文字列表現に順番に置き換えます。 ## 戻り値の動作 utils ### 戻り値の動作 utils リスト ****`$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.autoUlid() : String`**** ランダムに生成された 128 ビットの ULID (辞書的にソート可能なユニバーサルユニーク識別子) を返します。 ****`$util.autoKsuid() : String`**** 長さ 27 の文字列としてエンコードされた、ランダムに生成された 128 ビットの KSUID (K ソート可能な固有識別子) base62 を返します。 ** `$util.unauthorized()` ** 解決されるフィールドに対して `Unauthorized` をスローします。これは、呼び出し元にそのフィールドの解決が許可されるかどうかを判別するために、リクエストまたはレスポンスのマッピングテンプレートで使用できます。 ** `$util.error(String)` ** カスタムエラーをスローします。リクエストや呼び出し結果のエラーを検出するために、リクエストやレスポンスのマッピングテンプレートでこれを使用します。 ** `$util.error(String, String)` ** カスタムエラーをスローします。リクエストや呼び出し結果のエラーを検出するために、リクエストやレスポンスのマッピングテンプレートでこれを使用します。`errorType` を指定することもできます。 ** `$util.error(String, String, Object)` ** カスタムエラーをスローします。リクエストや呼び出し結果のエラーを検出するために、リクエストやレスポンスのマッピングテンプレートでこれを使用します。`errorType` と `data` フィールドを指定することもできます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。**注 :** `data` はクエリ選択セットに基づいてフィルタリングされます。 ** `$util.error(String, String, Object, Object)` ** カスタムエラーをスローします。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` フィールド、`data` フィールド、および `errorInfo` フィールドを指定できます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。**注 :** `data` はクエリ選択セットに基づいてフィルタリングされます。`errorInfo` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。**注 : **`errorInfo` はクエリ選択セットに基づいてフィルタリング**されません**。 ** `$util.appendError(String)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。`$util.error(String)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。 ** `$util.appendError(String, String)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` を指定できます。`$util.error(String, String)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。 ** `$util.appendError(String, String, Object)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` と `data` フィールドを指定できます。`$util.error(String, String, Object)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。**注 :** `data` はクエリ選択セットに基づいてフィルタリングされます。 ** `$util.appendError(String, String, Object, Object)` ** カスタムエラーを追加します。これは、テンプレートがリクエストまたは呼び出し結果でエラーを検出した場合に、リクエストまたはレスポンスのマッピングテンプレートで使用できます。また、`errorType` フィールド、`data` フィールド、および `errorInfo` フィールドを指定できます。`$util.error(String, String, Object, Object)` とは異なり、テンプレートの評価は中断されないため、データを呼び出し元に返すことができます。`data` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。**注 :** `data` はクエリ選択セットに基づいてフィルタリングされます。`errorInfo` の値は、GraphQL レスポンスの `errors` 内の該当する `error` ブロックに追加されます。**注 : **`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](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html) を参照してください。 ** `$util.authType() : String` ** リクエストで使用されているマルチ認可タイプを表す文字列型 (String) の値を返します。「IAM 認可」、「ユーザープールの認可」、「オープン ID Connect 認可」、または「API キー認可」のいずれかを返します。 ****`$util.log.info(Object) : Void`**** API のログレベル `ALL` でリクエストレベルとフィールドレベルの CloudWatch ロギングが有効になっている場合、提供されたオブジェクトの String 表現をリクエストされたログストリームに記録します。 ****`$util.log.info(String, Object...) : Void`**** API のログレベル `ALL` でリクエストレベルとフィールドレベルの CloudWatch ロギングが有効になっている場合、提供されたオブジェクトの String 表現をリクエストされたログストリームに記録します。このユーティリティは、最初の入力フォーマット String の「\$1\$1」で示されるすべての変数を、指定されたオブジェクトの文字列表現に順番に置き換えます。 ****`$util.log.error(Object) : Void`**** ログレベル `ERROR` または API のログレベル `ALL` でフィールドレベルの CloudWatch ロギングが有効になっている場合、要求されたログストリームに提供されたオブジェクトの文字列表現を記録します。 ****`$util.log.error(String, Object...) : Void`**** ログレベル `ERROR` または API のログレベル `ALL` でフィールドレベルの CloudWatch ロギングが有効になっている場合、要求されたログストリームに提供されたオブジェクトの文字列表現を記録します。このユーティリティは、最初の入力フォーマット String の「\$1\$1」で示されるすべての変数を、指定されたオブジェクトの文字列表現に順番に置き換えます。 ** `$util.escapeJavaScript(String) : String` ** 入力文字列を JavasScript のエスケープした文字列として返します。 ## リゾルバー認可 ### リゾルバー承認リスト ** `$util.unauthorized()` ** 解決されるフィールドに対して `Unauthorized` をスローします。これは、呼び出し元にそのフィールドの解決が許可されるかどうかを判別するために、リクエストまたはレスポンスのマッピングテンプレートで使用できます。 # AWS AppSync ディレクティブ **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 AWS AppSync は、VTL で記述するときに開発者の生産性を向上させるためのディレクティブを公開します。 ## ディレクティブ utils ****`#return(Object)`**** `#return(Object)` により、どのマッピングテンプレートからも早期に戻ることができます。`#return(Object)` はプログラミング言語の *return* キーワードに似ており、最も近いスコープのロジックブロックから戻ります。つまり、リゾルバーのマッピングテンプレート内で `#return(Object)` を使用すると、リゾルバーから戻ることになります。さらに、関数のマッピングテンプレートから `#return(Object)` を使用すると、実行は関数から戻り、パイプライン内の次の関数に、またはリゾルバーのレスポンスマッピングテンプレートに継続されます。 ****`#return`**** `#return` ディレクティブは `#return(Object)` と同じ動作をしますが、`null` は代わりに返されます。 # \$1util.time の日時ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.time` 変数には、タイムスタンプの生成、日時形式間の変換、および日時文字列の解析に役立つ日時メソッドが含まれています。日時形式の構文は Java の DateTimeFormatter に基づいています。詳細については、[DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) を参照してください。いくつかの例、および利用可能なメソッドの一覧と説明を以下に示します。 ## 日時 utils ### 日時 utils リスト ** `$util.time.nowISO8601() : String` ** [ISO 8601 形式](https://en.wikipedia.org/wiki/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.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 AppSync 定義されたスカラーの使用 次の形式は、`AWSDate`、`AWSDateTime`、および `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 ``` # \$1util.list のヘルパーのリスト **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.list` には、よく使用されるリストオペレーション (フィルタリングのユースケースでのリストの項目の削除や保持など) に役立つメソッドが含まれています。 ## utils を一覧表示する ** `$util.list.copyAndRetainAll(List, List) : List` ** 最初の引数で指定されたリストのシャローコピーを作成し、2 番目の引数で指定された項目のみを保持します (存在する場合)。他のすべての項目はそのコピーから削除されます。 ** `$util.list.copyAndRemoveAll(List, List) : List` ** 最初の引数で指定されたリストのシャローコピーを作成し、2 番目の引数で指定されたすべての項目を削除します (存在する場合)。他のすべての項目はそのコピーで保持されます。 ** `$util.list.sortList(List, Boolean, String) : List` ** 最初の引数で指定されたオブジェクトのリストをソートします。2 番目の引数が true の場合、リストは降順でソートされます。2 番目の引数が false の場合、リストは昇順でソートされます。3 番目の引数は、カスタムオブジェクトのリストをソートするために使用されるプロパティの文字列名です。文字列、整数、浮動小数点数、倍精度浮動小数点数だけのリストの場合、3 番目の引数は任意のランダムな文字列になります。すべてのオブジェクトが同じクラスのものでない場合は、元のリストが返されます。最大 1000 個のオブジェクトを含むリストのみがサポートされます。以下は、このユーティリティの使用例です。 ``` INPUT: $util.list.sortList([{"description":"youngest", "age":5},{"description":"middle", "age":45}, {"description":"oldest", "age":85}], false, "description") OUTPUT: [{"description":"middle", "age":45}, {"description":"oldest", "age":85}, {"description":"youngest", "age":5}] ``` # \$1util.map のマップヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.map` には、よく使用されるマップオペレーション (フィルタリングのユースケースでのマップの項目の削除や保持など) に役立つメソッドが含まれています。 ## Map utils ** `$util.map.copyAndRetainAllKeys(Map, List) : Map` ** 最初の引数で指定されたマップのシャローコピーを作成し、リストで指定されたキーのみを保持します (存在する場合)。他のすべてのキーはそのコピーから削除されます。 ** `$util.map.copyAndRemoveAllKeys(Map, List) : Map` ** 最初の引数で指定されたマップのシャローコピーを作成し、リストで指定されたキーを持つすべてのエントリを削除します (存在する場合)。他のすべてのキーはそのコピーで保持されます。 # \$1util.dynamodb の DynamoDB ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.dynamodb` には、Amazon DynamoDB に対するデータの読み書きを容易にするヘルパーメソッド (自動型マッピングやフォーマットなど) が含まれています。これらのメソッドは、プリミティブ型やリスト型を適切な DynamoDB 入力形式に自動的にマッピングするように設計されていて、そのマッピングは `{ "TYPE" : VALUE }` 形式の `Map` です。 例えば、前述の例で、DynamoDB に新しい項目を作成するリクエストマッピングテンプレートは次のようになっていました。 ``` { "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : { "S" : "$util.autoId()" } }, "attributeValues" : { "title" : { "S" : $util.toJson($ctx.args.title) }, "author" : { "S" : $util.toJson($ctx.args.author) }, "version" : { "N", $util.toJson($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!")) ``` ## toDynamoDB ### toDynamoDB utils リスト ** `$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 エンコード形式の文字列として返します。 ## toString utils ### toString utils リスト ****`$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) : Map` ** 文字列型のリスト型を DynamoDB の文字列セット形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。 ``` Input: $util.dynamodb.toStringSet([ "foo", "bar", "baz" ]) Output: { "SS" : [ "foo", "bar", "baz" ] } ``` ** `$util.dynamodb.toStringSetJson(List) : String` ** `$util.dynamodb.toStringSet(List) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。 ## toNumber utils ### toNumber utils リスト ** `$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) : Map` ** 数値のリストを DynamoDB の数値セット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: $util.dynamodb.toNumberSet([ 1, 23, 4.56 ]) Output: { "NS" : [ 1, 23, 4.56 ] } ``` ** `$util.dynamodb.toNumberSetJson(List) : String` ** `$util.dynamodb.toNumberSet(List) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。 ## toBinary utils ### toBinary utils リスト ** `$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) : Map` ** base64 文字列としてエンコードされたバイナリデータのリストを DynamoDB のバイナリセット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。 ``` Input: $util.dynamodb.toBinarySet([ "foo", "bar", "baz" ]) Output: { "BS" : [ "foo", "bar", "baz" ] } ``` ** `$util.dynamodb.toBinarySetJson(List) : String` ** `$util.dynamodb.toBinarySet(List) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。 ## toBoolean utils ### toBoolean utils リスト ** `$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 エンコード形式の文字列として返します。 ## toNull utils ### toNull utils リスト ** `$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 エンコード形式の文字列として返します。 ## toList utils ### toList utils リスト ****`$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 エンコード形式の文字列として返します。 ## toMap utils ### toMap utils リスト ** `$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 エンコード形式の文字列として返します。 ## S3Object utils ### S3Object utils リスト ** `$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" } ``` # \$1util.rds の Amazon RDS ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.rds` には、結果出力から不要なデータを削除して Amazon RDS オペレーションをフォーマットするヘルパーメソッドが含まれています。 ## \$1util.rds utils リスト ****`$util.rds.toJsonString(String serializedSQLResult): String`**** 文字列化された生の Amazon Relational Database Service (Amazon RDS) Data API オペレーションの結果形式をより簡潔な文字列に変換することにより `String` を返します。返される文字列は、結果セットの SQL レコードのリストのシリアル化されたリストです。すべてのレコードはキーと値のペアの集合として表されます。キーは対応する列名です。 入力内の対応するステートメントがミューテーションの実行元の SQL クエリ (INSERT、UPDATE、DELETE など) であった場合は、空のリストが返されます。例えば、クエリ `select * from Books limit 2` では、Amazon RDS Data オペレーション からの生の結果が返されます。 ``` { "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" } ] } ] } ``` `util.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`**** これは `util.rds.toJsonString` と同じですが、結果は JSON `Object` になります。 # \$1util.http の HTTP ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.http` ユーティリティには、HTTP リクエストパラメータの管理やレスポンスヘッダーの追加に使用できるヘルパーメソッドが用意されています。 ## \$1util.http utils リスト ** `$util.http.copyHeaders(Map) : Map` ** 以下の制限された HTTP ヘッダーを除き、マップからヘッダーをコピーします。 + transfer-encoding + connection + host + expect + keep-alive + upgrade + proxy-authenticate + proxy-authorization + te + content-length このユーティリティを使用して、リクエストヘッダーをダウンストリーム HTTP エンドポイントに転送することができます。 ``` { ... "params": { ... "headers": $util.http.copyHeaders($ctx.request.headers), ... }, ... } ``` **\$1util.http.addResponseHeader(String, Object)** レスポンスの名前 (`String`) と値 (`Object`) を含むカスタムヘッダーを 1 つ追加します。以下の制限が適用されます。 + `copyHeaders(Map)` の制限付きヘッダーのリストに加えて、ヘッダー名は次のいずれかと一致することはできません。 + Access-Control-Allow-Credentials + Access-Control-Allow-Origin + Access-Control-Expose-Headers + Access-Control-Max-Age + Access-Control-Allow-Methods + Access-Control-Allow-Headers + Vary + Content-Type + ヘッダー名は、`x-amzn-` や `x-amz-` などの制限付きプレフィックスで始めることはできません。 + カスタムレスポンスヘッダーのサイズは 4 KB を超えることはできません。これにはヘッダー名と値が含まれます。 + 各レスポンスヘッダーは、GraphQL 操作ごとに 1 回定義する必要があります。ただし、同じ名前のカスタムヘッダーを複数回定義すると、最新の定義がレスポンスに表示されます。名前に関係なく、すべてのヘッダーがヘッダーサイズの上限に含まれます。 + 名前 `(String)` が空または制限されているヘッダーや null 値 `(Object)` のヘッダーは無視され、オペレーションの `errors` 出力に追加される `ResponseHeaderError` エラーが発生します。 ``` export function request(ctx) { util.http.addResponseHeader('itemsCount', 7) util.http.addResponseHeader('render', ctx.args.render) return {} } ``` ****`$util.http.addResponseHeaders(Map)`**** 複数のレスポンスヘッダーを、名前 `(String)` と値 `(Object)` の指定したマップからのレスポンスに追加します。`addResponseHeader(String, Object)` メソッドにリストされているのと同じ制限が、このメソッドにも適用されます。 ``` export function request(ctx) { const headers = { headerInt: 12, headerString: 'stringValue', headerObject: { field1: 7, field2: 'string' } } util.http.addResponseHeaders(headers) return {} } ``` # \$1util.xml の XML ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.xml` には、XML レスポンスを JSON またはディクショナリに変換しやすくするヘルパーメソッドが含まれています。 ## \$1util.xml utils リスト ****`$util.xml.toMap(String) : Map`**** XML 文字列を辞書に変換します。 ``` Input: 1 Getting started with GraphQL Output (JSON representation): { "posts":{ "post":{ "id":1, "title":"Getting started with GraphQL" } } } Input: 1 Getting started with GraphQL 2 Getting started with AWS AppSync Output (JSON representation): { "posts":{ "post":[ { "id":1, "title":"Getting started with GraphQL" }, { "id":2, "title":"Getting started with AWS AppSync" } ] } } ``` ****`$util.xml.toJsonString(String) : String`**** XML 文字列を JSON 文字列に変換します。これは、出力が文字列である点を除き、*toMap* に似ています。これは、XML レスポンスを HTTP オブジェクトから JSON に直接変換し、返す場合に便利です。 ****`$util.xml.toJsonString(String, Boolean) : String`**** XML 文字列を JSON 文字列に変換します。オプションのブールパラメータを使用して、JSON を文字列エンコードするか判断します。 # util.transform の変換ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.transform` には、Amazon DynamoDB フィルター処理などの、データソースに対する複雑なオペレーションの実行を容易にするヘルパーメソッドが含まれています。 ## 変換ヘルパー ### 変換ヘルパー utils リスト ****`$util.transform.toDynamoDBFilterExpression(Map) : Map`**** DynamoDB で使用するために、入力文字列をフィルター式に変換します。 ``` Input: $util.transform.toDynamoDBFilterExpression({ "title":{ "contains":"Hello World" } }) Output: { "expression" : "contains(#title, :title_contains)" "expressionNames" : { "#title" : "title", }, "expressionValues" : { ":title_contains" : { "S" : "Hello World" } }, } ``` ****`$util.transform.toElasticsearchQueryDSL(Map) : Map`**** 指定された入力を同等の OpenSearch Query DSL 式に変換し、JSON 文字列として返します。 ``` Input: $util.transform.toElasticsearchQueryDSL({ "upvotes":{ "ne":15, "range":[ 10, 20 ] }, "title":{ "eq":"hihihi", "wildcard":"h*i" } }) Output: { "bool":{ "must":[ { "bool":{ "must":[ { "bool":{ "must_not":{ "term":{ "upvotes":15 } } } }, { "range":{ "upvotes":{ "gte":10, "lte":20 } } } ] } }, { "bool":{ "must":[ { "term":{ "title":"hihihi" } }, { "wildcard":{ "title":"h*i" } } ] } } ] } } ``` デフォルトの演算子は AND であると仮定されます。 ## 変換ヘルパーサブスクリプションフィルター ### 変換ヘルパー、サブスクリプションフィルター、ユーティリティリスト ****`$util.transform.toSubscriptionFilter(Map) : Map`**** `Map` 入力オブジェクトを `SubscriptionFilter` 式オブジェクトに変換します。`$util.transform.toSubscriptionFilter` メソッドは`$extensions.setSubscriptionFilter()` 拡張子への入力として使用されます。詳細については、「[拡張子](https://docs.aws.amazon.com/appsync/latest/devguide/extensions)」を参照してください。 ****`$util.transform.toSubscriptionFilter(Map, List) : Map`**** `Map` 入力オブジェクトを `SubscriptionFilter` 式オブジェクトに変換します。`$util.transform.toSubscriptionFilter` メソッドは`$extensions.setSubscriptionFilter()` 拡張子への入力として使用されます。詳細については、「[拡張子の使用](https://docs.aws.amazon.com/appsync/latest/devguide/extensions)」を参照してください。 1 番目の引数は、`SubscriptionFilter` 式オブジェクトに変換される `Map` 入力オブジェクトです。2 番目の引数は、`SubscriptionFilter` 式オブジェクトを作成する際に 1 番目の `Map` 入力オブジェクトでは無視されるフィールド名の `List` です。 ****`$util.transform.toSubscriptionFilter(Map, List, Map) : Map`**** `Map` 入力オブジェクトを `SubscriptionFilter` 式オブジェクトに変換します。`$util.transform.toSubscriptionFilter` メソッドは`$extensions.setSubscriptionFilter()` 拡張子への入力として使用されます。詳細については、「[拡張子](https://docs.aws.amazon.com/appsync/latest/devguide/extensions)」を参照してください。 1 番目の引数は `SubscriptionFilter` 式オブジェクトに変換される `Map` 入力オブジェクト、2 番目の引数は最初の `Map` 入力オブジェクトでは無視されるフィールド名の`List`、3 番目の引数は `SubscriptionFilter` 式オブジェクトの作成時に含まれる厳密な規則の `Map` 入力オブジェクトです。これらの厳密なルールは、少なくとも 1 つのルールが満たされてサブスクリプションフィルターを通過するように `SubscriptionFilter` 式オブジェクトに含まれています。 ## サブスクリプションフィルター引数 以下の表では、以下のユーティリティの引数の定義方法について説明しています。 + `$util.transform.toSubscriptionFilter(Map) : Map` + `$util.transform.toSubscriptionFilter(Map, List) : Map` + `$util.transform.toSubscriptionFilter(Map, List, Map) : Map` ------ #### [ Argument 1: Map ] 引数 1 は、以下のキー値を持つ `Map` オブジェクトです。 + フィールド名 + "and" + "or" フィールド名をキーとする場合、これらのフィールドのエントリの条件は `"operator" : "value"` という形式になります。 次の例では、`Map` にエントリを追加する方法を示します。 ``` "field_name" : { "operator1" : value } ## We can have multiple conditions for the same field_name: "field_name" : { "operator1" : value "operator2" : value . . . } ``` フィールドに 2 つ以上の条件が設定されている場合、これらの条件はすべて OR 演算を使用するものとみなされます。 入力 `Map` には「and」と「or」をキーとして使用することもできます。つまり、その中のすべてのエントリは、キーに応じて AND または OR ロジックを使用して結合する必要があります。キー値「and」と「or」には条件の配列が必要です。 ``` "and" : [ { "field_name1" : { "operator1" : value } }, { "field_name2" : { "operator1" : value } }, . . ]. ``` 「and」と「or」はネストできることに注意してください。つまり、「and/or」を別の「and/or」ブロック内にネストしてもかまいません。ただし、これは単純なフィールドでは機能しません。 ``` "and" : [ { "field_name1" : { "operator" : value } }, { "or" : [ { "field_name2" : { "operator" : value } }, { "field_name3" : { "operator" : value } } ]. ``` 次の例は、`$util.transform.toSubscriptionFilter(Map) : Map`を使用して*引数 1* を入力したものです。 **入力** 引数 1: マップ: ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 2000 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` **出力** 結果は `Map` オブジェクトです。 ``` { "filterGroup": [ { "filters": [ { "fieldName": "percentageUp", "operator": "lte", "value": 50 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "author", "operator": "eq", "value": "Admin" } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "lte", "value": 50 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "gte", "value": 20 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "author", "operator": "eq", "value": "Admin" } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "gte", "value": 20 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] } ] } ``` ------ #### [ Argument 2: List ] 引数 2 には、`SubscriptionFilter` 式オブジェクトを作成するときに入力 `Map` (引数 1) で考慮してはいけないフィールド名の `List` が含まれています。`List` は空になることもあります。 次の例は、`$util.transform.toSubscriptionFilter(Map, List) : Map` を使用した引数 1 と引数 2 の入力を示しています。 **入力** 引数 1: マップ: ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 引数 2: リスト: ``` ["percentageUp", "author"] ``` **出力** 結果は `Map` オブジェクトです。 ``` { "filterGroup": [ { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] } ] } ``` ------ #### [ Argument 3: Map ] 引数 3 は、フィールド名をキー値とする `Map` オブジェクトです (「and」や「or」は使用できません)。フィールド名がキーの場合、これらのフィールドの条件は `"operator" : "value"` という形式のエントリになります。引数 1 とは異なり、引数 3 では同じキーに複数の条件を設定できません。さらに、引数 3 には「and」や「or」句がないため、ネストも必要ありません。 引数 3 は厳密な規則のリストを表し、これらの条件の**少なくとも 1 つ**が満たされてフィルタを通過するように `SubscriptionFilter` 式オブジェクトに追加されます。 ``` { "fieldname1": { "operator": value }, "fieldname2": { "operator": value } } . . . ``` 次の例は、`$util.transform.toSubscriptionFilter(Map, List, Map) : Map` を使用した*引数 1*、*引数 2*、*引数 3* の入力を示しています。 **入力** 引数 1: マップ: ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "lt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 引数 2: リスト: ``` ["percentageUp", "author"] ``` 引数 3: マップ: ``` { "upvotes": { "gte": 250 }, "author": { "eq": "Person1" } } ``` **出力** 結果は `Map` オブジェクトです。 ``` { "filterGroup": [ { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false }, { "fieldName": "upvotes", "operator": "gte", "value": 250 } ] }, { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false }, { "fieldName": "author", "operator": "eq", "value": "Person1" } ] } ] } ``` ------ # \$1util.math の math ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.math` には一般的な算術演算を支援するメソッドが含まれています。 ## \$1util.math utils リスト ** `$util.math.roundNum(Double) : Integer` ** 倍精度値 をとり、最も近い整数に四捨五入します。 ** `$util.math.minVal(Double, Double) : Double` ** 2 つの倍精度値を取り、2 つの倍精度浮動小数点間の最小値を返します。 ** `$util.math.maxVal(Double, Double) : Double` ** 2 つの倍精度値を取り、2 つの倍精度浮動小数点間の最大値を返します。 ** `$util.math.randomDouble() : Double` ** 0 から 1 までの乱数を返します。 この関数は、エントロピーランダム性が高い場合 (暗号など) には使用しないでください。 ** `$util.math.randomWithinRange(Integer, Integer) : Integer` ** 指定された範囲内のランダムな整数値を返します。最初の引数は範囲の下限値を指定し、2 番目の引数は範囲の上限値を指定します。 この関数は、エントロピーランダム性が高い場合 (暗号など) には使用しないでください。 # \$1util.str 内の文字列ヘルパー **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$util.str` には一般的な文字列操作を支援するメソッドが含まれています。 ## \$1util.str utils リスト ** `$util.str.toUpper(String) : String` ** 文字列を受け取り、それをすべて大文字に変換します。 ** `$util.str.toLower(String) : String` ** 文字列を受け取り、それをすべて小文字に変換します。 ** `$util.str.toReplace(String, String, String) : String` ** 文字列内の部分文字列を別の文字列に置き換えます。最初の引数は、置換操作を実行する文字列を指定します。2 番目の引数は、置換する部分文字列を指定します。3 番目の引数は、2 番目の引数を置き換える文字列を指定します。以下は、このユーティリティの使用例です。 ``` INPUT: $util.str.toReplace("hello world", "hello", "mellow") OUTPUT: "mellow world" ``` ** `$util.str.normalize(String, String) : String` ** NFC、NFD、NFKC、または NFKD の 4 つのユニコード正規化形式のいずれかを使用して文字列を正規化します。最初の引数は正規化する文字列です。2 番目の引数は、正規化プロセスに使用する正規化タイプを指定する「nfc」「nfd」「nfkc」「nfkd」のいずれかです。 # 拡張子 **注記** 現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。 `$extensions` には、リゾルバー内で追加のアクションを行うためのメソッドセットが含まれています。 ## 拡張子の使用 **`$extensions.evictFromApiCache(String, String, Object) : Object`** AWS AppSync サーバー側のキャッシュから項目を削除します。最初の引数は型名です。2 番目の引数はフィールド名です。3 番目の引数は、キャッシュキー値を指定するキーと値のペア項目を含むオブジェクトです。オブジェクト内の項目は、キャッシュされたリゾルバー `cachingKey` のキャッシュキーと同じ順序で配置する必要があります。 このユーティリティはミューテーションに対してのみ機能し、クエリには使用できません。 ## サブスクリプションの延長 **`$extensions.setSubscriptionFilter(filterJsonObject)`** 強化されたサブスクリプションフィルターを定義します。各サブスクリプション通知イベントは、提供されたサブスクリプションフィルタに対して評価され、すべてのフィルタが `true` に評価された場合、クライアントに通知を配信します。引数は以下のセクションで説明するとおり `filterJsonObject` です。 この拡張メソッドは、サブスクリプションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。 **`$extensions.setSubscriptionInvalidationFilter(filterJsonObject)`** サブスクリプション無効化フィルターを定義します。サブスクリプションフィルタは無効化ペイロードに照らして評価されてから、フィルターが `true` と評価された場合、与えられたサブスクリプションを無効にします。引数は以下のセクションで説明するとおり `filterJsonObject` です。 この拡張メソッドは、サブスクリプションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。 **`$extensions.invalidateSubscriptions(invalidationJsonObject)`** ミューテーションによるサブスクリプションの無効化を開始するために使用されます。引数は以下のセクションで説明するとおり `invalidationJsonObject` です。 この拡張関数はミューテーションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。 1 つのリクエストで使用できるユニークな `$extensions.invalidateSubscriptions()` メソッド呼び出しは 5 つまでです。この制限を超えた場合、GraphQL エラーが表示されます。 ## 引数: filterJsonObject JSON オブジェクトは、サブスクリプションフィルターまたは無効化フィルターのいずれかを定義します。これは、`filterGroup` 内のフィルターの配列です。各フィルターは個別のフィルターの集まりです。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` 各フィルターには次の 3 つの属性があります。 + `fieldName` – GraphQL スキーマフィールド。 + `operator` – オペレータータイプ。 + `value` – サブスクリプション通知 `fieldName` 値と比較する値。 以下は、これらの属性の割り当ての例です。 ``` { "fieldName" : "severity", "operator" : "le", "value" : $context.result.severity } ``` ### フィールド: fieldName 文字列タイプ `fieldName` は、サブスクリプション通知ペイロード内の `fieldName` と一致する GraphQL スキーマで定義されているフィールドを指します。一致するものが見つかると、GraphQL スキーマフィールドの `value` がサブスクリプション通知フィルターのフィールドの `value` と比較されます。次の例では、`fieldName` フィルターは特定の GraphQL タイプで定義された `service` フィールドと一致します。通知ペイロードが `AWS AppSync` と等しい `value` のある `service` フィールドを含む場合、フィルタは `true` と評価されます： ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ### フィールド: 値 値は演算子によって異なるタイプでもかまいません。 + 1 つの数値またはブール値 + 文字列型の例: `"test"`、`"service"` + 数値型の例: + ブール型の例: + 数字または文字列のペア + 文字列ペアの例: `["test1","test2"]`、`["start","end"]` + 数値ペアの例: `[1,4]`、`[67,89]`、`[12.45, 95.45]` + 数値または文字列の配列 + 文字列配列の例:`["test1","test2","test3","test4","test5"]` + 数値配列の例: `[1,2,3,4,5]`、`[12.11,46.13,45.09,12.54,13.89]` ### フィールド演算子 大文字と小文字が区別される文字列で、以下の値を指定できます。 | | | 演算子 | 説明 | 可能な値型 | | --- |--- |--- | | eq | Equal | integer, float, string, Boolean | | ne | Not equal | integer, float, string, Boolean | | le | Less than or equal | integer, float, string | | lt | Less than | integer, float, string | | ge | Greater than or equal | integer, float, string | | gt | Greater than | integer, float, string | | contains | Checks for a subsequence or value in the set. | integer, float, string | | notContains | Checks for the absence of a subsequence or absence of a value in the set. | integer, float, string | | beginsWith | Checks for a prefix. | string | | in | Checks for matching elements that are in the list. | Array of integer, float, or string | | notIn | Checks for matching elements that aren't in the list. | Array of integer, float, or string | | between | Between two values | integer, float, string | | containsAny | Contains common elements | integer, float, string | 次の表は、サブスクリプション通知での各オペレーターの使用法を示したものです。 ------ #### [ eq (equal) ] `eq` 演算子は、サブスクリプション通知フィールドの値がフィルターの値と一致し、厳密に等しいかどうかを `true` に対して評価します。次の例では、フィルターはサブスクリプション通知に `AWS AppSync` に等しい値の `service` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ:** 整数、浮動小数点、文字列、ブール値 ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ------ #### [ ne (not equal) ] `ne` 演算子は、サブスクリプション通知フィールドの値がフィルターの値と異なるかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に `AWS AppSync` と異なる値の `service` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ:** 整数、浮動小数点、文字列、ブール値 ``` { "fieldName" : "service", "operator" : "ne", "value" : "AWS AppSync" } ``` ------ #### [ le (less or equal) ] `le` 演算子は、サブスクリプション通知フィールドの値がフィルターの値以下かどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に`5`以下の値の`size`フィールドがあるかどうかを`true` に対して評価します。 **指定できる値のタイプ: **整数、浮動小数点、文字列 ``` { "fieldName" : "size", "operator" : "le", "value" : 5 } ``` ------ #### [ lt (less than) ] `lt` 演算子は、サブスクリプション通知フィールドの値がフィルターの値よりも小さいかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に `5` 以下の値の `size` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ: **整数、浮動小数点、文字列 ``` { "fieldName" : "size", "operator" : "lt", "value" : 5 } ``` ------ #### [ ge (greater or equal) ] `ge` 演算子は、`true` サブスクリプション通知フィールドの値がフィルターの値以上かどうかを評価します。次の例では、フィルターは、サブスクリプション通知に `5` 以上の値の `size` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ: **整数、浮動小数点、文字列 ``` { "fieldName" : "size", "operator" : "ge", "value" : 5 } ``` ------ #### [ gt (greater than) ] `gt` 演算子は、サブスクリプション通知フィールドの値がフィルターの値より大きいかどうかを に対して評価します。次の例では、フィルターは、サブスクリプション通知に `5` 以上の値の `size` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ: **整数、浮動小数点、文字列 ``` { "fieldName" : "size", "operator" : "gt", "value" : 5 } ``` ------ #### [ contains ] `contains` 演算子は、サブストリング、サブシーケンス、またはセットまたは単一アイテムをチェックします。`contains` 演算子を含むフィルターは、サブスクリプション通知フィールドの値にフィルタ値が含まれているかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に値 `10` を含む配列値を持つ `seats` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ: **整数、浮動小数点、文字列 ``` { "fieldName" : "seats", "operator" : "contains", "value" : 10 } ``` 別の例として、フィルターはサブスクリプション通知にサブストリングとして `launch` を含む `event` フィールドがあるかどうかを`true` に対して評価します。 ``` { "fieldName" : "event", "operator" : "contains", "value" : "launch" } ``` ------ #### [ notContains ] `notContains` 演算子は、サブストリング、サブシーケンス、またはセットまたは値がないことをチェックします。`notContains` 演算子を使ったフィルターは、サブスクリプション通知フィールドの値にフィルタ値が含まれていないかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に値 `10` を含まない配列値の `seats` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ: **整数、浮動小数点、文字列 ``` { "fieldName" : "seats", "operator" : "notContains", "value" : 10 } ``` 別の例として、フィルターはサブスクリプション通知のサブシーケンスとしての `launch` なしで `event` フィールド値があるかどうかを `true` に対して評価します。 ``` { "fieldName" : "event", "operator" : "notContains", "value" : "launch" } ``` ------ #### [ beginsWith ] `beginsWith` 演算子は文字列のプレフィックスをチェックします。`beginsWith` 演算子を含むフィルターは、サブスクリプション通知フィールドの値がフィルタの値で始まるかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に値がで始まる `service` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値の種類: 文字列** ``` { "fieldName" : "service", "operator" : "beginsWith", "value" : "AWS" } ``` ------ #### [ in ] `in` 演算子は配列内の一致する要素をチェックします。`in` 演算子を含むフィルタは、サブスクリプション通知フィールド値が配列に存在するかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に配列 `[1,2,3]` 内のいずれかの値を含む `severity` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ:** 整数、浮動小数点数、または文字列の配列 ``` { "fieldName" : "severity", "operator" : "in", "value" : [1,2,3] } ``` ------ #### [ notIn ] `notIn` 演算子は配列に欠けている要素がないかチェックします。`notIn` 演算子を含むフィルタは、サブスクリプション通知フィールド値が配列に存在しないかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に、配列 `[1,2,3]` に存在しない値のいずれかを含む `severity` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ:** 整数、浮動小数点数、または文字列の配列 ``` { "fieldName" : "severity", "operator" : "notIn", "value" : [1,2,3] } ``` ------ #### [ between ] `between` 演算子は 2 つの数値または文字列の間の値をチェックします。`between` 演算子を含むフィルターは、サブスクリプション通知フィールドの値がフィルタの値ペアの間にあるかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知に値 `2`、`3`、`4` を含む `severity` フィールドがあるかどうかを `true` に対して評価します。 **指定できる値のタイプ:** 整数、浮動小数点数、または文字列のペア ``` { "fieldName" : "severity", "operator" : "between", "value" : [1,5] } ``` ------ #### [ containsAny ] `containsAny` 演算子は配列内の共通要素をチェックします。`containsAny` 演算子を使ったフィルタ＝は、サブスクリプション通知フィールドの設定値とフィルタセット値の共通部分が空でないかどうかを `true` に対して評価します。次の例では、フィルターは、サブスクリプション通知にまたはを含む配列値を持つ `seats` フィールドがあるかどうかを`true`に対して評価します。つまり、フィルターは、サブスクリプション通知の `[15,20,30]` フィールド値が `true` または `seats` であるかどうかを `[10,11]` に対して評価します。 **指定できる値のタイプ:** 整数、浮動小数点数、または文字列 ``` { "fieldName" : "seats", "operator" : "containsAny", "value" : [10, 15] } ``` ------ ### AND ロジック `filterGroup` 配列内の `filters` オブジェクト内に複数のエントリを定義することで、AND ロジックを使用して複数のフィルターを組み合わせることができます。次の例では、フィルターは、サブスクリプション通知にフィールドの値が等しく、`userId` フィールド値が `1` または `group` のいずれかであるかどうかを `true` に対して評価します。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### OR ロジック `filterGroup` 配列内に複数のフィルターオブジェクトを定義することで、OR ロジックを使用して複数のフィルターを組み合わせることができます。次の例では、フィルターは、サブスクリプション通知に `Admin` OR `Developer` と同等の値の `userId` フィールドがあるかどうか、`1` またはの `group` フィールド値があるかどうかを `true` に対して評価します。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### 例外 フィルターの使用にはいくつかの制限があることに注意してください。 + `filters` オブジェクトには、フィルターごとに最大 5 つのユニークな `fieldName` 項目を設定できます。つまり、AND ロジックを使用して最大 5 つの個別の `fieldName` オブジェクトを組み合わせることができます。 + `containsAny` 演算子には最大 20 個の値を指定できます。 + `in` and `notIn` 演算子には最大 5 つの値を指定できます。 + 接続文字列は最大 255 文字です。 + 文字列比較では、大文字と小文字を区別します。 + ネストされたオブジェクトフィルタリングでは、最大 5 つのネストレベルのフィルタリングが可能です。 + `filterGroup` にはそれぞれ、最大 10 個 `filters` 設定できます。つまり、OR ロジックを使用して最大 10 個 `filters` を組み合わせることができます。 + `in` 演算子は OR ロジックの特殊なケースです。次の例には、次の 2 つの `filters` があります。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` 前述のフィルターグループは次のように評価され、最大フィルター制限に加算されます。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "eq", "value" : "Admin" } ] }, { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "eq", "value" : "Developer" } ] } ] } ``` ## 引数: invalidationJsonObject `invalidationJsonObject` では以下が定義されます。 + `subscriptionField` – 無効にする GraphQL スキーマのサブスクリプション。`subscriptionField`で文字列として定義されている 1 つのサブスクリプションは無効とみなされます。 + `payload` — 無効化フィルターがその値に対して `true` と評価された場合に、サブスクリプションを無効化するための入力として使用されるキーと値のペアリスト。 以下の例では、サブスクリプションリゾルバーで定義された無効化フィルターが `payload` 値に対して `true` と評価されたとき、`onUserDelete` サブスクリプションを使用してサブスクライブして接続しているクライアントを無効にします。 ``` $extensions.invalidateSubscriptions({ "subscriptionField": "onUserDelete", "payload": { "group": "Developer" "type" : "Full-Time" } }) ```