Mit Listen arbeiten
Auf den meisten Publisher-Seiten kann Yext exklusive Listen für Ihre Einträge hinzufügen, die die Interaktion mit den Benutzern fördern. Mithilfe dieser Listen können Sie personalisierbare, strukturierte Daten für Speisekarten, Biografien, Produktlisten und Events erstellen, die im gesamten PowerListings®-Netzwerk von Yext syndiziert werden. Yext unterstützt vier Arten von Listen:
  • Speisekarten,
  • Biografie-Listen,
  • Produktlisten und
  • Event-Listen (Kalender).

Übersicht über das Datenmodell

Bevor wir uns die API näher ansehen, lassen Sie uns kurz einen Blick auf das Datenmodell der Listen werfen.

Ein Standort kann mehrere Listen einer bestimmten Art haben. Jedes Listenobjekt hat eines oder mehrere Abschnittsobjekte und jedes Abschnittsobjekt hat eines oder mehrere Elementobjekte. Event-Listen-Objekte können nur einen Abschnitt (mit name = "") enthalten.

Wenn Sie zum Beispiel eine Frühstücksspeisekarte für ein Restaurant erstellen, dann könnte diese Abschnitte wie „Müsli“, „Rühreier“ und „Getränke“ enthalten. In „Rühreier“ könnte es dann die Elemente „Rühreier mit Schinken“, „Rühreier mit Speck“ und „Rühreier mit Spinat“ geben.

Wir empfehlen nachdrücklich, Listen innerhalb des Dashboards zu erstellen, um alle Funktionen sehen zu können.

ListStructure

Die vier Listenarten unterscheiden sich hauptsächlich auf der Element-Ebene sowie in ein oder zwei Feldern auf der Listen-Ebene. Speisekarten- und Produktlistenobjekte haben zum Beispiel einen currencyCode und die entsprechenden Element-Objekte haben Preis-Felder, doch bei Biografie- und Event-Listen ist das nicht der Fall. Das Element-Objekt einer Event-Liste wiederum hat Datumsfelder (starts und ends).

Neue Liste erstellen

Jetzt wissen wir über das Listenmodell Bescheid und können eine Liste über die API erstellen. In dieser Anleitung erläutern wir Ihnen Schritt für Schritt, wie man eine Speisekarte erstellt. Wenn Sie das Erstellen von Listen üben möchten, können Sie die in den unten stehenden Anfragen die entsprechenden Endpunkte für den jeweiligen Listentyp sowie die geringfügigen Änderungen im Anfragentext angeben. Wie bereits zuvor angemerkt, empfehlen wir nachdrücklich, die gewünschte Liste zuerst im Dashboard zu erstellen und sie anschließend aufzurufen. (Beachten Sie hierzu auch den Abschnitt „Daten einer bestehenden Liste anzeigen“ in dieser Anleitung.) So müssen Sie das Datenmodell nicht vollständig neu konstruieren. Los geht’s!

Wenn Sie eine Speisekarte erstellen möchten, brauchen Sie hierfür die Anfrage Menu: Create. Im Antworttext sind die Speisekartendaten enthalten.

POSThttps://api.yext.com/v2/accounts/{accountId}/menus

{
  "id": "Frühstück01",
  "name": "Frühstück",
  "title": "Frühstücksmenü",
  "publish": true,
  "language": "en",
  "currency": "USD",
  "sections": [
    {
      "id": "FrühstückUntergruppe01",
      "name": "Pancakes",
      "description": "Lassen Sie sich unsere leckeren Pancakes schmecken.",
      "items": [
        {
          "id": "Pancake01",
          "name": "Buttermilch-Pancakes",
          "description": "Unsere köstlichen Buttermilch-Pancakes",
          "photo": {
            "url": "https://image.shutterstock.com/z/stock-photo-high-stack-of-oatmeal-pancakes-the-rustic-style-with-copy-space-shallow-dof-540640885.jpg",
            "height": 150,
            "width": 150
          },
          "calories": {
            "type": "UNVERÄNDERLICH",
            "calorie": 200
          },
          "cost": {
            "type": "PREIS",
            "price": "3,00",
            "unit": "Pro Stück"
          }
        }
      ]
    }
  ]
}
Wenn die Anfrage erfolgreich war, erhalten Sie eine 201-Antwort und im Antwortfeld steht die ID der erstellten Speisekarte:
{
  "id": "Frühstück01"
}
Versuchen Sie, eine weitere Speisekarte zu erstellen und einige der obigen Felder zu verändern bzw. hinzuzufügen.

Eine bestehende Liste aktualisieren

Jetzt haben Sie bereits einige Listen erstellt. Lassen Sie uns nun den Inhalt der ersten Frühstücksspeisekarte, die Sie erstellt haben, ändern. Um eine Speisekarte zu aktualisieren, müssen Sie die Anfrage Menu: Update ausführen. Im Antworttext dieser Anfrage stehen wieder alle Daten dieser Speisekarte. In untenstehendem Beispiel fügen wir ein weiteres Element zum Abschnitt „Rühreier“ hinzu.

PUThttps://api.yext.com/v2/accounts/{accountId}/menus/{listId}

{
  "id": "Frühstück01",
  "name": "Frühstück",
  "title": "Frühstücksmenü",
  "publish": true,
  "language": "en",
  "currency": "USD",
  "sections": [
    {
      "id": "FrühstückUntergruppe01",
      "name": "Pancakes",
      "description": "Lassen Sie sich unsere leckeren Pancakes schmecken.",
      "items": [
        {
          "id": "Pancake01",
          "name": "Buttermilch-Pancakes",
          "description": "Unsere köstlichen Buttermilch-Pancakes",
          "photo": {
            "url": "https://image.shutterstock.com/z/stock-photo-high-stack-of-oatmeal-pancakes-the-rustic-style-with-copy-space-shallow-dof-540640885.jpg",
            "height": 150,
            "width": 150
          },
          "calories": {
            "type": "UNVERÄNDERLICH",
            "calorie": 200
          },
          "cost": {
            "type": "PREIS",
            "price": "3,00",
            "unit": "Pro Stück"
          }
        },
        {
          "id": "Pancake02",
          "name": "Blaubeer-Pancakes",
          "description": "Unsere köstlichen Blaubeer-Pancakes",
          "calories": {
            "type": "UNVERÄNDERLICH",
            "calorie": 275
          },
          "cost": {
            "type": "PREIS",
            "price": "3,75",
            "unit": "Pro Stück"
          }
        }
      ]
    }
  ]
}
Sie sollten eine 200-Antwort mit folgenden Angaben im Antwortfeld erhalten:
{
  "id": "Frühstück01",
  “accountId”: accountId von URL,
  "name": "Frühstück",
  "title": "Frühstücksmenü",
  "publish": true,
  "language": "en",
  "currency": "USD",
  “size”: 2,
  "sections": [
    {
      "id": "FrühstückUntergruppe01",
      "name": "Pancakes",
      "description": "Lassen Sie sich unsere leckeren Pancakes schmecken",
      "items": [
        {
          "id": "Pancake01",
          "name": "Buttermilch-Pancakes",
          "description": "Unsere köstlichen Buttermilch-Pancakes",
          "photo": {
            "url": "https://image.shutterstock.com/z/stock-photo-high-stack-of-oatmeal-pancakes-the-rustic-style-with-copy-space-shallow-dof-540640885.jpg",
            "height": 150,
            "width": 150
          },
          "calories": {
            "type": "UNVERÄNDERLICH",
            "calorie": 200
          },
          "cost": {
            "type": "PREIS",
            "price": "3,00",
            "unit": "Pro Stück"
          }
        },
        {
          "id": "Pancake02",
          "name": "Blaubeer-Pancakes",
          "description": "Unsere köstlichen Blaubeer-Pancakes",
          "calories": {
            "type": "UNVERÄNDERLICH",
            "calorie": 275
          },
          "cost": {
            "type": "PREIS",
            "price": "3,75",
            "unit": "Pro Stück"
          }
        }
      ]
    }
  ]
}

Daten einer bestehenden Liste anzeigen

Manchmal kann es sein, dass Sie sich die Listendaten ansehen möchten, die Sie bereits in unser System eingegeben haben. Sie können sich Ihre Daten mithilfe einer GET-Anfrage für die entsprechende Listenart anzeigen lassen. Versuchen Sie, folgende Menu: GET-Anfrage auszuführen:

GEThttps://api.yext.com/v2/accounts/{accountId}/menus/{listId}

Wenn die Speisekarte vorhanden ist, erhalten Sie eine 200-Antwort mit den Daten der Speisekarte im Antworttext.

Eine Liste mit einem Standort verknüpfen

Sie haben jetzt einige Speisekarten erstellt und deren Daten geprüft, haben aber noch keine Verknüpfung zwischen den erstellten Speisekarten und einem bestehenden Standort in der Yext Knowledge Engine hergestellt. Listen können mit einem Standort verknüpft und wieder davon getrennt werden. Hierzu dient eine Location: Update-Anfrage, in der die ID im entsprechenden List-IDs-Feld des Standorts (im Falle von Speisekarten heißt dieses Feld menuIds) angegeben wird. Für die erste Speisekarte, die wir erstellt haben, würde die Anfrage z. B. so aussehen:

PUThttps://api.yext.com/v2/accounts/{accountId}/locations/{locationId}

{
  "menuIds": ["Frühstück01"]
  "menuLabel": "Restaurantmenüs"
}
Wenn die oben stehende Anfrage erfolgreich war, erhalten Sie eine 201-Antwort mit einem leeren Antworttext. Mithilfe einer Location: GET-Anfrage können Sie sich vergewissern, dass die Liste mit dem Standort verknüpft wurde. Yext wird Ihre Speisekarte mit dem PowerListings®-Netzwerk syndizieren, wenn das Feld publish der Speisekarte true ist. Wenn Sie also eine Liste hinzufügen, deren Feld publish false ist, wird die Liste nicht mit dem PowerListings®-Netzwerk syndiziert und wird nicht in Ihren Einträgen angezeigt.

Das Feld menuLabel enthält den Hyperlink-Text, der in Ihren Einträgen angezeigt wird. In unserem Beispiel wird Verbrauchern, die sich Ihren Eintrag auf einer Publisher-Seite ansehen, eine Schaltfläche angezeigt, auf der „Speisekarten des Restaurants“ steht. Wenn Sie auf die Schaltfläche klicken, werden alle veröffentlichten Speisekarten angezeigt, die mit dem Standort des Eintrags verknüpft sind.
BITTE BEACHTEN SIE: Wenn Sie mehrere Speisekarten erstellt und mit einem Standort verknüpft haben, werden sie alle unter dem gleichen menuLabel auf der Seite des Publishers angezeigt.

Wenn Sie diese Speisekarte von dem Standort entfernen möchten, können Sie eine weitere Location: Update-Anfrage durchführen. Lassen Sie diesmal aber die ID der Speisekarte in menuIds weg.

PUThttps://api.yext.com/v2/accounts/{accountId}/locations/{locationId}

{
  “menuIds”: []
}
Wie zuvor erhalten Sie bei einer erfolgreichen Anfrage eine 201-Antwort.

Nehmen Sie sich einen Augenblick Zeit, um ein paar Speisekarten zu einem Ihrer Beispielstandorte hinzuzufügen und wieder zu entfernen.

Liste löschen

Jetzt sind Sie in der Lage, Ihre eigenen Speisekarten zu erstellen, zu aktualisieren und zu Standorten hinzuzufügen – super! Wenn Sie nun eine Speisekarte komplett aus der Yext Knowledge Engine entfernen möchten, steht Ihnen hierfür die Anfrage Menu: Delete zur Verfügung:

DELETEhttps://api.yext.com/v2/accounts/{accountId}/menus/{listId}

Sie sollten bei einer erfolgreichen Anfrage eine 200-Antwort mit einem leeren Antworttext erhalten.

Damit sind wir am Ende der Listen-Anleitung angelangt. Probieren Sie zu Übungszwecken das Erstellen einiger Listen der anderen Arten aus. Die Anwendungsmöglichkeiten hier sind unglaublich vielfältig und je mehr Listen Sie hinzufügen, desto attraktiver sind Ihre Einträge!