翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# \$1util のユーティリティヘルパー
<a name="utility-helpers-in-util"></a>

**注記**  
現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。

`$util` 変数には、データの操作を容易にする一般的なユーティリティメソッドが含まれています。特に指定されていない限り、すべてのユーティリティでは UTF-8 文字セットが使用されます。

## JSON パーシング utils
<a name="utility-helpers-in-json-parsing"></a>

### JSON パーシング utils リスト
<a name="utility-helpers-in-json-parsing-list"></a>

** **`$util.parseJson(String) : Object`** **  
"stringified" JSON を受け取り、結果のオブジェクト表現を返します。

** **`$util.toJson(Object) : String`** **  
オブジェクトを受け取り、そのオブジェクトの「文字列化された」JSON 表現を返します。

## エンコーディング utils
<a name="utility-helpers-in-encoding"></a>

### エンコーディング utils リスト
<a name="utility-helpers-in-encoding-list"></a>

** **`$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
<a name="utility-helpers-in-id-gen"></a>

### ID 生成 utils リスト
<a name="utility-helpers-in-id-gen-list"></a>

** **`$util.autoId() : String`** **  
ランダムに生成された 128 ビットの UUID を返します。

****`$util.autoUlid() : String`****  
ランダムに生成された 128 ビットの ULID (辞書的にソート可能なユニバーサルユニーク識別子) を返します。

****`$util.autoKsuid() : String`****  
長さ 27 の文字列としてエンコードされた、ランダムに生成された 128 ビットの KSUID (K ソート可能な固有識別子) base62 を返します。

## エラー utils
<a name="utility-helpers-in-error"></a>

### エラー utils リスト
<a name="utility-helpers-in-error-list"></a>

** `$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
<a name="utility-helpers-in-condition"></a>

### 条件検証 utils リスト
<a name="utility-helpers-in-condition-list"></a>

** `$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
<a name="utility-helpers-in-null-behavior"></a>

### Null 動作 utils リスト
<a name="utility-helpers-in-null-behavior-list"></a>

** `$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
<a name="utility-helpers-in-pattern-matching"></a>

### タイプとパターンの一致 utils リスト
<a name="utility-helpers-in-type-pattern-matching-list"></a>

** `$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
<a name="utility-helpers-in-object-validation"></a>

### Object validation utils リスト
<a name="utility-helpers-in-object-validation-list"></a>

** `$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
<a name="utility-helpers-in-logging"></a>

### CloudWatch ログ記録 Utils リスト
<a name="utility-helpers-in-cloudwatch-logs"></a>

**`$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
<a name="utility-helpers-in-return-behavior"></a>

### 戻り値の動作 utils リスト
<a name="utility-helpers-in-behavior-list"></a>

****`$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 のエスケープした文字列として返します。

## リゾルバー認可
<a name="utility-helpers-in-resolver-auth"></a>

### リゾルバー承認リスト
<a name="utility-helpers-in-resolver-auth-list"></a>

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