Metadatos

Actualmente disponible para Batches. El soporte para scrapes, crawls, maps y answers 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"
  }
}

import requests

response = requests.post(
    "https://api.olostep.com/v1/batches",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "items": [{"custom_id": "1", "url": "https://example.com"}],
        "metadata": {
            "project": "q4-analysis",
            "team": "data-ops",
            "priority": "high"
        }
    }
)

const response = await fetch("https://api.olostep.com/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [{ custom_id: "1", url: "https://example.com" }],
    metadata: {
      project: "q4-analysis",
      team: "data-ops",
      priority: "high"
    }
  })
});

Los metadatos se devuelven en todas las respuestas GET posteriores para ese recurso.

Reglas de Validación

Restricción	Límite	Ejemplo de Error
Máximo de claves	50	`"Los metadatos pueden tener un máximo de 50 claves. Proporcionaste 51 claves."`
Longitud de la clave	40 caracteres	`"La clave de metadatos \"my_very_long_key_name...\" excede el límite de 40 caracteres."`
Formato de la clave	Sin corchetes	`"La clave de metadatos \"items[0]\" no puede contener corchetes ([ o ])."`
Longitud del valor	500 caracteres	`"El valor de metadatos para la clave \"description\" excede el límite de 500 caracteres."`
Tipo de valor	Solo 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: Batches 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 batches existentes usando el endpoint PATCH. Las actualizaciones usan un comportamiento de fusión.

Operaciones de Actualización

Añadir nuevas claves

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"}

Actualizar claves existentes

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"}

Eliminar claves específicas

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"}

Borrar todos los metadatos

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: {}

Operaciones mixtas

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ón	Solicitud	Resultado
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
Borrar todo	`{"metadata": null}`	Todas las claves eliminadas
Borrar todo	`{"metadata": ""}`	Todas las claves eliminadas
Sin cambios	`{"metadata": {}}`	Sin cambios

Común

Raspaduras

Lotes

Rastreos

Mapas

Respuestas

Buscar

Monitores

Archivos

Horarios

Recuperar

Saldo y Facturación

Casos de Uso

Seguimiento y Organización

Filtrado y Búsqueda

Contexto de Flujo de Trabajo

Rastro de Auditoría

Añadiendo Metadatos al Crear

Reglas de Validación

Actualizando Metadatos (PATCH)

Operaciones de Actualización

Resumen del Comportamiento de PATCH

​Casos de Uso

Seguimiento y Organización

Filtrado y Búsqueda

Contexto de Flujo de Trabajo

Rastro de Auditoría

​Añadiendo Metadatos al Crear

​Reglas de Validación

​Actualizando Metadatos (PATCH)

​Operaciones de Actualización

​Resumen del Comportamiento de PATCH

Casos de Uso

Añadiendo Metadatos al Crear

Reglas de Validación

Actualizando Metadatos (PATCH)

Operaciones de Actualización

Resumen del Comportamiento de PATCH