# フィルター

> Use filters to determine whether to execute a trigger and avoid unnecessary trigger execution.

フィルターを使用して、トリガーを実行するかどうかを決定し、トリガーの不必要な実行を回避できます。フィルターは、トリガーの設定の `filter` フィールドで定義できます。

> **Note:**
>
> **ノート:** UGS CLI は、フィルターを使用したトリガーをサポートしていません。かわりに、[Triggers API](/triggers/tutorials/define-triggers/rest-api.md) または [Unity Dashboard](/triggers/tutorials/define-triggers/unity-dashboard.md) を使用して、フィルターを使用したトリガーを作成できます。

フィルターは、トリガーの設定の `filter` フィールドで定義します。このフィールドの値は、ブーリアン値に評価される [CEL 式](#cel-syntax) です。式が `true` と評価された場合に、トリガーが実行されます。

例えば、以下のトリガー設定は、`my-leaderboard` リーダーボード ID を持つリーダーボードがリセットされた場合にのみ実行されます。

```json
{
  "name": "reset-another-leaderboard",
  "eventType": "com.unity.services.leaderboards.reset.v1",
  "actionType": "cloud-code",
  "actionUrn": "urn:ugs:cloud-code:test-script",
  "filter": "data['leaderboardId'] == 'my-leaderboard'"
}
```

トリガーは、イベントペイロードを入力として使用します。イベントペイロードは、イベントに関連するデータが含まれる JSON オブジェクトです。例えば、`com.unity.services.leaderboards.reset.v1` イベントのペイロードは以下のようになります。

```json
{
  "leaderboardId": "my-leaderboard",
  "leaderboardVersionId": "20230213175322850781977"
}
```

## CEL 構文##cel-syntax

フィルターは、Google Cloud 製品で使用される式言語である [CEL (Common Expression Language)](https://github.com/google/cel-spec) で記述する必要があります。CEL の詳細については、[言語定義](https://github.com/google/cel-spec/blob/master/doc/langdef.md) を参照してください。

以下のサンプルは、フィルターで使用できる一般的な CEL 式の一部を示しています。

### Equality (等値)##equality

フィールドが特定の値と等しい場合に、フィルターを true に設定できます。これらのフィルターを使用すると、渡されたパラメーターが特定の値であることを確認できます。

例えば、以下のフィルターを使用して、`leaderboardId` の値が `my-leaderboard` であるかどうかを確認できます。

```text
data['leaderboardId'] == 'my-leaderboard'
```

### 正規表現##regular-expressions

正規表現を使用して、フィールドをパターンと照合できます。例えば、以下のフィルターを使用して、`leaderboardId` の値が `tiered-leaderboard#` で始まるかどうかを確認できます。

```text
data['leaderboardId'].matches('^tiered-leaderboard#.*')
```

### ネストされたフィールド##nested-fields

ネストされたフィールドを持つフィルターを使用できます。例えば、スクリプトまたはモジュールのパラメーターが以下のようであるとします。

```json
{
  "inventory": {
    "primaryWeapon": "sword",
    "secondaryWeapon": "bow"
  }
}
```

以下のフィルターを使用して、`inventory.primaryWeapon` の値が `sword` であるかどうかを確認できます。

```text
data['inventory']['primaryWeapon'] == 'sword'
```

### 論理演算子##logical-operators

論理演算子を使用して、複数の式を組み合わせることができます。

例えば、以下のフィルターを使用して、プレイヤーにクエストを発行するタイミングを決定できます。プレイヤーがレベル 5 に達したとき、またはプレイヤーが `collectWood` クエストを完了し、現在のクエストが `buildFence` である場合に、クエストを発行します。

```text
(data['currentQuest'] == 'buildFence' && data['lastQuest'] == 'collectWood') || data['level'] == 5
```

## 型の不一致##type-mismatch

イベントペイロードの値の型がフィルター内の値の型と一致しない場合、フィルターはログにエラーメッセージを返し、トリガーは実行されません。

例えば、以下のフィルターは、Cloud Save イベントペイロードに 5 より大きい `value` フィールドが含まれているかどうかを確認します。

```text
data['value'] > 5
```

`data['value']` の値が `string` の場合、フィルターは期待どおりに機能しません。このフィルターは、イベントペイロード内の `value` が数値である場合にのみ評価されます。

### 型のキャスト##type-casting

イベントペイロード内の値の型を別の型にキャストできます。これにより、型の不一致エラーを回避できます。例えば、数字である文字列値を渡す場合、それを数値にキャストし、数値を期待するフィルターで引き続き使用できます。

```text
int(data['value']) > 5
```

ただし、`data['value']` の値が数字ではない文字列の場合、フィルターはログにエラーメッセージを返し、トリガーは実行されません。

キャスト可能な型を確認するには、[標準定義のリスト](https://github.com/google/cel-spec/blob/master/doc/langdef.md#list-of-standard-definitions) を参照してください。