The documentation you are viewing is for Dapr v1.13 which is an older version of Dapr. For up-to-date documentation, see the latest version.

Actor timers 和 reminders

为 Actors 设置计时器和提醒事项并执行错误处理

参与者可以通过注册 timer 或 reminder 来安排自己的定期工作。

Timer 和 reminder 的功能非常相似。 主要的区别在于，Dapr actor 运行时在停用后不保留任何有关 timer 的信息，而使用 Dapr actor 状态提供程序持久化有关 reminder 的信息。

这种区别允许用户在轻量级但无状态的 timer 和需要更多资源但有状态的 reminder 之间进行权衡。

Timer 和 reminder 的调度配置是相同的，总结如下:

dueTime是一个可选的参数，它设置了首次调用回调之前的时间或时间间隔。 如果忽略了 dueTime ，则在 timer/reminder 注册后立即调用回调。

支持的格式：

  • RFC3339 日期格式，例如 2020-10-02T15:00:00Z
  • time.Duration 格式，例如 2h30m
  • ISO 8601持续时间格式，例如PT2H30M

period 是一个可选参数，用于设置两个连续回调调用之间的时间间隔。 当以ISO 8601-1 duration格式指定时，您还可以配置重复次数，以限制回调调用的总次数。 如果period被省略，回调函数将只被调用一次。

支持的格式：

ttl是一个可选的参数，它设定时间或时间间隔，其后timer/reminder将过期并删除。 如果省略ttl，则不应用任何限制。

支持的格式：

  • RFC3339 日期格式，例如 2020-10-02T15:00:00Z
  • time.Duration 格式，例如 2h30m
  • ISO 8601持续时间格式。 示例：PT2H30M

Actor 运行时验证调度配置的正确性并返回无效输入的错误。

当您在period中指定重复次数以及在ttl中指定时间时，当满足任何条件时，timer/reminder将停止。

Actor 计时器

你可以通过 timer 在 actor 中注册一个回调。

Dapr actor 运行时确保回调方法遵守基于回合的并发保证。 这意味着，在此回调完成执行之前，没有其他执行者的方法或 timer/reminder 回调将在进行中。

Dapr actor 运行时在回调完成时保存对 actor 的状态所作的更改。 如果在保存状态时发生错误，那么将取消激活该 actor 对象，并且将激活新实例。

当 actor 作为垃圾回收(Gc) 的一部分被停用时，所有 timer 都会停止。 在此之后，将不会再调用 timer 的回调。 另外，Dapr actor 运行时不会保留关于在停用之前正在运行的 timer 的任何信息。 Actor 在将来重新激活时要注册所需的 timer，而这完全取决于 actor。

您可以通过将 HTTP/gRPC 请求调用 Dapr 来为 actor 创建 timer。

POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>

示例

Timer 的 duetime 可以在请求主体中指定。

下面的请求体配置了一个timer，dueTime为9秒，period为3秒。 这意味着它将在9秒后首次触发，然后每3秒触发一次。

{
  "dueTime":"0h0m9s0ms",
  "period":"0h0m3s0ms"
}

下面的请求体配置一个 timer，其period为3秒（以ISO 8601持续时间格式）。 它还将调用次数限制为10次。 这意味着它将在注册之后立即触发，然后每3秒触发一次。

{
  "period":"R10/PT3S",
}

下面的请求体配置一个 timer，其period为3秒（以ISO 8601持续时间格式），并且ttl为20秒。 这意味着它在注册后立即触发，然后每3秒触发一次，持续20秒。

{
  "period":"PT3S",
  "ttl":"20s"
}

下面的请求体配置一个 timer，其dueTime为10秒，period为3秒，ttl为10秒。 它还把调用次数限制在4次。 这意味着它会在10秒后第一次启动，然后每3秒启动一次，持续10秒，但总次数不超过4次。

{
  "dueTime":"10s",
  "period":"R4/PT3S",
  "ttl":"10s"
}

您可以通过调用来除去 Actor timer

DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>

请参阅 Api 描述 以获取更多详细信息。

Actor reminder

提醒是一种在指定时间内触发_持久_回调的机制。 它们的功能类似于 timer。 但与 timer 不同，在所有情况下 reminder 都会触发，直到 actor 显式取消注册 reminder 或删除 actor 或者执行次数已经到达给定值。 具体而言， reminder 会在所有 actor 失活和故障时也会触发，因为Dapr Actor 运行时会将 reminder 信息持久化到 Dapr Actor 状态提供者中。

您可以通过将 HTTP/gRPC 请求调用 Dapr 来为 actor 创建 reminder。

POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>

请求 reminder 的结构与 actor 相同。 请参考actor 计时器示例。

检索 actor reminder

您可以通过调用来检索 actor reminder

GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>

删除 actor reminder

您可以通过调用来除去 Actor timer

DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>

请参阅 Api 描述 以获取更多详细信息。

错误处理

当一个角色的方法成功完成后，运行时将继续在指定的定时器或提醒计划中调用该方法。 但是，如果该方法抛出异常，运行时会捕获异常并将错误信息记录在 Dapr 副卡日志中，而不会重试。

为了让行为体从故障中恢复并在崩溃或重启后重试，可以通过配置状态存储（如 Redis 或 Azure Cosmos DB）来持久化行为体的状态。

如果方法调用失败，计时器不会被移除。 只有在下列情况下，计时器才会被移除

  • Sidecar 崩溃
  • 执行完毕
  • 明确删除

提醒数据序列化格式

Actor提醒数据默认以JSON序列化。 Dapr v1.13及以上版本支持使用protobuf序列化格式来处理提醒数据，这可以根据吞吐量和负载大小带来显著的性能提升，使开发人员能够获得更高的吞吐量和更低的延迟。 另一个好处是将较小的数据存储在 actor 底层数据库中，这可以在使用某些云数据库时实现成本优化。 使用protobuf序列化的限制是无法再查询提醒数据。

在 Dapr 1.12.x 及之前的版本中，以 protobuf 格式保存的提醒数据无法读取。 建议在 Dapr v1.13 中测试此功能，并在将其投入生产之前，验证它与您的数据库是否按预期工作。

在Kubernetes上启用protobuf序列化

要在Kubernetes上使用protobuf序列化来处理actor提醒，请使用以下Helm值：

--set dapr_placement.maxActorApiLevel=20

在自托管上启用protobuf序列化

要在自托管上使用protobuf序列化来处理actor提醒，请使用以下daprd标志：

--max-api-level=20

下一步

配置actor运行时行为 >>

相关链接