bemserver-api-client 0.21.1

入口点

API资源可以通过API客户端实例中的专用入口点（Python属性）访问。

例如，/sites/资源可以通过sites属性请求，但/energy_consumption_timeseries_by_sites/可以通过energy_cons_ts_by_sites（比原始名称略短）请求。

# Get a list of all the sites available for the authenticated user.
sites_resp = api_client.sites.getall()

大多数API客户端入口点都有通用函数（CF）来请求API端点（资源上的操作）

• getall用于GET资源列表

• getone用于GET特定资源（通过其ID）

• create用于POST新资源

• update用于UPDATE特定资源

• 删除 以 删除 指定资源

  请注意，如 API 文档 中所述，某些操作在特定 API 资源上不可用（见 /timeseries_data/）。其他 API 资源有额外的操作，例如在 sites 上，可以调用 get_degree_days 和 download_weather_data 函数。

下表显示了 API 端点 URI 与 API 客户端入口点及其可用功能之间的对应关系。

CF 提到，所描述的入口点实现了所有 常用功能（getall，getone，create，update，delete）。CF - update 表示除了 update 外，所有常用功能都已实现。

使用示例

请务必参考API 文档，因为它全面描述了所有 API 端点：所需查询参数、有效负载中的数据格式和响应内容（状态码、数据格式等）。

import datetime as dt

from bemserver_api_client import BEMServerAPIClient
from bemserver_api_client.enums import DegreeDaysPeriod
from bemserver_api_client.exceptions import (
    BEMServerAPINotFoundError,
    BEMServerAPIValidationError,
)

# Get an instance of API client, setting the API host.
api_client = BEMServerAPIClient("localhost:5000")

# Get the authentication bearer access and refresh tokens (JWT).
auth_resp = api_client.auth.get_tokens("user@email.com", "password")
if auth_resp.data["status"] == "failure":
    # User could not be authenticated (no access/refresh tokens are returned).
    # Raise exception, ...
    pass
# At this point (auth_resp.data["status"] == "success"), the user is authenticated.
#  auth_resp.data contains access and refresh tokens:
#  {
#      "status": "success",
#      "access_token": "...",
#      "refresh_token": "..."
#  }

# Set authentication method (bearer token authentication) in API client instance,
#  in order to call private API endpoints.
api_client.set_authentication_method(
    BEMServerAPIClient.make_bearer_token_auth(
        auth_resp.data["access_token"], auth_resp.data["refresh_token"]
    )
)

# NOTE: When expired access token is automatically refreshed inside API client
#  and requests goes on. Else `BEMServerAPIAuthenticationError` is raised and
#  a new authentication is needed to continue calling private API endpoints.

# Get a list of all the sites available (for the authenticated user).
sites_resp = api_client.sites.getall()
# sites_resp is an instance of `BEMServerApiClientResponse` class,
#  which has processed yet API response data
# sites_resp.data contains sites list:
#  [
#      {
#          "id": 0,
#          "name": "A",
#          "latitude": -90,
#          "longitude": -180,
#          "description": "AAAAAA",
#          "ifc_id": "AAAAAA",
#          "campaign_id": 0
#      }
#  ]

# Get the heating degree days data of a specific site.
dd_resp = api_client.sites.get_degree_days(
    1,
    dt.date(2024, 1, 1).isoformat(),
    dt.date(2025, 1, 1).isoformat(),
    period=DegreeDaysPeriod.month,
)
# dd_resp.data contains:
#  {
#      "degree_days": {
#          "2024-01-01T00:00:00+01:00": 76.05166666666668,
#          "2024-02-01T00:00:00+01:00": 85.16583333333332,
#          "2024-03-01T00:00:00+01:00": 65.69916666666667,
#          "2024-04-01T00:00:00+02:00": 11.920000000000002,
#          "2024-05-01T00:00:00+02:00": 0,
#          "2024-06-01T00:00:00+02:00": 0,
#          "2024-07-01T00:00:00+02:00": 0,
#          "2024-08-01T00:00:00+02:00": 0,
#          "2024-09-01T00:00:00+02:00": 0,
#          "2024-10-01T00:00:00+02:00": 0,
#          "2024-11-01T00:00:00+01:00": 2.098333333333331,
#          "2024-12-01T00:00:00+01:00": null
#      }
#  }

# Get a specific site, that does not exists (status code 404).
# In this case, the API error response is processed and api client raises an exception.
try:
    sites_resp = api_client.sites.getone(42)
except BEMServerAPINotFoundError:
    # Manage resource not found error.
    pass

# Some kind of errors, like BEMServerAPIValidationError, includes details on what occured.
try:
    sites_resp = api_client.sites.create({"campaign_id": 1})
except BEMServerAPIValidationError as exc:
    # Manage validation error.
    print(exc.errors)
    # exc.errors actually contains a dict of validation messages:
    #  {
    #      "name": [
    #          "Missing data for required field."
    #      ]
    #  }