Python API¶
Versión del paquete: 0.2.1
Esta guía corresponde a tecsci-cloud-api 0.2.1.
La Python API de TECSCI Cloud permite consultar dispositivos y activos, recuperar mediciones y exportar datos para sus informes.
El paquete oficial es tecsci-cloud-api en PyPI. Se instala como tecsci-cloud-api y se importa desde tecsci_cloud_python_api.
Casos de uso
- Consultar la última temperatura y humedad de un dispositivo.
- Integrar datos históricos en un análisis de Python.
- Obtener inventarios de dispositivos y activos de un cliente.
- Exportar CSV para informes periódicos.
Todos los nombres y valores de los ejemplos son ficticios. sensor-001 y Demo no identifican entidades disponibles automáticamente: reemplácelos por entidades autorizadas antes de ejecutar consultas. Para el detalle de cada método, consulte la referencia de API.
Equivalencia de términos
La API usa los nombres internos de TECSCI Cloud, que no siempre coinciden con los del resto de esta ayuda:
| En la API | En el resto de la ayuda | Ejemplo |
|---|---|---|
Cliente (customer) |
Su organización | El laboratorio |
Activo (asset) |
El equipo monitoreado | Una heladera, un freezer o una conservadora |
Dispositivo (device) |
El dispositivo de TECSCI que mide y transmite | Un datalogger TC-CORE o un TC-MOB |
| Telemetría | Las mediciones | Temperatura, humedad, apertura de puerta |
| Atributos | La configuración de cada equipo | El rango de temperatura (minTemp y maxTemp) |
Un dispositivo puede medir más de un equipo: por ejemplo, un datalogger con dos sensores que mide una heladera y su freezer. Por eso el nombre de un activo no tiene que coincidir con el del dispositivo.
Requisitos¶
- Python 3.10 o posterior.
- Una API key de TECSCI Cloud con permisos de lectura para las entidades necesarias.
- Conectividad HTTPS con TECSCI Cloud.
Instalación¶
Entorno virtual opcional¶
Use un entorno virtual para separar los paquetes de cada proyecto.
Verifique que la versión mostrada sea 3.10 o posterior. Si PowerShell no permite activar el entorno, puede usar directamente su intérprete, sin modificar la política de la computadora:
Actualización y verificación¶
Estos comandos sirven en Linux, macOS y PowerShell con el entorno activado:
python -m pip install --upgrade tecsci-cloud-api==0.2.1
python -c "from importlib.metadata import version; print(version('tecsci-cloud-api'))"
python -c "from tecsci_cloud_python_api import TecsciCloudClient; print('Importación correcta')"
La versión esperada es 0.2.1. La actualización queda fijada a la versión cubierta por esta guía; revise la documentación de una nueva versión antes de cambiarla.
Para salir del entorno, ejecute deactivate.
Autenticación¶
La clave se obtiene exclusivamente de TECSCI_CLOUD_API_KEY. El programa Python debe leer esa variable y entregar su valor al constructor; el constructor no lee el entorno automáticamente. Los comandos de exportación sí lo hacen.
Configurar la sesión¶
Estos ejemplos solicitan la clave sin escribirla en el comando ni guardarla en el historial.
La variable se hereda por los programas iniciados desde esa terminal. Un editor o notebook ya abierto puede necesitar reiniciarse desde la sesión configurada.
import os
from tecsci_cloud_python_api import TecsciCloudClient
api_key = os.environ.get("TECSCI_CLOUD_API_KEY")
if not api_key or not api_key.strip():
raise SystemExit("Configure TECSCI_CLOUD_API_KEY antes de continuar.")
with TecsciCloudClient(api_key=api_key) as client:
print("Sesión iniciada")
No guarde la clave en código, archivos versionados, notebooks compartidos ni argumentos de terminal. No imprima su valor ni publique registros de errores sin revisarlos.
Permisos y errores¶
- 401: revise si la clave es válida, está vigente o fue revocada. Vuelva a cargar la clave autorizada.
- 403: verifique los permisos asociados a la clave para esa entidad y operación. Solicite únicamente el acceso necesario.
Rotación y revocación¶
Coordine la emisión de una nueva clave con quien administra el acceso a TECSCI Cloud, actualice el entorno de cada proceso, verifique una lectura autorizada y revoque la anterior. Ante una exposición, solicite su revocación inmediata. Esta interfaz no ofrece métodos públicos para emitir, rotar o revocar API keys.
Al terminar, retírela de la terminal:
Eliminar una variable local no revoca la clave ni la elimina de otros procesos. Consulte Seguridad.
Inicio rápido¶
Guarde este programa como consulta.py. Antes de ejecutarlo, complete la instalación y configure la variable de entorno. El ejemplo realiza una lectura; el nombre sensor-001 es ficticio.
import os
from tecsci_cloud_python_api import TecsciCloudClient
def main():
api_key = os.environ.get("TECSCI_CLOUD_API_KEY")
if not api_key or not api_key.strip():
raise SystemExit("Falta configurar TECSCI_CLOUD_API_KEY.")
try:
with TecsciCloudClient(api_key=api_key) as client:
datos = client.get_latest_device_telemetry(
"sensor-001", ["temperature", "humidity"]
)
if datos:
print(datos)
else:
print("No hay mediciones disponibles para esas claves.")
except LookupError:
raise SystemExit("No se encontró el dispositivo solicitado.")
except ValueError:
raise SystemExit("Revise la clave y los parámetros de la consulta.")
except Exception as error:
estado = getattr(error, "status", None)
if estado is None:
estado = getattr(getattr(error, "response", None), "status_code", None)
if estado == 401:
mensaje = "Autenticación rechazada: revise la API key."
elif estado == 403:
mensaje = "Acceso denegado: revise los permisos de la API key."
else:
mensaje = "No se pudo consultar TECSCI Cloud. Revise conexión y certificados."
raise SystemExit(mensaje) from None
if __name__ == "__main__":
main()
El bloque with cierra la conexión al salir, incluso si falla la consulta. La autenticación ocurre al construir el cliente, antes de entrar al bloque. El manejo general de errores evita depender de clases adicionales y no imprime el contenido de la excepción.
Una respuesta ilustrativa, completamente ficticia:
{
"temperature": [{"ts": 1767225600000, "value": "21.5"}],
"humidity": [{"ts": 1767225600000, "value": "45"}]
}
Cada clave contiene una lista de puntos con ts (Unix epoch en milisegundos) y value. No suponga que los valores son siempre numéricos ni que todas las claves tienen datos.
Consultas¶
Las siguientes operaciones leen datos. Use la autenticación configurada y reemplace los nombres ficticios por entidades autorizadas.
Dispositivos, activos y cliente¶
Un activo representa una entidad organizada en TECSCI Cloud; su nombre no tiene que coincidir con el del dispositivo que produce mediciones.
import os
from tecsci_cloud_python_api import TecsciCloudClient
with TecsciCloudClient(api_key=os.environ["TECSCI_CLOUD_API_KEY"]) as client:
dispositivo = client.get_device("sensor-001")
activo = client.get_asset("Demo", customer_title="Demo")
cliente = client.get_customer("Demo")
dispositivos = client.list_customer_devices("Demo", page_size=100)
activos = client.list_customer_assets("Demo", page_size=100)
print(dispositivos)
print(activos)
get_device, get_asset y get_customer devuelven objetos, no necesariamente diccionarios. Los listados devuelven listas de diccionarios y recorren las páginas; page_size controla el tamaño de cada solicitud, no el total.
Respuesta ficticia de list_customer_devices:
[
{"name": "sensor-001", "type": "Demo", "relation_to_1": "Demo", "relation_to_2": "", "relation_to_3": ""}
]
customer_title ayuda a buscar activos, pero no debe interpretarse como un filtro estricto de pertenencia de get_asset: una coincidencia directa por nombre puede resolverse antes. Los permisos de la API key siguen limitando el acceso.
Telemetría actual¶
import os
from tecsci_cloud_python_api import TecsciCloudClient
with TecsciCloudClient(api_key=os.environ["TECSCI_CLOUD_API_KEY"]) as client:
ultima = client.get_latest_device_telemetry("sensor-001", ["temperature", "humidity"])
varias = client.get_latest_devices_telemetry({"sensor-001": ["temperature"]})
print(ultima)
print(varias)
El segundo método transforma valores numéricos y presenta la fecha en UTC. Respuesta ficticia de get_latest_devices_telemetry:
Una clave sin datos puede devolver null; un dispositivo con error devuelve un diccionario con error. Revise cada resultado.
Telemetría histórica¶
Los límites temporales y los campos ts usan Unix epoch en milisegundos, no segundos. Multiplique por 1000 al convertir desde datetime.timestamp().
import os
from datetime import datetime, timedelta, timezone
from tecsci_cloud_python_api import TecsciCloudClient
fin = datetime.now(timezone.utc)
inicio = fin - timedelta(days=7)
start_ts = int(inicio.timestamp() * 1000)
end_ts = int(fin.timestamp() * 1000)
with TecsciCloudClient(api_key=os.environ["TECSCI_CLOUD_API_KEY"]) as client:
datos = client.get_device_telemetry(
"sensor-001", ["temperature", "humidity"], start_ts, end_ts, limit=10000
)
activo = client.get_asset("Demo", customer_title="Demo")
datos_activo = client.get_asset_telemetry(
activo.id.id, "temperature", start_ts, end_ts, order_by="ASC"
)
print(datos)
print(datos_activo)
Respuesta ficticia del activo:
limit limita los puntos de la consulta; estos métodos no descargan automáticamente todo el historial. Para exportaciones paginadas use Exportaciones CSV.
Vacío no siempre significa ausencia de datos
get_device_telemetry puede devolver {} ante errores de consulta; get_asset_telemetry y get_asset_telemetry_keys pueden devolver []. La búsqueda inicial del dispositivo sí puede lanzar una excepción. Verifique permisos, nombres, claves y fechas antes de concluir que no existen mediciones.
Exportaciones CSV¶
Los dos comandos instalados leen TECSCI_CLOUD_API_KEY del entorno. Consultan TECSCI Cloud y escriben archivos locales; no modifican los datos remotos. Ejecute primero:
Telemetría por activo¶
El mismo comando funciona en Linux, macOS y PowerShell con el entorno activado:
tecsci-export-telemetry --customer "Demo" --days 7 --asset-type "Demo" --output-dir "exports/demo-telemetria"
| Opción | Uso |
|---|---|
--customer |
Título del cliente; obligatorio. |
--days |
Días de 24 horas hacia atrás desde la ejecución; entero positivo obligatorio. |
--asset-type |
Tipo exacto del activo; predeterminado temp_door. Demo es ficticio. |
--output-dir |
Directorio de destino; predeterminado exports/<cliente>_<tipo>_<dias>d. |
--page-size |
Activos por solicitud; predeterminado 100. |
--page-limit |
Puntos por solicitud de telemetría; predeterminado 10000. |
Se crea el directorio y un CSV por activo del tipo seleccionado. El nombre se deriva del nombre del activo, reemplaza caracteres no admitidos, se limita a 120 caracteres y agrega sufijos si hay colisiones dentro de la exportación. Por ejemplo: exports/demo-telemetria/Demo.csv.
Los CSV usan UTF-8, comas y columnas timestamp (UTC), timestamp_ms y las claves de telemetría ordenadas. Las filas están ordenadas de la más antigua a la más reciente; una medición ausente queda vacía. Un activo sin mediciones genera un archivo con encabezado. Sin activos coincidentes no se generan CSV.
Ejemplo ficticio:
Límites de temperatura¶
tecsci-export-temperature-limits --customer "Demo" --asset-type "Demo" --output "exports/demo-limites.csv"
| Opción | Uso |
|---|---|
--customer |
Título del cliente; obligatorio. |
--asset-type |
Tipo exacto del activo; predeterminado temp_door. |
--scope |
Ámbito de atributos; predeterminado SERVER_SCOPE. |
--output |
Archivo de destino; predeterminado exports/<cliente>_<tipo>_temperature_limits.csv. |
--page-size |
Activos por solicitud; entero positivo, predeterminado 100. |
Exporta los atributos actuales minTemp y maxTemp, no un historial; no admite --days. Crea los directorios necesarios y un CSV con columnas asset_name, asset_id, asset_type, minTemp, maxTemp. Los valores ausentes quedan vacíos. Sin coincidencias escribe solo el encabezado. El resumen informa cuántos valores encontró y, si faltan, qué claves de atributos recibió.
Ambos comandos admiten --base-url; conserve el destino predeterminado de TECSCI Cloud salvo indicación expresa del responsable del servicio. No entregue credenciales a un destino desconocido.
Archivos existentes
Los archivos de destino se abren para escritura y pueden sobrescribirse. Elija una carpeta nueva para cada exportación. Una falla puede dejar archivos parciales; revise el resumen y los archivos antes de usarlos.
Los comandos terminan con código 2 si falta la variable; los argumentos inválidos también producen un error de uso. --help no requiere autenticación. No hay una opción de argumento para pasar la API key.
Solución de problemas¶
| Síntoma | Qué revisar |
|---|---|
ModuleNotFoundError |
Instale el paquete en el mismo intérprete que ejecuta el programa. El import es tecsci_cloud_python_api. |
| Variable ausente | Configure TECSCI_CLOUD_API_KEY en la sesión que inicia Python. No imprima su valor para comprobarla. |
| Clave inválida o 401 | Revise vigencia, revocación y errores al copiar la clave; cargue una clave autorizada. |
| 403 | Pida al administrador que revise permisos sobre la entidad y operación. |
| Entidad no encontrada | Revise nombre o etiqueta, permisos y cliente. Los nombres de esta guía son ficticios. |
| Resultado vacío | Revise claves, rango temporal en milisegundos y tipo de activo. Algunos métodos convierten errores en resultados vacíos. |
| Red o certificados | Compruebe la conectividad, la fecha de la computadora y los certificados de confianza con el área de sistemas. No desactive la verificación TLS. |
| Comando no encontrado | Active el entorno virtual donde instaló el paquete. |
Mismo paquete, mismo intérprete¶
pip puede pertenecer a otro Python. Use siempre el intérprete con el que ejecutará el programa:
python -m pip show tecsci-cloud-api
python -c "import sys; print(sys.executable)"
python -c "from importlib.metadata import version; print(version('tecsci-cloud-api'))"
En PowerShell, si no activó el entorno, reemplace python por .\.venv\Scripts\python.exe. En notebooks, verifique el intérprete del kernel.
Comprobación de la variable sin revelar la clave:
Errores parciales¶
No todos los errores se lanzan como excepciones. get_latest_devices_telemetry incluye errores por entidad en el resultado. get_device_telemetry puede devolver {} ante una falla de consulta, mientras que get_asset_telemetry y get_asset_telemetry_keys pueden devolver [].
Al solicitar ayuda, indique versión, operación y código HTTP si está disponible. Revise y oculte credenciales, datos e identificadores antes de compartir registros. Consulte Autenticación y Seguridad.
Seguridad¶
El acceso a TECSCI Cloud queda limitado por los permisos asociados a la API key. Poder importar un método no implica tener autorización para ejecutarlo sobre cualquier entidad.
- Aplique mínimo privilegio: para informes y consultas, solicite permisos de lectura sobre las entidades necesarias.
- No comparta API keys ni las incluya en ejemplos, capturas, repositorios o notebooks compartidos.
- Obtenga la clave únicamente desde
TECSCI_CLOUD_API_KEY, según Autenticación. - Proteja la computadora y los procesos que reciben la variable de entorno.
- Revoque inmediatamente las claves comprometidas y reemplácelas en todos los procesos afectados.
- Conserve la verificación de certificados y el destino predeterminado del cliente.
- Proteja también los CSV: una exportación real puede contener información de su organización e identificadores.
Los ejemplos usan exclusivamente nombres y datos ficticios; no contienen credenciales. El cliente se comunica con la API de TECSCI Cloud.