Paginación y rangos de tiempo

Las operaciones que pueden devolver muchos resultados los paginan con uno de varios estilos. La página de cada operación en la referencia de la API (en inglés) muestra qué campos recibe; esta página explica cómo funciona cada estilo.

Todas las marcas de tiempo son milisegundos de época Unix.

Páginas con cursor

La mayoría de las operaciones de lista reciben maxPageSize y lastEvaluatedKey, y devuelven lastEvaluatedKey mientras quedan resultados. Envíalo sin cambios para obtener la página siguiente; cuando la respuesta no trae lastEvaluatedKey, ya tienes todo. Por ejemplo, findAccessControlledDoors:

import os
import requests

URL = "https://api2.rhombussystems.com/api/component/findAccessControlledDoors"
HEADERS = {"x-auth-scheme": "api-token", "x-auth-apikey": os.environ["RHOMBUS_API_KEY"]}

doors, key = [], None
while True:
    body = {"maxPageSize": 100}
    if key:
        body["lastEvaluatedKey"] = key
    page = requests.post(URL, headers=HEADERS, json=body).json()
    if page.get("error"):
        raise RuntimeError(page.get("errorMsg"))
    doors += page.get("accessControlledDoors", [])
    key = page.get("lastEvaluatedKey")
    if not key:
        break

const url = "https://api2.rhombussystems.com/api/component/findAccessControlledDoors";
const headers = {
  "x-auth-scheme": "api-token",
  "x-auth-apikey": process.env.RHOMBUS_API_KEY,
  "Content-Type": "application/json",
};

const doors = [];
let key;
do {
  const body = { maxPageSize: 100, ...(key && { lastEvaluatedKey: key }) };
  const page = await (await fetch(url, { method: "POST", headers, body: JSON.stringify(body) })).json();
  if (page.error) throw new Error(page.errorMsg);
  doors.push(...(page.accessControlledDoors ?? []));
  key = page.lastEvaluatedKey;
} while (key);

Algunas operaciones anidan esos dos campos en un objeto pageRequest ({"pageRequest": {"maxPageSize": 100, "lastEvaluatedKey": "…"}}) y devuelven lastEvaluatedKey en el nivel superior de la respuesta.

• Sigue hasta que falte lastEvaluatedKey. Una página puede traer menos resultados que maxPageSize, o ninguno, aunque queden más: los resultados que no puedes ver se eliminan después de leer la página.
• Indica siempre maxPageSize. Sin él, algunas operaciones devuelven todos los resultados en una sola respuesta y otras aplican su propio valor predeterminado. Cada operación tiene su propio máximo, y un valor mayor se rechaza con 400.
• Trata lastEvaluatedKey como opaco. No lo construyas, edites ni guardes a largo plazo. Un valor que el servidor no puede leer no se rechaza: la operación vuelve a empezar desde la primera página.
• Mantén iguales los demás campos en todas las páginas de un mismo listado.

Tokens de página

Algunas operaciones, como getClipsWithProgress, usan pageSize y pageToken. Envía el pageToken de cada respuesta en la solicitud siguiente y detente cuando la respuesta no lo incluya. En getClipsWithProgress, pageSize va de 1 a 200 y su valor predeterminado es 100.

Cursores de marca de tiempo

getSavedClipsV2 devuelve lastEvaluatedTimestampMs. Envíalo como pageTimestampMs en la solicitud siguiente y detente cuando la respuesta no lo incluya. Indica maxPageSize; su valor predeterminado es 100. Igual que con los cursores, una página puede ser corta aunque queden más clips.

Ventanas de tiempo

El historial de eventos de puertas y sensores, como findComponentEventsByAccessControlledDoor, recibe una ventana y una cantidad en lugar de un cursor:

• createdAfterMs y createdBeforeMs delimitan la ventana. createdBeforeMs es exclusivo.
• limit limita la cantidad de eventos, empezando por los más recientes. Indícalo: sin limit, todos los eventos de la ventana llegan en una sola respuesta.

Para leer más atrás, repite la solicitud con createdBeforeMs igual a un milisegundo después del evento más antiguo que recibiste, y descarta por su UUID los eventos que ya tienes. Mover el límite exactamente a la marca de tiempo más antigua puede omitir eventos que comparten ese milisegundo.

Alertas de políticas

getPolicyAlerts devuelve las alertas de la más reciente a la más antigua, hasta maxResults, sin cursor en la respuesta. Para la página siguiente, envía el timestampMs y el uuid de la última alerta recibida como lastTimestampMs y lastUuid, con los mismos filtros y la misma ventana (afterTimestampMs, beforeTimestampMs). Detente cuando una página llegue vacía o cuando alcances el inicio de tu ventana.

Elegir el tamaño de página

Las páginas más grandes implican menos solicitudes contra tu límite de tasa, pero respuestas más lentas. Para sincronizar por completo una organización grande, usa el tamaño más grande que acepte la operación y continúa el ciclo hasta la condición de última página de la tabla anterior.