Medien und Dateien mit nucli einer Produktvariante zuordnen

Dieser Quickstart richtet sich an Integratoren und PIM-Verantwortliche, die Bilder, Dokumente, Videos, Tabellen oder CAD-Dateien über nucli an einer Produktvariante pflegen. Nach Abschluss liegt die Datei als Storage-Objekt vor und ist über ein Product Asset mit genau einer Variante verbunden. Die öffentliche Auslieferung ist ein zusätzlicher, ausdrücklich freizugebender Schritt.

Voraussetzungen

Sie benötigen:

  • eine Anmeldung am richtigen Tenant,
  • die UUID der Produktvariante,
  • einen beschreibbaren Storage-Store und seine UUID,
  • die lokale Datei und ihren richtigen Medientyp,
  • jq, wenn Sie die IDs aus den Beispielantworten übernehmen möchten.

Prüfen Sie zuerst den aktiven Kontext und die vorhandenen Datensätze:

bash
nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> api GET /api/v1/storage/stores --save storage-stores.json
nucli --tenant <tenant> api GET /api/v1/pim/product-variants/<variant-id> --save product-variant.json

Verwenden Sie nur einen Store, für den Ihre Identität Schreibzugriff besitzt. Ein 404 Not Found kann deshalb auch bedeuten, dass der Store im aktiven Tenant nicht für Sie freigegeben ist.

1. Datei hochladen

Der Upload sendet die Datei unverändert als Request-Body. Setzen Sie den tatsächlichen Medientyp und den gewünschten Dateinamen ausdrücklich:

bash
nucli --tenant <tenant> api POST \
  /api/v1/storage/stores/<store-id>/objects \
  -H 'Content-Type: image/jpeg' \
  -H 'X-Filename: produkt-vorne.jpg' \
  --input produkt-vorne.jpg \
  --save storage-object-response.json

Lesen Sie anschließend die Objekt-ID aus der Antwort:

bash
jq -er '.data.id' storage-object-response.json

Workspace prüft unter anderem Dateiname, Größe, Medientyp, Tenant, Store-Zugriff und Speicherlimit. Das neue Storage-Objekt ist zunächst privat. Der Upload allein ordnet es noch keiner Produktvariante zu.

2. Product Asset anlegen

Erstellen Sie eine JSON-Datei, die das Storage-Objekt mit der Variante verbindet:

json
{
  "storageObjectId": "<storage-object-id>",
  "type": "image",
  "status": "draft",
  "sortOrder": 10,
  "name": {
    "de": "Vorderansicht"
  },
  "alternativeText": {
    "de": "Produkt in der Vorderansicht"
  },
  "title": {
    "de": "Vorderansicht"
  },
  "tags": ["produktbild"]
}

Speichern Sie den Inhalt als product-asset.json und legen Sie das Asset an:

bash
nucli --tenant <tenant> api POST \
  /api/v1/pim/product-variants/<variant-id>/assets \
  --input product-asset.json \
  --save product-asset-response.json
jq -er '.data.id' product-asset-response.json

type akzeptiert image, document, video, spreadsheet oder cad. Beginnen Sie mit status: draft. Die spätere Freigabe kann abhängig von der Tenant-Richtlinie eine bestätigte Herkunfts- oder KI-Deklaration verlangen.

Prüfen Sie die Zuordnung über die Varianten-ID:

bash
nucli --tenant <tenant> api GET \
  /api/v1/pim/product-variants/<variant-id>/assets \
  --save product-assets.json

Die Antwort muss das neue Product Asset mit derselben storageObjectId enthalten.

3. Medienzweck zuordnen

Ein Medienzweck beschreibt, wo ein freigegebenes Asset verwendet werden darf. Typische Schlüssel sind primary, gallery, hero, datasheet, manual, spreadsheet, cad und video. Raten Sie den Schlüssel nicht aus dem Dateinamen, sondern lesen Sie die aktiven Zwecke vom Server:

bash
nucli --tenant <tenant> api GET \
  '/api/v1/pim/product-media-purposes?q=key=primary' \
  --save media-purposes.json

Für die Zuordnung benötigt purpose-assignment.json die UUID des ausgewählten Zwecks:

json
{
  "purposeId": "<purpose-id>",
  "sortOrder": 10
}
bash
nucli --tenant <tenant> api POST \
  /api/v1/pim/assets/<product-asset-id>/purpose-assignments \
  --input purpose-assignment.json \
  --save purpose-assignment-response.json
nucli --tenant <tenant> api GET \
  /api/v1/pim/assets/<product-asset-id>/purpose-assignments \
  --save purpose-assignments.json

Die gelesene Liste muss die gewählte purposeId enthalten. Der Zweck primary bezeichnet das einfache Hauptbild für Produktkacheln und die grundlegende Produktdetail-Readiness. Zusätzliche Zwecke ersetzen primary nicht automatisch.

4. Redaktionell freigeben

Prüfen Sie vor dem Wechsel auf released, ob der Content-Provenance-Vertrag für die Master-Datei erfüllt ist:

bash
nucli --tenant <tenant> skills show pim-content-transparency
nucli --tenant <tenant> api GET \
  /api/v1/pim/content-provenance/product-assets/<product-asset-id> \
  --save product-asset-provenance.json

Bestätigen Sie die Herkunft nur mit tatsächlicher redaktioneller Freigabe. Eine Dateibezeichnung, ein Modellname oder eingebettete Metadaten ersetzen diese Bestätigung nicht. Setzen Sie das Product Asset danach über die PIM-Oberfläche oder den serverseitig beschriebenen Product-Asset-Vertrag auf released.

Interne Dokumente können privat bleiben. Führen Sie die folgenden Schritte nur aus, wenn das Asset öffentlich ausgeliefert werden soll.

5. Öffentliche Auslieferung veröffentlichen

Der Public-Media-Publish prüft das freigegebene Product Asset und seinen Medienzweck. Nur das zugehörige, tenantgebundene Storage-Objekt wird dabei öffentlich markiert und für die Auslieferung eingeplant:

bash
nucli --tenant <tenant> pim assets public-media publish \
  --variant <variant-id-or-sku> \
  --purpose <purpose-key> \
  --asset-id <product-asset-id>

Prüfen Sie anschließend den serverseitigen Status:

bash
nucli --tenant <tenant> api GET \
  '/api/v1/pim/product-assets/public-media/status?assetId=<product-asset-id>' \
  --save public-media-status.json

Die Medienproduktion läuft asynchron. Falls ein bereits öffentliches, freigegebenes Asset trotz korrekter Zweckzuordnung keine Projektion erhält, stoßen Sie gezielt einen Neuaufbau an:

bash
nucli --tenant <tenant> pim assets public-media rebuild \
  --variant <variant-id-or-sku> \
  --purpose <purpose-key> \
  --asset-id <product-asset-id>

rebuild ändert weder Sichtbarkeit noch Freigabestatus oder Zweckzuordnung. Nutzen Sie den Befehl deshalb erst, wenn diese Voraussetzungen bereits erfüllt sind.

Ergebnis prüfen

Der Ablauf ist erfolgreich, wenn:

  • das Storage-Objekt unter der erwarteten id und im gewählten Store vorhanden ist,
  • das Product Asset dieselbe storageObjectId und die richtige Varianten-ID enthält,
  • die Zweckzuordnung auf den vorgesehenen aktiven Medienzweck zeigt,
  • ein intern genutztes Asset privat bleibt oder ein öffentliches Asset den Public-Media-Publish bestanden hat,
  • die öffentliche Produktprojektion das Medium nach Abschluss der asynchronen Verarbeitung ausliefert.

Die kommerzielle Produktveröffentlichung, Lifecycle-Aktivierung, Route und Storefront-Readiness sind eigene Verträge. Ein veröffentlichtes Medium schaltet die Variante nicht automatisch für einen Verkaufskanal frei.

Nächste Schritte