TianGong LCA
OpenAPI

API d'import de packages TIDAS

Importer des packages TIDAS ZIP via l'API TianGong LCA avec authentification par clé API.

Ce guide explique comment importer un package TIDAS ZIP via l'API Edge Function de TianGong LCA. La base d'API recommandée est l'URL de votre Edge Function déployée avec /functions/v1 ajouté.

Cas d'usage typiques

  • Importer en masse des packages TIDAS ZIP depuis un système externe
  • Réutiliser le même flux d'import asynchrone que l'interface produit
  • Exploiter les échecs de validation structurés, les résultats de filtrage des données ouvertes et les détails de conflits utilisateur

Authentification et URL de base

L'en-tête d'authentification recommandé est :

Authorization: Bearer <USER_API_KEY>
  • USER_API_KEY peut être généré depuis la page de profil du compte TianGong LCA
  • Traitez la clé API comme un secret avec le même soin que les identifiants de compte
  • Les sessions navigateur internes peuvent toujours utiliser USER_JWT, mais les intégrations API externes devraient privilégier USER_API_KEY

Exemple d'URL de base :

https://<your-project-ref>.supabase.co/functions/v1

Si vous utilisez le service cloud TianGong LCA actuel, utilisez :

https://qgzvkongdjqiiamzbbts.supabase.co/functions/v1

Vue d'ensemble du flux

Le flux d'import complet comporte quatre étapes :

  1. Appeler POST /import_tidas_package avec action=prepare_upload
  2. Téléverser les octets du ZIP vers la cible de téléversement signée renvoyée
  3. Appeler POST /import_tidas_package avec action=enqueue
  4. Interroger GET /tidas_package_jobs/{job_id} et examiner le rapport d'import

Il est conseillé d'envoyer X-Idempotency-Key avec prepare_upload et enqueue afin que les clients puissent réessayer sans risque.

Pré-contrôle local avec tidas

Automation clients can check a package with the released Rust tidas 0.1.3 CLI before calling the API. Extract the ZIP into a temporary directory, then run:

tidas validate ./unpacked-package \
  --input-format tidas-json \
  --issues ./validation-issues.jsonl \
  --format json

Le code de sortie 0 signifie que la validation locale a réussi ; le code 2 signifie que la validation s'est terminée avec des problèmes de données. Un pipeline devrait inspecter le code de sortie, le rapport JSON et validation-issues.jsonl, et ne téléverser qu'après validation locale réussie.

Un pré-contrôle local ne crée pas de tâche d'import TianGong LCA et ne remplace ni la validation côté serveur, les vérifications de conflits, ni l'import_report final. L'exécutable tidas et l'API de la plateforme sont des frontières d'exécution distinctes.

1. Préparer le téléversement

Requête :

curl -i --location --request POST "${BASE_URL}/import_tidas_package" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${USER_API_KEY}" \
  --header 'X-Idempotency-Key: tidas-import-prepare-001' \
  --data '{
    "action": "prepare_upload",
    "filename": "example-package.zip",
    "byte_size": 123456,
    "content_type": "application/zip"
  }'

Exemple de réponse :

{
  "ok": true,
  "action": "prepare_upload",
  "job_id": "4a56e7b2-8f18-4f0f-a6b4-cf40f343d8b8",
  "source_artifact_id": "9ad0da68-3933-4f7b-a3cb-a494b70ec0a2",
  "artifact_url": "https://example.supabase.co/storage/v1/object/sign/tidas/import/example-package.zip",
  "upload": {
    "bucket": "tidas",
    "object_path": "imports/example-package.zip",
    "path": "imports/example-package.zip",
    "token": "signed-upload-token",
    "signed_url": "https://example.supabase.co/storage/v1/upload/resumable",
    "expires_in_seconds": 300,
    "filename": "example-package.zip",
    "byte_size": 123456,
    "content_type": "application/zip"
  }
}

Champs importants :

  • job_id : utilisé pour interroger la tâche asynchrone
  • source_artifact_id : requis dans l'appel enqueue ultérieur
  • upload.signed_url : l'URL de téléversement direct que les clients CLI ou HTTP génériques peuvent utiliser
  • upload.bucket + upload.path + upload.token : utiles lorsque votre client est déjà intégré au SDK Supabase Storage

2. Téléverser le fichier ZIP

Lorsque upload.signed_url est présent, l'approche recommandée, adaptée au CLI, consiste à téléverser le ZIP directement :

curl -i --request PUT "${SIGNED_URL}" \
  --header 'Content-Type: application/zip' \
  --data-binary @./example-package.zip

Ici, SIGNED_URL est la valeur upload.signed_url renvoyée par prepare_upload.

Si votre client utilise déjà le SDK Supabase Storage, vous pouvez sinon employer upload.bucket, upload.path et upload.token avec uploadToSignedUrl(...) :

const { error } = await supabase.storage
  .from(upload.bucket)
  .uploadToSignedUrl(upload.path, upload.token, file, {
    contentType: upload.content_type,
    upsert: true,
  });

3. Mise en file d'attente

Après un téléversement réussi, marquez l'artefact source comme prêt et mettez le worker d'import asynchrone en file d'attente :

curl -i --location --request POST "${BASE_URL}/import_tidas_package" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${USER_API_KEY}" \
  --header 'X-Idempotency-Key: tidas-import-enqueue-001' \
  --data '{
    "action": "enqueue",
    "job_id": "4a56e7b2-8f18-4f0f-a6b4-cf40f343d8b8",
    "source_artifact_id": "9ad0da68-3933-4f7b-a3cb-a494b70ec0a2",
    "artifact_sha256": "<optional-sha256>",
    "artifact_byte_size": 123456,
    "filename": "example-package.zip",
    "content_type": "application/zip"
  }'

Exemple de réponse :

{
  "ok": true,
  "mode": "queued",
  "job_id": "4a56e7b2-8f18-4f0f-a6b4-cf40f343d8b8",
  "source_artifact_id": "9ad0da68-3933-4f7b-a3cb-a494b70ec0a2"
}

Valeurs mode possibles :

  • queued : la tâche a été mise en file
  • in_progress : la même tâche est déjà en cours
  • completed : la même tâche s'est déjà terminée précédemment

4. Interroger l'état de la tâche

Requête d'interrogation recommandée :

curl -i --location --request GET "${BASE_URL}/tidas_package_jobs/<job-id>" \
  --header "Authorization: Bearer ${USER_API_KEY}"

L'API prend aussi en charge GET /tidas_package_jobs?job_id=<job-id> et POST /tidas_package_jobs avec job_id dans le corps de la requête.

Champs de réponse importants :

  • status : queued, running, completed, failed et états associés
  • artifacts : la liste des artefacts de la tâche
  • artifacts_by_kind.import_report : l'artefact de rapport d'import
  • artifacts_by_kind.import_report.signed_download_url : une URL temporaire pour télécharger le JSON du rapport d'import
  • artifacts_by_kind.import_report.download_status : état de téléchargement de l'artefact de rapport, tel que available, not_ready, expired, deleted, object_missing, storage_path_invalid ou signed_url_failed
  • artifacts_by_kind.import_report.download_error_code / download_error_message : motif et action recommandée lorsque signed_download_url est vide ou indisponible

Lorsque status=completed, les clients doivent généralement encore télécharger l'artefact import_report et interpréter cette charge utile comme résultat métier final. Si download_status n'est pas available, utilisez download_error_code pour décider de créer une nouvelle tâche, d'attendre l'artefact ou d'examiner le chemin de stockage / l'URL signée. Ne considérez pas status=completed seul comme une preuve que le rapport est téléchargeable.

Sémantique du rapport d'import

Une fois la tâche d'import terminée, la charge utile import_report appartient généralement à l'une de ces classes de résultats :

  • IMPORTED : import réussi
  • USER_DATA_CONFLICT : l'import a été rejeté car il entre en conflit avec des jeux de données existants appartenant à l'utilisateur
  • VALIDATION_FAILED : l'import a été bloqué par des échecs de validation du package

Cela signifie :

  • tidas_package_jobs.status=completed ne signifie pas automatiquement que des données ont été importées
  • Le résultat métier final devrait être déterminé à partir de import_report.ok et import_report.code

Exemple de succès :

{
  "ok": true,
  "code": "IMPORTED",
  "message": "TIDAS package imported successfully",
  "summary": {
    "total_entries": 42,
    "filtered_open_data_count": 3,
    "user_conflict_count": 0,
    "importable_count": 39,
    "imported_count": 39,
    "validation_issue_count": 0,
    "error_count": 0,
    "warning_count": 0
  },
  "filtered_open_data": [],
  "user_conflicts": [],
  "validation_issues": []
}

Exemple d'échec de validation

La validation s'exécute de façon asynchrone dans le worker après enqueue. En cas d'échec, l'import_report contient une liste de problèmes lisible par machine.

{
  "ok": false,
  "code": "VALIDATION_FAILED",
  "message": "TIDAS package validation failed",
  "summary": {
    "total_entries": 7,
    "filtered_open_data_count": 0,
    "user_conflict_count": 0,
    "importable_count": 0,
    "imported_count": 0,
    "validation_issue_count": 2,
    "error_count": 1,
    "warning_count": 1
  },
  "filtered_open_data": [],
  "user_conflicts": [],
  "validation_issues": [
    {
      "issue_code": "schema_error",
      "severity": "error",
      "category": "sources",
      "file_path": "sources/a.json",
      "location": "<root>",
      "message": "Schema Error at <root>: missing required field",
      "context": {
        "validator": "required"
      }
    },
    {
      "issue_code": "localized_text_language_error",
      "severity": "warning",
      "category": "processes",
      "file_path": "processes/b.json",
      "location": "processDataSet/name/baseName/0",
      "message": "Localized text error at processDataSet/name/baseName/0: invalid lang",
      "context": {}
    }
  ]
}

Recommandations pour les clients :

  • Localisez par issue_code quand c'est possible
  • Affichez aussi les message, file_path et location bruts pour le débogage
  • Utilisez summary.error_count, summary.warning_count et summary.validation_issue_count pour les résumés de haut niveau
  • Für Produktfluss-Klassifikationen prüft die Validierung @classId, @level, #text und die Elternkette gemeinsam. CPC-/ILCD-Produktklassifikationen können spezifischere Issue-Codes zurückgeben wie product_category_unknown_class_id, product_category_level_mismatch, product_category_text_mismatch oder product_category_parent_mismatch; extern benannte Klassifikationssysteme erhalten weiterhin strukturelle Validierung.

Compatibilité des champs des jeux de processus

Le worker d'import valide processes/*.json par rapport au schéma TIDAS actuel. Lors de la préparation des jeux de processus, portez une attention particulière à ces champs :

  • processDataSet.modellingAndValidation.dataSourcesTreatmentAndRepresentativeness.annualSupplyOrProductionVolume ist nun erforderlich und nutzt eine feldspezifische mehrsprachige Textform. Jeder #text-Wert sollte mit einer parsbaren Zahl beginnen und einen Einheiten- oder Kontext- Suffix behalten, etwa "123.45 kg/year" oder "1.2E3 kg/year".
  • Senden Sie annualSupplyOrProductionVolume nicht als alten schlichten numerischen String und lassen Sie den Einheiten- oder Kontext-Suffix nicht weg.
  • processDataSet.exchanges.exchange[].location sollte nach Möglichkeit einen TIDAS-/ILCD- Standortkategoriecode verwenden, etwa CN, CN-BJ, RER oder GLO. Nicht-leere Alt-Strings werden aus Kompatibilität mit externen Daten weiterhin akzeptiert.
  • exchange.location ist kein mehrsprachiger Text; senden Sie kein StringMultiLang- Objekt oder Array. Bei Produkteingabe-Austauschvorgängen dient dieses Feld zusätzlich als expliziter Versorgungsregions-Anker der nachgelagerten Anbieter-Verknüpfung.
  • Klassifikationsfelder dürfen an ihrer natürlichen Kategorietiefe enden. Fügen Sie keine leeren unteren Ebenen hinzu, nur um die Hierarchie zu füllen; gültige Ebene-0- oder Ebene-0-1-Pfade können die Validierung bestehen.
  • common:classification / common:category erzwingen weiterhin maximale Tiefe, einen Wert je Ebene und gültige Kategoriewerte. Zu tiefe Pfade, doppelte Ebenen oder ungültige Kategoriewerte liefern weiterhin schema_error oder einen Klassifikationshierarchie-Fehler.
  • Das veröffentlichte Produktfluss-Klassifikationsschema behält weiterhin den vollständigen kontrollierten Klassifikationsvertrag. Der Plattform-Validator nutzt einen internen Index zur Beschleunigung der Prüfungen von Klassenwert, Ebene, Text und Elternkette; dies erweitert nicht die beim API-Import akzeptierten Produktklassifikationen.

Pakete mit Feldformen oder -werten, die nicht zum aktuellen Schema passen, scheitern mit schema_error; der Importbericht verweist über file_path, location und message auf die Prozessdatei und das Feld.

Validation des numéros CAS

Le schéma TIDAS actuel marque les numéros CAS avec le format cas-number. Le worker d'import vérifie la forme de style 64-17-5 puis valide le chiffre de contrôle CAS final.

  • Les numéros CAS TIDAS JSON avec un mauvais chiffre de contrôle sont renvoyés comme problèmes de format.
  • Les valeurs CASNumber des XML de flux eILCD/ILCD reçoivent la même validation supplémentaire du chiffre de contrôle.
  • Si le rapport contient issue_code: "cas_number_checksum_error", la valeur ressemble à un numéro CAS mais son chiffre de contrôle ne correspond pas ; corrigez le numéro CAS source avant de réessayer.

Notes d'implémentation

  • La validation du package ne s'achève pas de façon synchrone dans le navigateur ; elle s'exécute dans le worker asynchrone
  • prepare_upload seul ne suffit pas ; téléversement, mise en file et interrogation sont tous requis
  • L'authentification par clé API et le JWT navigateur partagent le même contrat d'endpoint ; les intégrations externes devraient préférer les clés API
  • Gardez l'URL de base des Edge Functions alignée sur l'environnement déployé qui sert votre interface produit

OpenAPI

Consultez les conventions d'appel et les exemples des interfaces ouvertes de TianGong LCA.

Déploiement et développement

Obtenez les étapes du déploiement privé et le guide de l'environnement de développement.

Sur cette page

Cas d'usage typiquesAuthentification et URL de baseVue d'ensemble du fluxPré-contrôle local avec tidas1. Préparer le téléversement2. Téléverser le fichier ZIP3. Mise en file d'attente4. Interroger l'état de la tâcheSémantique du rapport d'importExemple d'échec de validationCompatibilité des champs des jeux de processusValidation des numéros CASNotes d'implémentation