十一 Home Assistant 失败的处理

处理安装失败

你的集成可能由于多种原因无法安装。最常见的情况是设备或服务离线，或者凭据不再有效。你的集成必须重试安装，以便在设备或服务重新上线时尽快恢复，而无需用户重新启动Home Assistant。

处理离线或不可用的设备和服务

使用async_setup_entry的集成

在集成的__init__.py中的async_setup_entry函数中抛出ConfigEntryNotReady异常，Home Assistant将自动在稍后重试安装。需要注意的是，在平台的async_setup_entry中抛出ConfigEntryNotReady是无效的，因为此时配置项安装已经太晚，无法捕获该异常。

示例：

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """为我的设备设置配置项。"""
    device = MyDevice(entry.data[CONF_HOST])
    try:
        await device.async_setup()
    except (asyncio.TimeoutError, TimeoutException) as ex:
        raise ConfigEntryNotReady(f"连接到{device.ipaddr}超时") from ex

如果你正在使用[DataUpdateCoordinator](https://developers.home-assistant.io/docs/integration_fetching_data#coordinated-single-api-poll-for-data-for-all-entities)，如果首次刷新失败，调用await coordinator.async_config_entry_first_refresh()也将自动触发此异常。

如果你的集成支持发现功能，一旦你的设备或服务被发现，Home Assistant将自动重试。

处理重试的日志记录

将错误消息作为第一个参数传递给ConfigEntryNotReady。Home Assistant将以警告日志级别记录一次重试，后续重试将以调试级别记录。如果在抛出ConfigEntryNotReady时未设置消息，Home Assistant将尝试从导致ConfigEntryNotReady的异常中提取原因（如果它是由另一个异常传播而来）。

集成不应记录任何关于重试的非调试消息，而应依赖ConfigEntryNotReady内置的逻辑，以避免日志泛滥。

使用async_setup_platform的集成

在async_setup_platform中抛出PlatformNotReady异常，Home Assistant将自动在稍后重试安装。

示例：

async def async_setup_platform(
    hass: HomeAssistant,
    config: ConfigType,
    async_add_entities: AddEntitiesCallback,
    discovery_info: DiscoveryInfoType | None = None,
) -> None:
    """设置平台。"""
    device = MyDevice(conf[CONF_HOST])
    try:
        await device.async_setup()
    except ConnectionError as ex:
        raise PlatformNotReady(f"连接到{device.ipaddr}时出错：{ex}") from ex

处理重试的日志记录

将错误消息作为第一个参数传递给PlatformNotReady。Home Assistant将以警告日志级别记录一次重试，后续重试将以调试级别记录。如果在抛出ConfigEntryNotReady时未设置消息，Home Assistant将尝试从导致ConfigEntryNotReady的异常中提取原因（如果它是由另一个异常传播而来）。

集成不应记录任何关于重试的非调试消息，而应依赖PlatformNotReady内置的逻辑，以避免日志泛滥。

处理过期的凭据

抛出ConfigEntryAuthFailed异常，Home Assistant将自动将配置项置于失败状态并启动重新认证流程。异常必须从__init__.py中的async_setup_entry或DataUpdateCoordinator中抛出，否则无法有效触发重新认证流程。如果你的集成不使用DataUpdateCoordinator，可以使用entry.async_start_reauth()作为启动重新认证流程的替代方法。

重新认证流程将以下列上下文变量启动，这些变量在async_step_reauth步骤中可用：

• source：始终为“SOURCE_REAUTH”
• entry_id：需要重新认证的配置项的entry_id
• unique_id：需要重新认证的配置项的unique_id

示例：

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """为我的设备设置配置项。"""
    device = MyDevice(entry.data[CONF_HOST])
    try:
        await device.async_setup()
    except AuthFailed as ex:
        raise ConfigEntryAuthFailed(f"{device.name}的凭据已过期") from ex
    except (asyncio.TimeoutError, TimeoutException) as ex:
        raise ConfigEntryNotReady(f"连接到{device.ipaddr}超时") from ex