diff --git a/homeassistant/components/recorder/icons.json b/homeassistant/components/recorder/icons.json index 9e41637184a..87634bedcc8 100644 --- a/homeassistant/components/recorder/icons.json +++ b/homeassistant/components/recorder/icons.json @@ -11,6 +11,9 @@ }, "enable": { "service": "mdi:database" + }, + "get_statistics": { + "service": "mdi:chart-bar" } } } diff --git a/homeassistant/components/recorder/services.py b/homeassistant/components/recorder/services.py index cc74d7a2376..ba454c59bf3 100644 --- a/homeassistant/components/recorder/services.py +++ b/homeassistant/components/recorder/services.py @@ -8,7 +8,13 @@ from typing import cast import voluptuous as vol from homeassistant.const import ATTR_ENTITY_ID -from homeassistant.core import HomeAssistant, ServiceCall, callback +from homeassistant.core import ( + HomeAssistant, + ServiceCall, + ServiceResponse, + SupportsResponse, + callback, +) from homeassistant.helpers import config_validation as cv from homeassistant.helpers.entityfilter import generate_filter from homeassistant.helpers.service import ( @@ -16,15 +22,18 @@ from homeassistant.helpers.service import ( async_register_admin_service, ) from homeassistant.util import dt as dt_util +from homeassistant.util.json import JsonArrayType, JsonObjectType from .const import ATTR_APPLY_FILTER, ATTR_KEEP_DAYS, ATTR_REPACK, DOMAIN from .core import Recorder +from .statistics import statistics_during_period from .tasks import PurgeEntitiesTask, PurgeTask SERVICE_PURGE = "purge" SERVICE_PURGE_ENTITIES = "purge_entities" SERVICE_ENABLE = "enable" SERVICE_DISABLE = "disable" +SERVICE_GET_STATISTICS = "get_statistics" SERVICE_PURGE_SCHEMA = vol.Schema( { @@ -63,6 +72,20 @@ SERVICE_PURGE_ENTITIES_SCHEMA = vol.All( SERVICE_ENABLE_SCHEMA = vol.Schema({}) SERVICE_DISABLE_SCHEMA = vol.Schema({}) +SERVICE_GET_STATISTICS_SCHEMA = vol.Schema( + { + vol.Required("start_time"): cv.datetime, + vol.Optional("end_time"): cv.datetime, + vol.Required("statistic_ids"): vol.All(cv.ensure_list, [cv.string]), + vol.Required("period"): vol.In(["5minute", "hour", "day", "week", "month"]), + vol.Required("types"): vol.All( + cv.ensure_list, + [vol.In(["change", "last_reset", "max", "mean", "min", "state", "sum"])], + ), + vol.Optional("units"): vol.Schema({cv.string: cv.string}), + } +) + @callback def _async_register_purge_service(hass: HomeAssistant, instance: Recorder) -> None: @@ -135,6 +158,79 @@ def _async_register_disable_service(hass: HomeAssistant, instance: Recorder) -> ) +@callback +def _async_register_get_statistics_service( + hass: HomeAssistant, instance: Recorder +) -> None: + async def async_handle_get_statistics_service( + service: ServiceCall, + ) -> ServiceResponse: + """Handle calls to the get_statistics service.""" + start_time = dt_util.as_utc(service.data["start_time"]) + end_time = ( + dt_util.as_utc(service.data["end_time"]) + if "end_time" in service.data + else None + ) + + statistic_ids = service.data["statistic_ids"] + types = service.data["types"] + period = service.data["period"] + units = service.data.get("units") + + result = await instance.async_add_executor_job( + statistics_during_period, + hass, + start_time, + end_time, + statistic_ids, + period, + units, + types, + ) + + formatted_result: JsonObjectType = {} + for statistic_id, statistic_rows in result.items(): + formatted_statistic_rows: JsonArrayType = [] + + for row in statistic_rows: + formatted_row: JsonObjectType = { + "start": dt_util.utc_from_timestamp(row["start"]).isoformat(), + "end": dt_util.utc_from_timestamp(row["end"]).isoformat(), + } + if (last_reset := row.get("last_reset")) is not None: + formatted_row["last_reset"] = dt_util.utc_from_timestamp( + last_reset + ).isoformat() + if (state := row.get("state")) is not None: + formatted_row["state"] = state + if (sum_value := row.get("sum")) is not None: + formatted_row["sum"] = sum_value + if (min_value := row.get("min")) is not None: + formatted_row["min"] = min_value + if (max_value := row.get("max")) is not None: + formatted_row["max"] = max_value + if (mean := row.get("mean")) is not None: + formatted_row["mean"] = mean + if (change := row.get("change")) is not None: + formatted_row["change"] = change + + formatted_statistic_rows.append(formatted_row) + + formatted_result[statistic_id] = formatted_statistic_rows + + return {"statistics": formatted_result} + + async_register_admin_service( + hass, + DOMAIN, + SERVICE_GET_STATISTICS, + async_handle_get_statistics_service, + schema=SERVICE_GET_STATISTICS_SCHEMA, + supports_response=SupportsResponse.ONLY, + ) + + @callback def async_register_services(hass: HomeAssistant, instance: Recorder) -> None: """Register recorder services.""" @@ -142,3 +238,4 @@ def async_register_services(hass: HomeAssistant, instance: Recorder) -> None: _async_register_purge_entities_service(hass, instance) _async_register_enable_service(hass, instance) _async_register_disable_service(hass, instance) + _async_register_get_statistics_service(hass, instance) diff --git a/homeassistant/components/recorder/services.yaml b/homeassistant/components/recorder/services.yaml index 7d7b926548c..65aa797d91b 100644 --- a/homeassistant/components/recorder/services.yaml +++ b/homeassistant/components/recorder/services.yaml @@ -48,3 +48,63 @@ purge_entities: disable: enable: + +get_statistics: + fields: + start_time: + required: true + example: "2025-01-01 00:00:00" + selector: + datetime: + + end_time: + required: false + example: "2025-01-02 00:00:00" + selector: + datetime: + + statistic_ids: + required: true + example: + - sensor.energy_consumption + - sensor.temperature + selector: + entity: + multiple: true + + period: + required: true + example: "hour" + selector: + select: + options: + - "5minute" + - "hour" + - "day" + - "week" + - "month" + + types: + required: true + example: + - "mean" + - "sum" + selector: + select: + options: + - "change" + - "last_reset" + - "max" + - "mean" + - "min" + - "state" + - "sum" + multiple: true + + units: + required: false + example: + energy: "kWh" + temperature: "°C" + selector: + object: diff --git a/homeassistant/components/recorder/strings.json b/homeassistant/components/recorder/strings.json index 0c8d47548bf..eb7e0c8b63d 100644 --- a/homeassistant/components/recorder/strings.json +++ b/homeassistant/components/recorder/strings.json @@ -66,6 +66,36 @@ "enable": { "name": "[%key:common::action::enable%]", "description": "Starts the recording of events and state changes." + }, + "get_statistics": { + "name": "Get statistics", + "description": "Retrieves statistics data for entities within a specific time period.", + "fields": { + "end_time": { + "name": "End time", + "description": "The end time for the statistics query. If omitted, returns all statistics from start time onward." + }, + "period": { + "name": "Period", + "description": "The time period to group statistics by." + }, + "start_time": { + "name": "Start time", + "description": "The start time for the statistics query." + }, + "statistic_ids": { + "name": "Statistic IDs", + "description": "The entity IDs or statistic IDs to return statistics for." + }, + "types": { + "name": "Types", + "description": "The types of statistics values to return." + }, + "units": { + "name": "Units", + "description": "Optional unit conversion mapping." + } + } } } } diff --git a/tests/components/recorder/test_statistics.py b/tests/components/recorder/test_statistics.py index ed754723426..a8d8ed61020 100644 --- a/tests/components/recorder/test_statistics.py +++ b/tests/components/recorder/test_statistics.py @@ -2,12 +2,15 @@ from collections.abc import Generator from datetime import timedelta +import re from typing import Any from unittest.mock import ANY, Mock, patch import pytest from sqlalchemy import select +import voluptuous as vol +from homeassistant import exceptions from homeassistant.components import recorder from homeassistant.components.recorder import Recorder, history, statistics from homeassistant.components.recorder.db_schema import StatisticsShortTerm @@ -40,7 +43,7 @@ from homeassistant.components.recorder.table_managers.statistics_meta import ( ) from homeassistant.components.recorder.util import session_scope from homeassistant.components.sensor import UNIT_CONVERTERS -from homeassistant.core import HomeAssistant +from homeassistant.core import Context, HomeAssistant from homeassistant.exceptions import HomeAssistantError from homeassistant.helpers import entity_registry as er from homeassistant.setup import async_setup_component @@ -56,7 +59,7 @@ from .common import ( statistics_during_period, ) -from tests.common import MockPlatform, mock_platform +from tests.common import MockPlatform, MockUser, mock_platform from tests.typing import RecorderInstanceContextManager, WebSocketGenerator @@ -3421,3 +3424,319 @@ async def test_recorder_platform_with_partial_statistics_support( for meth in supported_methods: getattr(recorder_platform, meth).assert_called_once() + + +@pytest.mark.parametrize( + ("service_args", "expected_result"), + [ + ( + { + "start_time": "2023-05-08 07:00:00Z", + "period": "hour", + "statistic_ids": ["sensor.i_dont_exist"], + "types": ["change", "last_reset", "max", "mean", "min", "state", "sum"], + }, + {"statistics": {}}, + ), + ( + { + "start_time": "2023-05-08 07:00:00Z", + "period": "hour", + "statistic_ids": [ + "sensor.total_energy_import1", + "sensor.total_energy_import2", + ], + "types": ["change", "last_reset", "max", "mean", "min", "state", "sum"], + }, + { + "statistics": { + "sensor.total_energy_import1": [ + { + "last_reset": "2021-12-31T22:00:00+00:00", + "change": 2.0, + "end": "2023-05-08T08:00:00+00:00", + "start": "2023-05-08T07:00:00+00:00", + "state": 0.0, + "sum": 2.0, + "min": 0.0, + "max": 10.0, + "mean": 1.0, + }, + { + "change": 1.0, + "end": "2023-05-08T09:00:00+00:00", + "start": "2023-05-08T08:00:00+00:00", + "state": 1.0, + "sum": 3.0, + "min": 1.0, + "max": 11.0, + "mean": 1.0, + }, + { + "change": 2.0, + "end": "2023-05-08T10:00:00+00:00", + "start": "2023-05-08T09:00:00+00:00", + "state": 2.0, + "sum": 5.0, + "min": 2.0, + "max": 12.0, + "mean": 1.0, + }, + { + "change": 3.0, + "end": "2023-05-08T11:00:00+00:00", + "start": "2023-05-08T10:00:00+00:00", + "state": 3.0, + "sum": 8.0, + "min": 3.0, + "max": 13.0, + "mean": 1.0, + }, + ], + "sensor.total_energy_import2": [ + { + "last_reset": "2021-12-31T22:00:00+00:00", + "change": 2.0, + "end": "2023-05-08T08:00:00+00:00", + "start": "2023-05-08T07:00:00+00:00", + "state": 0.0, + "sum": 2.0, + "min": 0.0, + "max": 10.0, + "mean": 1.0, + }, + { + "change": 1.0, + "end": "2023-05-08T09:00:00+00:00", + "start": "2023-05-08T08:00:00+00:00", + "state": 1.0, + "sum": 3.0, + "min": 1.0, + "max": 11.0, + "mean": 1.0, + }, + { + "change": 2.0, + "end": "2023-05-08T10:00:00+00:00", + "start": "2023-05-08T09:00:00+00:00", + "state": 2.0, + "sum": 5.0, + "min": 2.0, + "max": 12.0, + "mean": 1.0, + }, + { + "change": 3.0, + "end": "2023-05-08T11:00:00+00:00", + "start": "2023-05-08T10:00:00+00:00", + "state": 3.0, + "sum": 8.0, + "min": 3.0, + "max": 13.0, + "mean": 1.0, + }, + ], + } + }, + ), + ( + { + "start_time": "2023-05-08 07:00:00Z", + "period": "day", + "statistic_ids": [ + "sensor.total_energy_import1", + "sensor.total_energy_import2", + ], + "types": ["sum"], + }, + { + "statistics": { + "sensor.total_energy_import1": [ + { + "start": "2023-05-08T07:00:00+00:00", + "end": "2023-05-09T07:00:00+00:00", + "sum": 8.0, + } + ], + "sensor.total_energy_import2": [ + { + "start": "2023-05-08T07:00:00+00:00", + "end": "2023-05-09T07:00:00+00:00", + "sum": 8.0, + } + ], + } + }, + ), + ( + { + "start_time": "2023-05-08 07:00:00Z", + "end_time": "2023-05-08 08:00:00Z", + "period": "hour", + "types": ["change", "sum"], + "statistic_ids": ["sensor.total_energy_import1"], + "units": {"energy": "Wh"}, + }, + { + "statistics": { + "sensor.total_energy_import1": [ + { + "start": "2023-05-08T07:00:00+00:00", + "end": "2023-05-08T08:00:00+00:00", + "change": 2000.0, + "sum": 2000.0, + }, + ], + } + }, + ), + ], +) +@pytest.mark.usefixtures("recorder_mock") +async def test_get_statistics_service( + hass: HomeAssistant, + hass_read_only_user: MockUser, + service_args: dict[str, Any], + expected_result: dict[str, Any], +) -> None: + """Test the get_statistics service.""" + period1 = dt_util.as_utc(dt_util.parse_datetime("2023-05-08 00:00:00")) + period2 = dt_util.as_utc(dt_util.parse_datetime("2023-05-08 01:00:00")) + period3 = dt_util.as_utc(dt_util.parse_datetime("2023-05-08 02:00:00")) + period4 = dt_util.as_utc(dt_util.parse_datetime("2023-05-08 03:00:00")) + + last_reset = dt_util.parse_datetime("2022-01-01T00:00:00+02:00") + external_statistics = ( + { + "start": period1, + "state": 0, + "sum": 2, + "min": 0, + "max": 10, + "mean": 1, + "last_reset": last_reset, + }, + { + "start": period2, + "state": 1, + "sum": 3, + "min": 1, + "max": 11, + "mean": 1, + "last_reset": None, + }, + { + "start": period3, + "state": 2, + "sum": 5, + "min": 2, + "max": 12, + "mean": 1, + "last_reset": None, + }, + { + "start": period4, + "state": 3, + "sum": 8, + "min": 3, + "max": 13, + "mean": 1, + "last_reset": None, + }, + ) + external_metadata1 = { + "has_mean": True, + "has_sum": True, + "name": "Total imported energy", + "source": "recorder", + "statistic_id": "sensor.total_energy_import1", + "unit_of_measurement": "kWh", + } + external_metadata2 = { + "has_mean": True, + "has_sum": True, + "name": "Total imported energy", + "source": "recorder", + "statistic_id": "sensor.total_energy_import2", + "unit_of_measurement": "kWh", + } + async_import_statistics(hass, external_metadata1, external_statistics) + async_import_statistics(hass, external_metadata2, external_statistics) + + await async_setup_component(hass, "sensor", {}) + await async_recorder_block_till_done(hass) + + result = await hass.services.async_call( + "recorder", "get_statistics", service_args, return_response=True, blocking=True + ) + assert result == expected_result + + with pytest.raises(exceptions.Unauthorized): + result = await hass.services.async_call( + "recorder", + "get_statistics", + service_args, + return_response=True, + blocking=True, + context=Context(user_id=hass_read_only_user.id), + ) + + +@pytest.mark.parametrize( + ("service_args", "missing_key"), + [ + ( + { + "period": "hour", + "statistic_ids": ["sensor.sensor"], + "types": ["change", "last_reset", "max", "mean", "min", "state", "sum"], + }, + "start_time", + ), + ( + { + "start_time": "2023-05-08 07:00:00Z", + "period": "hour", + "types": ["change", "last_reset", "max", "mean", "min", "state", "sum"], + }, + "statistic_ids", + ), + ( + { + "start_time": "2023-05-08 07:00:00Z", + "statistic_ids": ["sensor.sensor"], + "types": ["change", "last_reset", "max", "mean", "min", "state", "sum"], + }, + "period", + ), + ( + { + "start_time": "2023-05-08 07:00:00Z", + "period": "hour", + "statistic_ids": ["sensor.sensor"], + }, + "types", + ), + ], +) +@pytest.mark.usefixtures("recorder_mock") +async def test_get_statistics_service_missing_mandatory_keys( + hass: HomeAssistant, + service_args: dict[str, Any], + missing_key: str, +) -> None: + """Test the get_statistics service with missing mandatory keys.""" + + await async_recorder_block_till_done(hass) + + with pytest.raises( + vol.error.MultipleInvalid, + match=re.escape(f"required key not provided @ data['{missing_key}']"), + ): + await hass.services.async_call( + "recorder", + "get_statistics", + service_args, + return_response=True, + blocking=True, + )