-
Bartosz StarygaFront-End Solution Architect, Magnolia
Kopflose Magnolia: Die Liefer-Endpunkt-API
Wenn Sie Magnoliaals Headless Content Management kennenlernen möchten, aber nicht wissen, wo Sie anfangen sollen, sind Sie hier genau richtig. Im Rahmen unserer "Headless Magnolia"-Serie werden wir relevante Funktionen aufschlüsseln, die es Ihnen ermöglichen, Magnolia als Headless CMS zu nutzen. In diesem Artikel geht es um die Delivery Endpoint API.
Die Zustellungsendpunkt-API stellt JCR-Daten als JSON bereit. Die API ist anpassbar und flexibel einsetzbar. Sie können mehrere Endpunktkonfigurationen erstellen, lokalisierte Inhalte bereitstellen und Verweise auf Knoten in anderen Arbeitsbereichen, einschließlich Assets und Asset-Renditions, auflösen.
Endpunktdefinition in einem Lichtmodul
Zustellungsendpunkt-API-Konfigurationen befinden sich im Ordner restEndpoints oder einem seiner Unterordner.
my-light-module/ └── restEndpoints ├── delivery │ └── another-endpoint.yaml └── my-endpoint.yaml Die Eigenschaft endpointPath
Der endpointPath ermöglicht den Zugang zu einem Zustellungsendpunkt.
<magnolia-base-path>/.rest/endpointPath/{path}<magnolia-base-path>/.rest/endpointPath?query-parameters Um die Versionsnummer des Endpunkts in den Pfad des Endpunkts aufzunehmen, fügen Sie _v$number an den YAML-Dateinamen an.
YAML-Definition
Die einfachste YAML-Konfiguration für einen Zustellungsendpunkt enthält nur 2 Zeilen:
Klasse: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition Arbeitsbereich: website class definiert die Java-Klasse, die den Endpunkt behandelt.
workspace ist der Name des JCR-Arbeitsbereichs, von dem aus Inhalte geliefert werden sollen.
Sie können die Endpunktdefinition mithilfe von Parametern anpassen.
depth gibt an, wie tief der Knotenbaum durchlaufen werden soll.
includeSystemProperties gibt an, ob das Ergebnis Systemeigenschaften anzeigen soll.
limit gibt die Anzahl der Knoten im Ergebnis an.
Eine Liste aller unterstützten Konfigurationsoptionen finden Sie in unserer Dokumentation.
Using Magnolia as a headless CMS
Manage content in one hub and reuse it across the web and all your channels. See why Magnolia is great for headless—no need to sacrifice authoring experience and enterprise features.
Methoden
Knoten lesen
Diese Methode gibt einen Knoten über einen bestimmten Pfad zurück, einschließlich seiner Eigenschaften und Unterknoten bis zu einer bestimmten Tiefe. Unterknoten werden in der natürlichen Reihenfolge zurückgegeben.
<magnolia-base-path>/.rest/endpointPath/{path} 
Abfrageknoten
Diese Methode gibt eine Liste von Knoten zurück, die den Abfrageparametern entsprechen. Sie können auch Filter auf die Abfrage anwenden.
<magnolia-base-path>/.rest/endpointPath?param1=value1&=value2&... 
Ein paar nützliche Abfrageparameter sind:
orderBy bestimmt die Eigenschaften, die zur Sortierung der Knoten verwendet werden. Ab Magnolia 6.2.6 wird bei der Sortierung nicht mehr zwischen Groß- und Kleinschreibung unterschieden.
limit gibt die Anzahl der Knoten an, die in einer Seitenabfrage angezeigt werden sollen.
Sie können auch einen oder mehrere Filter als Anfrageparameter hinzufügen. Ihre Werte müssen ordnungsgemäß URL-kodiert sein. Der Filterparameter hat das folgende Format:
Eigenschaft[Operator]=Wert Zum Beispiel
.rest/my-endpoint?description[like]=%demonstration%. Eine vollständige Liste der Filteroperatoren finden Sie in unserer Dokumentation.
Lokalisierte Inhalte
Es gibt zwei Parameteroptionen, um den Inhalt einer bestimmten Sprachvariante abzufragen:
lang
- zum Beispiel
- lang=de
Accept-Language
- z. B. Accept-Language: de
Wenn beide Parameter gesetzt sind, hat der Parameter lang Vorrang. Wenn keiner der beiden Parameter gesetzt ist, wird die Ausweichsprache verwendet.
Um alle Sprachvarianten zurückzugeben, setzen Sie den Parameter lang auf lang=all.
Auflösen von Referenzen
Die Zustellungsendpunkte geben Inhalte als JSON aus dem JCR-Arbeitsbereich zurück, der durch die Eigenschaft workspace konfiguriert wurde.
Die Eigenschaft image enthält einen Asset-Bezeichner, der auf ein Asset verweist. In diesem Beispiel ist das Asset im Magnolia DAM im Dam Workspace gespeichert.
Wir könnten anschließend Inhalte aus dem DAM-Arbeitsbereich anfordern. Es ist jedoch effizienter, die Referenzen innerhalb der ersten Anfrage mit einem von Magnolias Referenzauflösern aufzulösen.
AssetReferenceResolverDefinition
Dieser Magnolia-Referenzauflöser arbeitet mit dem DAM-Arbeitsbereich. Er kann auch Links zu Asset-Wiedergaben generieren, wenn sich die referenzierten Assets im Magnolia-DAM befinden.
Um diesen Referenzauflöser hinzuzufügen, erweitern Sie die YAML-Definition des Endpunkts:
Referenzen: - Name: imageReference propertyName: image referenceResolver: Klasse: info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition name ist ein beliebiger Revolvername.
propertyName ist der Name der Eigenschaft, die Sie auflösen möchten.
referenceResolver ist der Resolver, den Sie verwenden möchten.
JcrReferenceResolverDefinition
Dieser Magnolia-Referenzauflöser arbeitet mit einem bestimmten Zielarbeitsbereich. Er löst Eigenschaften in JCR-Rohdaten auf.
references: - name: tourTypeReference propertyName: tourTypes referenceResolver: class: info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition targetWorkspace: category targetWorkspace gibt den Namen des Arbeitsbereichs an, der die referenzierten Knoten enthält.
Erste Schritte mit Zustellungsendpunkten in Magnolia
Die Erstellung eines neuen Endpunkts in Magnolia ist schnell, einfach und flexibel. Sie brauchen keine Hilfe von spezialisierten Backend-Entwicklern, um neue Endpunkte für die Bereitstellung von Daten zu erstellen. Testen Sie es selbst und erstellen Sie noch heute einen Endpunkt!
Erfahren Sie mehr über die Headless-Funktionen von Magnolia
Als nächstes werden wir folgende Themen behandeln:
Nodes Endpoint API und Commands Endpoint API
