Quản lý việc chuyển hướng trang bằng API Notiondesk

Việc chuyển hướng trang sẽ đưa người đọc khi họ truy cập vào đường dẫn cũ trên trung tâm trợ giúp của bạn đến một bài viết hoặc bộ sưu tập. API Notiondesk cho phép bạn liệt kê, tạo, cập nhật và xóa các chuyển hướng trang, nhờ đó bạn có thể nhập hàng trăm URL cũ sau khi di chuyển thay vì thêm chúng từng cái một trong bảng điều khiển. Dấu trang, liên kết được chia sẻ và kết quả tìm kiếm vẫn hoạt động bình thường.

Để quản lý chuyển hướng trong bảng điều khiển, hãy xem Cách quản lý chuyển hướng trang trong trung tâm trợ giúp của bạn .

Việc tạo và cập nhật các liên kết chuyển hướng đòi hỏi một kế hoạch bao gồm cả việc chuyển hướng trang.

Chuyển hướng trang danh sách

Danh sách này bao gồm mọi ngôn ngữ, ngôn ngữ mới nhất được liệt kê trước. Nó bao gồm cả các liên kết chuyển hướng do bạn tạo và các liên kết mà Notiondesk tự động tạo sau khi thay đổi slug.

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
}

Lưu ý: Chuyển hướng chỉ gửi người đọc đến trang đích khi trang đó đã được xuất bản. Chuyển hướng đến bản nháp sẽ chờ đến khi bạn xuất bản trang đích.

Danh sách chỉ hiển thị tối đa 10.000 liên kết chuyển hướng mới nhất. Nếu hệ thống tích hợp của bạn xóa các liên kết chuyển hướng trong khi liệt kê chúng, hãy bắt đầu lại từ trang đầu tiên sau đó: việc xóa sẽ làm dịch chuyển các mục tiếp theo, do đó trang tiếp theo có thể bỏ qua một mục. Xem Phân trang và các yêu cầu API phiên bản Notiondesk .

Tạo trang chuyển hướng

Mọi trường thông tin đều bắt buộc:

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"}'

Tuyến đường trả lời 201 Created với lệnh chuyển hướng mới, trong cùng các trường như danh sách.

• Một source_path chuyển hướng khác đã sử dụng câu trả lời 409 conflict_error, và thông báo nêu tên đường dẫn.

• Một target_id không có bản dịch trong locale trả về 404 not_found, và thông báo nêu tên ID.

Gửi mã lỗi Idempotency-Key với mỗi lần tạo. Việc thử lại với cùng khóa và nội dung sẽ trả về mã lỗi 201 mà không tạo chuyển hướng thứ hai. Xem Xử lý lỗi API Notiondesk, giới hạn tỷ lệ và thử lại .

Cập nhật chuyển hướng trang

Chỉ gửi các trường cần thay đổi. Các trường bạn không gửi sẽ giữ nguyên giá trị hiện tại.

Các trường tuân theo các quy tắc tạo. Tuyến đường trả lời 200 OK với lệnh chuyển hướng đã cập nhật.

Việc chuyển hướng vẫn phải trỏ đến một mục tiêu tồn tại trong locale sau khi thay đổi. Để trỏ việc chuyển hướng bài viết đến một bộ sưu tập, hãy gửi type và target_id cùng nhau.

Xóa chuyển hướng trang

Việc xóa không thể hoàn tác, vì vậy tuyến đường này cần hai biện pháp bảo vệ:

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}'

• phạm vi admin;

• phần thân {"confirm": true}, với giá trị boolean JSON true.

Đường dẫn trả về lỗi 204 No Content. Người đọc mở đường dẫn cũ sẽ không còn bị chuyển hướng nữa. Xóa cùng một đường dẫn chuyển hướng sẽ trả về lỗi 404 not_found, trừ khi bạn thử lại với cùng lỗi Idempotency-Key.

Phạm vi quyền chỉ hoạt động trên khóa được tạo bởi chủ sở hữu không gian làm việc hoặc Quản trị viên. Người biên tập có thể xóa liên kết chuyển hướng trong bảng điều khiển, nhưng không thể xóa bằng khóa API.admin

Chuyển hướng nhập sau khi di chuyển

Bạn đang chuyển từ một công cụ trung tâm trợ giúp khác? Hãy ánh xạ từng đường dẫn cũ đến bài viết mới tương ứng, sau đó tạo một liên kết chuyển hướng cho mỗi hàng. Đoạn mã này đọc một tệp CSV với các cột 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);
}

• Khóa được tạo ra từ hàng, vì vậy chạy tập lệnh hai lần sẽ không tạo ra gì hai lần. Hàng được sửa sẽ có một khóa mới.

• Đường dẫn đã có nhật ký chuyển hướng sẽ hiển thị conflict_error. Thay vào đó, hãy cập nhật nó hoặc giữ nguyên.

• Số lượng yêu cầu ghi bị giới hạn ở mức 20 yêu cầu mỗi phút cho mỗi khóa, vì vậy 500 lần chuyển hướng sẽ mất khoảng 25 phút. Tập lệnh sẽ chờ khi bị giới hạn tốc độ, sau đó sẽ thử lại hàng đó.

• Chỉ sử dụng khóa có phạm vi read và write.

Lỗi

Xem các lỗi API, giới hạn tốc độ và số lần thử lại của Handle Notiondesk để biết phạm vi lỗi và các mã khác.

Câu hỏi thường gặp

Tiếp theo là gì?

• Tự động hóa các tác vụ thường gặp trong trung tâm trợ giúp bằng API Notiondesk

• Đọc các bài viết, bộ sưu tập và mục nhật ký thay đổi bằng API Notiondesk

• Xử lý các lỗi API, giới hạn tỷ lệ và các lần thử lại của Notiondesk