Listas y paginación
Reelwire tiene dos clases de lista, y se comportan de forma distinta a propósito.
Los registros nunca dejan de crecer: /v1/jobs, /v1/posts, /v1/render-jobs, /v1/ingest-events, /v1/approvals y /v1/deliveries. El servidor los pagina, busca y ordena, sobre cada fila que tiene el espacio de trabajo. Las listas de sindicación también las pagina el servidor, con algunas diferencias propias: consulte Otras listas paginadas.
La configuración no crece sin límite: marcas, canales, streams, listas de publicaciones, la biblioteca multimedia. Vuelve completa, y el cliente la busca y la ordena por sí mismo. Una biblioteca son cientos de archivos, no millones, y paginarla no aportaría nada y costaría un viaje de ida y vuelta.
Los parámetros de los registros
| Parámetro | Qué hace |
|---|---|
page | Qué página, a partir de 1. Cualquier otro valor se trata como 1. |
perPage | Cuántos por página. De 1 a 200; fuera de ese rango, el valor predeterminado propio de la ruta. |
limit | El nombre anterior de perPage, que se sigue respetando. |
q | Lo que se escribió, comparado sin distinguir mayúsculas de minúsculas en las columnas que imprime la fila. Como máximo 200 caracteres. |
sort | Un nombre de columna que ofrece la ruta. Cualquier otro vuelve al orden predeterminado de la ruta. |
ascending | "true" o "false". Si falta, rige el valor predeterminado propio de la ruta: lo más reciente primero, salvo en /v1/approvals, que es una cola y se lee con lo más antiguo primero. |
since, until | La ventana, como instantes absolutos. |
curl "http://localhost:4000/v1/render-jobs?page=2&perPage=25&q=bund&sort=state&ascending=true" \
-H "Authorization: Bearer rw_your_key_here"
Las columnas por las que se puede ordenar cada registro:
| Ruta | sort |
|---|---|
/v1/jobs | createdAt. Cualquier otra cosa es el valor predeterminado, cuándo cambió el trabajo por última vez. |
/v1/posts | createdAt, state, platform, channelName |
/v1/render-jobs | submittedAt, state, templateId |
/v1/ingest-events | receivedAt, status, origin |
/v1/approvals | requestedAt, channelName |
/v1/deliveries | createdAt, updatedAt |
Cada registro responde con la página y los recuentos que la rodean:
{
"jobs": [],
"total": 7,
"all": 7,
"page": 1,
"perPage": 1,
"facets": { "state": ["COMPLETED"] }
}
| Campo | Qué es |
|---|---|
total | Filas que cumplen los filtros. Divida entre perPage para obtener la última página. |
all | Filas en la ventana pedida, sin tener en cuenta los demás filtros ni la búsqueda, para que pueda decir «7 de 412». |
page, perPage | Lo que obtuvo realmente, tras el ajuste. |
facets | Los valores que puede tomar cada filtro con utilidad. |
El perPage predeterminado difiere por ruta, porque las pantallas difieren: 25 para /v1/jobs, 40 para /v1/posts y /v1/deliveries, 30 para /v1/render-jobs, 50 para /v1/ingest-events, 200 para /v1/approvals. Envíe perPage en lugar de confiar en cualquiera de ellos.
/v1/jobs responde con dos recuentos más: stages, cuántas publicaciones contiene cada etapa, y unstaged, cuántas dejan la búsqueda y los filtros antes de elegir una etapa.
Las facetas se leen de las filas
facets se calcula a partir de lo que realmente contiene el espacio de trabajo, no de una lista fija. Un valor de filtro que aparece ahí es uno que puede devolver algo, y un estado en el que no hay nada no aparece. Algunas listas llevan también labels, que asigna nombres a los ids de las facetas, de modo que un menú desplegable de filtro no necesita una segunda solicitud para decir «Channel 4 de» en lugar de un ULID. Las excepciones son las tres opciones fijas de /v1/jobs, stage, approval y archive, que listan todo lo que admite el filtro.
Un filtro no interpretable amplía en lugar de rechazar
since y until que no se pueden leer se ignoran, no se rechazan. Es un filtro sobre una lista, y el fallo honesto es mostrar más, no mostrar un error. Lo mismo vale para una columna sort que una ruta no ofrece, y para un filtro repetido en la cadena de consulta: una clave dada dos veces llega como array, un filtro es siempre un solo valor, así que se trata como si no hubiera ningún filtro.
Una búsqueda de más de 200 caracteres es la única excepción, y es un 400.
Las ventanas significan cosas distintas
En /v1/jobs, la ventana es cuándo ocurrió algo al trabajo: llegó, se renderizó o cambió una de sus publicaciones. Un trabajo que llegó ayer y se publicó hace diez minutos está dentro de la última hora, porque las filas se ordenan por Actualizado y cualquier otra cosa sería mentira.
En /v1/posts, /v1/render-jobs y /v1/deliveries es cuándo se creó la fila, y en /v1/ingest-events cuándo llegó el evento. /v1/approvals no admite ventana: es la cola de lo que espera ahora.
/v1/calendar no es un registro y admite en su lugar from y to, ambos obligatorios, ambos instantes absolutos, con una ventana de como máximo 367 días.
Paginar con seguridad mientras llegan cosas
Un registro se ordena con lo más reciente primero, así que una fila que llega entre dos solicitudes desplaza todo un lugar hacia abajo y la página 2 puede repetir una fila que la página 1 ya mostró. Dos formas de evitarlo:
- Fije la ventana. Pase
untilcon el momento en que empezó y pagine por un conjunto que no puede crecer bajo sus pies. - Pagine desde el extremo más antiguo, con
ascending=true, cuando lea todo y no solo lo más reciente.
Cada fila lleva un id, así que deduplicar por el camino funciona hagas lo que hagas.
Otras listas paginadas
/v1/syndication/partners y /v1/syndication/deliveries admiten q, page, perPage y ascending, y ni sort ni ventana: siempre están en el orden en que se crearon las filas, lo más reciente primero. perPage es 50 por defecto y como máximo 500 para los participantes, 200 para las entregas, y un número mayor se recorta a ese máximo en lugar de ignorarse. Las entregas responden con total, all (cada línea que tiene el espacio de trabajo) y facets; los participantes responden con total y room, la cuota contra la que cuentan, y sin facetas. Consulte Sindicación.
Las listas que no se paginan
/v1/brands, /v1/channels, /v1/streams, /v1/queues, /v1/media, /v1/media/renders, /v1/feeds, /v1/templates y /v1/syndication/groups devuelven todo. page y perPage no hacen nada en ellas.
Unas pocas están en un punto intermedio: listas que admiten solo limit, sin página.
| Ruta | limit |
|---|---|
/v1/direct-export/videos | Por defecto 24, como máximo 100. |
/v1/direct-export/queue | No se toman: cada video que aún se renderiza o espera, los que fallaron en las últimas dos horas y los 100 conservados más recientes. |
/v1/ai/chats | No se toman: los 50 chats más recientes del último día. |
/v1/pipeline es una vista en vivo y no un registro: admite since y until y muestra como máximo 12 trabajos en cada carril junto a recuentos que los cubren todos. Consulte Publicaciones y trabajos.