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 métodos de conexión, consulta y exportación 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; conserve el valor predeterminado.
`auto_login`	Autentica al construir si es `True`; si es `False`, llame a `login()` antes de consultar.

Devuelve una instancia del cliente. Puede propagar errores de autenticación o conexión al construirse. Use 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.

Los métodos de consulta no modifican datos de TECSCI Cloud. 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 {}.

`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.

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 los atributos que se leen: `SERVER_SCOPE` (predeterminado) o `SHARED_SCOPE`.
`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.

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¶

get_asset_telemetry_keys¶

get_asset_telemetry¶

get_device_telemetry_keys_by_id¶

get_device_telemetry_by_id¶

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¶

`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`¶

`get_asset_telemetry_keys`¶

`get_asset_telemetry`¶

`get_device_telemetry_keys_by_id`¶

`get_device_telemetry_by_id`¶

`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`¶