Saltar al contenido principal
Actualmente disponible para Lotes. El soporte para scrapes, crawls, mapas y respuestas estará disponible pronto.
Los metadatos te permiten adjuntar pares clave-valor personalizados a los recursos de Olostep. Esto es útil para el seguimiento, filtrado, organización y almacenamiento de contexto junto con tus solicitudes de API. Los metadatos siguen el enfoque de Stripe: simple, flexible y consistente en todos los endpoints.

​
Casos de Uso

Seguimiento y Organización

Vincula recursos a sistemas internos con IDs de pedidos, IDs de clientes o nombres de proyectos.

Filtrado y Búsqueda

Etiqueta recursos para una fácil recuperación y filtrado en tu aplicación.

Contexto de Flujo de Trabajo

Almacena la etapa del pipeline, el nivel de prioridad o las instrucciones de procesamiento.

Rastro de Auditoría

Registra quién inició una solicitud, marcas de tiempo o información de versión.

​
Añadiendo Metadatos al Crear

Incluye el parámetro metadata al crear un recurso: 
{
  "url": "https://example.com",
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Doe",
    "priority": "high",
    "internal_ref": "proj-2024-001"
  }
}
Los metadatos se devuelven en todas las respuestas GET posteriores para ese recurso.

​
Reglas de Validación

RestricciónLímiteEjemplo de Error
Máximo de claves50"Los metadatos pueden tener un máximo de 50 claves. Proporcionaste 51 claves."
Longitud de la clave40 caracteres"La clave de metadatos \"my_very_long_key_name...\" excede el límite de 40 caracteres."
Formato de la claveSin corchetes"La clave de metadatos \"items[0]\" no puede contener corchetes ([ o ])."
Longitud del valor500 caracteres"El valor de metadatos para la clave \"description\" excede el límite de 500 caracteres."
Tipo de valorSolo cadenas"El valor de metadatos para la clave \"count\" debe ser una cadena. Se obtuvo un objeto."
Coerción de Tipo: Los números y booleanos se convierten automáticamente a cadenas.
  • 42 → "42"
  • true → "true"
  • 3.14 → "3.14"
Los objetos y arreglos son rechazados.

​
Actualización de Metadatos (PATCH)

Actualmente disponible para: Lotes solamente.Crawls, Scrapes, Maps y Answers aún no soportan la actualización de metadatos después de la creación.
Puedes actualizar los metadatos en lotes existentes usando el endpoint PATCH. Las actualizaciones utilizan un comportamiento de fusión.

​
Operaciones de Actualización

Las nuevas claves se agregan mientras se preservan las existentes.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"new_key": "new_value"}}'
Antes: {"project": "alpha"}
Después: {"project": "alpha", "new_key": "new_value"}
Las claves existentes se sobrescriben con nuevos valores.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "beta"}}'
Antes: {"project": "alpha", "priority": "high"}
Después: {"project": "beta", "priority": "high"}
Establece una clave en null o "" (cadena vacía) para eliminarla.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"priority": null}}'
Antes: {"project": "alpha", "priority": "high"}
Después: {"project": "alpha"}
Establece todo el campo de metadatos en null o "" para eliminar todas las claves.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": null}'
Antes: {"project": "alpha", "priority": "high"}
Después: {}
Agrega, actualiza y elimina claves en una sola solicitud.
curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'
Antes: {"project": "alpha", "old_field": "remove_me"}
Después: {"project": "gamma", "new_field": "value"}

​
Resumen del Comportamiento de PATCH

OperaciónSolicitudResultado
Agregar clave{"metadata": {"new": "value"}}Clave agregada, otras preservadas
Actualizar clave{"metadata": {"existing": "new_value"}}Clave actualizada, otras preservadas
Eliminar clave{"metadata": {"key": null}}Clave eliminada, otras preservadas
Eliminar clave{"metadata": {"key": ""}}Clave eliminada, otras preservadas
Borrar todo{"metadata": null}Todas las claves eliminadas
Borrar todo{"metadata": ""}Todas las claves eliminadas
Sin cambios{"metadata": {}}Sin cambios