FLY

i am fengdy.

0%

杂项

发表于
杂项

验证输入

configuration.yaml文件包含组件和平台的配置选项。我们使用voluptuous来确保用户提供的配置是有效的。为了设置平台或组件，有些条目是可选的，或者可能是必需的。其他类型必须是已定义的类型或来自已定义的列表。

我们对配置进行了测试，以确保用户有良好的体验，并尽量减少Home Assistant运行之前平台或组件设置出现问题时的通知。

除了voluptuous的默认类型外，还有许多自定义类型可供选择。要了解概述，请查看config_validation.py helper。

  • Types: string, byte, and boolean
  • Entity ID: entity_id and entity_ids
  • Numbers: small_float and positive_int
  • Time: time, time_zone
  • Misc: template, slug, temperature_unit, latitude, longitude, isfile, sun_event, ensure_list, port, url, and icon

要使用MQTT,验证平台，可以使用valid_subscribe_topic和valid_publish_topic。

请记住以下几点:

  • 使用在const.py中定义的常量
  • 从要集成的集成中导入PLATFORM_SCHEMA并扩展它。
  • 优先顺序是必需的，其次是可选的
  • 可选配置键的默认值需要是有效值。Don’t use a default which is None like vol.Optional(CONF_SOMETHING, default=None): cv.string, set the default to default='' if required.

片段

默认名称

如果用户没有提供使用的名称，通常为传感器设置一个默认值。

1
2
3
4
5
6
7
8
DEFAULT_NAME = "Sensor name"

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
    {
        # ...
        vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,
    }
)

限制值

1
2
3
4
5
6
7
8
DEFAULT_METHOD = "GET"

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
    {
        # ...
        vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(["POST", "GET"]),
    }
)

端口

All port numbers are from a range of 1 to 65535.

1
2
3
4
5
6
7
8
DEFAULT_PORT = 993

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
    {
        # ...
        vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,
    }
)

列表

如果传感器有一个预定义的可用选项列表，测试以确保配置条目与列表匹配。

1
2
3
4
5
6
7
8
9
10
11
12
13
SENSOR_TYPES = {
    "article_cache": ("Article Cache", "MB"),
    "average_download_rate": ("Average Speed", "MB/s"),
}

PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
    {
        # ...
        vol.Optional(CONF_MONITORED_VARIABLES, default=[]): vol.All(
            cv.ensure_list, [vol.In(SENSOR_TYPES)]
        ),
    }
)

向代码中添加类型提示

略

获取实例URL

在某些情况下，集成需要知道匹配当前用例所需需求的用户Home Assistant实例的URL。例如，导致设备需要向Home Assistant通信数据，或者外部服务或设备从Home Assistant获取数据(例如，生成的图像或声音文件)。

考虑到用户可以有一堆不同的URL可用，获取一个实例URL可能相当复杂:

  • 一个用户配置的内部家庭网络URL。
  • 自动检测的内部家庭网络URL。
  • 一个用户配置的，公共可访问的，从互联网工作的外部URL。
  • 一个由Nabu Casa提供的家庭助理云的URL，以防用户有一个订阅。

url可以在非标准端口(例如，不是80或443)上提供，并且可以使用或不使用SSL (http:// vs https://).)，这增加了额外的复杂性

幸运的是，HA提供了一个助手方法来缓解这一点。

URL 助手

Home Assistant提供了一个网络助手方法来获取与集成需求匹配的实例URL，该方法称为get_url。

helper方法的签名:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# homeassistant.helpers.network.get_url
def get_url(
    hass: HomeAssistant,
    *,
    require_current_request: bool = False,
    require_ssl: bool = False,
    require_standard_port: bool = False,
    allow_internal: bool = True,
    allow_external: bool = True,
    allow_cloud: bool = True,
    allow_ip: bool = True,
    prefer_external: bool = False,
    prefer_cloud: bool = False,
) -> str:

方法的不同参数:

  • require_current_request要求返回的URL与用户当前在浏览器中使用的URL匹配。如果当前没有请求，则会引发错误。
  • require_ssl:要求返回的URL以使用https方案。
  • require_standard_port:要求返回的URL使用标准HTTP端口。因此，http方案需要端口80,https方案需要端口443。
  • allow_internal:允许该URL为用户的内部设置URL或检测到的内网URL。如果只需要外部URL，则将此设置为False。
  • allow_external:允许URL为用户设置的外部URL或Home Assistant云URL。如果只需要一个内部URL，则将此设置为False。
  • allow_cloud:允许返回Home Assistant Cloud URL，如果不需要云URL，则设置为False。
  • allow_ip:允许URL的主机部分为IP地址，在用例不可用的情况下设置为False。
  • prefer_external:默认情况下，我们更喜欢内部url而不是外部url。将此选项设置为True将逻辑转换为外部URL而不是内部URL。
  • prefer_cloud:默认情况下，首选由用户设置的外部URL，但是，在极少数情况下，云URL可能更可靠。将此选项设置为True将优先使用Home Assistant Cloud URL，而不是用户定义的外部URL。

默认行为

默认情况下，不传递附加参数(get_url(hass))，它将尝试:

  • 获取用户设置的内部URL，或者如果不可用，尝试从网络接口检测一个(基于http设置)。
  • 如果一个内部URL失败，它将尝试获取一个外部URL。它优先使用用户设置的外部URL，以防失败;获得一个家庭助理云URL，如果是可用的。

默认的目标是:允许任何URL，但最好是本地URL，没有要求。

使用示例

使用helper的最基本的例子:

1
2
3
from homeassistant.helpers.network import get_url

instance_url = get_url(hass)

这个调用helper方法的示例将返回一个内部URL，最好是用户集或检测到的URL。如果不能提供，它将尝试用户的外部URL。最后，如果用户没有设置，它将尝试使用Home Assistant云URL。

如果绝对没有可用的URL(或者没有匹配给定需求的URL)，将引发一个异常:NoURLAvailableError。

1
2
3
4
5
6
7
8
9
10
11
12
from homeassistant.helpers import network

try:
    external_url = network.get_url(
        hass,
        allow_internal=False,
        allow_ip=False,
        require_ssl=True,
        require_standard_port=True,
    )
except network.NoURLAvailableError:
    raise MyInvalidValueError("Failed to find suitable URL for my integration")

上面的例子展示了URL帮助器的更复杂的用法。在这种情况下，请求的URL可能不是内部地址，URL可能不包含IP地址，需要SSL，必须在标准端口上提供服务。

如果没有可用的，则可以捕获和处理NoURLAvailableError异常。