Installation für Agenturen

Diese Anleitung richtet sich ausschließlich an Agenturen und technische Shop-Administratoren mit Datei-, Composer- und Konsolenzugriff. Einstellungen und tägliche Abläufe für Shop-Betreiber sind unter Bedienung für Shop-Betreiber beschrieben.

Paket passend zur OXID-Hauptversion wählen

Verwenden Sie ausschließlich das zur Shop-Hauptversion gehörende Paket:

Paketauswahl
Shop	Ausgabe	Ziel
OXID eShop 7 ab 7.1	Twig	`vendor/ecs/contentapi`
OXID eShop 6 ab 6.1	Smarty	`source/modules/ecs/ContentApi`

Warnung

Die OXID-6- und OXID-7-Pakete sind nicht austauschbar. Sichern Sie vor Installation und Update mindestens die Projekt-composer.json, die Shopdatenbank, die OXID-Konfiguration und den vorhandenen Modulordner.

Voraussetzungen

Prüfen Sie vor der Installation:

Das OXID-7-Paket verlangt PHP ab Version 8.0; maßgeblich bleiben die höheren Anforderungen der eingesetzten OXID-Version.
Der Shop muss per HTTPS erreichbar sein – die Browser-Freigabe und die API-Aufrufe setzen eine verschlüsselte Verbindung voraus.
Ein vollständiges Datenbankbackup und ein Wiederherstellungsweg wurden geprüft.
Der Webserver-PHP-Prozess benötigt Schreibrechte auf das Compile-Verzeichnis.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Twig-Paket nach:

vendor/ecs/contentapi

Prüfen Sie danach insbesondere metadata.php, composer.json, services.yaml, assets, src und views des ausgelieferten OXID-7-Pakets.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\ContentApi\\": "vendor/ecs/contentapi/src/"

Vollständiges Beispiel mit einem vorhandenen Namespace:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "vendor/vorhandener/anbieter/modul/src/",
            "Ecs\\ContentApi\\": "vendor/ecs/contentapi/src/"
        }
    }
}

Der Eintrag gehört in die Projekt-composer.json, nicht in die Datei des Moduls. Vorhandene Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require ist bei dieser manuellen Installation nicht notwendig.

3. Autoloader und Modul installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/contentapi
vendor/bin/oe-console oe:module:activate ecs_contentapi
vendor/bin/oe-console oe:cache:clear

Alternativ kann die Aktivierung nach oe:module:install im Admin unter Erweiterungen ‣ Module erfolgen.

4. OXID-7-Installation kontrollieren

Prüfen Sie mindestens:

Das Modul ist im Admin sichtbar und aktiv; die Moduleinstellungen zeigen die Bereiche „Zugang und Sicherheit“, „Schreibzugriff“ und „Bild-Uploads“.
Die API ist erreichbar und antwortet ohne Freigabe mit einer Zugriffsverweigerung.
Der Shopcache wurde geleert.

OXID 6 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Smarty-Paket nach:

source/modules/ecs/ContentApi

Prüfen Sie mindestens metadata.php, composer.json, Controller, Core, Service und views. Die Klassen des Smarty-Pakets liegen direkt im Modulordner, nicht in einem src-Unterverzeichnis.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\ContentApi\\": "./source/modules/ecs/ContentApi/"

Vollständiges Beispiel:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "./source/modules/vorhandenes/modul/",
            "Ecs\\ContentApi\\": "./source/modules/ecs/ContentApi/"
        }
    }
}

Alle vorhandenen Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require ist für die manuelle Installation nicht notwendig.

3. Autoloader und Modulkonfiguration installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/ContentApi
vendor/bin/oe-console oe:module:activate ecs_contentapi

Leeren Sie anschließend die temporären Shopdateien beziehungsweise den OXID-Cache mit dem in der jeweiligen OXID-6-Umgebung vorgesehenen Verfahren.

4. OXID-6-Installation kontrollieren

Prüfen Sie mindestens:

Modul und Moduleinstellungen sind im Admin sichtbar.
Die API ist erreichbar und verweigert nicht freigegebene Zugriffe.
Die temporären Shopdateien wurden geleert.

Datenbankänderung und Aktivierungsereignisse

Das Modul legt keine eigenen Datenbanktabellen oder -felder an. Bei der Aktivierung und Deaktivierung leert es das Compile-Verzeichnis; temporäre Freigabe-Dateien des Moduls bleiben dabei erhalten.

Modul aktualisieren

OXID 7 aktualisieren

Deaktivieren Sie das Modul für den Dateiaustausch. Ersetzen Sie den vollständigen Ordner vendor/ecs/contentapi durch das aktuelle OXID-7-/Twig-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/contentapi
vendor/bin/oe-console oe:module:activate ecs_contentapi
vendor/bin/oe-console oe:cache:clear

OXID 6 aktualisieren

Deaktivieren Sie das Modul und ersetzen Sie source/modules/ecs/ContentApi vollständig durch das aktuelle OXID-6-/Smarty-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/ContentApi
vendor/bin/oe-console oe:module:activate ecs_contentapi

Leeren Sie anschließend die temporären Shopdateien.

Nach jedem Update

Prüfen Sie die Moduleinstellungen; neue Paketvorgaben setzen vorhandene Betreiberwerte nicht automatisch zurück.
Führen Sie eine Freigabe mit einem Testzugang durch und kontrollieren Sie Lese- und Schreibzugriff.

Client-Anbindung nach dem Update prüfen

Der verkürzte Verbindungs-Prompt für Shop-Betreiber steht unter Bedienung für Shop-Betreiber. Prüfen Sie bei der Client-Anbindung auch das automatische Warten: Freigabe-Link anzeigen, nach Möglichkeit im Browser des Benutzers öffnen und dieselbe Anfrage seriell bis zum Token, zur Ablehnung oder zum Ablauf weiter abfragen. Eine Chat-Bestätigung darf dafür nicht nötig sein. Das Browseröffnen und Warten benötigt entsprechende Werkzeuge im Client.

Die Antwort von POST /content-api/auth/device enthält die Felder direkt im JSON, ohne data-Hülle. Zusätzlich zu den OAuth-Feldern liefert sie client_id, die absolute token_url, next_action und workflow. Zum Token-Abruf sendet der Client grant_type, device_code und dieselbe client_id per POST an token_url. Der Grant lautet urn:ietf:params:oauth:grant-type:device_code.

HTTP 400 mit authorization_pending oder slow_down ist ein fortsetzbarer Wartezustand. Beide Antworten enthalten terminal: false, interval, retry_after_seconds, next_action und instruction; der Header Retry-After nennt ebenfalls den Abstand. Nach slow_down bleibt das erhöhte Intervall für Folgeabfragen verbindlich. Nach access_denied oder expired_token stoppt der Client. Die ursprüngliche Frist expires_in darf beim Warten nicht bei jeder Antwort neu beginnen.

Tokens und Device-Codes müssen zwischen Client-Aufrufen geschützt erhalten bleiben und dürfen nicht in Chat, Werkzeugausgaben oder Logs erscheinen. Nach erfolgreicher Freigabe folgt der Client discovery.next_actions und verwendet den Token bis zum Ablauf oder zur Zurückweisung mit HTTP 401 weiter.

Variantenvererbung kontrollieren

Die API liest und bearbeitet die gespeicherten Eigenwerte der Variante. Erbbare Felder werden beim Anlegen weggelassen, sofern keine eigene Ausprägung gewünscht ist. Ein PATCH ohne das betreffende Feld erhält bestehende Eigenwerte. Die vier nativ synchronisierten Kontrollfelder intangible, free_shipping, is_downloadable und show_custom_agreement folgen weiterhin dem OXID-Artikelmodell.

data.long_description liefert den eigenen gespeicherten Text, keine Storefront-Vererbung. Zum Zurücksetzen einer eigenen Langbeschreibung zuerst den vollständigen Detaildatensatz lesen und anschließend senden:

{
    "long_description": "",
    "content_revision": "<data.content_revision aus dem vorherigen Detail-GET>"
}

Bei Sprachblöcken stattdessen einen leeren String in languages.de.long_description und den aktuellen Schutzwert in content_revisions.de senden. Das Zurücksetzen betrifft nur diese Sprache. Prüfen Sie danach sowohl den leeren Eigenwert in der API als auch die geerbte Beschreibung in der Storefront. Frühere Kopien werden nicht automatisch bereinigt.

Datenaufbewahrung bei Deaktivierung

Eine Deaktivierung schaltet die API vollständig ab – Zugriffe sind dann nicht mehr möglich. Die Moduleinstellungen (Freigaben, Zugangsdaten- Konfiguration) bleiben in der Shop-Konfiguration erhalten und greifen bei einer erneuten Aktivierung wieder. Es gibt keine automatische Bereinigung.