Referencia de API¶

Versión del paquete: 0.2.1

Esta guía corresponde a tecsci-cloud-api 0.2.1.

La referencia cubre los 49 métodos públicos de TecsciCloudClient. Las firmas conservan nombres, anotaciones, orden y valores predeterminados de la distribución publicada. self es la instancia y no se pasa al llamar al método. Any indica que la anotación no restringe el tipo; Optional[T] admite None. date y datetime corresponden a los tipos de Python.

Crear y cerrar el cliente¶

TecsciCloudClient(
    api_key: str,
    base_url: str = "https://cloud.tecsci.com.ar",
    auto_login: bool = True,
)

Parámetro	Significado
`api_key`	Obligatorio: valor leído de `TECSCI_CLOUD_API_KEY`. Una cadena vacía o no válida como texto produce `ValueError`.
`base_url`	Destino preconfigurado de Tecsci Cloud; conservá el valor predeterminado.
`auto_login`	Autentica al construir si es `True`; si es `False`, llamá a `login()` antes de consultar.

Devuelve una instancia del cliente. Puede propagar errores de autenticación o conexión al construirse. Usá el bloque with del inicio rápido para cerrar los recursos al salir. No se documentan métodos privados ni clases adicionales.

Interpretar errores y efectos¶

Los errores de API pueden representar 401, 403, entidad no disponible o fallas de red. No todos los métodos lanzan excepciones: cada ficha aclara los resultados vacíos o errores por entidad. No se promete una jerarquía propia de excepciones públicas. El inicio rápido muestra manejo sin importar clases adicionales.

Las escrituras pueden reemplazar valores existentes y los lotes pueden completarse parcialmente. Los permisos de la API key se aplican a todas las operaciones. Una exportación modifica archivos locales, aunque solo lea datos de Tecsci Cloud.

Conexión¶

`login`¶

Inicia la sesión de autenticación.

Efecto: Gestiona la conexión; no modifica datos de las entidades.

login(
    self,
) -> None

Parámetros: ninguno.

Retorno: None. Sin valor de retorno.

Posibles errores: Propaga errores de autenticación y conexión.

`close`¶

Cierra los recursos de la conexión.

Efecto: Gestiona la conexión; no modifica datos de las entidades.

close(
    self,
) -> None

Parámetros: ninguno.

Retorno: None. Sin valor de retorno.

Posibles errores: Puede propagar errores al cerrar recursos; no define una excepción pública propia.

Consultas¶

`get_device`¶

Obtiene un dispositivo por nombre.

Efecto: Lectura; no modifica datos.

get_device(
    self,
    device_name: str,
) -> Any

Parámetro	Significado
`device_name`	Nombre del dispositivo.

Retorno: Any. Objeto de dispositivo; puede accederse a name e id.id.

Posibles errores: LookupError si no se encuentra; propaga errores de API.

`get_asset`¶

Obtiene un activo por nombre o etiqueta.

Efecto: Lectura; no modifica datos.

get_asset(
    self,
    asset_name: str,
    customer_title: Optional[str] = None,
) -> Any

Parámetro	Significado
`asset_name`	Nombre o etiqueta del activo.
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.

Retorno: Any. Objeto de activo con id.id.

Posibles errores: LookupError si no se encuentra o si la búsqueda resulta ambigua; propaga errores de API.

`list_customer_assets`¶

Lista activos del cliente con grupos y relaciones.

Efecto: Lectura; no modifica datos.

list_customer_assets(
    self,
    customer_title: str,
    page_size: int = 100,
) -> list[dict[str, str]]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`page_size`	Cantidad positiva de entidades por solicitud.

Retorno: list[dict[str, str]]. Filas con name, type, equipmentKind, sensed_by, groups, contains_from y contains_to; valores múltiples unidos por ;.

Posibles errores: ValueError si page_size no es positivo; LookupError y errores de API.

`list_customer_devices`¶

Lista dispositivos del cliente y hasta tres orígenes de relaciones entrantes.

Efecto: Lectura; no modifica datos.

list_customer_devices(
    self,
    customer_title: str,
    page_size: int = 100,
) -> list[dict[str, str]]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`page_size`	Cantidad positiva de entidades por solicitud.

Retorno: list[dict[str, str]]. Filas con name, type, relation_to_1, relation_to_2, relation_to_3.

Posibles errores: ValueError si page_size no es positivo; LookupError y errores de API/conexión.

`get_device_profile_infos`¶

Consulta una página de información de perfiles de dispositivo.

Efecto: Lectura; no modifica datos.

get_device_profile_infos(
    self,
    page_size: int,
    page: int,
    text_search: Optional[str] = None,
    sort_property: Optional[str] = None,
    sort_order: Optional[str] = None,
    transport_type: Optional[str] = None,
) -> Any

Parámetro	Significado
`page_size`	Cantidad positiva de entidades por solicitud.
`page`	Índice de página, comenzando en 0.
`text_search`	Texto de búsqueda opcional.
`sort_property`	Propiedad por la que se ordenan los resultados.
`sort_order`	Sentido del orden solicitado.
`transport_type`	Filtro opcional de tipo de transporte del perfil.

Retorno: Any. Objeto de página; la anotación pública no especifica un tipo más concreto.

Posibles errores: Propaga errores de API para filtros o solicitudes rechazadas.

`get_customer`¶

Obtiene un cliente por título.

Efecto: Lectura; no modifica datos.

get_customer(
    self,
    customer_title: str,
) -> Any

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.

Retorno: Any. Objeto de cliente con id.id.

Posibles errores: LookupError si no se encuentra; propaga errores de API.

Telemetría¶

`get_latest_device_telemetry`¶

Consulta la última telemetría de un dispositivo.

Efecto: Lectura; no modifica datos.

get_latest_device_telemetry(
    self,
    device_name: str,
    keys: list[str],
) -> dict[str, Any]

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`keys`	Claves de telemetría. En exportaciones o copias, `None` selecciona todas las disponibles; en importación CSV selecciona las columnas de valores.

Retorno: dict[str, Any]. Diccionario por clave con listas de puntos ts y value.

Posibles errores: LookupError al resolver el dispositivo; propaga errores de API.

`get_latest_devices_telemetry`¶

Consulta y transforma la última telemetría de varios dispositivos.

Efecto: Lectura; no modifica datos.

get_latest_devices_telemetry(
    self,
    devices_and_keys: dict[str, list[str]],
) -> dict[str, Any]

Parámetro	Significado
`devices_and_keys`	Diccionario de nombres de dispositivos a listas de claves.

Retorno: dict[str, Any]. Diccionario por dispositivo y clave; fecha timestamp en UTC y value convertido cuando es numérico. Puede incluir None.

Posibles errores: Captura errores por dispositivo y devuelve {"error": ...} en su resultado.

`get_device_telemetry`¶

Consulta un intervalo de telemetría por nombre de dispositivo.

Efecto: Lectura; no modifica datos.

get_device_telemetry(
    self,
    device_name: str,
    keys: list[str],
    start_ts: int,
    end_ts: int,
    limit: int = 10000,
) -> dict[str, Any]

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`keys`	Claves de telemetría. En exportaciones o copias, `None` selecciona todas las disponibles; en importación CSV selecciona las columnas de valores.
`start_ts`	Inicio del intervalo, Unix epoch en milisegundos.
`end_ts`	Fin del intervalo, Unix epoch en milisegundos. En copia, `None` usa la hora actual.
`limit`	Máximo de puntos solicitado por consulta; no implica paginación automática.

Retorno: dict[str, Any]. Diccionario por clave con puntos ts y value, o {}.

Posibles errores: La búsqueda puede lanzar LookupError o errores de API; una falla posterior de consulta devuelve {}.

`post_device_telemetry`¶

Guarda una muestra; alias de compatibilidad de save_device_telemetry con timestamp obligatorio.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

post_device_telemetry(
    self,
    device_name: str,
    ts: int,
    values: dict[str, Any],
) -> Any

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`ts`	Unix epoch en milisegundos, no negativo; cuando es opcional, `None` usa la hora UTC actual.
`values`	Diccionario no vacío de claves de texto no vacías a valores.

Retorno: Any. Respuesta de escritura sin estructura pública más específica.

Posibles errores: ValueError para nombre, valores o timestamp inválidos; LookupError y errores de API.

`save_device_telemetry`¶

Guarda una muestra de telemetría por nombre de dispositivo.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_device_telemetry(
    self,
    device_name: str,
    values: dict[str, Any],
    ts: Optional[int] = None,
) -> Any

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`values`	Diccionario no vacío de claves de texto no vacías a valores.
`ts`	Unix epoch en milisegundos, no negativo; cuando es opcional, `None` usa la hora UTC actual.

Retorno: Any. Respuesta de escritura sin estructura pública más específica.

Posibles errores: ValueError para nombre, valores o timestamp inválidos; LookupError y errores de API.

`save_asset_telemetry`¶

Guarda una muestra por nombre o etiqueta de activo.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_asset_telemetry(
    self,
    asset_name: str,
    values: dict[str, Any],
    ts: Optional[int] = None,
    customer_title: Optional[str] = None,
) -> int

Parámetro	Significado
`asset_name`	Nombre o etiqueta del activo.
`values`	Diccionario no vacío de claves de texto no vacías a valores.
`ts`	Unix epoch en milisegundos, no negativo; cuando es opcional, `None` usa la hora UTC actual.
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.

Retorno: int. Cantidad de muestras guardadas: 1 si se completa.

Posibles errores: ValueError para datos inválidos; LookupError para activo ausente o ambiguo y errores de API.

`save_asset_telemetry_by_id`¶

Guarda una muestra por identificador de activo.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_asset_telemetry_by_id(
    self,
    asset_id: str,
    values: dict[str, Any],
    ts: Optional[int] = None,
) -> int

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`values`	Diccionario no vacío de claves de texto no vacías a valores.
`ts`	Unix epoch en milisegundos, no negativo; cuando es opcional, `None` usa la hora UTC actual.

Retorno: int. Cantidad de muestras guardadas: 1 si se completa.

Posibles errores: ValueError para identificador vacío, valores o timestamp inválidos; errores de API.

`save_asset_telemetry_points`¶

Guarda muestras de un activo por lotes.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_asset_telemetry_points(
    self,
    asset_id: str,
    points: list[dict[str, Any]],
    batch_size: int = 1000,
) -> int

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`points`	Lista de muestras con forma `{"ts": 1767225600000, "values": {"temperature": 21.5}}`.
`batch_size`	Cantidad positiva de muestras por lote de escritura.

Retorno: int. Cantidad de puntos enviados correctamente al completarse.

Posibles errores: ValueError para identificador vacío o tamaño de lote inválido; errores de API. Puede haber escrituras parciales.

`get_asset_telemetry_keys`¶

Lista las claves de telemetría de un activo.

Efecto: Lectura; no modifica datos.

get_asset_telemetry_keys(
    self,
    asset_id: str,
) -> list[str]

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.

Retorno: list[str]. Lista de nombres de claves.

Posibles errores: Captura errores y devuelve [].

`get_asset_telemetry`¶

Consulta una clave histórica de un activo.

Efecto: Lectura; no modifica datos.

get_asset_telemetry(
    self,
    asset_id: str,
    key: str,
    start_ts: int,
    end_ts: int,
    limit: int = 10000,
    order_by: str = 'DESC',
) -> list[dict[str, Any]]

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`key`	Una clave de telemetría.
`start_ts`	Inicio del intervalo, Unix epoch en milisegundos.
`end_ts`	Fin del intervalo, Unix epoch en milisegundos. En copia, `None` usa la hora actual.
`limit`	Máximo de puntos solicitado por consulta; no implica paginación automática.
`order_by`	Orden temporal: `ASC` o `DESC`.

Retorno: list[dict[str, Any]]. Lista de puntos ts y value.

Posibles errores: Captura errores y devuelve [].

`get_device_telemetry_keys_by_id`¶

Lista las claves de telemetría de un dispositivo por identificador.

Efecto: Lectura; no modifica datos.

get_device_telemetry_keys_by_id(
    self,
    device_id: str,
) -> list[str]

Parámetro	Significado
`device_id`	Identificador obtenido de una entidad autorizada, por ejemplo `dispositivo.id.id`.

Retorno: list[str]. Lista de nombres de claves.

Posibles errores: Propaga errores de API.

`get_device_telemetry_by_id`¶

Consulta una página histórica de una clave de dispositivo.

Efecto: Lectura; no modifica datos.

get_device_telemetry_by_id(
    self,
    device_id: str,
    key: str,
    start_ts: int,
    end_ts: int,
    limit: int = 10000,
    order_by: str = 'DESC',
) -> list[dict[str, Any]]

Parámetro	Significado
`device_id`	Identificador obtenido de una entidad autorizada, por ejemplo `dispositivo.id.id`.
`key`	Una clave de telemetría.
`start_ts`	Inicio del intervalo, Unix epoch en milisegundos.
`end_ts`	Fin del intervalo, Unix epoch en milisegundos. En copia, `None` usa la hora actual.
`limit`	Máximo de puntos solicitado por consulta; no implica paginación automática.
`order_by`	Orden temporal: `ASC` o `DESC`.

Retorno: list[dict[str, Any]]. Lista de puntos ts y value.

Posibles errores: Propaga errores de API.

`copy_device_telemetry_to_asset`¶

Copia telemetría de un dispositivo a un activo, conservando timestamps y opcionalmente renombrando claves.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

copy_device_telemetry_to_asset(
    self,
    device_name: str,
    asset_name: str,
    start_ts: int = 0,
    end_ts: Optional[int] = None,
    keys: Optional[list[str]] = None,
    page_limit: int = 10000,
    batch_size: int = 1000,
    customer_title: Optional[str] = None,
    key_mapping: Optional[dict[str, str]] = None,
) -> dict[str, Any]

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`asset_name`	Nombre o etiqueta del activo.
`start_ts`	Inicio del intervalo, Unix epoch en milisegundos.
`end_ts`	Fin del intervalo, Unix epoch en milisegundos. En copia, `None` usa la hora actual.
`keys`	Claves de telemetría. En exportaciones o copias, `None` selecciona todas las disponibles; en importación CSV selecciona las columnas de valores.
`page_limit`	Cantidad positiva de puntos por solicitud de telemetría.
`batch_size`	Cantidad positiva de muestras por lote de escritura.
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`key_mapping`	Mapa opcional de clave origen a destino; destinos no vacíos y sin colisiones.

Retorno: dict[str, Any]. Resumen con keys, key_mapping, points_read, points_uploaded y conteos por clave.

Posibles errores: ValueError para rango, tamaños o mapeos inválidos; LookupError y errores de API. Puede sobrescribir y completar parcialmente.

Atributos¶

`save_device_attributes`¶

Guarda atributos de dispositivo en SERVER_SCOPE.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_device_attributes(
    self,
    device_name: str,
    attrs: dict[str, Any],
) -> None

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`attrs`	Diccionario de nombres de atributos a valores; las claves existentes pueden sobrescribirse.

Retorno: None. Sin valor de retorno.

Posibles errores: LookupError al resolver el dispositivo y errores de API.

`save_device_attributes_by_id`¶

Guarda atributos de dispositivo por identificador y ámbito.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_device_attributes_by_id(
    self,
    device_id: str,
    attrs: dict[str, Any],
    scope: str = 'SERVER_SCOPE',
) -> None

Parámetro	Significado
`device_id`	Identificador obtenido de una entidad autorizada, por ejemplo `dispositivo.id.id`.
`attrs`	Diccionario de nombres de atributos a valores; las claves existentes pueden sobrescribirse.
`scope`	Ámbito de atributos; usá `SERVER_SCOPE` o `SHARED_SCOPE` para escritura según el destino.

Retorno: None. Sin valor de retorno.

Posibles errores: Propaga errores de API.

`save_asset_attributes`¶

Guarda atributos de activo por identificador y ámbito.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

save_asset_attributes(
    self,
    asset_id: str,
    attrs: dict[str, Any],
    scope: str = 'SERVER_SCOPE',
) -> None

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`attrs`	Diccionario de nombres de atributos a valores; las claves existentes pueden sobrescribirse.
`scope`	Ámbito de atributos; usá `SERVER_SCOPE` o `SHARED_SCOPE` para escritura según el destino.

Retorno: None. Sin valor de retorno.

Posibles errores: Propaga errores de API.

`set_attributes_for_customer_assets`¶

Actualiza atributos de todos los activos del tipo indicado del cliente.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

set_attributes_for_customer_assets(
    self,
    customer_title: str,
    asset_type: str,
    attrs: dict[str, Any],
    scope: str = 'SERVER_SCOPE',
    page_size: int = 100,
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`asset_type`	Tipo exacto de activo a seleccionar.
`attrs`	Diccionario de nombres de atributos a valores; las claves existentes pueden sobrescribirse.
`scope`	Ámbito de atributos; usá `SERVER_SCOPE` o `SHARED_SCOPE` para escritura según el destino.
`page_size`	Cantidad positiva de entidades por solicitud.

Retorno: dict[str, Any]. Diccionario por nombre con updated y datos de la entidad o error.

Posibles errores: ValueError para parámetros inválidos; errores de búsqueda/paginación; fallas individuales con updated=False.

`set_attributes_for_customer_devices`¶

Actualiza atributos de todos los dispositivos seleccionados del cliente.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

set_attributes_for_customer_devices(
    self,
    customer_title: str,
    attrs: dict[str, Any],
    scope: str = 'SHARED_SCOPE',
    page_size: int = 100,
    device_type: Optional[str] = None,
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`attrs`	Diccionario de nombres de atributos a valores; las claves existentes pueden sobrescribirse.
`scope`	Ámbito de atributos; usá `SERVER_SCOPE` o `SHARED_SCOPE` para escritura según el destino.
`page_size`	Cantidad positiva de entidades por solicitud.
`device_type`	Filtro opcional de tipo de dispositivo.

Retorno: dict[str, Any]. Diccionario por nombre con updated y datos de la entidad o error.

Posibles errores: Errores de búsqueda/paginación pueden propagarse; las fallas de actualización individuales se informan con updated=False.

`copy_device_attributes_to_asset`¶

Copia atributos del dispositivo al activo en los ámbitos seleccionados.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

copy_device_attributes_to_asset(
    self,
    device_name: str,
    asset_name: str,
    scopes: Optional[list[str]] = None,
    customer_title: Optional[str] = None,
) -> dict[str, Any]

Parámetro	Significado
`device_name`	Nombre del dispositivo.
`asset_name`	Nombre o etiqueta del activo.
`scopes`	Ámbitos que se copian. `None` o lista vacía selecciona `SERVER_SCOPE` y `SHARED_SCOPE`; solo admite esos dos.
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.

Retorno: dict[str, Any]. Resumen con scopes, attribute_keys_by_scope, attributes_copied_by_scope y attributes_copied.

Posibles errores: ValueError para ámbitos no admitidos; LookupError y errores de API. Puede sobrescribir y completar parcialmente.

Exportaciones¶

`download_customer_devices_to_csv`¶

Exporta el listado de dispositivos a CSV.

Efecto: Lee Tecsci Cloud y escribe o sobrescribe CSV locales.

download_customer_devices_to_csv(
    self,
    customer_title: str,
    output_path: str,
    page_size: int = 100,
) -> int

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`output_path`	Ruta del CSV de salida; crea directorios y puede sobrescribir el archivo.
`page_size`	Cantidad positiva de entidades por solicitud.

Retorno: int. Cantidad de filas escritas.

Posibles errores: Errores del listado y OSError al crear o escribir el destino.

`download_customer_assets_to_csv`¶

Exporta el listado de activos a CSV.

Efecto: Lee Tecsci Cloud y escribe o sobrescribe CSV locales.

download_customer_assets_to_csv(
    self,
    customer_title: str,
    output_path: str,
    page_size: int = 100,
) -> int

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`output_path`	Ruta del CSV de salida; crea directorios y puede sobrescribir el archivo.
`page_size`	Cantidad positiva de entidades por solicitud.

Retorno: int. Cantidad de filas escritas.

Posibles errores: Errores del listado y OSError al crear o escribir el destino.

`download_customer_asset_telemetry_to_csvs`¶

Exporta un CSV de telemetría por activo del tipo indicado.

Efecto: Lee Tecsci Cloud y escribe o sobrescribe CSV locales.

download_customer_asset_telemetry_to_csvs(
    self,
    customer_title: str,
    asset_type: str,
    start_ts: int,
    end_ts: int,
    output_dir: str,
    page_size: int = 100,
    page_limit: int = 10000,
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`asset_type`	Tipo exacto de activo a seleccionar.
`start_ts`	Inicio del intervalo, Unix epoch en milisegundos.
`end_ts`	Fin del intervalo, Unix epoch en milisegundos. En copia, `None` usa la hora actual.
`output_dir`	Directorio de salida; crea directorios y puede sobrescribir archivos coincidentes.
`page_size`	Cantidad positiva de entidades por solicitud.
`page_limit`	Cantidad positiva de puntos por solicitud de telemetría.

Retorno: dict[str, Any]. Resumen con assets_seen, assets, files_written, rows_written, rango, cliente, tipo y destino.

Posibles errores: ValueError para título/tipo vacío, rango invertido o paginación no positiva; LookupError, errores de API y OSError.

`download_customer_asset_attributes_to_csv`¶

Exporta atributos seleccionados de activos de un cliente.

Efecto: Lee Tecsci Cloud y escribe o sobrescribe CSV locales.

download_customer_asset_attributes_to_csv(
    self,
    customer_title: str,
    asset_type: str,
    attribute_keys: list[str],
    output_path: str,
    scope: str = 'SERVER_SCOPE',
    page_size: int = 100,
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`asset_type`	Tipo exacto de activo a seleccionar.
`attribute_keys`	Claves de atributos que se exportan; debe quedar al menos una clave no vacía.
`output_path`	Ruta del CSV de salida; crea directorios y puede sobrescribir el archivo.
`scope`	Ámbito de atributos; usá `SERVER_SCOPE` o `SHARED_SCOPE` para escritura según el destino.
`page_size`	Cantidad positiva de entidades por solicitud.

Retorno: dict[str, Any]. Resumen con rows_written, assets_seen, values_found, available_attribute_keys, claves, ámbito y destino.

Posibles errores: ValueError para título/tipo/ámbito vacío, claves vacías o paginación no positiva; LookupError, errores de API y OSError.

`download_asset_telemetry_to_csv`¶

Exporta telemetría paginada de un activo a un CSV.

Efecto: Lee Tecsci Cloud y escribe o sobrescribe CSV locales.

download_asset_telemetry_to_csv(
    self,
    asset_id: str,
    start_ts: int,
    end_ts: int,
    output_path: str,
    keys: Optional[list[str]] = None,
    page_limit: int = 10000,
) -> int

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`start_ts`	Inicio del intervalo, Unix epoch en milisegundos.
`end_ts`	Fin del intervalo, Unix epoch en milisegundos. En copia, `None` usa la hora actual.
`output_path`	Ruta del CSV de salida; crea directorios y puede sobrescribir el archivo.
`keys`	Claves de telemetría. En exportaciones o copias, `None` selecciona todas las disponibles; en importación CSV selecciona las columnas de valores.
`page_limit`	Cantidad positiva de puntos por solicitud de telemetría.

Retorno: int. Cantidad de filas; devuelve 0 sin crear el archivo si no hay claves o puntos.

Posibles errores: ValueError para paginación o rango inválidos al descargar; OSError. Algunas fallas de consulta pueden convertirse en datos vacíos y producir una exportación incompleta.

`upload_asset_telemetry_from_csv`¶

Importa muestras desde un CSV a un activo. Omite celdas vacías y preserva timestamps.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

upload_asset_telemetry_from_csv(
    self,
    asset_id: str,
    csv_path: str,
    keys: Optional[list[str]] = None,
    batch_size: int = 1000,
) -> int

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`csv_path`	Ruta del CSV de entrada con columna `timestamp_ms`.
`keys`	Claves de telemetría. En exportaciones o copias, `None` selecciona todas las disponibles; en importación CSV selecciona las columnas de valores.
`batch_size`	Cantidad positiva de muestras por lote de escritura.

Retorno: int. Cantidad de filas subidas; 0 si no hay valores.

Posibles errores: OSError, ValueError si falta timestamp_ms, timestamps no convertibles o lote inválido, y errores de API. Puede sobrescribir puntos y completar parcialmente.

Administración¶

`rename_devices_by_prefix`¶

Renombra dispositivos cuyo prefijo va seguido únicamente de dígitos.

Efecto: Modifica nombres únicamente con dry_run=False; simula por defecto.

rename_devices_by_prefix(
    self,
    old_prefix: str,
    new_prefix: str,
    page_size: int = 100,
    dry_run: bool = True,
) -> dict[str, Any]

Parámetro	Significado
`old_prefix`	Prefijo actual; solo coincide si lo que sigue son dígitos.
`new_prefix`	Nuevo prefijo para los nombres coincidentes.
`page_size`	Cantidad positiva de entidades por solicitud.
`dry_run`	Si es `True`, informa los cambios previstos sin aplicarlos. Revisá el valor predeterminado de este método.

Retorno: dict[str, Any]. Diccionario por nombre original con renamed, datos del cambio, dry_run cuando corresponde o error.

Posibles errores: ValueError para prefijos vacíos o página no positiva; errores de consulta y errores por dispositivo en el resumen.

`change_customer_devices_profile`¶

Cambia el perfil de los dispositivos seleccionados de un cliente.

Efecto: Modifica perfiles por defecto; dry_run=True permite simular.

change_customer_devices_profile(
    self,
    customer_title: str,
    target_profile_name: Optional[str] = None,
    target_profile_id: Optional[str] = None,
    page_size: int = 100,
    device_type: Optional[str] = None,
    dry_run: bool = False,
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`target_profile_name`	Nombre del perfil destino; indicá nombre o identificador.
`target_profile_id`	Identificador del perfil destino; alternativa al nombre.
`page_size`	Cantidad positiva de entidades por solicitud.
`device_type`	Filtro opcional de tipo de dispositivo.
`dry_run`	Si es `True`, informa los cambios previstos sin aplicarlos. Revisá el valor predeterminado de este método.

Retorno: dict[str, Any]. Diccionario por dispositivo con updated, datos del perfil, dry_run cuando corresponde o error.

Posibles errores: ValueError para selección de perfil inválida; LookupError y errores de consulta; fallas individuales en el resumen.

`delete_device_connectivity_alarms`¶

Elimina alarmas de conectividad de los dispositivos indicados.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

delete_device_connectivity_alarms(
    self,
    device_names: list[str],
) -> int

Parámetro	Significado
`device_names`	Lista de nombres de dispositivos.

Retorno: int. Cantidad de alarmas eliminadas.

Posibles errores: Captura errores por dispositivo y continúa; el conteo puede reflejar una ejecución parcial.

`assign_devices_to_customer`¶

Asigna dispositivos al cliente; ignora nombres vacíos y duplicados.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

assign_devices_to_customer(
    self,
    customer_title: str,
    device_names: list[str],
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`device_names`	Lista de nombres de dispositivos.

Retorno: dict[str, Any]. Diccionario por dispositivo con assigned y datos de la entidad o error.

Posibles errores: Errores de búsqueda del cliente; fallas por dispositivo con assigned=False.

`create_customer_users`¶

Crea usuarios del cliente y puede asignarlos a grupos y paneles. Puede enviar correos de activación.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

create_customer_users(
    self,
    customer_title: str,
    users: list[dict[str, Any]],
    authority: str = 'CUSTOMER_USER',
    send_activation_mail: bool = True,
    groups: Optional[list[str]] = None,
    default_dashboard: Optional[str] = None,
    home_dashboard: Optional[str] = None,
    home_dashboard_hide_toolbar: bool = False,
) -> dict[str, Any]

Parámetro	Significado
`customer_title`	Título del cliente. En búsquedas de activos ayuda a resolver el nombre; no garantiza un filtro estricto de pertenencia.
`users`	Lista de diccionarios con `email` y opcionalmente `first_name`, `last_name`, `phone`; ignora otras claves, correos vacíos y duplicados.
`authority`	Nivel de autorización solicitado para los usuarios; sujeto a los permisos de la API key.
`send_activation_mail`	`True` solicita enviar activación por correo; `False` obtiene el enlace en el resultado. Tratá esos enlaces como información sensible.
`groups`	Nombres de grupos de usuarios existentes a los que se incorporan los nuevos usuarios.
`default_dashboard`	Título del panel predeterminado del cliente.
`home_dashboard`	Título del panel de inicio del cliente.
`home_dashboard_hide_toolbar`	Oculta la barra del panel de inicio cuando ese panel está configurado.

Retorno: dict[str, Any]. Diccionario por correo con created, user_id, activation_link, groups o error. No compartas los enlaces de activación.

Posibles errores: Errores de búsqueda/configuración pueden propagarse; fallas por usuario con created=False. Puede completar parcialmente.

`get_rule_chain_metadata`¶

Consulta metadatos de una cadena de reglas accesible.

Efecto: Lectura; no modifica datos.

get_rule_chain_metadata(
    self,
    rule_chain_id: str,
) -> dict[str, Any]

Parámetro	Significado
`rule_chain_id`	Identificador de la cadena de reglas autorizada.

Retorno: dict[str, Any]. Diccionario de metadatos de la cadena.

Posibles errores: Propaga errores de API/conexión.

`list_rule_chain_nodes`¶

Lista nodos de una cadena de reglas accesible.

Efecto: Lectura; no modifica datos.

list_rule_chain_nodes(
    self,
    rule_chain_id: str,
) -> list[dict[str, Any]]

Parámetro	Significado
`rule_chain_id`	Identificador de la cadena de reglas autorizada.

Retorno: list[dict[str, Any]]. Lista de diccionarios de nodos.

Posibles errores: Propaga errores al obtener metadatos.

`clear_rule_node_debug_events`¶

Elimina eventos de depuración de entrada y salida del nodo.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

clear_rule_node_debug_events(
    self,
    rule_node_id: str,
    start_time: Optional[int] = None,
    end_time: Optional[int] = None,
) -> dict[str, Any]

Parámetro	Significado
`rule_node_id`	Identificador del nodo de reglas.
`start_time`	Límite inicial opcional de eventos en milisegundos.
`end_time`	Límite final opcional de eventos en milisegundos.

Retorno: dict[str, Any]. Resumen con cleared, nodo, tipo y direcciones de eventos y límites temporales.

Posibles errores: Propaga errores de API/conexión; el borrado puede ser parcial.

`clear_rule_chain_node_debug_events`¶

Resuelve un nodo de una cadena y elimina sus eventos de depuración.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

clear_rule_chain_node_debug_events(
    self,
    rule_chain_id: str,
    rule_node_id: Optional[str] = None,
    rule_node_name: Optional[str] = None,
    start_time: Optional[int] = None,
    end_time: Optional[int] = None,
) -> dict[str, Any]

Parámetro	Significado
`rule_chain_id`	Identificador de la cadena de reglas autorizada.
`rule_node_id`	Identificador del nodo de reglas.
`rule_node_name`	Nombre del nodo; alternativa al identificador.
`start_time`	Límite inicial opcional de eventos en milisegundos.
`end_time`	Límite final opcional de eventos en milisegundos.

Retorno: dict[str, Any]. Resumen del borrado con información de cadena y nodo.

Posibles errores: ValueError sin selector o ante nombres ambiguos; LookupError si el nodo no existe en la cadena; errores de API/conexión.

`relate_assets_to_devices`¶

Crea relaciones dirigidas de activos a dispositivos.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

relate_assets_to_devices(
    self,
    relations: list[tuple[str, str]],
    relation_type: str = 'Contains',
) -> dict[str, Any]

Parámetro	Significado
`relations`	Lista de tuplas de nombres `(origen, destino)`; el origen es un activo.
`relation_type`	Tipo de relación; predeterminado `Contains`.

Retorno: dict[str, Any]. Diccionario por pareja con related=True o related=False y error.

Posibles errores: Captura errores por pareja y los incluye en el resultado.

`relate_assets_to_assets`¶

Crea relaciones dirigidas entre activos.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

relate_assets_to_assets(
    self,
    relations: list[tuple[str, str]],
    relation_type: str = 'Contains',
) -> dict[str, Any]

Parámetro	Significado
`relations`	Lista de tuplas de nombres `(origen, destino)`; el origen es un activo.
`relation_type`	Tipo de relación; predeterminado `Contains`.

Retorno: dict[str, Any]. Diccionario por pareja con related=True o related=False y error.

Posibles errores: Captura errores por pareja y los incluye en el resultado.

`delete_all_device_relations`¶

Elimina todas las relaciones de los dispositivos indicados.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

delete_all_device_relations(
    self,
    device_names: list[str],
) -> dict[str, Any]

Parámetro	Significado
`device_names`	Lista de nombres de dispositivos.

Retorno: dict[str, Any]. Diccionario por dispositivo con deleted=True o deleted=False y error.

Posibles errores: Captura errores por dispositivo y los incluye en el resultado.

Procesamiento histórico¶

`previous_calendar_month_range`¶

Calcula los límites inclusivos del mes calendario anterior en la zona indicada.

Efecto: Cálculo local; no modifica datos.

previous_calendar_month_range(
    self,
    timezone: str = 'America/Argentina/Buenos_Aires',
) -> tuple[int, int]

Parámetro	Significado
`timezone`	Zona horaria para fechas sin zona y límites de calendario.

Retorno: tuple[int, int]. Tupla (inicio_ms, fin_ms). Cálculo local sin consultar datos.

Posibles errores: Puede fallar si la zona horaria no está disponible o no es válida.

`backfill_energy_delta_for_previous_month`¶

Calcula y guarda diferencias de un contador acumulativo del mes calendario anterior.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

backfill_energy_delta_for_previous_month(
    self,
    device_id: str,
    source_key: str = 'zygsz',
    target_key: str = 'energy_delta',
    timezone: str = 'America/Argentina/Buenos_Aires',
    reset_policy: str = 'zero',
    overwrite: bool = False,
    page_limit: int = 10000,
    batch_size: int = 1000,
) -> dict[str, Any]

Parámetro	Significado
`device_id`	Identificador obtenido de una entidad autorizada, por ejemplo `dispositivo.id.id`.
`source_key`	Clave de un contador acumulativo usado para calcular diferencias.
`target_key`	Clave de destino donde se guardan las diferencias.
`timezone`	Zona horaria para fechas sin zona y límites de calendario.
`reset_policy`	`zero` guarda cero ante una diferencia negativa; `discard` descarta ese punto.
`overwrite`	Si es `False`, omite timestamps existentes en destino; `True` permite reemplazarlos. No es una simulación.
`page_limit`	Cantidad positiva de puntos por solicitud de telemetría.
`batch_size`	Cantidad positiva de muestras por lote de escritura.

Retorno: dict[str, Any]. Resumen con rango, claves, source_points_read, previous_source_point_found, deltas_calculated, discarded_reset, discarded_invalid, skipped_existing y points_uploaded.

Posibles errores: ValueError para rango, fechas, tamaños o política inválidos; errores de zona horaria, API o datos no convertibles. Las consultas de activos pueden ocultar errores como vacíos. Puede completar parcialmente.

`backfill_energy_delta`¶

Calcula y guarda diferencias de un contador acumulativo en el intervalo indicado.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

backfill_energy_delta(
    self,
    device_id: str,
    start: int | float | str | date | datetime,
    end: int | float | str | date | datetime,
    source_key: str = 'zygsz',
    target_key: str = 'energy_delta',
    timezone: str = 'America/Argentina/Buenos_Aires',
    reset_policy: str = 'zero',
    overwrite: bool = False,
    page_limit: int = 10000,
    batch_size: int = 1000,
) -> dict[str, Any]

Parámetro	Significado
`device_id`	Identificador obtenido de una entidad autorizada, por ejemplo `dispositivo.id.id`.
`start`	Inicio como milisegundos, `date`, `datetime` o texto ISO; una fecha sin hora usa el inicio del día en la zona indicada.
`end`	Fin como milisegundos, `date`, `datetime` o texto ISO; una fecha sin hora usa el final del día en la zona indicada.
`source_key`	Clave de un contador acumulativo usado para calcular diferencias.
`target_key`	Clave de destino donde se guardan las diferencias.
`timezone`	Zona horaria para fechas sin zona y límites de calendario.
`reset_policy`	`zero` guarda cero ante una diferencia negativa; `discard` descarta ese punto.
`overwrite`	Si es `False`, omite timestamps existentes en destino; `True` permite reemplazarlos. No es una simulación.
`page_limit`	Cantidad positiva de puntos por solicitud de telemetría.
`batch_size`	Cantidad positiva de muestras por lote de escritura.

Retorno: dict[str, Any]. Resumen con rango, claves, source_points_read, previous_source_point_found, deltas_calculated, discarded_reset, discarded_invalid, skipped_existing y points_uploaded.

Posibles errores: ValueError para rango, fechas, tamaños o política inválidos; errores de zona horaria, API o datos no convertibles. Las consultas de activos pueden ocultar errores como vacíos. Puede completar parcialmente.

`backfill_asset_energy_delta`¶

Calcula y guarda diferencias de un contador acumulativo en el intervalo indicado.

Efecto: Escritura: modifica datos de Tecsci Cloud. Revisá el alcance antes de ejecutar.

backfill_asset_energy_delta(
    self,
    asset_id: str,
    start: int | float | str | date | datetime,
    end: int | float | str | date | datetime,
    source_key: str = 'zygsz',
    target_key: str = 'energy_delta',
    timezone: str = 'America/Argentina/Buenos_Aires',
    reset_policy: str = 'zero',
    overwrite: bool = False,
    page_limit: int = 10000,
    batch_size: int = 1000,
) -> dict[str, Any]

Parámetro	Significado
`asset_id`	Identificador obtenido de un activo autorizado, por ejemplo `activo.id.id`.
`start`	Inicio como milisegundos, `date`, `datetime` o texto ISO; una fecha sin hora usa el inicio del día en la zona indicada.
`end`	Fin como milisegundos, `date`, `datetime` o texto ISO; una fecha sin hora usa el final del día en la zona indicada.
`source_key`	Clave de un contador acumulativo usado para calcular diferencias.
`target_key`	Clave de destino donde se guardan las diferencias.
`timezone`	Zona horaria para fechas sin zona y límites de calendario.
`reset_policy`	`zero` guarda cero ante una diferencia negativa; `discard` descarta ese punto.
`overwrite`	Si es `False`, omite timestamps existentes en destino; `True` permite reemplazarlos. No es una simulación.
`page_limit`	Cantidad positiva de puntos por solicitud de telemetría.
`batch_size`	Cantidad positiva de muestras por lote de escritura.

Retorno: dict[str, Any]. Resumen con rango, claves, source_points_read, previous_source_point_found, deltas_calculated, discarded_reset, discarded_invalid, skipped_existing y points_uploaded.

Posibles errores: ValueError para rango, fechas, tamaños o política inválidos; errores de zona horaria, API o datos no convertibles. Las consultas de activos pueden ocultar errores como vacíos. Puede completar parcialmente.

Referencia de API¶

Crear y cerrar el cliente¶

Interpretar errores y efectos¶

Conexión¶

login¶

close¶

Consultas¶

get_device¶

get_asset¶

list_customer_assets¶

list_customer_devices¶

get_device_profile_infos¶

get_customer¶

Telemetría¶

get_latest_device_telemetry¶

get_latest_devices_telemetry¶

get_device_telemetry¶

post_device_telemetry¶

save_device_telemetry¶

save_asset_telemetry¶

save_asset_telemetry_by_id¶

save_asset_telemetry_points¶

get_asset_telemetry_keys¶

get_asset_telemetry¶

get_device_telemetry_keys_by_id¶

get_device_telemetry_by_id¶

copy_device_telemetry_to_asset¶

Atributos¶

save_device_attributes¶

save_device_attributes_by_id¶

save_asset_attributes¶

set_attributes_for_customer_assets¶

set_attributes_for_customer_devices¶

copy_device_attributes_to_asset¶

Exportaciones¶

download_customer_devices_to_csv¶

download_customer_assets_to_csv¶

download_customer_asset_telemetry_to_csvs¶

download_customer_asset_attributes_to_csv¶

download_asset_telemetry_to_csv¶

upload_asset_telemetry_from_csv¶

Administración¶

rename_devices_by_prefix¶

change_customer_devices_profile¶

delete_device_connectivity_alarms¶

assign_devices_to_customer¶

create_customer_users¶

get_rule_chain_metadata¶

list_rule_chain_nodes¶

clear_rule_node_debug_events¶

clear_rule_chain_node_debug_events¶

relate_assets_to_devices¶

relate_assets_to_assets¶

delete_all_device_relations¶

Procesamiento histórico¶

previous_calendar_month_range¶

backfill_energy_delta_for_previous_month¶

backfill_energy_delta¶

backfill_asset_energy_delta¶

`login`¶

`close`¶

`get_device`¶

`get_asset`¶

`list_customer_assets`¶

`list_customer_devices`¶

`get_device_profile_infos`¶

`get_customer`¶

`get_latest_device_telemetry`¶

`get_latest_devices_telemetry`¶

`get_device_telemetry`¶

`post_device_telemetry`¶

`save_device_telemetry`¶

`save_asset_telemetry`¶

`save_asset_telemetry_by_id`¶

`save_asset_telemetry_points`¶

`get_asset_telemetry_keys`¶

`get_asset_telemetry`¶

`get_device_telemetry_keys_by_id`¶

`get_device_telemetry_by_id`¶

`copy_device_telemetry_to_asset`¶

`save_device_attributes`¶

`save_device_attributes_by_id`¶

`save_asset_attributes`¶

`set_attributes_for_customer_assets`¶

`set_attributes_for_customer_devices`¶

`copy_device_attributes_to_asset`¶

`download_customer_devices_to_csv`¶

`download_customer_assets_to_csv`¶

`download_customer_asset_telemetry_to_csvs`¶

`download_customer_asset_attributes_to_csv`¶

`download_asset_telemetry_to_csv`¶

`upload_asset_telemetry_from_csv`¶

`rename_devices_by_prefix`¶

`change_customer_devices_profile`¶

`delete_device_connectivity_alarms`¶

`assign_devices_to_customer`¶

`create_customer_users`¶

`get_rule_chain_metadata`¶

`list_rule_chain_nodes`¶

`clear_rule_node_debug_events`¶

`clear_rule_chain_node_debug_events`¶

`relate_assets_to_devices`¶

`relate_assets_to_assets`¶

`delete_all_device_relations`¶

`previous_calendar_month_range`¶

`backfill_energy_delta_for_previous_month`¶

`backfill_energy_delta`¶

`backfill_asset_energy_delta`¶