API Đồ thị

Tổng quan

API Đồ thị là cách chính để đưa dữ liệu vào và ra khỏi nền tảng Facebook. API Đồ thị là API dựa trên HTTP mà ứng dụng có thể dùng để truy vấn dữ liệu, đăng tin mới, quản lý quảng cáo, tải ảnh lên và thực hiện nhiều tác vụ khác theo cách lập trình.

API Đồ thị được đặt tên theo ý tưởng về "đồ thị mạng xã hội" - biểu diễn thông tin trên Facebook. API Đồ thị bao gồm các nút, cạnh và trường thông tin. Thông thường, bạn sử dụng nút để lấy dữ liệu về một đối tượng cụ thể, sử dụng cạnh để lấy tập hợp đối tượng trên một đối tượng và sử dụng trường để lấy dữ liệu về một đối tượng hoặc mỗi đối tượng trong một tập hợp. Trong suốt tài liệu này, chúng tôi có thể gọi cả nút và cạnh là "điểm cuối". Ví dụ: "hãy gửi một yêu cầu GET đến điểm cuối Người dùng".

HTTP

Tất cả hoạt động truyền dữ liệu đều tuân thủ HTTP/1.1 và tất cả các điểm cuối đều yêu cầu HTTPS. Do API Đồ thị dựa trên HTTP nên API này hoạt động với bất kỳ ngôn ngữ nào có thư viện HTTP, chẳng hạn như cURL và urllib. Nghĩa là bạn có thể sử dụng API Đồ thị ngay trong trình duyệt của mình. Ví dụ: việc yêu cầu URL sau trong trình duyệt...

https://graph.facebook.com/facebook/picture?redirect=false

... tương ứng với việc thực hiện yêu cầu cURL sau:

curl -i -X GET "https://graph.facebook.com/facebook/picture?redirect=false"

Chúng tôi cũng đã bật lệnh hướng dẫn HSTS includeSubdomains trên facebook.com, nhưng điều này không ảnh hưởng tiêu cực đến các lệnh gọi API Đồ thị.

URL lưu trữ

Hầu hết các yêu cầu đều được chuyển vào URL lưu trữ graph.facebook.com. Ngoại lệ duy nhất là yêu cầu tải video lên, sử dụng graph-video.facebook.com.

Mã truy cập

Mã truy cập cho phép ứng dụng của bạn truy cập API Đồ thị. Hầu hết mọi điểm cuối API Đồ thị đều yêu cầu một loại mã truy cập nào đó. Vậy nên, mỗi khi bạn truy cập vào một điểm cuối, yêu cầu của bạn có thể phải có một mã truy cập. Mã này thường thực hiện 2 chức năng:

  • Cho phép ứng dụng của bạn truy cập thông tin của Người dùng mà không cần mật khẩu của Người dùng. Ví dụ: ứng dụng của bạn cần địa chỉ email của Người dùng để thực hiện một chức năng. Nếu Người dùng đồng ý cho phép ứng dụng truy xuất địa chỉ email của họ từ Facebook, Người dùng sẽ không cần nhập mật khẩu Facebook để ứng dụng lấy địa chỉ email.
  • Nhờ đó, chúng tôi có thể xác định ứng dụng của bạn, Người dùng đang dùng ứng dụng và loại dữ liệu mà Người dùng cho phép ứng dụng của bạn truy cập.

Hãy xem tài liệu về mã truy cập của chúng tôi để tìm hiểu thêm.

Nút

Nút là một đối tượng riêng có ID duy nhất. Ví dụ: có nhiều đối tượng nút Người dùng, mỗi đối tượng lại có một ID duy nhất đại diện cho một cá nhân trên Facebook. Các Trang, Nhóm, Bài viết, Ảnh và Bình luận chỉ là một trong số các nút của Đồ thị mạng xã hội của Facebook.

Ví dụ về cURL sau đây thể hiện một lệnh gọi đến nút Người dùng.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

Theo mặc định, yêu cầu này sẽ trả về các dữ liệu sau, được định dạng bằng JSON:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

Siêu dữ liệu nút

Bạn có thể lấy danh sách tất cả các trường, bao gồm tên trường, mô tả và loại dữ liệu của một đối tượng nút, chẳng hạn như Người dùng, Trang hoặc Ảnh. Hãy gửi một yêu cầu GET đến ID đối tượng và thêm thông số metadata=1:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

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

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

Nút /me là một điểm cuối đặc biệt. Điểm cuối này sẽ chuyển thành ID đối tượng của người hoặc Trang có mã truy cập đang được dùng để thực hiện lệnh gọi API. Nếu đã có mã truy cập dành cho Người dùng, bạn có thể truy xuất tên và ID của Người dùng bằng lệnh:

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

Cạnh

Cạnh là một kết nối giữa 2 nút. Ví dụ: nút Người dùng có thể được kết nối với ảnh và nút Ảnh có thể được kết nối với bình luận. Ví dụ về cURL dưới đây sẽ trả về danh sách ảnh mà một người đã đăng lên Facebook.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

Mỗi ID được trả về biểu thị một nút Ảnh và thời điểm tải ảnh đó lên Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

Trường

Trường là thuộc tính của nút. Khi bạn truy vấn nút hoặc cạnh, nút/cạnh đó sẽ trả về tập hợp các trường theo mặc định, như ví dụ ở trên. Tuy nhiên, bạn có thể chỉ định các trường mình muốn được trả về bằng cách sử dụng thông số fields và liệt kê từng trường. Hành động này sẽ ghi đè các giá trị mặc định và chỉ trả về những trường bạn chỉ định và ID của đối tượng - đây là giá trị luôn được trả về.

Yêu cầu cURL dưới đây có đưa vào thông số fields cũng như tên, email và ảnh đại diện của Người dùng.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

Dữ liệu được trả về

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

Thông số phức tạp

Hầu hết các loại thông số đều là loại dữ liệu gốc đơn giản, chẳng hạn như bool, string và int. Tuy nhiên, bạn cũng có thể chỉ định các loại list và object 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}

Đăng, cập nhật và xóa

Hãy xem hướng dẫn Chia sẻ trên Facebook của chúng tôi để tìm hiểu cách đăng lên Facebook của Người dùng hoặc tham khảo tài liệu về API Trang để đăng lên bảng tin Facebook của Trang.

Một số nút cho phép bạn cập nhật các trường bằng thao tác POST. Ví dụ: bạn có thể cập nhật trường email như sau:

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

Đọc sau khi ghi

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

Theo mặc định, hệ thống sẽ trả về ID của đối tượng được tạo hoặc cập nhật. Để đưa thêm thông tin vào phản hồi, hãy thêm 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 bảng tin của Trang, bạn có thể thực hiện yêu cầu sau:

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"
Mã mẫu ở trên đã được định dạng để dễ đọc.

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": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

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 một trường không tồn tại), API Đồ thị sẽ phản hồi bằng phản hồi lỗi tiêu chuẩn. Hãy truy cập hướng dẫn Xử lý lỗi của chúng tôi để biết thêm thông tin.

Bạn thường có thể xóa một nút, như nút Bài viết hoặc Ảnh, bằng cách thực hiện thao tác DELETE trên ID đối tượng:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

Thông thường, bạn chỉ có thể xóa các nút mình đã tạo, nhưng hãy xem hướng dẫn tham khảo của mỗi nút để biết các yêu cầu đối với thao tác xóa.

Webhooks

Bạn có thể đăng ký nhận webhooks để được thông báo về những thay đổi đối với nút hoặc hoạt động tương tác với nút. Hãy xem bài viết Webhooks.

Phiên bản

API Đồ thị có nhiều phiên bản, các phiên bản được phát hành hàng quý. Bạn có thể chỉ định phiên bản trong lệnh gọi bằng cách thêm chữ cái "v" và số phiên bản vào đầu đường dẫn yêu cầu. Ví dụ: dưới đây là lệnh gọi đến phiên bản 4.0:

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

Nếu bạn không thêm số phiên bản, chúng tôi sẽ đặt mặc định thành phiên bản có sẵn cũ nhất. Do đó, bạn nên thêm số phiên bản trong yêu cầu của mình.

Bạn có thể đọc thêm về phiên bản trong Hướng dẫn về cách lập phiên bản của chúng tôi và tìm hiểu tất cả các phiên bản có sẵn trong Nhật ký thay đổi API Đồ thị.

API, SDK và nền tảng của Facebook

Hãy kết nối các giao diện và phát triển trên nhiều nền tảng bằng cách sử dụng những API, SDK và nền tảng khác nhau của Facebook.

Các bước tiếp theo

Bắt đầu sử dụng API Đồ thị - Hãy khám phá Đồ thị mạng xã hội của Facebook bằng công cụ Trình khám phá đồ thị và chạy một số yêu cầu để lấy dữ liệu.