2025.3.4
首页 ▸ Integrations ▸

OpenUV

OpenUV 集成显示来自 openuv.io 的紫外线和臭氧数据。

Warning

本文件中的指南构成了估算，旨在帮助 informed decision making（明智决策）。它们不应替代经过训练的医疗专业人员的分析、建议或诊断。

生成 API 密钥

要生成 API 密钥，请登录 OpenUV 网站。

配置

要将 OpenUV service 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

手动配置步骤

如果上述 My 按钮不起作用，您也可以手动执行以下步骤：

传感器

名称 类型 值
当前臭氧水平 传感器 以杜宾单位（du，Dobson Units）表示的臭氧水平
当前紫外线指数 传感器 紫外线指数（数值）
当前紫外线水平 传感器 紫外线水平（字面值）
最大紫外线指数 传感器 当天的最大紫外线指数（在太阳正午时）
保护窗口 二进制传感器 是否应使用防晒保护
皮肤类型 1 安全暴露时间 传感器 菲茨帕特里克皮肤类型 1 可以在阳光下无保护的时间
皮肤类型 2 安全暴露时间 传感器 菲茨帕特里克皮肤类型 2 可以在阳光下无保护的时间
皮肤类型 3 安全暴露时间 传感器 菲茨帕特里克皮肤类型 3 可以在阳光下无保护的时间
皮肤类型 4 安全暴露时间 传感器 菲茨帕特里克皮肤类型 4 可以在阳光下无保护的时间
皮肤类型 5 安全暴露时间 传感器 菲茨帕特里克皮肤类型 5 可以在阳光下无保护的时间
皮肤类型 6 安全暴露时间 传感器 菲茨帕特里克皮肤类型 6 可以在阳光下无保护的时间

更新数据

Important

OpenUV 不会自动更新其实体的数据！用户必须通过 homeassistant.update_entity 操作手动更新数据。

自 2019 年 2 月 1 日起，“限制”计划（这是新用户默认获得的计划）每天限制 50 个 API 请求。由于不同的 API 计划和位置有不同的要求，OpenUV 集成不会在初次加载后自动查询 API 获取新数据。要请求新数据，应使用 homeassistant.update_entity 操作。

请注意，在处理紫外线和臭氧数据时，选择以下任意一项作为 homeassistant.update_entity 操作的目标将更新 所有 这些实体的数据：

  • 当前臭氧水平
  • 当前紫外线指数
  • 当前紫外线水平
  • 最大紫外线指数
  • 皮肤类型 1 安全暴露时间
  • 皮肤类型 2 安全暴露时间
  • 皮肤类型 3 安全暴露时间
  • 皮肤类型 4 安全暴露时间
  • 皮肤类型 5 安全暴露时间
  • 皮肤类型 6 安全暴露时间

为了防止可能的 API 调用浪费，所有引用 OpenUV 实体的 homeassistant.update_entity 调用之间的间隔至少为 15 分钟。

保护窗口

当需要使用防晒保护时，保护窗口二进制传感器将处于 on 状态。

默认情况下，当紫外线指数超过 3.5 时，这种情况会发生。可以通过 UI 中的配置条目选项进行配置。给定了两个参数：

  • 保护窗口的起始紫外线指数：当超过该紫外线指数时，表示应使用防护
  • 保护窗口的结束紫外线指数：当低于该紫外线指数时，表示不再需要防护

更新数据的示例

在阳光至少高于地平线 10 度的情况下每 20 分钟更新一次紫外线指数数据：

automation:
  - alias: "更新 OpenUV"
    triggers:
      - trigger: time_pattern
        minutes: "/20"
    conditions:
      - condition: numeric_state
        entity_id: sun.sun
        value_template: "{{ state.attributes.elevation }}"
        above: 10
    actions:
      - action: homeassistant.update_entity
        target:
          entity_id: sensor.LATITUDE_LONGITUDE_current_uv_index

在中午 12:00 每天更新保护窗口：

automation:
  - alias: "更新 OpenUV"
    triggers:
      - trigger: time
        at: "12:00:00"
    actions:
      - action: homeassistant.update_entity
        target:
          entity_id: binary_sensor.LATITUDE_LONGITUDE_protection_window

为了在白天时间变化较大的地方进行最佳的 API 调用，你需要知道一年中最长白天的总小时数。例如，如果这是 17 个小时，则可以每 45 分钟进行 2 次调用，而不会超过每天 50 次 API 调用限制：

automation:
  - alias: "更新 OpenUV"
    triggers:
      # 每 45 分钟的时间模式将无法按预期工作，因为它有时会在每小时（整点和整点 + 45 分钟）触发两次；
      # 使用更频繁的时间模式和条件以获得预期行为：
      - trigger: time_pattern
        minutes: "/15"
    conditions:
      - condition: sun
        after: sunrise
        before: sunset
        # 最后一次调用很可能会在日落之前，这将使紫外线指数在夜晚的剩余时间内保持在 0 以外；为了解决这个问题，我们允许
        # 在太阳落山后再进行一次操作：
        before_offset: "+00:45:00"
      - condition: template
        # 我们检查最后一次触发是否在 40 分钟或更久之前，以避免时间问题；通过检查 40 分钟或更长时间，我们确保
        # 这仅在 45 分钟标记时为真：
        value_template: >- 
          {{
            state_attr('automation.update_openuv', 'last_triggered') == None
            or (
              now() - state_attr('automation.update_openuv', 'last_triggered')
            ) >= timedelta(hours = 0, minutes = 40)
          }}
    actions:
      - action: homeassistant.update_entity
        target:
          entity_id:
            # 更新紫外线和保护窗口数据：
            - binary_sensor.LATITUDE_LONGITUDE_protection_window
            - sensor.LATITUDE_LONGITUDE_current_uv_index

过期的 API 密钥和重新认证

在 OpenUV 中，HTTP 403 响应指示以下两种情况之一：

  1. 无效的 API 密钥
  2. 达到每日/每月调用限制的 API 密钥

不幸的是，集成无法从 OpenUV 提供的 API 数据中判断是哪种情况。因此，遵循以下策略：

  1. 任何 HTTP 403 响应都会创建一个持久通知，要求您重新认证 OpenUV 集成。
  2. 在 API 调用限制超过时，成功的 homeassistant.update_entity 服务调用后，现有的重新认证通知将自动删除。

如果您收到重新认证通知，并确定您的密钥只是达到了每日调用限制，您可以安全地忽略它。