Métadonnées

Actuellement disponible pour les Lots. Le support pour les extractions, explorations, cartes et réponses arrive bientôt.

Les métadonnées vous permettent d’attacher des paires clé-valeur personnalisées aux ressources Olostep. Cela est utile pour le suivi, le filtrage, l’organisation et le stockage de contexte avec vos requêtes API. Les métadonnées suivent l’approche de Stripe — simple, flexible et cohérente sur tous les points de terminaison.

Cas d’utilisation

Suivi & Organisation

Liez les ressources à des systèmes internes avec des identifiants de commande, des identifiants de client ou des noms de projet.

Filtrage & Recherche

Étiquetez les ressources pour un accès et un filtrage faciles dans votre application.

Contexte de Flux de Travail

Stockez l’étape de pipeline, le niveau de priorité ou les instructions de traitement.

Piste d'Audit

Enregistrez qui a initié une requête, les horodatages ou les informations de version.

Ajout de Métadonnées lors de la Création

Incluez le paramètre metadata lors de la création d’une ressource :

{
  "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"
    }
  })
});

Les métadonnées sont renvoyées dans toutes les réponses GET ultérieures pour cette ressource.

Règles de Validation

Contrainte	Limite	Exemple d’erreur
Clés maximum	50	`"Les métadonnées peuvent avoir un maximum de 50 clés. Vous avez fourni 51 clés."`
Longueur de la clé	40 caractères	`"La clé de métadonnée \"my_very_long_key_name...\" dépasse la limite de 40 caractères."`
Format de la clé	Pas de crochets	`"La clé de métadonnée \"items[0]\" ne peut pas contenir de crochets ([ ou ])."`
Longueur de la valeur	500 caractères	`"La valeur de métadonnée pour la clé \"description\" dépasse la limite de 500 caractères."`
Type de valeur	Uniquement des chaînes	`"La valeur de métadonnée pour la clé \"count\" doit être une chaîne. Objet reçu."`

Conversion de Type : Les nombres et les booléens sont automatiquement convertis en chaînes.

42 → "42"
true → "true"
3.14 → "3.14"

Les objets et les tableaux sont rejetés.

Mise à Jour des Métadonnées (PATCH)

Actuellement disponible pour : uniquement les Lots.Les explorations, extractions, cartes et réponses ne supportent pas encore la mise à jour des métadonnées après création.

Vous pouvez mettre à jour les métadonnées sur des lots existants en utilisant le point de terminaison PATCH. Les mises à jour utilisent un comportement de fusion.

Opérations de Mise à Jour

Ajouter de nouvelles clés

De nouvelles clés sont ajoutées tout en préservant les existantes.

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

Avant : {"project": "alpha"}
Après : {"project": "alpha", "new_key": "new_value"}

Mettre à jour les clés existantes

Les clés existantes sont écrasées avec de nouvelles valeurs.

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

Avant : {"project": "alpha", "priority": "high"}
Après : {"project": "beta", "priority": "high"}

Supprimer des clés spécifiques

Attribuez à une clé la valeur null ou "" (chaîne vide) pour la supprimer.

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

Avant : {"project": "alpha", "priority": "high"}
Après : {"project": "alpha"}

Effacer toutes les métadonnées

Attribuez au champ entier des métadonnées la valeur null ou "" pour supprimer toutes les clés.

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": null}'

Avant : {"project": "alpha", "priority": "high"}
Après : {}

Opérations mixtes

Ajoutez, mettez à jour et supprimez des clés dans une seule requête.

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

Avant : {"project": "alpha", "old_field": "remove_me"}
Après : {"project": "gamma", "new_field": "value"}

Résumé du Comportement PATCH

Opération	Requête	Résultat
Ajouter une clé	`{"metadata": {"new": "value"}}`	Clé ajoutée, autres préservées
Mettre à jour une clé	`{"metadata": {"existing": "new_value"}}`	Clé mise à jour, autres préservées
Supprimer une clé	`{"metadata": {"key": null}}`	Clé supprimée, autres préservées
Supprimer une clé	`{"metadata": {"key": ""}}`	Clé supprimée, autres préservées
Effacer tout	`{"metadata": null}`	Toutes les clés supprimées
Effacer tout	`{"metadata": ""}`	Toutes les clés supprimées
Pas de changement	`{"metadata": {}}`	Aucun changement

Commun

Grattages

Lots

Explorations

Cartes

Réponses

Rechercher

Moniteurs

Fichiers

Horaires

Récupérer

Solde et Facturation

Cas d’utilisation

Suivi & Organisation

Filtrage & Recherche

Contexte de Flux de Travail

Piste d'Audit

Ajout de Métadonnées lors de la Création

Règles de Validation

Mise à Jour des Métadonnées (PATCH)

Opérations de Mise à Jour

Résumé du Comportement PATCH

​Cas d’utilisation

Suivi & Organisation

Filtrage & Recherche

Contexte de Flux de Travail

Piste d'Audit

​Ajout de Métadonnées lors de la Création

​Règles de Validation

​Mise à Jour des Métadonnées (PATCH)

​Opérations de Mise à Jour

​Résumé du Comportement PATCH

Cas d’utilisation

Ajout de Métadonnées lors de la Création

Règles de Validation

Mise à Jour des Métadonnées (PATCH)

Opérations de Mise à Jour

Résumé du Comportement PATCH