# 事件

> Understand how the Scheduler service and Unity Gaming Services produce events that Triggers service processes.

Scheduler 服务和 Unity Gaming Services（Unity 游戏服务）会产生事件。这些事件随后发送到 Triggers 服务，进而与配置进行匹配，然后执行相应的 Cloud Code 脚本或模块。

## 发出的事件##emitted-events

Scheduler 服务和 Unity Gaming Services（Unity 游戏服务）会发出事件，您可以将触发器关联到这些事件。

| 发出者                                                            | 可自定义 | 事件有效负载                 | 发出时间           | 用例                                                     |
| -------------------------------------------------------------- | ---- | ---------------------- | -------------- | ------------------------------------------------------ |
| [Unity Gaming Services（Unity 游戏服务）](./supported-ugs-events.md) | 否    | 使用特定于事件的有效负载和版本控制进行预定义 | 玩家或游戏状态更改时     | 当您想要触发 Cloud Code 脚本或模块作为对游戏或玩家状态更改的响应时，请使用 UGS 发出的事件。 |
| [Scheduler 服务](../tutorials/schedule-events/rest-api)          | 是    | 由用户在计划配置中创建            | 用户定义的设定时刻或重复时刻 | 当您想要控制何时触发 Cloud Code 脚本或模块时，请使用 Scheduler 服务发出的事件。    |

## 传递语义##delivery-semantics

默认情况下，事件具有“至少一次”传递语义。这意味着所有事件都保证被处理一次，但在发生网络问题时可能会被处理多次。为避免这种情况，建议的最佳做法是创建幂等 Cloud Code 脚本和模块。

## 事件结构##event-structure

所有事件都包含事件类型、有效负载版本并携带有效负载。

| 字段               | 描述                                               | 示例                                                         |
| ---------------- | ------------------------------------------------ | ---------------------------------------------------------- |
| `eventType`      | 事件类型是一个包含发出服务、事件名称和有效负载版本的字符串。事件类型也用于触发器配置创建关联性。 | `com.unity.services.scheduler.example-event.v1`            |
| `payloadVersion` | 有效负载版本是一个整数，表示有效负载的版本。                           | 1                                                          |
| `payload`        | 有效负载是包含事件数据的字符串。有效负载以脚本或模块参数的形式传递到 Cloud Code。   | `"{\"someBoolean\": true, \"someString\": \"something\"}"` |

事件类型略有不同，具体取决于该事件是由 Scheduler 服务还是由 UGS 发出。

| 事件类型                                                | 发出者               | 有效负载版本 | 有效负载  |
| --------------------------------------------------- | ----------------- | ------ | ----- |
| `com.unity.services.scheduler.example-event.v1`     | Scheduler 服务      | 1      | 由用户定义 |
| `com.unity.services.player-auth.signed-up.v1`       | Authentication 服务 | 1      | 预定义   |
| `com.unity.services.player-auth.signed-in.v1`       | Authentication 服务 | 1      | 预定义   |
| `com.unity.services.cloud-save.key-saved.v1`        | Cloud Save 服务     | 1      | 预定义   |
| `com.unity.servics.leaderboards.reset.v1`           | Leaderboards 服务   | 1      | 预定义   |
| `com.unity.servics.leaderboards.score-submitted.v1` | Leaderboards 服务   | 1      | 预定义   |

您可以在计划配置中定义事件名称、有效负载版本和有效负载来自定义 Scheduler 服务发出的事件。根据事件类型，UGS 发出的事件具有不同的有效负载结构，且无法自定义。

如需详细了解每种事件类型返回的结果，请参阅[支持的 UGS 事件](./supported-ugs-events.md)。

## 有效负载版本控制##payload-versioning

有效负载版本控制有助于避免重大更改。每个事件都包含事件有效负载的有效负载版本控制。

例如，`com.unity.services.player-auth.signed-up.v1` 是由 Authentication 服务发出的事件类型，其有效负载版本为 `1`。因此，可以为同一事件的不同有效负载版本设置不同的触发器。

> **Note:**
>
> **注意：** 计划性事件和 UGS 发出的事件都支持有效负载版本控制。不过，虽然可以自定义计划性事件的有效负载版本和内容，但不能自定义 UGS 发出的事件。

### 计划性事件有效负载##scheduled-event-payload

Scheduler 服务发出的事件具有可自定义的有效负载。有效负载在计划配置中进行定义。

例如，如果要向计划性事件有效负载添加新字段，则可以创建新版本的有效负载，并创建触发器以使用新版本的有效负载。

一个计划配置可能如下所示：

```json
{
"name" : "recurring-schedule",
"eventName": "example-event",
"type": "recurring",
"schedule": "0 0 * * *",
"payloadVersion": 1,
"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"
}
```

以上示例将产生事件类型 `com.unity.services.scheduler.example-event.v1`。

您可以为此事件类型设置一个触发器：

```json
{
"name" : "example-trigger",
"eventType" : "com.unity.services.scheduler.example-event.v1",
"actionUrn" : "urn:ugs:cloud-code:my-script",
"actionType" : "cloud-code"
}
```

如果要向事件有效负载添加新字段，则可以创建新版本的有效负载，并创建触发器以使用新版本的有效负载。

```json
{
"name" : "recurring-schedule",
"eventName": "example-event",
"type": "recurring",
"schedule": "0 0 * * *",
"payloadVersion": 2,
"payload": "{\"someBoolean\": true, \"someString\": \"something\", \"someNewField\": \"something else\"}"
}
```

以上示例将产生事件类型 `com.unity.services.scheduler.example-event.v2`。因此，您可以将新的触发器关联到新的事件类型。

## 计划性事件##scheduled-events

要发出计划性事件，必须创建计划配置。如需了解更多信息，请参阅[计划事件](../tutorials/schedule-events/rest-api)。

通过部署计划配置，您可以创建在设定时刻或重复时刻发出的事件。

以下是一个计划配置示例：

```json
{
"name" : "example-schedule",
"eventName": "example-event",
"type": "recurring",
"schedule": "0 0 * * *",
"payloadVersion": 1,
"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"
}
```

* `name`：计划的名称。对于每个项目，此名称必须具有唯一性。
* `eventName`：项目范围内的事件名称，决定了触发器的事件类型。
* `type`：计划的类型。必须为 `one-time` 或 `recurring`。
* `schedule`：指定应触发事件的时间。必须为时间戳或 cron 表达式，具体取决于 `type` 字段。
* `payloadVersion`：一个表示有效负载版本的整数，决定了触发器的事件类型。
* `payload`：用作事件有效负载的 `JSON` 对象，旨在将参数转发到 Cloud Code 脚本或模块。

> **Note:**
>
> **注意：** 有限制。请参阅[限制](/triggers/limits.md)以获取更多信息。

### 一次性计划##one-time-schedule

一次性计划是指在特定时间执行的单个事件。可能如下所示：

```json
{
"name" : "one-time-schedule",
"eventName": "example-event",
"type": "one-time",
"schedule": "2020-01-01T00:00:00Z",
"payloadVersion": 1,
"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"
}
```

`schedule` 字段是一个用于定义事件触发时间的 RFC3339 时间戳。

> **Note:**
>
> **注意：** 时间戳必须声明为将来的时间。

### 定期计划##recurring-schedule

定期计划是以特定时间间隔执行的一系列事件。可能如下所示：

```json
{
"name" : "recurring-schedule",
"eventName": "example-event",
"type": "recurring",
"schedule": "0 0 * * *",
"payloadVersion": 1,
"payload": "{\"someBoolean\": true, \"someString\": \"something\"}"
}
```

`schedule` 字段是一个用于定义事件触发时间的 cron 表达式。

## 与触发器重叠##overlap-with-triggers

请参阅[触发器结构](../tutorials/define-triggers/trigger-structure)，了解事件如何与触发器绑定。