# 过滤器

> 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`，则触发器将执行。

例如，下面的触发器配置仅当排行榜 ID 为 `my-leaderboard` 的排行榜重置时才会执行。

```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

您需要使用 [CEL（通用表达语言）](https://github.com/google/cel-spec)编写过滤器，这是 Google Cloud 产品使用的表达语言。如需了解有关 CEL 的更多信息，请参阅[语言定义](https://github.com/google/cel-spec/blob/master/doc/langdef.md)。

下面的示例展示了一些可以在过滤器中使用的通用 CEL 表达式。

### 均等##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)。