Sử dụng API Đồ thị

API Đồ thị là cách chủ yếu để tải dữ liệu vào và lấy dữ liệu ra khỏi đồ thị xã hội của Facebook. Đó là API dựa trên HTTP cấp thấp được sử dụng để truy vấn dữ liệu, đăng tin mới, tải ảnh lên và nhiều tác vụ khác mà ứng dụng có thể cần thực hiện. Hướng dẫn này giải thích cách hoàn thành tất cả những việc sau đây trong API Đồ thị.

Thông tin cơ bản

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ị. Phần sau đây giải thích thêm về các thao tác khác nhau có thể thực hiện được bằng API.

Đọc

Chỉ cần tạo yêu cầu HTTP GET tới điểm cuối phù hợp là bạn có thể đọc tất cả các nút và cạnh trong API Đồ thị. Chẳng hạn, nếu muốn truy xuất thông tin về người dùng hiện tại, bạn sẽ tạo yêu cầu HTTP GET như sau:

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

Hầu hết lệnh gọi API phải được ký bằng mã truy cập. Bạn có thể xác định quyền cần thiết trong mã truy cập này bằng cách xem Tài liệu tham khảo API Đồ thị cho nút hoặc cạnh mà bạn muốn đọc. Bạn cũng có thể sử dụng Trình khám phá API Đồ thị để tạo nhanh mã nhằm phát bằng API và khám phá cách hoạt động.

Nút /me là điểm cuối đặc biệt sẽ chuyển thành user_id của người dùng (hoặc page_id của Trang Facebook) có mã truy cập hiện đang được sử dụng để thực hiện lệnh gọi API. Nếu đã có mã truy cập người dùng, bạn có thể truy xuất tất cả ảnh của người dùng bằng cách sử dụng:

GET graph.facebook.com
  /me/photos

Phản hồi bạn nhận được sẽ thay đổi tùy theo nút hoặc cạnh bạn đang đọc nhưng phản hồi sẽ có dạng chung như sau:

{
   "fieldname": {field-value},
   ....
}

Chọn trường

Theo mặc định, không phải tất cả các trường trong nút hoặc cạnh đều được trả về khi bạn thực hiện truy vấn. Bạn có thể chọn trường hoặc cạnh mình muốn trả về bằng thông số truy vấn fields. Điều này thực sự hữu ích để thực hiện lệnh gọi API nhanh hơn và hiệu quả hơn.

Chẳng hạn, lệnh gọi API Đồ thị sau đây sử dụng mã truy cập người dùng của chính bạn https://graph.facebook.com/me?fields=id,name,picture sẽ chỉ trả về id, tên và ảnh trong trang cá nhân của bạn:

GET graph.facebook.com/me?fields=id,name,picture

Sắp xếp

Bạn có thể sắp xếp các nhóm dữ liệu nhất định theo thứ tự thời gian. Ví dụ: bạn có thể sắp xếp bình luận của ảnh theo thứ tự thời gian đảo ngược bằng cách sử dụng khóa reverse_chronological:

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

order phải là một trong các giá trị sau đây:

  • chronological
  • reverse_chronological

Tra cứu URL

Bạn có thể khám phá hầu hết các đối tượng bằng ID nhưng đôi khi lại không thể thực hiện việc này và tất cả những gì bạn có là URL để xác định nội dung nào đó.

Bạn có thể sử dụng nút URL đã được đưa vào v2.1 để trả về ID của URL đối tượng trong Open Graph hoặc để tìm dữ liệu được liên kết với URL liên kết ứng dụng.

Tìm hiểu thêm về cách tìm dữ liệu Liên kết ứng dụng bằng API chỉ mục trong tài liệu về Liên kết ứng dụng của chúng tôi.

Sửa đổi yêu cầu API

Bạn có thể sử dụng một số điểm cuối API với các thông số bổ sung sẽ sửa đổi yêu cầu. Tính chất về chức năng của các thông số sửa đổi này khác nhau nên chúng tôi đã ghi lại riêng mỗi thông số sửa đổi trong từng tài liệu tham khảo API khi thích hợp. Dưới đây là danh sách các thông số sửa đổi phổ biến có thể dùng với hầu hết các điểm cuối.

Tên Mô tả Loại

return_ssl_resources

Được dùng khi bạn yêu cầu trả về ảnh qua kết nối bảo mật (HTTPS) để tránh cảnh báo nội dung kết hợp trong trình duyệt.

bool

locale

Được dùng khi ứng dụng của bạn cần khả năng truy xuất nội dung bản địa hóa bằng ngôn ngữ cụ thể (nếu có).

Locale

Các thông số sửa đổi khác cho phân trangxem xét nội quan được trình bày dưới đây.

Tạo yêu cầu lồng ghép

Tính năng mở rộng trường của API Đồ thị cho phép bạn lồng ghép hiệu quả nhiều truy vấn đồ thị vào một lệnh gọi duy nhất. Một số tài nguyên, bao gồm hầu hết các API Quảng cáo, không thể sử dụng tính năng mở rộng trường trên một số hoặc tất cả các kết nối.

Ví dụ: trong một lệnh gọi đơn lẻ, bạn có thể yêu cầu N ảnh đầu tiên của K album đầu tiên. Phản hồi này duy trì phân cấp dữ liệu để nhà phát triển không phải kết hợp dữ liệu lại với nhau trên máy khách.

Tính năng này khác với tính năng Yêu cầu theo lô cho phép bạn thực hiện nhiều lệnh gọi API Đồ thị có thể không liên quan trong một yêu cầu duy nhất.

Dưới đây là định dạng chung của tính năng mở rộng trường:

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

<first-level> trong trường hợp này sẽ là một hoặc nhiều trường hoặc cạnh (được phân tách bằng dấu phẩy) từ nút gốc. <second-level> sẽ là một hoặc nhiều trường hoặc cạnh (được phân tách bằng dấu phẩy) từ nút cấp độ đầu tiên.

Không có giới hạn về số lượng lồng ghép các cấp độ có thể xảy ra ở đây. Bạn cũng có thể sử dụng đối số .limit(n) trên mỗi trường hoặc cạnh để hạn chế số lượng đối tượng mà mình muốn nhận.

Điều này sẽ dễ hiểu hơn khi áp dụng vào thực tiễn, vì vậy dưới đây sẽ là một truy vấn mẫu truy xuất tối đa năm album do một người tạo và năm bài viết cuối trong nguồn cấp của người đó.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

Sau đó, chúng ta có thể mở rộng trường này thêm một chút và đối với từng đối tượng album, chúng ta cũng truy xuất hai ảnh đầu tiên và những người được gắn thẻ trong từng ảnh:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

Giờ chúng ta có thể mở rộng trường thêm lần nữa bằng cách truy xuất tên của từng ảnh, URL ảnh và người được gắn thẻ:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

Hãy xem ví dụ sử dụng phân trang dựa vào con trỏ:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

Bạn có thể thấy được cách hoạt động của tính năng mở rộng trường trên các nút, cạnh và trường để trả về dữ liệu thực sự phức tạp trong một yêu cầu đơn lẻ.

Chuyển kết quả theo trang

Khi bạn tạo yêu cầu API cho 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 đượ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 pháp 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. Trừ khi mục này bị xóa, con trỏ sẽ luôn trỏ tới cùng một phần trong danh sách nhưng sẽ mất hiệu lực nếu một mục bị xóa. Vì vậy, ứng dụng của bạn không được lưu trữ con trỏ và giả định rằng chúng sẽ có hiệu lực trong tương lai.

Khi đọc một cạnh hỗ trợ 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/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/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 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 đã đạt tới cuối danh sách dữ liệu chưa mà hãy sử dụng next như được mô tả ở trên. 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ặt hàng đã bị xóa do lọc theo quyền riêng tư. Một số cạnh cũng có thể có giá trị tối đa đối với giá trị limit vì các lý do hiệu suất. Trong tất cả các trường hợp, API 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 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 'tiếp theo'. Dừng phân trang khi liên kết 'tiếp theo' 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 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 thông qua dữ liệu kết quả bằng cách sử dụng dấu thời gian Unix trỏ tới 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â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/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/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 : Dấu thời gian Unix hoặc giá trị dữ liệu strtotime trỏ tới phần cuối của phạm vi dữ liệu dựa theo thời gian.
  • since : Dấu thời gian Unix hoặc giá trị dữ liệu strtotime trỏ tới 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 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 đã đạt tới cuối danh sách dữ liệu chưa mà hãy sử dụng next như được mô tả ở trên. 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ặt hàng đã bị xóa do lọc theo quyền riêng tư. Một số cạnh cũng có thể có giá trị tối đa đối với giá trị limit vì các lý do hiệu suất. Trong tất cả các trường hợp, API 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ố sinceuntil. 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ù

Có thể sử dụng phân trang dựa vào phần bù khi bạn không quan tâm đến thứ tự thời gian mà chỉ muốn trả về số đối tượng cụ thể. Bạn chỉ có thể sử dụng phương pháp 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 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 đã đạt tới cuối danh sách dữ liệu chưa mà hãy sử dụng next như được mô tả ở trên. 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ặt hàng đã bị xóa do lọc theo quyền riêng tư. Một số cạnh cũng có thể có giá trị tối đa đối với giá trị limit vì các lý do hiệu suất. Trong tất cả các trường hợp, API 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 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 'tiếp theo'. Dừng phân trang khi liên kết 'tiếp theo' 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, chúng tôi khuyên bạn nên phân trang bằng liên kết trước/tiếp theo mà chúng tôi trả về trong phản hồi.

Tạo yêu cầu lớn

Một số điểm cuối API Đồ thị có thể lấy thông số rất lớn. Nếu yêu cầu của bạn lớn hơn một vài nghìn ký tự, có thể bạn sẽ nhận thấy lỗi máy chủ vì máy chủ của chúng tôi sẽ từ chối các yêu cầu GET quá lớn.

Đối với các yêu cầu lớn, thực tiễn tốt nhất đó là sử dụng yêu cầu POST thay vì yêu cầu GET và thêm thông số method=GET. Nếu bạn thực hiện việc này, POST sẽ được diễn giải như thể đó là GET.

Tạo nhiều yêu cầu

Phiên bản chuẩn của API Đồ thị được thiết kế để giúp bạn dễ dàng nhận dữ liệu cho từng đối tượng và duyệt qua kết nối giữa các đối tượng. Phiên bản này cũng bao gồm khả năng truy xuất dữ liệu giới hạn cho một vài đối tượng cùng lúc.

Nếu ứng dụng của bạn cần khả năng truy cập lượng lớn dữ liệu cùng lúc hoặc bạn cần thực hiện thay đổi cho một vài đối tượng cùng lúc thì việc đưa các truy vấn vào một lô thường hiệu quả hơn là tạo nhiều yêu cầu HTTP riêng.

Để bật phiên bản này, API Đồ thị hỗ trợ một số chức năng, bao gồm cả tra cứu nhiều ID và tạo lô. Yêu cầu theo lô được giải thích trong một hướng dẫn riêng biệt nhưng bạn có thể đọc thêm về chức năng tra cứu nhiều ID dưới đây.

Yêu cầu đọc nhiều ID

Bạn có thể tạo một yêu cầu GET đơn lẻ truy xuất nhiều nút bằng cách sử dụng điểm cuối ?ids với ID đối tượng của các nút đó. Chẳng hạn, để tra cứu trang Nhà phát triển trên Facebook và người dùng phiên hiện tại trong một yêu cầu, bạn có thể sử dụng lệnh gọi API Đồ thị sau đây:

GET graph.facebook.com
  /?ids=platform,me

Lệnh gọi này tương đương với từng yêu cầu API sau:

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

Dữ liệu được trả về sẽ giống như sau:

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

Yêu cầu này cũng hoạt động với các cạnh, miễn là tất cả các ID được yêu cầu đều có cạnh được yêu cầu. Ví dụ:

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

Tương đương với từng yêu cầu API sau:

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

Dữ liệu được trả về sẽ giống như sau:

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

Lưu ý rằng trong khi lọc trường, mở rộng trường và giới hạn sẽ hoạt động với những tra cứu nhiều ID này, bạn sẽ nhận được lỗi nếu một trong các đối tượng không có bất kỳ trường được yêu cầu nào. Ví dụ: nếu bạn tra cứu Trang và Người dùng bằng phương pháp này, sau đó lọc trên fields=id,picture,gender, yêu cầu sẽ không thành công do Trang không có trường gender.

Xem xét nội quan

API Đồ thị hỗ trợ xem xét nội quan các nút. API Đồ thị cho phép bạn xem tất cả các cạnh của một nút mà không cần biết trước loại nút. Để lấy thông tin này, hãy thêm metadata=1 vào yêu cầu API Đồ thị:

GET graph.facebook.com
  /{node-id}?
    metadata=1

JSON kết quả sẽ bao gồm thuộc tính metadata liệt kê tất cả các cạnh được hỗ trợ cho nút đã cho:

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

Đăng

Hầu hết các nút trong API Đồ thị có các cạnh có thể là mục tiêu đăng, chẳng hạn như /{user-id}/feed hoặc /{album-id}/photos. Toàn bộ quá trình đăng API Đồ thị được thực hiện với yêu cầu POST HTTP cho cạnh có liên quan khi mọi thông số cần thiết được thêm vào. Chẳng hạn, để đăng bài viết thay mặt ai đó, bạn sẽ tạo yêu cầu POST HTTP như sau:

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

Hầu hết lệnh gọi đăng phải được ký bằng mã truy cập. Bạn có thể xác định quyền cần thiết trong mã truy cập này bằng cách xem tài liệu tham khảo API Đồ thị cho nút bạn muốn đăng.

Có nhiều cạnh có thể là mục tiêu đăng. Bạn có thể tìm thấy thông tin chi tiết trong tài liệu tham khảo cho mỗi nút.

Hướng dẫn về Các trường hợp phổ biến dành cho API Đồ thị chứa thông tin bổ sung cho một vài trường hợp đăng phổ biến.

Tạo nhiều yêu cầu

Bạn có thể nối các lệnh đăng với nhau bằng các lệnh gọi đọc khi sử dụng Yêu cầu theo lô. Để biết thêm thông tin, hãy xem Thực hiện nhiều yêu cầu API.

Đọc sau khi ghi

Nhiều cạnh hỗ trợ đọc sau khi ghi. Hãy xem tài liệu tham khảo của mỗi điểm cuối để xem điểm cuối có hỗ trợ đọc sau khi ghi không và có sẵn những trường nào.

Cập nhật

Toàn bộ quá trình cập nhật API Đồ thị được thực hiện với yêu cầu POST HTTP cho nút có liên quan khi mọi thông số cập nhật được thêm vào:

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

Tất cả các lệnh gọi cập nhật phải được ký bằng mã truy cập với cùng một quyền cần thiết cho việc đăng lên điểm cuối đó theo Tài liệu tham khảo API Đồ thị cho nút bạn muốn cập nhật.

Đọc sau khi ghi

Nhiều cạnh hỗ trợ đọc sau khi ghi. Hãy xem tài liệu tham khảo của mỗi điểm cuối để xem điểm cuối có hỗ trợ đọc sau khi ghi không và có sẵn những trường nào.

Xóa

Xóa nút khỏi đồ thị bằng cách gửi yêu cầu DELETE HTTP cho nút:

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

Nhìn chung, ứng dụng chỉ có thể xóa nội dung mà ứng dụng tạo. Hãy xem hướng dẫn tham khảo cho nút hoặc cạnh để biết thêm thông tin.

Để hỗ trợ các máy khách không hỗ trợ tất cả các phương thức HTTP, bạn có thể lựa chọn đưa ra yêu cầu POST cho điểm cuối với đối số bổ sung method=delete để ghi đè phương thức HTTP. Chẳng hạn, bạn có thể xóa bình luận bằng cách đưa ra yêu cầu sau:

POST graph.facebook.com
  /{comment-id}?
    method=delete

Đọc sau khi ghi

Để tạo và cập nhật điểm cuối, API Đồ thị có thể đọc ngay đối tượng đã cập nhật hoặc đăng thành công và trả về bất cứ trường nào được điểm cuối đọc tương ứng hỗ trợ.

Để sử dụng tính năng này, hãy đưa thông số fields vào yêu cầu của bạn và liệt kê các trường bạn muốn được trả về. Ví dụ: để đăng tin nhắn “Xin chào” trong nguồn cấp của người dùng, bạn có thể thực hiện yêu cầu sau:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

Yêu cầu này sẽ trả về các trường được chỉ định dưới dạng phản hồi có định dạng JSON như sau:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

Hãy xem tài liệu tham khảo của mỗi điểm cuối để xem điểm cuối có hỗ trợ đọc sau khi ghi không và có sẵn những trường nào.

Lỗi

Nếu lệnh đọc không thành công vì bất cứ lý do gì (ví dụ: yêu cầu trường không tồn tại), thì API Đồ thị sẽ phản hồi bằng phản hồi lỗi tiêu chuẩn. Ngoài ra, phản hồi sẽ bao gồm thuộc tính original_response có giá trị là giá trị mà điểm cuối thường trả về khi thành công.

Ví dụ: yêu cầu sau chứa một trường không hợp lệ:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

Đây sẽ là phản hồi:

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

Bạn có thể tìm kiếm qua nhiều đối tượng công khai trong đồ thị xã hội bằng điểm cuối /search. Cú pháp tìm kiếm là:

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

Tất cả các truy vấn tìm kiếm API Đồ thị đều bắt buộc đưa mã truy cập vào yêu cầu. Bạn cần mã truy cập người dùng để tiến hành tìm kiếm.

Các loại tìm kiếm có sẵn

Chúng tôi hỗ trợ tìm kiếm cho các loại sau:

Loại Mô tả giá trị `q`

user

Tìm kiếm một người (nếu họ cho phép tìm kiếm tên của mình).

Tên

page

Tìm kiếm Trang.

Tên

event

Tìm kiếm sự kiện.

Tên

group

Tìm kiếm Nhóm.

Tên

place

Tìm kiếm địa điểm. Bạn hiện có thể thu hẹp tìm kiếm ở một vị trí và khoảng cách cụ thể bằng cách thêm thông số center (với vĩ độ và kinh độ) và thông số tùy chọn distance (tính theo mét):

Tên

placetopic

Trả về danh sách các chủ đề Trang địa điểm có thể xuất hiện và ID của chúng. Sử dụng cùng thông số topic_filter=all để có danh sách đầy đủ.

Không có

ad_*

Một bộ sưu tập các tùy chọn tìm kiếm khác nhau có thể sử dụng để tìm tùy chọn nhắm mục tiêu.

Xem Tùy chọn nhắm mục tiêu

Ví dụ:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

Xử lý lỗi

Các yêu cầu được thực hiện với API của chúng tôi có thể dẫn đến nhiều phản hồi lỗi khác nhau. Chủ đề sau mô tả các chiến thuật phục hồi và cung cấp danh sách giá trị lỗi với sơ đồ các chiến thuật phục hồi phổ biến nhất mà bạn có thể sử dụng.

Nhận mã lỗi

Phản hồi sau đây là phản hồi lỗi phổ biến do yêu cầu API không thành công:

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message: Mô tả lỗi có thể đọc được.
  • code: Mã lỗi. Giá trị phổ biến được liệt kê bên dưới, cùng với các chiến thuật phục hồi phổ biến.
  • error_subcode: Thông tin bổ sung về lỗi. Giá trị phổ biến được liệt kê bên dưới.
  • error_user_msg: Thông báo hiển thị cho người dùng. Ngôn ngữ của thông báo dựa vào ngôn ngữ của yêu cầu API.
  • error_user_title: Tiêu đề của hộp thoại, nếu được hiển thị. Ngôn ngữ của thông báo dựa vào ngôn ngữ của yêu cầu API.
  • fbtrace_id: Số nhận dạng hỗ trợ nội bộ. Khi báo cáo một lỗi có liên quan đến lệnh gọi API Đồ thị, hãy thêm fbtrace_id để giúp chúng tôi tìm dữ liệu nhật ký để gỡ lỗi.

Mã lỗi

Mã hoặc loại Tên Việc cần làm

OAuthException

Nếu không có mã phụ nào xuất hiện, điều này nghĩa là trạng thái đăng nhập hoặc mã truy cập đã hết hạn, đã bị thu hồi hoặc không hợp lệ. Nhận mã truy cập mới.

Nếu xuất hiện mã phụ, hãy xem mã phụ đó.

102

Phiên API

Nếu không có mã phụ nào xuất hiện, điều này nghĩa là trạng thái đăng nhập hoặc mã truy cập đã hết hạn, đã bị thu hồi hoặc không hợp lệ. Nhận mã truy cập mới.

Nếu xuất hiện mã phụ, hãy xem mã phụ đó.

1

API không xác định

Có thể là sự cố tạm thời do thời gian chết. Hãy đợi và thử thực hiện lại thao tác. Nếu sự cố vẫn tiếp diễn, hãy kiểm tra xem bạn có đang yêu cầu một API có sẵn hay không.

2

Dịch vụ API

Sự cố tạm thời do thời gian chết. Hãy đợi và thử thực hiện lại thao tác.

4

Quá nhiều lệnh gọi API

Sự cố tạm thời do giới hạn tốc độ. Hãy đợi và thử thực hiện lại thao tác hoặc kiểm tra số lượng yêu cầu API của bạn.

17

Quá nhiều lệnh gọi người dùng API

Sự cố tạm thời do giới hạn tốc độ. Hãy đợi và thử thực hiện lại thao tác hoặc kiểm tra số lượng yêu cầu API của bạn.

10

Quyền API bị từ chối

Quyền không được cấp hoặc đã bị xóa. Xử lý quyền bị thiếu.

190

Mã truy cập đã hết hạn

Nhận mã truy cập mới.

200-299

Quyền API (Nhiều giá trị tùy thuộc vào quyền)

Quyền không được cấp hoặc đã bị xóa. Xử lý quyền bị thiếu.

341

Đã đạt đến giới hạn ứng dụng

Sự cố tạm thời do giới hạn tốc độ hoặc thời gian chết. Hãy đợi và thử thực hiện lại thao tác hoặc kiểm tra số lượng yêu cầu API của bạn.

368

Tạm thời bị chặn vì vi phạm chính sách

Hãy đợi và thử thực hiện lại thao tác.

506

Bài viết trùng lặp

Không thể đăng bài viết trùng lặp liên tiếp. Hãy thay đổi nội dung của bài viết và thử lại.

1609005

Liên kết đăng bị lỗi

Đã xảy ra sự cố khi trích xuất dữ liệu từ liên kết cho sẵn. Kiểm tra URL và thử lại.

Mã phụ của lỗi xác thực

Tên Việc cần làm

458

Ứng dụng không được cài đặt

Người dùng chưa đăng nhập ứng dụng của bạn. Xác thực lại người dùng.

459

Đã tạo điểm kiểm tra cho người dùng

Người dùng cần đăng nhập tại https://www.facebook.com hoặc https://m.facebook.com để khắc phục sự cố.

460

Đã thay đổi mật khẩu

Trên iOS 6 trở lên, nếu người dùng đã đăng nhập bằng luồng tích hợp với hệ điều hành, họ sẽ được chuyển hướng đến cài đặt hệ điều hành của Facebook trên thiết bị để cập nhật mật khẩu. Nếu không, họ phải đăng nhập lại vào ứng dụng.

463

Đã hết hạn

Trạng thái đăng nhập hoặc mã truy cập đã hết hạn, bị thu hồi hoặc không hợp lệ. Xử lý mã truy cập đã hết hạn.

464

Chưa xác nhận người dùng

Người dùng cần đăng nhập tại https://www.facebook.com hoặc https://m.facebook.com để khắc phục sự cố.

467

Mã truy cập không hợp lệ

Mã truy cập đã hết hạn, bị thu hồi hoặc không hợp lệ. Xử lý mã truy cập đã hết hạn.

Thông số phức tạp

Hầu hết các loại thông số đều là thông số gốc đơn giản, chẳng hạn như stringint, tuy nhiên, cũng có thể chỉ định các loại listobject trong yêu cầu.

Loại list được chỉ định bằng cú pháp JSON, ví dụ: ["firstitem", "seconditem", "thirditem"]

Loại object cũng được chỉ định bằng cú pháp JSON, ví dụ: {"firstkey": "firstvalue", "secondKey": 123}

Gỡ lỗi yêu cầu API

Chế độ gỡ lỗi API Đồ thị

Khi chế độ gỡ lỗi được bật, phản hồi API Đồ thị có thể chứa trường bổ sung giải thích các sự cố có thể xảy ra với yêu cầu.

Để bật chế độ gỡ lỗi, hãy sử dụng thông số chuỗi truy vấn debug. Ví dụ:

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

Nếu quyền user_friends không được cấp, thông số này sẽ tạo ra phản hồi sau đây:

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

Bạn có thể đặt giá trị thông số debug thành "all" hoặc đặt ở cấp độ nghiêm trọng tối thiểu được yêu cầu tương ứng với type của thông báo:

Giá trị thông số gỡ lỗi Kết quả sẽ được trả về

all

Tất cả các thông báo gỡ lỗi hiện có.

info

Thông báo gỡ lỗi có loại infowarning.

warning

Chỉ thông báo gỡ lỗi có loại warning.

Thông tin gỡ lỗi, nếu có, được trả về dưới dạng đối tượng JSON trong khóa __debug__ trong mảng messages. Mỗi phần tử của mảng này là một đối tượng JSON, chứa các trường sau:

Trường Loại dữ liệu Mô tả

message

Chuỗi

Thông báo.

loại

Chuỗi

Mức độ nghiêm trọng của thông báo.

liên kết

Chuỗi

[Tùy chọn] URL trỏ đến thông tin liên quan.

Bạn cũng có thể sử dụng Chế độ gỡ lỗi với Trình khám phá API Đồ thị.

Xác định phiên bản được dùng bởi yêu cầu API

Khi bạn xây dựng ứng dụng và tạo yêu cầu API Đồ thị, bạn có thể thấy hữu ích khi có thể xác định phiên bản API mà mình đang nhận phản hồi từ đó. Chẳng hạn, nếu bạn đang thực hiện lệnh gọi mà không chỉ định phiên bản thì có thể bạn sẽ không biết phiên bản API phản hồi.

API Đồ thị cung cấp cho tiêu đề yêu cầu bất kỳ phản hồi nào có tên là facebook-api-version, cho biết phiên bản chính xác của API đã tạo phản hồi. Chẳng hạn, một lệnh gọi API Đồ thị tạo một yêu cầu có v2.0 sẽ có tiêu đề HTTP sau đây:

facebook-api-version:v2.0

Tiêu đề facebook-api-version này cho phép bạn xác định xem các lệnh gọi API có đang được trả về từ phiên bản mong đợi hay không.

Thông tin gỡ lỗi để báo cáo lỗi

Nếu bạn cần báo cáo lỗi trong API Đồ thị, chúng tôi sẽ thêm một số tiêu đề yêu cầu bổ sung mà bạn sẽ gửi cùng báo cáo lỗi để giúp chúng tôi xác định và tái tạo sự cố của bạn. Các tiêu đề yêu cầu này là X-FB-Debug, x-fb-revX-FB-Trace-ID.