1. Einleitung

CaaS stellt die redaktionellen Daten von FirstSpirit über ein einheitliches JSON-basiertes Datenformat beliebigen Endpunkten bereit. Die Daten werden dabei transparent bei Änderung beziehungsweise bei Freigabe im FirstSpirit Redaktionssystem aktualisiert. Bei einer Cloud-Installation der CaaS-Plattform sind die Daten damit effizient weltweit abrufbar. In FirstSpirit wird dabei ausschließlich auf die Formularkonfigurationen und die von der Redaktion gepflegten Daten zugegriffen. Das Templating in FirstSpirit entfällt völlig und wird auf das Front-End bzw. Front-End-Services verlagert (für weitere Informationen siehe FSXA-Dokumentation).

Der FirstSpirit Entwickler kann sich somit vollständig auf das Modellieren der fachlichen Objekte und das Erstellen der zugehörigen Eingabekomponenten konzentrieren. Im Folgenden werden die Konventionen zu Datenformat und URLs beschrieben, als auch die optimale Aussteuerung von Inhalten für verschiedene Konsumenten.

Content as a Service wird im Folgenden als CaaS abgekürzt.

2. Einleitung FirstSpirit-Modul

Das CaaS Connect-Modul ist das Bindeglied zwischen FirstSpirit-Redaktionsumgebung und der ausliefernden CaaS-Plattform. Diese Verbindung ist für die Redaktion weitestgehend unsichtbar und bedarf nur im Falle eines technischen Problems der Beachtung. Den aktuellen Datenbestand kann die Redaktion immer direkt über die CaaS-Plattform einsehen. Sobald eine Änderung in FirstSpirit durchgeführt wurde, wird im Hintergrund der Abgleich ausgelöst, und der Datenbestand spiegelt umgehend die Änderung wider.

In FirstSpirit gibt es klassische Projekte und Fragmenteprojekte. Fachliche Seiten - und damit auch die Elemente, die in die CaaS-Plattform übertragen werden - entsprechen in klassischen Projekten den Seitenreferenzen und in Fragmenteprojekten den Fragmenten. Der Einfachheit halber sprechen wir in beiden Fällen von Seiten. Die Unterscheidung zwischen klassischem und Fragmenteprojekt nimmt das CaaS Connect-Modul automatisch vor.

2.1. CaaS-URLs

Das Modul erzeugt für folgende FirstSpirit Elemente Dokumente in der CaaS-Plattform:

  • Seitenreferenzen

  • Medien

  • Globale Inhaltsseiten

  • Projekteinstellungsseite

  • Datensätze

Dabei wird für jede aktivierte Sprache des FirstSpirit Projekts und jeweils für den Vorschau- und Freigabestand ein Dokument für ein Element erzeugt. Jedes dieser Dokumente kann mit einer eindeutigen URL identifiziert und referenziert werden.

Sprachen gelten als aktiviert, sofern die Option Sprache generieren in der Konfiguration der Projektsprache aktiviert ist.

2.1.1. URL-Schema

Die CaaS-URL für ein Dokument setzt sich aus vier Teilen zusammen: Tenant-ID, Projektbezeichner, Collection-Bezeichner und Dokumentbezeichner. Die Tenant-ID ist der gepflegte Name oder Kürzel des Mandanten. Sie wird vom Serveradministrator im CaaS Connect Service eingepflegt. Der Projektbezeichner ist die GID des FirstSpirit-Projektes. Der Collection-Bezeichner ermöglicht die Unterscheidung von Freigabe- und Vorschaustand. Er enthält entweder den Wert release.content oder preview.content. Der Dokumentbezeichner setzt sich aus der FirstSpirit-GID des FirstSpirit-Elements und der Sprache zusammen. Gemeinsam mit der Basis-URL des CaaS-Endpunkts ergibt sich die vollqualifizierte URL eines Dokumentes.

CaaS-URLs für Projekteinstellungen verwenden als Dokumentenbezeichner nicht ihre FirstSpirit-GID, sondern den Bezeichner projectsettings.

Beispiel:

Die ID des Mandanten lautet defaultTenant.

Die FirstSpirit-Projekt-GID lautet e54cb80e-1f9c-4e8d-84b8-022f473202eb.

Die vollqualifizierte CaaS-URL einer Beispielseite mit der GID f6910b22-6ae8-4ce1-af45-c7b364b3117a in der Vorschau und für die Sprache Englisch sieht wie folgt aus:

http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

CaaS-Endpunkt: http://localhost:8080

CaaS-URL: defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.en_GB

Die von CaaS Connect erzeugten Collections enthalten lediglich Dokumente in einem Standardformat (siehe Abschnitt Datenformat). Sowohl einige Features des CaaS Connect Moduls, als auch andere Nutzer der CaaS-Plattform API erwarten Dokumente mit diesem Format in diesen Collections. Um etwaige Probleme bei den Features des CaaS Connect Moduls und bei API Nutzern zu vermeiden wird von dem Anlegen eigener Dokumente in diesen Collections abgeraten.

Der Konfigurationsdialog der Projekt-Komponente zeigt eine Übersicht aller Collection-URLs des Projektes an.

2.2. Datenformat

Anders als klassische FirstSpirit-Projekte und frühere Modulversionen unterstützt CaaS ab Version 3 keine Ausgabekanäle und somit kein FirstSpirit-Templating. Stattdessen wird für jede Seite des Projektes ein JSON-Dokument erzeugt, das auf dem toJson-Standard von FirstSpirit basiert. Eine Anpassung des Formats ist nicht möglich. Diese Einschränkung ermöglicht es über die CaaS-Plattform ein vollständiges, standardisiertes Datenformat auszuliefern, sodass alle konsumierenden Endpunkte auf einer gemeinsamen Basis entstehen können. Da das Standarddatenformat sehr umfassend ist, bietet die Plattform Filter- und Aggregationsmöglichkeiten, um beispielsweise Datenaufkommen für mobile Endpunkte zu reduzieren. Weitere Informationen zur CaaS-Plattform finden Sie in der Produktdokumentation zur Plattform.

Da die CaaS-URLs den Dokumentbezeichner unter anderem aus einer eindeutigen FirstSpirit-ID ableiten, muss die Abfrage eines Dokumentes über dessen Namen mit einer Filterabfrage an die CaaS-Plattform passieren. Um eine CaaS-Seite (eine FirstSpirit-Seitenreferenz) mit dem Namen services abzufragen wird mit folgender URL ein GET-Request ausgeführt:

http://localhost:8080/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb/preview.content?filter={'name': "services"}

Weitere Information zu Abfragen mit der CaaS-Plattform finden Sie in der Plattform-Dokumentation.

2.2.1. CaaS-JSON-Format

Das Standard-JSON-Format von FirstSpirit dient als Basis für das CaaS-JSON-Format und wird vom CaaS Connect-Modul sowohl mit CaaS spezifischer JSON-Format-Konfiguration, als auch um einige Attribute erweitert, die dessen Verwendung vereinfachen. Die CaaS spezifischen Format-Konfigurationen beinhalten die Beschränkung der Ausgabe von Datensätzen auf Referenzen, die indirekte Referenzierung von Datensätzen einer Contentprojektionen, sowie die Aktivierung der Ausgabe der FirstSpirit Metadaten.

Datensatz-URLs: FirstSpirit adressiert einzelne Datensätze nicht, sondern arbeitet mit Content-Projektionen oder -Selects und bettet Datensätze in Seiten ein. In CaaS-Projekten sind einzelne Datensätze durch eine eindeutige URL identifiziert und können damit abgefragt werden. Seiten betten Datensätze deshalb nicht ein, sondern beinhalten Referenzen auf die gespeicherten Datensätze in der CaaS-Plattform.

JSON-Ausschnitt Beispiel 
{
   "fsType" : "FS_DATASET",
   "name" : "st_button_link",
   "value" : {
      "fsType" : "DatasetReference",
      "target" : {
         "entityType" : "product",
         "fsType" : "Dataset",
         "identifier" : "fae0687b-c365-4851-919e-566f4d587201",
         "schema" : "products"
      }
   }
}

Das Attribut route wurde durch das neue routes-Array ersetzt, wird aber aus Kompatibilitätsgründen noch berechnet.

Datensatz-Routen Das Attribut routes ist ein Array, welches alle verfügbaren Content-Projektionen eines Datensatzes als separate Objekte auflistet. Ein Datensatz besitzt mehrere Routen, wenn dieser Teil mehrerer Content-Pojektionen ist und somit mehrere Vorschauseiten für diesen Datensatz verfügbar sind.

Das Attribut pageRef ist die FirstSpirit-GID der zugehörigen Seitenreferenz.

JSON-Ausschnitt Beispiel 
{
    "routes": [
          {
            "pageRef": "39332e1e-0a42-4fb9-934a-dd3efe58cbc8",
            "route": "/Unternehmen/Presse/Solaranlage-im-Old-Trafford-Stadion-eingeweiht.html"
          },
          {
            "pageRef": "78dc7762-657b-4524-ab00-debbfd5e6d62",
            "route": "/Unternehmen/Solarneuigkeiten/Solaranlage-im-Old-Trafford-Stadion-eingeweiht.html"
          }
    ]
}

Neue Datensatz-Routen werden im Vorschaufall immer von der UrlFactory erzeugt. Bereits existierende stored custom URLs werden im Vorschaufall berücksichtigt.

Seitenreferenz-Routen Das Attribut route enthält die mit der konfigurierten projektspezifischen URL Factory gerenderte URL einer Seitenreferenz.

JSON-Ausschnitt Beispiel 
{
  "fsType": "PageRef",
  "name": "news_overview",
  "route": "/Unternehmen/Presse/Presse-Übersicht.html"
}

Fragment-Metadaten: Das Attribut fragmentMetaData beinhaltet die Attribute id (Fragmente-ID) und type (Fragmente-Typ).

JSON-Ausschnitt Beispiel 
{
    "fragmentMetaData": {
        "id": "378d5ec9_58f1_4dec_83bc_724dc93de5c2",
        "type": "news"
    }
}

Locale: Das Attribut locale enthält die Attribute identifier (Abkürzung der Sprache), country (zugehöriges Land) und language (zugehörige Sprache).

JSON-Ausschnitt Beispiel 
{
    "locale": {
        "identifier": "EN",
        "country": "GB",
        "language": "en"
    }
}

Medienreferenzen: Referenzen auf Medien verweisen auf das zugehörige Dokument des Mediums. Die URLs zu den tatsächlichen Binärdaten des Mediums befinden sich innerhalb des referenzierten Dokuments.

JSON-Ausschnitt Beispiel einer Medienreferenz 
{
   "st_header_image": {
        "fsType": "FS_REFERENCE",
        "name": "st_header_image",
        "value": {
            "fsType": "Media",
            "name": "header_home",
            "identifier": "b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2",
            "uid": "header_home",
            "uidType": "MEDIASTORE_LEAF",
            "mediaType": "PICTURE",
            "url": "https://some-caas-api/some-tenant/631e4786-0dc3-4db6-bad8-adaad685944a.preview.content/b7fd2e2c-a022-44d6-ae2d-f0b9fd48f9a2.de_DE"
        }
    }
}

Content2Section: Die JSON-Daten von Contentprojektionen bzw. dessen Absätze enthalten in der Standard-JSON-Konfiguration von FirstSpirit Referenzen auf dessen Datensätze. Das CaaS Connect-Modul benutzt jedoch eine spezifische Konfiguration für das JSON-Format, sodass die Datensätze nicht direkt, sondern indirekt über ein Query-Objekt referenziert werden. Das Query-Objekt beinhaltet hierzu identifizierbare Attribute der Contentprojektion.

JSON-Ausschnitt Beispiel 
{
   "displayName" : "blog",
   "entityType" : "blog",
   "filterParams" : {},
   "fsType" : "Content2Section",
   "maxPageCount" : 0,
   "name" : "blog",
   "ordering" : [
      {
         "ascending" : false,
         "attribute" : "fs_id"
      }
   ],
   "query" : null,
   "recordCountPerPage" : 1,
   "schema" : "global",
   "template" : {
      "displayName" : "Blog entry",
      "fsType" : "TableTemplate",
      "identifier" : "e657e0f0-0fd3-456f-b5ab-560a879ca748",
      "name" : "Blog entry",
      "uid" : "global.blog",
      "uidType" : "TEMPLATESTORE_SCHEMA"
   }
}

Projekt-Mastersprache Das Projekteinstellungsdokument hat das Attribut projectConfiguration mit dem Unterattribut masterLocale, in dem die Projekt-Mastersprache enthalten ist.

JSON-Ausschnitt Beispiel 
{
  ..,
  "projectConfiguration": {
    "masterLocale": "en_GB"
  }
}

Wird die Projekt-Mastersprache verändert, wird diese Information nicht automatisch via Eventing aktualisiert. Um das Dokument zu updaten muss stattdessen entweder eine Änderung an den Projekteinstellungen gemacht werden, um das Eventing anzustoßen, oder ein Generierungsauftrag mit dem Parameter replicationmode=true gestartet werden.

2.3. Vorschau- und Freigabestand

Eine wesentliche Unterscheidung zwischen Freigabe- und Vorschaudatenständen macht sowohl FirstSpirit, als auch das CaaS Connect-Modul. Die Plattform führt beide Datenbestände, die durch unterschiedliche CaaS-URLs unterscheidbar sind (siehe URL-Schema). Ein Abgleich beider Bestände erfolgt immer auf bestimmte Aktionen, die die Redaktion in FirstSpirit vornimmt. Freigabeaktionen sind dabei die einzigen Aktionen, die eine Aktualisierung des Freigabestandes bewirken, alle anderen Änderungen haben nur Einfluss auf den Vorschaustand.

2.4. Projekt ohne "Freigabe nutzen"

Falls im FirstSpirit-Projekt die Freigabe ausgeschaltet wurde (Siehe FirstSpirit Dokumentation zu Projekteigenschaften), werden nur Vorschaudatenstände in den CaaS übertragen. Um den Freigabestand zu aktuallisieren, muss manuell der CaaS Connect Release Generation Auftrag ausgeführt werden.

2.5. Manueller Vollabgleich

Für bestimmte Szenarien kann es notwendig sein, einen Vollabgleich zwischen den Datenbeständen auszuführen:

  • Befüllung des CaaS mit vorhandenen Projektdaten zum Start eines Projekts

  • Abgleichen der Daten im Fehlerfall, um Datenkonsistenz zwischen den Systemen manuell wiederherzustellen

Dieser manuelle Vollabgleich der Datenbestände wird über Aufträge ermöglicht, die automatisch mit der Installation des CaaS Connect-Moduls angelegt werden. Dabei enthält das Projekt zwei Aufträge CaaS Connect Release Generation und CaaS Connect Preview Generation, die einen Vollabgleich für den Freigabe- oder Vorschaustand ausführen können. Die Aufträge werden bei einer Aktualisierung des CaaS Connect-Moduls aktualisiert.

schedules
Abbildung 1. Konfigurationsdialog der Projekt-Komponente des CaaS-Moduls

Änderungen an der Konfiguration dieser Aufträge sind nicht persistent, da die Aufträge durch die automatische Aktualisierung wieder auf den Ursprungszustand zurückgesetzt werden. Sind Änderungen an den Aufträgen notwendig, so können diese auf einer Kopie der Aufträge angewandt werden.

2.5.1. Überschreiben des kompletten Datenbestands

Sofern Änderungen im FirstSpirit Projekt keine Aktualisierung der Daten im CaaS auslösen, dies aber für alle Daten gewünscht ist, können die Aufträge zum Überschreiben des kompletten Datenbestands des CaaS genutzt werden. Hierzu ist es notwendig, den jeweiligen Auftrag zu kopieren und dessen Konfiguration anzupassen, sodass der Parameter replicationMode des Skript-Tasks den Wert FULL enthält (im Gegensatz zum Standardwert DELTA). Ein Ausführen dieses Auftrags überschreibt dann den kompletten Datenbestand im CaaS.

full replication
Abbildung 2. Konfigurationsdialog des Auftrags

2.5.2. Ausgeblendete Absätze

In FirstSpirit ist es möglich Absätze auszublenden. Die Daten dieser Absätze werden je nach Vorschau- oder Freigabestand unterschiedlich behandelt.

In FirstSpirit ausgeblendete Absätze sind immer Teil der Vorschaudaten, jedoch nie im Freigabestand enthalten. Die Vorschaudaten enthalten zusätzlich pro Absatz ein weiteres JSON-Attribut mit dem Namen displayed. Dieses zeigt an, ob der Absatz ein- oder ausgeblendet ist und demnach auch, ob dieser als Teil des Freigabestandes in den CaaS übertragen wird.

Demnach ergeben sich folgende Möglichkeiten für Absätze:

Sichtbarkeit Teil des Vorschaustandes Wert von displayed im Vorschaustand Teil des Freigabestandes

Eingeblendet

Ja

true

Ja

Ausgeblendet

Ja

false

Nein

Bitte beachten Sie, dass das displayed-Attribut nur im Vorschaustand vorhanden ist. Im Freigabestand sind nur eingeblendete Absätze vorhanden und daher wird dieses Attribut dort nicht verwendet.

2.6. Push-Benachrichtigungen (Change Streams)

Es ist oft gewünscht, über Änderungen in der CaaS-Plattform informiert zu werden. Hierzu bietet die CaaS-Plattform Change Streams. Dieses Feature ermöglicht es eine Websocket-Verbindung zur CaaS-Plattform aufzubauen, worüber Events zu den verschiedenen Änderungen publiziert werden.

Standardmäßig wird für jede von CaaS Connect angelegte Collection ein crud Change Stream angeboten. Dieser publiziert die sämtliche insert, replace, update und delete Events. Er ist unter <collectionUrl>/_streams/crud erreichbar. Die genaue Definition des Change Streams lässt sich jederzeit in den Metadaten der Collection abfragen.

Weitere Informationen zur Nutzung von Change Streams sind in der CaaS-Plattform Dokumentation verfügbar.

2.7. Indizes

Zur Abfrage von Dokumenten aus der CaaS-Plattform können Filter genutzt werden, in denen Kriterien für die zurückzugebenden Dokumente festgelegt sind. Um Filterabfragen auf häufig genutzte Dokument-Attribute zu beschleunigen, werden auf einigen von CaaS Connect angelegten Collections diverse Indizes erstellt. Informationen zu vorhandenen Indizes können unter <collectionUrl>/_indexes/ abgerufen werden.

Folgende Indizes werden in den Collections preview.content und release.content angelegt:

  • idx_identifier_lang_country mit der Attribut-Kombination identifier, locale.language und locale.country

  • idx_entity_lang_country mit der Attribut-Kombination entityType, locale.language und locale.country

  • idx_fstype_lang_country mit der Attribut-Kombination fsType, locale.language und locale.country

  • idx_route mit dem Dokument-Attribut route

  • idx_routes_route mit dem Dokument-Attribut routes.route

Die Reihenfolge der Index-Attribute ist relevant. Bitte stellen Sie mithilfe der Datenbank-Dokumentation sicher, dass Ihre Filterabfragen so formuliert sind, dass die Indizes auch genutzt werden.

Weitere Informationen zu Indizes sind in der CaaS-Plattform Dokumentation verfügbar.

3. Bereitstellung der Medienbinärdaten

Das CaaS Connect-Modul unterstützt verschiedene Optionen, um die Binärdaten von Medien bereitzustellen.

  • Übertragung der Binärdaten in einen S3-Bucket und Bereitstellung über eine CloudFront-Distribution (CloudFront CDN).

    • Dies ist der Standard in der Crownpeak-Cloud.

  • Übertragung der Binärdaten in einen S3-Bucket und Bereitstellung über eine S3 REST API.

  • Übertragung der Binärdaten in File Buckets des CaaS und Bereitstellung über die CaaS REST API.

    • Dies ist der Standard, wenn keine S3 Konfiguration existiert.

Die Optionen haben unterschiedliche Verwendungen und werden deshalb im Folgenden einzeln erläutert.

Die Anzahl der Mediendateien, die in das Zielsystem übertragen werden, ist jedoch bei allen Bereitstellungsoptionen identisch. Für sprachunabhängige Medien wird genau eine Binärdatei übertragen. Für sprachabhängige Medien wird für jede aktivierte Sprache eine Binärdatei übertragen. Außerdem werden für Bilder die Binärdaten jeder Auflösung übertragen, falls kein CaaS-Tag gepflegt worden ist (Siehe Exklusion bestimmter Auflösungen).

Sprachen gelten als aktiviert, sofern die Option Sprache generieren in der Konfiguration der Projektsprache aktiviert ist.

3.1. Übertragung in S3-Bucket

Diese Option beinhaltet das Übertragen der Mediendateien in einen S3-Bucket. Dabei werden die Binärdateien innerhalb des Buckets unter dem konfigurierten Pfad-Präfix abgelegt (Standard ist Präfix /). Anschließend folgt dem Pfad die GID des Projekts und das Pfad-Segment /preview, abhängig davon, ob sich das Medium im Freigabe- oder Vorschaustand befindet. Der restliche Pfad und der Dateiname einer Mediendatei ergeben sich aus der Advanced URL des Mediums.

Beispiel eines S3-Pfades: /631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png

Bei der Verwendung eines S3-Buckets können die Mediendateien entweder über eine CloudFront-Distribution oder direkt über den zugehörigen Endpunkt der S3 REST API bereitgestellt werden. Die folgenden Kapitel beschreiben diese zwei Bereitstellungsmöglichkeiten.

3.1.1. Bereitstellung über CloudFront-Distribution

Bei der Bereitstellung über eine CloudFront-Distribution setzt sich die URL zu einer Mediendatei aus der Domain der CloudFront-Distribution und dem oben beschriebenen Pfad des S3-Objekts zusammen.

Die folgende URL zeigt beispielsweise auf die Originalauflösung eines Bilds des Vorschaustands, welches über eine CloudFront-Distribution erreichbar ist, die für Domain my-cloudfront-domain.tld den S3-Bucket nutzt.

https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png

Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments inklusive der URLs, die auf die Binärdaten der einzelnen Auflösungen des Bilds verweisen.

Wird in den Projekteinstellungen das CaaS-Tag in den Auflösungen gesetzt, werden auch nur diese im resolutionsMetaData-Objekt aufgeführt.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    "displayName": "thisisatest",
    "identifier": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61",
    "uid": "thisisatest",
    "uidType": "MEDIASTORE_LEAF",
    "fileName": "thisisatest",
    "languageDependent": false,
    "mediaType": "PICTURE",
    "description": null,
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png"
        },
        "Teaser": {
            "fileSize": 1192,
            "extension": "png",
            "mimeType": "image/png",
            "width": 111,
            "height": 65,
            "url": "https://my-cloudfront-domain.tld/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest_Teaser.png"
        }
    },
    "metaFormData": {},
    "changeInfo": {
        "date": "2021-05-10T10:41Z",
        "revision": 21077
    },
    "locale": {
        "identifier": "EN",
        "country": "US",
        "language": "en"
    },
    "_etag": {
        "$oid": "60990def3542845893b034da"
    }
}

Neue Mediendatei-URLs werden im Vorschaufall immer von der UrlFactory erzeugt. Bereits vorhandene stored custom URLs werden daher nicht im Vorschaufall berücksichtigt!

CloudFront Caching

Bei Änderungen an den Binärdaten von Medien werden dessen Dateien nicht instantan in dem Cache der CloudFront-Distribution invalidiert. Stattdessen findet eine automatische Aktualisierung nach maximal 15 Minuten statt, sofern die CloudFront-Distribution so konfiguriert ist, dass der Cache-Control Header aus den HTTP Antworten eines Origins berücksichtigt wird. In der Crownpeak-Cloud ist dies standardmäßig aktiv.

Genauere Informationen zu dem Cache-Control Header sind dem Abschnitt S3-Objekt-Metadaten zu entnehmen.

3.1.2. Bereitstellung über S3 REST API

Bei der Bereitstellung über die S3 REST API setzt sich die URL zu einer Mediendatei aus (dem virtuell gehosteten Endpunkt des Buckets) der S3 REST API und dem oben beschriebenen Pfad des S3-Objekts zusammen.

Die folgende URL zeigt beispielsweise auf die Originalauflösung eines Bilds des Vorschaustands im S3-Bucket my-bucket, der sich in der Region eu-central-1 befindet.

https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png

Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments inklusive der URLs, die auf die Mediendaten der einzelnen Auflösungen des Bildes verweisen.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png"
        },
        "Teaser": {
            ...
            "url": "https://my-bucket.s3.eu-central-1.amazonaws.com/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest_Teaser.png"
        }
    },
    ...
}

3.1.3. S3-Objekt-Metadaten

Beim Upload der Mediendateien in den S3-Bucket werden unterschiedliche Metadaten-Attribute für das S3-Objekt gesetzt:

  • Content-Type

    • Dieses Attribut wird für den Response Header Content-Type für Requests an das S3-Objekt genutzt.

    • Es beinhaltet den MIME-Type der Mediendatei (z.B. image/png).

  • Cache-Control

    • Dieses Attribut wird für den Response Header Cache-Control für Requests an das S3-Objekt genutzt.

    • Für den Freigabestand beinhaltet es im Standard den Wert public, max-age=300, s-maxage=900.

    • Für den Vorschaustand beinhaltet es den Wert private, no-cache.

3.2. Übertragung in CaaS File Bucket und Bereitstellung über CaaS REST API

In diesem Modus werden die Binärdaten von Medien in den CaaS übertragen. Dabei werden die Binärdateien der Medien in das CaaS File Bucket

  • [Projekt-GID].release.files oder

  • [Projekt-GID].preview.files

übertragen, abhängig davon, ob diese sich im Freigabe- oder Vorschaustand befinden. Die File Buckets befinden sich dabei in der Datenbank, die der Tenant-ID entspricht. Der restliche Pfad und der Dateiname einer Mediendatei ergibt aus der FirstSpirit-GID des Mediums, sowie Sprache und/oder Auflösung (sofern das Medium abhängig von Sprache und/oder Auflösung ist).

Die Bereitstellung der Mediendaten erfolgt über die CaaS REST API. Die URL zu einer Mediendatei setzt sich aus der Basis-URL der CaaS REST API, dem (oben beschriebenen) Pfad und dem Suffix /binary zusammen.

Der folgende Codeausschnitt zeigt beispielhaft den Inhalt eines Mediendokuments inklusive der URLs, die auf die Mediendaten der einzelnen Auflösungen des Bilds verweisen.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    "name": "thisisatest",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-caas-url.tld/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.ORIGINAL/binary"
        },
        "Teaser": {
            ...
            "url": "https://my-caas-url.tld/defaultTenant/e54cb80e-1f9c-4e8d-84b8-022f473202eb.preview.files/f6910b22-6ae8-4ce1-af45-c7b364b3117a.Teaser/binary"
        }
    },
    ...
}

3.3. Steuerung der zu übertragenden Auflösungen mittels CaaS-Tag

Durch die optionale Vergabe des CaaS-Tags lässt sich steuern, welche Auflösungen bei einer Generierung in einen File Bucket bzw. S3-Bucket übertragen werden.

add resolution tag
Abbildung 3. Konfigurationsdialog eines neuen Tags

Im folgenden Beispiel werden somit nur drei Auflösungen in den CaaS übertragen.

resolution list
Abbildung 4. Auflistung der Projektauflösungen

Falls kein CaaS-Tag im ServerManager für das jeweilige Projekt konfiguriert ist, werden standardmäßig für alle im Projekt vorhandenen Auflösungen entsprechende Binärdaten übertragen.

Mehr Informationen über das Taggen von Auflösungen können der FirstSpirit-Dokumentation für Administratoren entnommen werden.

Bitte beachten Sie, dass übertragene Binärdaten durch Änderungen an dem CaaS-Tag nicht aus dem CaaS entfernt werden.

Bei einer Änderung der CaaS-Tags werden die CaaS-Daten nicht automatisch aktualisiert; Eine Synchronisierung muss manuell durchgeführt werden.

3.4. URL Anpassungen (CaaS Connect SaaS)

In dem CaaS Connect SaaS Angebot werden Mediendateien durch eine CloudFront Domain (*-media.e-spirit.cloud) in einem standardisierten Format (siehe Bereitstellung über CloudFront-Distribution) bereitgestellt. Wenn dieses Format der URLs nicht gewünscht ist, können die API Consumer des CaaS URLs im gewünschten Format erzeugen und weiterverarbeiten. Zusätzlich muss eine serverseitige Komponente die Um- bzw. Weiterleitung der Requests übernehmen. In dem folgenden Abschnitt wird das Erzeugen eigener URLs Schritt für Schritt anhand von Beispielen erklärt.

API Consumer

API Consumer, die Daten von der CaaS API auslesen und weiterverarbeiten, können das Attribut seoRoute aus CaaS Mediendokumenten nutzen, um die gewünschte URL zusammenzustellen.

Beispiel: JSON-Inhalt eines Mediendokuments aus dem Vorschaustand 
{
    "_id": "3b3fe5b6-9ec1-4e45-84c8-bc6a39d0aa61.en_US",
    "fsType": "Media",
    ...
    "resolutionsMetaData": {
        "ORIGINAL": {
            "fileSize": 16358,
            "extension": "png",
            "mimeType": "image/png",
            "width": 578,
            "height": 340,
            "url": "https://my-customer-name-media.e-spirit.cloud/631e4786-0dc3-4db6-bad8-adaad685944a/preview/FirstSpirit/Bilder/thisisatest.png",
            "seoRoute": "/FirstSpirit/Bilder/thisisatest.png"
        },
        ...
    },
    ...
}

Dieser Pfad kann einer gewünschten Domain (und ggf. Pfad-Präfix) angehangen werden. Im folgenden Beispiel wird der Pfad ohne Präfix an die gewünschte Domain angehangen:

https://de-de.my-custom-domain.tld + /FirstSpirit/Bilder/thisisatest.png

Server

Damit diese URLs aufrufbar sind, kann eine Serverkomponente genutzt werden, die entweder Umleitungen z.B. per Reverse Proxying oder Weiterleitungen per URL Redirect anwendet.

In dem folgenden Konfigurationsbeispiel wird ein NGINX Server genutzt und konfiguriert, sodass Requests auf Basis des angefragten Hostnames umgeleitet werden (Name-based virtual hosting und URL Rewrite). Dabei werden alle eingehenden Requests für den Hostname de-de.my-custom-domain.tld auf die Vorschaudaten eines FirstSpirit Projekts mit der UUID 631e4786-0dc3-4db6-bad8-adaad685944a umgeleitet (was dem Pfad /631e4786-0dc3-4db6-bad8-adaad685944a/preview entspricht).

Beispiel: Teilinhalt einer NGINX Konfiguration de-de.my-custom-domain.tld.conf 
server {
    listen              443 ssl http2;
    listen              [::]:443 ssl http2;
    server_name         de-de.my-custom-domain.tld;

    # SSL
    ssl_certificate     /etc/nginx/ssl/de-de.my-custom-domain.tld.crt;
    ssl_certificate_key /etc/nginx/ssl/de-de.my-custom-domain.tld.key;

    # security
    include             nginxconfig.io/security.conf;

    location / {
        proxy_pass https://my-customer-name-media.e-spirit.cloud/631e4786-0dc3-4db6-bad8-adaad685944a/preview/;
        include    nginxconfig.io/proxy.conf;
    }

    # additional config
    include nginxconfig.io/general.conf;
}

# HTTP redirect
server {
    listen      80;
    listen      [::]:80;
    server_name .de-de.my-custom-domain.tld;
    return      301 https://de-de.my-custom-domain.tld$request_uri;
}

Dieses Beispiel ist NICHT VOLLSTÄNDIG und dient lediglich zur Erläuterung des Name-based virtual hostings mit URL Rewrite. Zusätzliche NGINX Konfigurationen (z.B. Security Header, Proxykonfigurationen, …​), dessen Nutzung für den Produktionsbetrieb empfohlen ist, sind NICHT in diesem Beispiel vorhanden.

Dieses Beispiel nutzt einen NGINX als Reverse Proxy zur Umleitung der Requests. Dabei ist zu beachten, dass die Vorteile wie Caching und Edge Locations des Crownpeak Technology GmbH CloudFront CDNs nur genutzt werden können, wenn der NGINX Server in einem Edge-Computing Netzwerk betrieben wird. Alternativ sollte der Server so nah wie möglich zu der CloudFront Edge Location betrieben werden, die für den Usertraffic in Frage kommt.

Zusätzlich muss beachtet werden, dass sogar bei der Verwendung einer Edge-Computing Lösung die genannten Vorteile des CloudFront CDNs nicht vollständig genutzt werden, sofern sich die Lösung in einem anderen CDN Netzwerk befindet. Wenn diese Einschränkungen umgangen werden sollen, muss eine Lösung im CloudFront CDN gewählt werden (z.B. CloudFront Distribution oder Lambda@Edge).

4. Fehlerbehandlung: Bekannte Fehler

4.1. Fehler im Vollabgleich-Auftrag beim Übertragen der Dokumente der Projekteinstellungsseite

Der Fehler ReferenceNotFoundException: No template defined for project properties kann während eines Vollabgleich-Auftrags auftauchen, sofern im Projekt keine Vorlage als Projekteinstellungsseite ausgewählt ist.

Dieser Fehler ist ab FirstSpirit Version 2023-04 behoben und kann somit durch ein Update des FirstSpirit Servers oder das Setzen einer Vorlage als Projekteinstellungsseite gelöst werden.

5. Rechtliche Hinweise

CaaS ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.

Für die Verwendung des Produkts gilt gegenüber dem Anwender nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

6. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.