API Đồ thị

Yêu cầu hàng loạt

Gửi một yêu cầu HTTP duy nhất chứa nhiều lệnh gọi API Đồ thị trên Facebook. Các thao tác độc lập được xử lý song song, còn các thao tác phụ thuộc được xử lý tuần tự. Sau khi hoàn tất mọi thao tác, một phản hồi hợp nhất sẽ được chuyển lại cho bạn và kết nối HTTP đóng lại.

Thứ tự của các phản hồi tương ứng với thứ tự của các thao tác trong yêu cầu. Bạn nên xử lý các phản hồi tương ứng để xác định thao tác nào thành công và thao tác nào cần thử lại trong thao tác tiếp theo.

Các giới hạn

  • Chỉ được thực hiện tối đa 50 yêu cầu mỗi loạt. Mỗi lệnh gọi trong loạt được tính riêng nhằm mục đích tính toán giới hạn lệnh gọi API và giới hạn tài nguyên. Chẳng hạn, một loạt gồm 10 lệnh gọi API sẽ được tính là 10 lệnh gọi và mỗi lệnh gọi trong loạt góp phần vào giới hạn tài nguyên CPU theo cùng cách thức. Vui lòng xem Hướng dẫn giới hạn tốc độ của chúng tôi để biết thêm thông tin.
  • Yêu cầu hàng loạt không được chứa nhiều Nhóm quảng cáo trong cùng một Chiến dịch. Hãy tìm hiểu thêm về cách tạo yêu cầu API Marketing hàng loạt.

Yêu cầu hàng loạt

Yêu cầu hàng loạt nhận một đối tượng JSON chứa một mảng yêu cầu của bạn. Yêu cầu này trả về một mảng phản hồi HTTP logic được biểu thị dưới dạng mảng JSON. Mỗi phản hồi có một mã trạng thái, một mảng tiêu đề không bắt buộc và một phần nội dung tùy chọn (là chuỗi JSON được mã hóa).

Để thực hiện yêu cầu hàng loạt, hãy gửi yêu cầu POST đến điểm cuối mà thông số batch là đối tượng JSON của bạn.

POST /ENDPOINT?batch=[JSON-OBJECT]

Yêu cầu hàng loạt mẫu

Trong ví dụ này, chúng tôi lấy thông tin về 2 Trang mà ứng dụng của chúng tôi quản lý.

Được định dạng để dễ đọc.
curl -i -X POST 'https://graph.facebook.com/me?batch=  
  [
    {
      "method":"GET",
      "relative_url":"PAGE-A-ID"
    },  
    {
      "method":"GET",
      "relative_url":"PAGE-B-ID"
    }
  ]
  &include_headers=false             // Included to remove header information
  &access_token=ACCESS-TOKEN'

Sau khi hoàn tất mọi thao tác, lệnh sẽ trả về phản hồi kèm theo kết quả của từng thao tác. Các tiêu đề trả về đôi khi có thể lớn hơn nhiều so với phản hồi API thực tế. Do vậy, bạn nên gỡ các tiêu đề để tăng hiệu quả. Để bao gồm thông tin tiêu đề, hãy gỡ thông số include_headers hoặc đặt thông số này thành true.

Ví dụ về phản hồi

Trường nội dung chứa một đối tượng JSON được mã hóa theo chuỗi:

[
  {
    "code": 200,
    "body": "{
      \"name\": \"Page A Name\",
      \"id\": \"PAGE-A-ID\"
      }"
  },
  {
    "code": 200,
    "body": "{
      \"name\": \"Page B Name\",
      \"id\": \"PAGE-B-ID\"
      }"
  }
]

Yêu cầu hàng loạt phức tạp

Bạn có thể kết hợp các thao tác thường sử dụng những phương thức HTTP khác nhau thành một yêu cầu hàng loạt. Mặc dù thao tác GET và DELETE chỉ được có một relative_url và một trường method, nhưng thao tác POST và PUT có thể chứa trường body tùy chọn. Bạn nên định dạng phần nội dung này ở dạng chuỗi HTTP POST thô, tương tự như chuỗi truy vấn URL.

Ví dụ về yêu cầu

Trong ví dụ sau đây, chỉ với một thao tác, bài viết được đăng lên Trang mà chúng tôi quản lý và có quyền đăng, rồi đăng lên bảng tin của Trang:

curl "https://graph.facebook.com/PAGE-ID?batch=
  [
    { 
      "method":"POST",
      "relative_url":"PAGE-ID/feed",
      "body":"message=Test status update"
    },
    { 
      "method":"GET",
      "relative_url":"PAGE-ID/feed"
    }
  ]
  &access_token=ACCESS-TOKEN"

Kết quả của lệnh gọi này sẽ là:

[
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"}
       ],
      "body":"{\"id\":\"…\"}"
    },
    { "code": 200,
      "headers": [
          { "name":"Content-Type", 
            "value":"text/javascript; charset=UTF-8"
          },
          { "name":"ETag", 
            "value": "…"
          }
      ],
      "body": "{\"data\": [{…}]}
    }
]

Ví dụ sau đây tạo quảng cáo mới cho một chiến dịch, sau đó lấy thông tin chi tiết về đối tượng mới tạo. Hãy ghi lại URLEncoding cho thông số nội dung:

curl \
-F 'access_token=...' \
-F 'batch=[
  {
    "method":"POST",
    "name":"create-ad",
    "relative_url":"11077200629332/ads",
    "body":"ads=%5B%7B%22name%22%3A%22test_ad%22%2C%22billing_entity_id%22%3A111200774273%7D%5D"
  }, 
  {
    "method":"GET",
    "relative_url":"?ids={result=create-ad:$.data.*.id}"
  }
]' \
https://graph.facebook.com

Ví dụ sau đây thêm nhiều trang vào một Trình quản lý kinh doanh:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[
  {
    "method":"POST",
    "name":"test1",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_1>"
  }, 
  {
    "method":"POST",
    "name":"test2",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_2>"
  }, 
  {
    "method":"POST",
    "name":"test3",
    "relative_url":"<BUSINESS_ID>/owned_pages",
    "body":"page_id=<PAGE_ID_3>"
  }, 
]' \
"https://graph.facebook.com/v12.0"

Trong đó:

  • <ACCESS_TOKEN> là mã truy cập có quyền business_management.
  • <BUSINESS_ID> là ID của Trình quản lý kinh doanh sẽ nhận các trang.
  • <PAGE_ID_n> là các ID Trang sẽ được nhận.

Lỗi

Có khả năng là một trong các thao tác mà bạn yêu cầu gây ra lỗi. Điều này có thể là do bạn không có quyền thực hiện thao tác được yêu cầu chẳng hạn. Phần phản hồi tương tự như API Đồ thị chuẩn nhưng được đưa vào cú pháp phản hồi hàng loạt:

[
    { "code": 403,
      "headers": [
          {"name":"WWW-Authenticate", "value":"OAuth…"},
          {"name":"Content-Type", "value":"text/javascript; charset=UTF-8"} ],
      "body": "{\"error\":{\"type\":\"OAuthException\", … }}"
    }
]

Các yêu cầu khác trong loạt vẫn sẽ hoàn tất thành công và được trả về như thường lệ kèm theo mã trạng thái 200.

Hết thời gian chờ

Các loạt lớn hoặc phức tạp có thể hết thời gian chờ nếu mất quá nhiều thời gian để hoàn tất mọi yêu cầu trong loạt đó. Trường hợp này sẽ dẫn đến việc loạt được hoàn tất một phần. Trong loạt được hoàn tất một phần, các yêu cầu được hoàn tất thành công sẽ trả về kết quả bình thường kèm theo mã trạng thái 200. Phản hồi cho các yêu cầu không thành công sẽ là null. Bạn có thể thử lại bất kỳ yêu cầu không thành công nào.

Lệnh gọi hàng loạt với JSONP

API Loạt hỗ trợ JSONP, cũng giống như phần còn lại của API Đồ thị – hàm gọi lại JSONP được chỉ định bằng cách sử dụng chuỗi truy vấn callback hoặc thông số đăng mẫu.

Sử dụng nhiều mã truy cập

Các yêu cầu riêng lẻ của một yêu cầu hàng loạt có thể chỉ định mã truy cập riêng dưới dạng chuỗi truy vấn hoặc thông số đăng mẫu. Trong trường hợp đó, mã truy cập ở cấp cao nhất được xem là mã dự phòng và sẽ được dùng nếu một yêu cầu riêng lẻ chưa chỉ định rõ mã truy cập.

Điều này có thể hữu ích khi bạn muốn truy vấn API bằng nhiều mã truy cập của Người dùng/Trang hoặc nếu một số lệnh gọi của bạn cần được thực hiện bằng mã truy cập ứng dụng.

Bạn phải thêm mã truy cập làm thông số ở cấp cao nhất ngay cả khi mọi yêu cầu riêng lẻ đều chứa mã truy cập riêng.

Tải dữ liệu nhị phân lên

Bạn có thể tải nhiều mục nhị phân lên trong một lệnh gọi hàng loạt. Để thực hiện việc này, bạn cần thêm mọi mục nhị phân làm file đính kèm multipart/mime vào yêu cầu của mình, đồng thời cần từng thao tác tham chiếu đến các mục nhị phân bằng cách dùng thuộc tính attached_files trong thao tác. Thuộc tính attached_files có thể nhận danh sách tên file đính kèm được phân tách bằng dấu phẩy trong giá trị của thuộc tính.

Ví dụ sau đây cho biết cách tải 2 ảnh lên trong một lệnh gọi hàng loạt:

curl 
     -F 'access_token=…' \
     -F 'batch=[{"method":"POST","relative_url":"me/photos","body":"message=My cat photo","attached_files":"file1"},{"method":"POST","relative_url":"me/photos","body":"message=My dog photo","attached_files":"file2"},]' \
     -F 'file1=@cat.gif' \
     -F 'file2=@dog.jpg' \
    https://graph.facebook.com
-->