How do you manage 301 redirects using the BigCommerce Redirect API?

This entry was posted in BigCommerce and tagged on by .

Jede Shop-Migration, URL-Umstrukturierung oder Umbenennung von Kategorien führt letztendlich dazu, dass irgendwo eine Menge toter Links entsteht. Alte Produktseiten, die früher bei Google rankten, verschobene Blogbeiträge, Kategoriepfade, die während der Migration vereinfacht wurden. Eine Handvoll davon manuell im Control Panel zu bearbeiten, ist kein Problem. Tausende davon nach einer vollständigen Umstrukturierung der Website einzeln zu bearbeiten, ist jedoch eine Aufgabe, die niemand gerne übernehmen möchte. Genau hier spielt die Bigcommerce Redirects API ihre Stärken aus.

Die gute Nachricht dabei – und das sollte man gleich zu Beginn erwähnen, da es im Gegensatz zum Verhalten der Catalog-API steht – ist, dass BigCommerce tatsächlich einen echten Batch-Endpunkt für Weiterleitungen bereitstellt. Man ist nicht darauf angewiesen, diese wie bei Produkten einzeln per Anfrage zu erstellen. Es gibt jedoch noch ein paar Fallstricke, die man kennen sollte, bevor man ein Skript auf einen Live-Shop anwendet.

Verzichten Sie auf die alte Redirects-API, wenn Sie ganz von vorne anfangen.

Wenn Sie nach Beispielen für BigCommerce-Weiterleitungen suchen, werden Sie auf viel älteren Code stoßen, der POST /v2/redirects mit nur einem Pfad und einem „forward“-Feld verwendet. Dieser Endpunkt funktioniert technisch gesehen zwar noch, ist aber veraltet. Er erstellt pro Aufruf eine Weiterleitung und unterstützt die Multi-Storefront-Konfiguration von BigCommerce überhaupt nicht. BigCommerce drängt schon seit einiger Zeit darauf, auf die Version v3 der Management-API umzusteigen, und genau diese Version lohnt es sich zu nutzen: PUT /v3/storefront/redirects, auch als „Upsert Redirects“ bezeichnet.

Ja, es handelt sich um einen PUT-Aufruf, nicht um einen POST-Aufruf, auch wenn man damit oft völlig neue Weiterleitungen erstellt. Das verwirrt viele beim ersten Lesen der Dokumentation. Der Grund dafür ist das „Upsert“-Verhalten selbst, das sich als wirklich nützlich erweist, sobald man verstanden hat, wie es funktioniert.

Das „Upsert“-Verhalten ist der springende Punkt

So sieht die Anfrage aus:

[
  {
    "from_path": "/old-product-page/",
    "site_id": 1,
    "to": {
      "type": "product",
      "entity_id": 482
    }
  }
]

„from_path“ und „site_id“ sind Pflichtangaben. „to“ ist technisch gesehen optional, sollte aber fast immer angegeben werden. Andernfalls kann die Weiterleitung den Traffic nirgendwohin leiten. Das Feld „type“ bei „to“ kann auf ein Produkt, eine Kategorie, eine Seite, einen Blogbeitrag, eine Marke oder einfach eine reine externe oder interne URL verweisen, wenn Sie keine bestimmte Katalogentität ansprechen.

Da es sich hierbei um einen „Upsert“ und nicht um eine einfache Erstellung handelt, führt die zweimalige Ausführung derselben Payload nicht zu einem Duplikatfehler, wie es beispielsweise beim Anlegen eines Produkts mit einer bereits vorhandenen SKU der Fall wäre. Wenn für diese Kombination aus „from_path“ und „site_id“ bereits eine Weiterleitung existiert, aktualisiert BigCommerce diese einfach. Falls keine vorhanden ist, wird eine neue erstellt. Dieses eine Detail macht die gesamte Angelegenheit wesentlich benutzerfreundlicher für die Erstellung eines Skripts. Sie können einen Import nach einem teilweisen Fehlschlag erneut ausführen, ohne zuvor herausfinden zu müssen, welche Weiterleitungen bereits übernommen wurden.

Warum Ihre Weiterleitung zwar vorhanden ist, aber dennoch nicht funktioniert

Dieses Thema verdient einen eigenen Abschnitt, da es zu einer übermäßigen Anzahl von Support-Anfragen mit der Frage „Warum funktioniert meine Weiterleitung nicht?“ führt. Wenn Ihr Shop mehrere Storefronts betreibt – also mehrere Kanäle, die auf denselben Backend-Katalog verweisen –, hat jede davon ihre eigene site_id, und eine für Site 1 erstellte Weiterleitung hat keine Auswirkung auf einen Kunden, der auf der Domain von Site 2 landet.

Wenn Sie nur eine einzige Storefront haben, ist dies kein Problem: Ihre Site-ID entspricht einfach dem Standardwert, und jede Weiterleitung verwendet diese. Wenn Sie jedoch Weiterleitungen für eine Konfiguration mit mehreren Storefronts oder eine Headless-Lösung mit mehreren angeschlossenen Kanälen verwalten, müssen Sie zunächst die Liste der Sites abrufen (GET /v3/sites) und sicherstellen, dass Sie jede Weiterleitung mit der richtigen Site-ID versehen. Das Überspringen dieses Schritts ist wahrscheinlich der häufigste Grund dafür, dass eine „korrekt erstellte“ Weiterleitung für echte Besucher tatsächlich keine Weiterleitung bewirkt.

Wie groß darf ein Batch sein?

Im Gegensatz zur Katalog-API, bei der eine Obergrenze von 10 Einträgen pro Aufruf für Produkt-Batch-Aktualisierungen ausdrücklich dokumentiert ist, veröffentlicht BigCommerce keine konkrete Zahl dafür, wie viele Redirect-Objekte Sie in einem einzigen „Upsert Redirects“-Aufruf senden können. In der Praxis bedeutet dies, dass Sie dies in einem Sandbox-Shop testen sollten, anstatt von einer bestimmten Zahl auszugehen. Das Senden von einigen hundert Objekten auf einmal hat im Allgemeinen gut funktioniert, aber es gibt keine veröffentlichte Garantie. Daher ist es die sicherere Vorgehensweise, Ihr Skript so zu gestalten, dass es das Array in Blöcke aufteilt und eine abgelehnte Charge elegant verarbeitet – unabhängig davon, wo die tatsächliche Obergrenze liegt.

Darüber hinaus gelten weiterhin die üblichen Regeln zur Ratenbegrenzung. Es gilt dieselbe Quote von 150 Anfragen pro 30 Sekunden (Standard/Plus) bzw. 450 pro 30 Sekunden (Pro) wie bei jedem anderen Management-API-Aufruf, und diese wird mit allen anderen Zugriffe geteilt, die gleichzeitig auf den Shop erfolgen. Die Aufteilung in angemessene Batch-Größen erfüllt hier einen doppelten Zweck: Sie sorgt dafür, dass Sie unterhalb der möglicherweise bestehenden, undokumentierten Payload-Obergrenze bleiben, und hält die Anzahl Ihrer Anfragen im Rahmen der Ratenbegrenzung.

So strukturieren Sie den Import

Hier ist nichts Aufwendiges erforderlich, lediglich ein Skript, das sich an die Struktur der API hält. Lesen Sie Ihr Quell-Mapping ein, normalisieren Sie jeden „from_path“ so, dass er mit einem „/“ beginnt und der abschließende Schrägstrich den Vorgaben von BigCommerce entspricht, bauen Sie jede Zeile in die Struktur des Redirect-Objekts ein und führen Sie anschließend eine Stapelverarbeitung und den Push durch:

import axios from "axios";

const client = axios.create({
  baseURL: `https://api.bigcommerce.com/stores/${process.env.STORE_HASH}/v3`,
  headers: {
    "X-Auth-Token": process.env.BC_ACCESS_TOKEN,
    "Content-Type": "application/json",
  },
});

const SITE_ID = 1;
const BATCH_SIZE = 200;

async function runImport(rows) {
  const failures = [];

  for (let i = 0; i < rows.length; i += BATCH_SIZE) {
    const batch = rows.slice(i, i + BATCH_SIZE).map(row => ({
      from_path: row.old_path.startsWith("/") ? row.old_path : `/${row.old_path}`,
      site_id: SITE_ID,
      to: { type: "url", url: row.new_path },
    }));

    try {
      await client.put("/storefront/redirects", batch);
    } catch (err) {
      failures.push(...batch);
      console.error(err.response?.data || err.message);
    }

    await new Promise(r => setTimeout(r, 500));
  }

  return failures;
}

„Upsert Redirects“ ist ein Upsert und kein reines „Create“, daher musst du nicht prüfen, ob bereits eine Weiterleitung existiert. Bei einer erneuten Ausführung wird die vorhandene einfach überschrieben. Das macht die Fehlerbehandlung so einfach. Wenn bei einem Batch ein Fehler auftritt, speicherst du ihn einfach ab und versuchst es später erneut.

Achten Sie auf führende und abschließende Schrägstriche

„from_path“ muss mit einem „/“ beginnen, und BigCommerce ist sehr streng, was abschließende Schrägstriche angeht, die nicht immer der URL-Struktur Ihrer alten Plattform entsprechen. Wenn Sie von Shopify oder WordPress migrieren, enthalten Ihre Quell-URLs möglicherweise abschließende Schrägstriche an Stellen, an denen BigCommerce diese nicht erwartet, oder umgekehrt. Es lohnt sich, jeden Pfad in Ihrem Skript zu normalisieren, anstatt sich auf den Inhalt Ihrer Exportdatei zu verlassen, da ein nicht übereinstimmender abschließender Schrägstrich dazu führt, dass die Weiterleitung für diese URL einfach stillschweigend nicht ausgelöst wird.

Alte Weiterleitungen bereinigen

Die gleiche v3-Ressource unterstützt auch das Löschen von Weiterleitungen im Massenverfahren: DELETE /v3/storefront/redirects?id:in=101,102,103. Dies ist nach einer Migration sehr praktisch. Sobald Sie sich vergewissert haben, dass die neuen Weiterleitungen funktionieren, können Sie eine Reihe veralteter Weiterleitungen aus einem früheren Import löschen, die nicht mehr korrekt sind. Es empfiehlt sich, zuvor einen GET-Aufruf an /v3/storefront/redirects zu senden, um sicherzustellen, dass Sie tatsächlich die beabsichtigten IDs löschen, da der Vorgang nach dem Löschen nicht rückgängig gemacht werden kann.

Wo setzt man das eigentlich ein?

Der naheliegendste Anwendungsfall ist eine Plattformmigration, bei der jede alte URL ihrem neuen Äquivalent zugeordnet wird, damit der über Jahre hinweg aufgebaute SEO-Wert nicht verloren geht. Aber auch außerhalb von Migrationen gibt es zahlreiche Anwendungsfälle. Beispiele hierfür sind: Umstrukturierungen von Kategorien, Änderungen an Produkt-URL-Slugs aus SEO-Gründen, die jährliche Umbenennung saisonaler Kollektionen oder die Bereinigung nach einer falschen URL-Entscheidung, die vor drei Jahren getroffen wurde und immer noch in Backlinks vorkommt, auf die man keinen Einfluss hat. Immer dann, wenn die Anzahl der zu ändernden URLs das Maß übersteigt, das man noch manuell im Control Panel bewältigen möchte, ist dies das richtige Tool dafür.

Bitte kontaktieren Sie uns unter wargis@bay20.com/manish@bay20.com oder rufen Sie uns unter +91-9582784309 oder +91-8800519180 an, wenn Sie Unterstützung im Zusammenhang mit BigCommerce benötigen. Sie können auch unsere Website besuchen, um sich über unser Leistungsangebot zu informieren.