API Đồ thị

Kết quả được phân trang

Chúng tôi trình bày thông tin cơ bản về thuật ngữ và cấu trúc của API Đồ thị trong phần Tổng quan về API Đồ thị. Tài liệu này sẽ nêu chi tiết hơn về kết quả từ yêu cầu API.

Chuyển kết quả theo trang

Khi tạo yêu cầu API đến một nút hoặc cạnh, bạn thường không nhận được tất cả kết quả của yêu cầu đó trong một phản hồi. Điều này là do một số phản hồi có thể chứa hàng nghìn đối tượng nên hầu hết mọi phản hồi đều được phân trang theo mặc định.

Phân trang dựa vào con trỏ

Phân trang dựa vào con trỏ là phương thức phân trang hiệu quả nhất và luôn được sử dụng khi có thể. Con trỏ chỉ một chuỗi ký tự ngẫu nhiên để đánh dấu mục cụ thể trong danh sách dữ liệu. Con trỏ sẽ luôn trỏ đến mục nhưng sẽ mất hiệu lực nếu mục này bị xóa hoặc gỡ. Do đó, ứng dụng của bạn không được lưu trữ con trỏ hoặc giả định rằng chúng sẽ có hiệu lực trong tương lai.

Khi đọc một cạnh hỗ trợ tính năng phân trang dựa vào con trỏ, bạn sẽ nhìn thấy phản hồi JSON sau:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Cạnh được phân trang dựa vào con trỏ sẽ hỗ trợ các thông số sau:

  • before: Đây là con trỏ trỏ đến phần đầu của trang dữ liệu đã được trả về.
  • after: Đây là con trỏ trỏ đến phần cuối của trang dữ liệu đã được trả về.
  • limit: Đây là số đối tượng tối đa có thể được trả về. Một truy vấn có thể trả về ít hơn giá trị limit do quá trình lọc. Không dựa vào số kết quả ít hơn giá trị limit để biết truy vấn của bạn đã đến cuối danh sách dữ liệu chưa mà hãy sử dụng next như mô tả bên dưới. Ví dụ: nếu bạn đặt limit là 10 và 9 kết quả được trả về, có thể có nhiều dữ liệu hơn nhưng một mục đã bị gỡ do quá trình lọc theo quyền riêng tư. Một số cạnh cũng có thể đạt giá trị limit ở mức tối đa do những nguyên nhân về hiệu quả. Trong mọi trường hợp, API này sẽ trả về các liên kết phân trang chính xác.
  • next: Điểm cuối API Đồ thị sẽ trả về trang dữ liệu tiếp theo. Nếu không có điểm cuối này thì đây là trang dữ liệu cuối cùng. Do cách kết hợp của tính năng phân trang với mức độ hiển thị và quyền riêng tư, nên có khả năng một trang sẽ bị trống nhưng chứa liên kết phân trang next. Dừng phân trang khi liên kết next không còn xuất hiện nữa.
  • previous: Điểm cuối API Đồ thị sẽ trả về trang dữ liệu trước đó. Nếu không có điểm cuối này thì đây là trang dữ liệu đầu tiên.

Không lưu trữ con trỏ. Con trỏ có thể nhanh chóng chuyển thành không hợp lệ nếu các mục được thêm hoặc xóa.

Phân trang theo thời gian

Phân trang theo thời gian được dùng để điều hướng qua dữ liệu kết quả bằng cách sử dụng nhãn thời gian Unix trỏ đến thời điểm cụ thể trong danh sách dữ liệu.

Khi sử dụng một điểm cuối dùng phương thức phân trang theo thời gian, bạn sẽ nhìn thấy phản hồi JSON sau:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

Cạnh được phân trang theo thời gian sẽ hỗ trợ các thông số sau:

  • until: Nhãn thời gian Unix hoặc giá trị dữ liệu strtotime trỏ đến phần cuối của phạm vi dữ liệu dựa theo thời gian.
  • since: Nhãn thời gian Unix hoặc giá trị dữ liệu strtotime trỏ đến phần đầu của phạm vi dữ liệu dựa theo thời gian.
  • limit: Đây là số đối tượng tối đa có thể được trả về. Một truy vấn có thể trả về ít hơn giá trị limit do quá trình lọc. Không dựa vào số kết quả ít hơn giá trị limit để biết truy vấn của bạn đã đến cuối danh sách dữ liệu chưa mà hãy sử dụng next như mô tả bên dưới. Ví dụ: nếu bạn đặt limit là 10 và 9 kết quả được trả về, có thể có nhiều dữ liệu hơn nhưng một mục đã bị gỡ do quá trình lọc theo quyền riêng tư. Một số cạnh cũng có thể đạt giá trị limit ở mức tối đa do những nguyên nhân về hiệu quả. Trong mọi trường hợp, API này sẽ trả về các liên kết phân trang chính xác.
  • next: Điểm cuối API Đồ thị sẽ trả về trang dữ liệu tiếp theo.
  • previous: Điểm cuối API Đồ thị sẽ trả về trang dữ liệu trước đó.

Để có kết quả nhất quán, hãy chỉ định cả thông số since và until. Ngoài ra, bạn nên đặt khoảng chênh lệch thời gian tối đa là 6 tháng.

Phân trang dựa vào phần bù

Bạn có thể sử dụng phương thức phân trang dựa vào phần bù khi không quan tâm đến thứ tự thời gian mà chỉ muốn trả về số lượng đối tượng cụ thể. Bạn chỉ có thể dùng phương thức này nếu cạnh không hỗ trợ phân trang dựa vào con trỏ hoặc theo thời gian.

Cạnh được phân trang dựa vào phần bù sẽ hỗ trợ các thông số sau:

  • offset: Thông số này bù cho phần đầu của mỗi trang theo số được chỉ định.
  • limit: Đây là số đối tượng tối đa có thể được trả về. Một truy vấn có thể trả về ít hơn giá trị limit do quá trình lọc. Không dựa vào số kết quả ít hơn giá trị limit để biết truy vấn của bạn đã đến cuối danh sách dữ liệu chưa mà hãy sử dụng next như mô tả bên dưới. Ví dụ: nếu bạn đặt limit là 10 và 9 kết quả được trả về, có thể có nhiều dữ liệu hơn nhưng một mục đã bị gỡ do quá trình lọc theo quyền riêng tư. Một số cạnh cũng có thể đạt giá trị limit ở mức tối đa do những nguyên nhân về hiệu quả. Trong mọi trường hợp, API này sẽ trả về các liên kết phân trang chính xác.
  • next: Điểm cuối API Đồ thị sẽ trả về trang dữ liệu tiếp theo. Nếu không có điểm cuối này thì đây là trang dữ liệu cuối cùng. Do cách kết hợp của tính năng phân trang với mức độ hiển thị và quyền riêng tư, nên có khả năng một trang sẽ bị trống nhưng chứa liên kết phân trang next. Dừng phân trang khi liên kết next không còn xuất hiện nữa.
  • previous: Điểm cuối API Đồ thị sẽ trả về trang dữ liệu trước đó. Nếu không có điểm cuối này thì đây là trang dữ liệu đầu tiên.

Lưu ý rằng nếu đối tượng mới được thêm vào danh sách các mục được phân trang thì nội dung của từng trang dựa vào phần bù sẽ thay đổi.

Phân trang dựa vào phần bù không được hỗ trợ cho tất cả lệnh gọi API. Để có kết quả nhất quán, bạn nên phân trang bằng các liên kết trước đó/tiếp theo mà chúng tôi trả về trong phản hồi.

Đối với những đối tượng có nhiều mục được trả về, chẳng hạn như bình luận với số lượng lên đến hàng chục nghìn, bạn có thể gặp phải giới hạn trong khi phân trang. API sẽ trả về lỗi khi ứng dụng của bạn đạt đến giới hạn con trỏ:

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

Các bước tiếp theo

Giờ thì bạn đã quen hơn với API Đồ thị, hãy truy cập Hướng dẫn về Công cụ khám phá đồ thị của chúng tôi để khám phá Đồ thị mà không cần viết mã, Cách sử dụng thường gặp để xem những tác vụ thường gặp nhất đã được thực hiện và các SDK hiện có.