Saltar al contenido principal
Actualmente disponible para Lotes. El soporte para scrapes, crawls, maps y answers llegará 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 pedido, IDs de cliente 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 de la tubería, 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.

​
Actualizando 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

Se añaden nuevas claves 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: {}
Añade, 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
Añadir clave{"metadata": {"new": "value"}}Clave añadida, 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
Limpiar todo{"metadata": null}Todas las claves eliminadas
Limpiar todo{"metadata": ""}Todas las claves eliminadas
Sin cambios{"metadata": {}}Sin cambios