Zarządzaj przekierowaniami stron za pomocą interfejsu API Notiondesk

Przekierowanie strony kieruje czytelników, którzy otwierają starą ścieżkę w centrum pomocy, do artykułu lub kolekcji. Interfejs API Notiondesk umożliwia wyświetlanie, tworzenie, aktualizowanie i usuwanie przekierowań stron, dzięki czemu po migracji można zaimportować setki starych adresów URL zamiast dodawać je pojedynczo w panelu. Zakładki, udostępnione linki i wyniki wyszukiwania nadal działają.

Aby zarządzać przekierowaniami z poziomu pulpitu nawigacyjnego, zapoznaj się z tematem Jak zarządzać przekierowaniami stron w centrum pomocy .

Tworzenie i aktualizowanie przekierowań wymaga planu uwzględniającego przekierowania stron.

Wyświetl przekierowania stron

Lista obejmuje wszystkie języki, od najnowszych na górze. Obejmuje przekierowania utworzone przez Ciebie oraz te, które Notiondesk tworzy automatycznie po zmianie ślimaka.

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects?page_size=100" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "id": "3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69",
      "locale": "en",
      "type": "article",
      "origin": "manual",
      "source_path": "/legacy/getting-started",
      "target_id": "1761580412",
      "target_title": "Getting started",
      "target_slug": "getting-started",
      "target_status": "published"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Uwaga: Przekierowanie wysyła czytelników tylko wtedy, gdy jego cel jest opublikowany. Przekierowanie do wersji roboczej czeka na opublikowanie celu.

Lista obejmuje maksymalnie 10 000 najnowszych przekierowań. Jeśli Twoja integracja usuwa przekierowania podczas ich wyświetlania, zacznij od nowa od pierwszej strony: usunięcie przesuwa kolejne elementy, więc następna strona może pominąć jeden z nich. Zobacz Paginat i wersję Notiondesk API Requests .

Utwórz przekierowanie strony

Każde pole jest wymagane:

curl -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0d6b1e-create-getting-started" \
  -d '{"type": "article", "source_path": "/legacy/getting-started", "target_id": "1761580412", "locale": "en"}'

Trasa odpowiada 201 Created nowym przekierowaniem w tych samych polach co lista.

• source_path inne przekierowanie już używa odpowiedzi 409 conflict_error, a komunikat podaje nazwę ścieżki.

• target_id bez tłumaczenia w locale odpowiada 404 not_found, a wiadomość podaje identyfikator.

Wysyłaj Idempotency-Key przy każdym utworzeniu. Ponowna próba z tym samym kluczem i treścią odpowiada na to samo 201 bez tworzenia drugiego przekierowania. Zobacz Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób .

Zaktualizuj przekierowanie strony

Wyślij tylko pola do zmiany. Każde pominięte pole zachowa swoją obecną wartość.

Pola są zgodne z regułami tworzenia. Trasa odpowiada 200 OK zaktualizowanym przekierowaniem.

Po zmianie przekierowanie musi nadal wskazywać na cel istniejący w locale. Aby skierować przekierowanie artykułu do kolekcji, wyślij razem type i target_id.

Usuń przekierowanie strony

Usunięcia nie można cofnąć, dlatego trasa wymaga dwóch zabezpieczeń:

curl -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects/3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/legacy/start"}'

curl -i -X DELETE "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects/3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

• zakres admin;

• treść {"confirm": true} z wartością logiczną JSON true.

Trasa odpowiada 204 No Content. Czytelnicy, którzy otworzą starą ścieżkę, przestaną być przekierowywani. Ponowne usunięcie tego samego przekierowania odpowiada 404 not_found, chyba że spróbujesz ponownie z tym samym Idempotency-Key.

Zakres działa tylko na kluczu utworzonym przez właściciela obszaru roboczego lub administratora. Edytor może usunąć przekierowanie w panelu, ale nie za pomocą klucza API.admin

Przekierowania importu po migracji

Przenosisz się z innego narzędzia centrum pomocy? Zmapuj każdą starą ścieżkę do nowego artykułu, a następnie utwórz jedno przekierowanie dla każdego wiersza. Ten skrypt odczytuje plik CSV z kolumnami source_path,target_id,locale:

import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";

const siteId = "c74781f6-1aea-4e17-ab23-bbb8b4d174b6";
const rows = readFileSync("redirects.csv", "utf8").trim().split(/\r?\n/).slice(1);

for (const row of rows) {
  const [source_path, target_id, locale] = row.split(",");
  const idempotencyKey = createHash("sha256").update(`${source_path}|${target_id}|${locale}`).digest("hex");

  const response = await fetch(`https://api.notiondesk.so/sites/${siteId}/page-redirects`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
      "nd-version": "2026-10-16",
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({ type: "article", source_path, target_id, locale }),
  });

  if (response.status === 429) {
    const seconds = Number(response.headers.get("Retry-After")) || 5;
    console.log(`Rate limited, waiting ${seconds}s`);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    rows.push(row);
    continue;
  }

  const result = await response.json();
  console.log(response.status, source_path, response.ok ? result.id : result.code);
}

• Klucz jest generowany z wiersza, więc dwukrotne uruchomienie skryptu nic nie daje. Poprawiony wiersz otrzymuje nowy klucz.

• Ścieżka, która ma już przekierowanie, loguje conflict_error. Zamiast tego zaktualizuj ją lub pozostaw.

• Liczba zapisów jest ograniczona do 20 żądań na minutę dla każdego klucza, więc 500 przekierowań zajmuje około 25 minut. Skrypt czeka, aż limit zostanie osiągnięty, a następnie ponawia próbę odczytania wiersza.

• Użyj klucza tylko z zakresami read i write.

Błędy

Zobacz temat Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób, aby zapoznać się z obwiednią błędu i innymi kodami.

Często zadawane pytania

Co dalej?

• Zautomatyzuj typowe zadania centrum pomocy za pomocą interfejsu API Notiondesk

• Czytaj artykuły, kolekcje i wpisy w dzienniku zmian za pomocą interfejsu API Notiondesk

• Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób