Yêu cầu không đồng bộ và yêu cầu hàng loạt

Sử dụng yêu cầu không đồng bộ để tạo quảng cáo và gửi nhiều yêu cầu quảng cáo mà không cần phải chặn. Chỉ định một URL để gọi sau khi yêu cầu hoàn tất hoặc kiểm tra trạng thái của yêu cầu này. Hãy xem Tài liệu tham khảo về quảng cáo.

Cách hiệu quả nhất để quản lý quảng cáo là thông qua yêu cầu hàng loạt. Hãy sử dụng cách này để thực hiện một số yêu cầu phổ biến hơn.

Yêu cầu không đồng bộ

Ví dụ: lấy trạng thái của nhóm yêu cầu không đồng bộ như sau:

curl -G \
  -d 'fields=name,success_count,error_count,is_completed' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

Lệnh gọi này sẽ trả về trạng thái chung của nhóm yêu cầu không đồng bộ dưới dạng một đối tượng JSON. Không phải trường nào cũng hiển thị theo mặc định. Nếu bạn muốn đưa các trường không phải trường mặc định vào truy vấn của mình, hãy chỉ định những trường đó trong fields, chẳng hạn như fields=id,owner_id,name,total_count,success_count,error_count,is_completed.

Tên Mô tả

id

loại: số nguyên

Hiển thị theo mặc định.

id của nhóm yêu cầu không đồng bộ hiện tại.

owner_id

loại: số nguyên

Hiển thị theo mặc định.

Đối tượng sở hữu nhóm yêu cầu không đồng bộ này. Đối với yêu cầu không đồng bộ trên quảng cáo, owner_id sẽ là ID tài khoản.

name

loại: chuỗi

Hiển thị theo mặc định.

Tên của nhóm yêu cầu không đồng bộ này.

is_completed

loại: boolean

Hiển thị theo mặc định.

Các yêu cầu không đồng bộ trong nhóm này đã hoàn tất

total_count

loại: số nguyên

Không hiển thị theo mặc định.

Tổng số lượng yêu cầu của nhóm yêu cầu này

initial_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu chưa được phân phối.

in_progress_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu đang xử lý.

success_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu đã hoàn tất và thành công.

error_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu đã hoàn tất và không thành công.

canceled_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu bị người dùng hủy

notification_uri

loại: chuỗi

Không hiển thị theo mặc định.

URI thông báo cho nhóm yêu cầu không đồng bộ này.

notification_mode

loại: chuỗi

Không hiển thị theo mặc định.

Cách nhận thông báo. Giá trị hợp lệ bao gồm:

  • OFF - Không có thông báo
  • ON_COMPLETE - Gửi thông báo khi toàn bộ nhóm hoàn tất.

Sau khi bạn lấy trạng thái chung của nhóm yêu cầu không đồng bộ, hãy lấy thông tin chi tiết về từng yêu cầu như sau:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests   

Lệnh gọi này sẽ trả về trạng thái và thông tin chi tiết của từng yêu cầu bên trong nhóm yêu cầu không đồng bộ. Đối với trường hợp tạo quảng cáo không đồng bộ, hãy gửi yêu cầu để tạo một quảng cáo. Thông số trạng thái sẽ được dùng để lọc yêu cầu theo trạng thái của chính yêu cầu đó và có thể là bất kỳ tổ hợp giá trị nào dưới đây:

  • initial - Chưa được xử lý.
  • in_progress - Yêu cầu đang xử lý
  • success - Yêu cầu đã hoàn tất và thành công.
  • error - Yêu cầu đã hoàn tất và không thành công
  • canceled - Yêu cầu bị người dùng hủy

Phản hồi là một mảng JSON gồm các trường mặc định. Nếu bạn muốn thêm bất kỳ trường nào không phải trường mặc định, hãy chỉ định trường đó trong fields, chẳng hạn như fields=id,scope_object_id,status,result,input,async_request_set.

Tên Mô tả

id

loại: số nguyên

Hiển thị theo mặc định.

ID yêu cầu không đồng bộ riêng lẻ

scope_object_id

loại: số nguyên

Hiển thị theo mặc định.

ID chính của đối tượng mà yêu cầu này tạo. Nếu bạn tạo một quảng cáo, đây sẽ là ID nhóm quảng cáo cho quảng cáo mới.

status

loại: chuỗi

Hiển thị theo mặc định.

Trạng thái của yêu cầu không đồng bộ này. Tùy chọn:

  • Initial - Chưa được xử lý
  • In_progress - Yêu cầu đang xử lý
  • Success - Yêu cầu đã hoàn tất và thành công
  • Error - Yêu cầu đã hoàn tất và không thành công
  • Canceled - Yêu cầu bị người dùng hủy

result

loại: mảng

Không hiển thị theo mặc định.

Nếu yêu cầu đã hoàn tất, kết quả của yêu cầu này sẽ hiển thị.
Khi thành công, kết quả đó sẽ giống như một yêu cầu không phải yêu cầu không đồng bộ. Ví dụ: nếu bạn tạo một quảng cáo, kết quả của từng yêu cầu sẽ là ID của quảng cáo mới. Trong trường hợp gặp lỗi, kết quả sẽ là một mảng gồm:

  • error_code - Mã lỗi được trả về
  • error_message - Thông báo lỗi

input

loại: đối tượng

Không hiển thị theo mặc định.

Đầu vào gốc cho yêu cầu không đồng bộ này. Nếu bạn tạo một quảng cáo, đầu vào sẽ là adgroup_spec.

async_request_set

loại: đối tượng

Không hiển thị theo mặc định.

Nhóm yêu cầu không đồng bộ chứa yêu cầu riêng lẻ này

Lấy thông tin chi tiết về yêu cầu

Để lấy thông tin chi tiết về một yêu cầu không đồng bộ cụ thể, hãy thực hiện lệnh gọi dưới đây:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests   

Lệnh gọi này sẽ trả về một đối tượng JSON gồm các trường được nêu ở trên.

Liệt kê các nhóm yêu cầu cho một tài khoản

Bạn có thể tạo nhiều nhóm yêu cầu quảng cáo không đồng bộ. Cách truy vấn mọi nhóm yêu cầu quảng cáo không đồng bộ cho một tài khoản quảng cáo như sau:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/asyncadrequestsets  

Lệnh gọi này sẽ trả về một mảng JSON gồm các đối tượng nhóm yêu cầu không đồng bộ. Mỗi đối tượng đều giống như được chỉ định trong phần nhóm yêu cầu không đồng bộ. Bạn có thể lọc kết quả bằng trường is_completed. Nếu is_completed=true, bạn sẽ chỉ thấy nhóm yêu cầu không đồng bộ đã hoàn tất.

Liệt kê các yêu cầu cho một nhóm quảng cáo

Bạn có thể thực hiện một lệnh gọi không đồng bộ để tạo quảng cáo trong các nhóm quảng cáo khác nhau. Để lấy trạng thái của từng nhóm quảng cáo, hãy lấy mọi yêu cầu tạo quảng cáo cho một nhóm quảng cáo như sau:

curl -G \
  -d 'fields=id,status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<AD_SET_ID>/asyncadrequests

Lệnh gọi này sẽ trả về một mảng JSON gồm các đối tượng yêu cầu không đồng bộ. Các trường trạng thái, bộ lọc trường và yêu cầu không đồng bộ sẽ giống như API https://graph.facebook.com/&lt;API_VERSION>/&lt;REQUEST_SET_ID>/requests.

Cập nhật nhóm yêu cầu

Bạn có thể thay đổi name, notification_urinotification_mode cho một nhóm yêu cầu không đồng bộ.

curl \
  -F 'name=New Name' \
  -F 'notification_mode=OFF' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

Lệnh gọi này sẽ trả về true khi cập nhật thành công. Bạn chỉ có thể thay đổi notification_urinotification_mode trước khi thông báo được gửi.

Hủy yêu cầu

Bạn có thể hủy một yêu cầu không đồng bộ, nhưng yêu cầu này chỉ hủy được khi chưa được xử lý.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_ID>

Lệnh gọi này sẽ trả về true khi hủy thành công. Bạn cũng có thể hủy các yêu cầu chưa xử lý trong nhóm yêu cầu không đồng bộ như sau:

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<REQUEST_SET_ID>

Lệnh gọi này sẽ trả về true khi hủy thành công.

Ví dụ về trường hợp không đồng bộ

Lấy trạng thái của một yêu cầu không đồng bộ cụ thể:

//pretty=true for command line readable output
curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "access_token=_____" \
"https://graph.facebook.com/v19.0/"

Trả về các giá trị:

{
   "id": "6012384857989",
   "owner_id": 12345,
   "name": "testasyncset",
   "is_completed": true
}

Lấy kết quả của yêu cầu:

curl -G \
-d "id=6012384857989" \
-d "pretty=true" \
-d "fields=result" \
-d "access_token=_____" \
"https://graph.facebook.com/v19.0/requests"

Trả về:

{
   "data": [
      {
         "result": {
            "id": "6012384860989"
         },
         "id": "6012384858389"
      },
      {
         "result": {
            "id": "6012384858789"
         },
         "id": "6012384858189"
      }
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Lấy danh sách các nhóm yêu cầu cho một tài khoản quảng cáo:

curl -G \
-d "is_completed=1" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v19.0/act_71597454/asyncadrequestsets"

Trả về:

{
   "data": [
      {
         "id": "6012384253789",
         "owner_id": 71597454,
         "name": "testasyncset",
         "is_completed": true
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

Lấy danh sách các yêu cầu cho một chiến dịch:

curl -G \
-d "status=SUCCESS,ERROR" \
-d "pretty=true" \
-d "access_token=___" \
"https://graph.facebook.com/v19.0/6008248529789/asyncadrequests"
    

Trả về các giá trị:

{
   "data": [
      {
         "id": "6012384951789",
         "scope_object_id": 6008248529789,
         "status": "SUCCESS"
      },
   ],
   "paging": {
      "cursors": {
         "after": "___",
         "before": "___"
      }
   }
}

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

Với yêu cầu hàng loạt, bạn có thể kết hợp một số lệnh gọi API Đồ thị thành một yêu cầu HTTP. API Marketing sẽ chia yêu cầu này thành các yêu cầu thành phần tương ứng. Do vậy, yêu cầu hàng loạt trở thành cách hiệu quả nhất để tương tác với API Marketing. Để đạt được hiệu quả cao hơn nữa, bạn có thể gửi các yêu cầu hàng loạt song song qua những luồng xử lý riêng biệt.

Mỗi yêu cầu hàng loạt có thể chứa tối đa 50 yêu cầu. Đối với trường hợp tạo quảng cáo, mỗi yêu cầu hàng loạt chỉ nên chứa tối đa 10 quảng cáo.

Yêu cầu hàng loạt cho quảng cáo, nội dung quảng cáonhóm quảng cáo rất giống nhau nên chúng tôi không thảo luận riêng biệt ở đây. Để biết thêm thông tin, hãy xem phần Yêu cầu hàng loạt trong API Đồ thịETag.

Tạo quảng cáo

Bạn có thể cung cấp nội dung quảng cáo và các đối tượng quảng cáo khác trong một yêu cầu hàng loạt. Ví dụ: bạn có thể tạo 3 quảng cáo dựa trên 1 nội dung quảng cáo và 3 quy cách nhắm mục tiêu khác nhau. Trước tiên, hãy xác định Nội dung quảng cáo của bạn, sau đó tham chiếu đến nội dung này khi bạn tạo từng quảng cáo:

curl -F 'access_token=______' 
  -F 'test1=@./test1.jpg'  
  -F 'batch=[
             {
              "method": "POST",
              "name": "create_adimage",
              "relative_url": "<API_VERSION>/act_187687683/adimages",
              "attached_files": "test1"
             },
             {
              "method": "POST",
              "name": "create_creative",
              "relative_url": "<API_VERSION>/act_187687683/adcreatives",
              "attached_files": "test1",
              "body": "name=sample creative&object_story_spec={\"link_data\": {\"image_hash\": \"{result=create_adimage:$.images.*.hash}\", \"link\": \"https://www.test12345.com\", \"message\": \"this is a sample message\"}, \"page_id\":\"12345678\"}&degrees_of_freedom_spec={\"creative_features_spec\": {\"standard_enhancements\": {\"enroll_status\": \"OPT_OUT\"}}}"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test1"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test2"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/act_187687683/ads",
              "body": "adset_id=6004163746239&redownload=1&status=PAUSED&optimization_goal=REACH&billing_event=IMPRESSIONS&&creative={\"creative_id\":\"{result=create_creative:$.id}\"}&targeting={\"countries\":[\"US\"]}&name=test3"
             }
            ]' https://graph.facebook.com/

Phản hồi sẽ bao gồm các mã phản hồi riêng biệt cho từng yêu cầu và phản hồi API Đồ thị tiêu chuẩn. Để biết chi tiết, hãy xem phần Tạo nhiều yêu cầu API.

Quy trình yêu cầu hàng loạt sử dụng định dạng biểu thức JSONPath để tham chiếu đến các yêu cầu trước đó.

Cập nhật quảng cáo

Bạn có thể cập nhật quảng cáo bằng yêu cầu hàng loạt. Cách cập nhật giá thầu cho 3 quảng cáo như sau:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715639",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": <API_VERSION>/v6004251716039",
              "body": "redownload=1&name=new name"
             },
             {
              "method": "POST",
              "relative_url": "<API_VERSION>/6004251715839",
              "body": "redownload=1&name=new name"
             }
            ]' https://graph.facebook.com

Nếu đưa redownload=1 vào URL tương đối, bạn sẽ lấy được đầy đủ thông tin chi tiết về quảng cáo, bao gồm cả ID quảng cáo. Nhờ vậy, bạn có thể xác định những quảng cáo mình đã cập nhật.

Nếu bạn muốn cập nhật nội dung quảng cáo, hãy chỉ định toàn bộ nội dung hoặc cung cấp một ID nội dung mới. Nguyên nhân là vì bạn không thể chỉnh sửa Nội dung quảng cáo sau khi nội dung đó được tạo, ngoại trừ tên và trạng thái chạy.

Đọc quảng cáo

Nếu bạn có lượng lớn quảng cáo, hãy chia yêu cầu thành nhiều yêu cầu trong một yêu cầu hàng loạt như sau:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/?ids=6003356308839,6004164369439&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356307839/ads&fields=<comma separated list of fields>"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/ads?adset_ids=[6003356307839, 6004164259439]&fields=<comma separated list of fields>"
             }
            ]' https://graph.facebook.com

60033563088396004164369439 là ID quảng cáo, còn 60033563078396004164259439 là ID nhóm quảng cáo.

Thông tin chi tiết về quảng cáo

Nếu bạn có lượng lớn Thông tin chi tiết về quảng cáo, hãy chia yêu cầu thành nhiều yêu cầu trong một yêu cầu hàng loạt như sau:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_19643108/insights?filtering=[{field:'ad.id',operator:'IN',value:[6003356308839,6004164369439]}]"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/6003356308839/insights"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_187687683/insights?filtering=[{field:'adset.id',operator:'IN',value:[6003356307839, 6004164259439]}]"
             }
            ]' https://graph.facebook.com

Trong ví dụ này, 60033563088396004164369439 là ID quảng cáo, còn 60033563078396004164259439 là ID nhóm quảng cáo.

Đối với Tài khoản quảng cáo có lượng lớn quảng cáo, bạn không nên sử dụng act_<account_ID>/adgroupstats vì điểm cuối này có thể khiến yêu cầu bị hết thời gian chờ.

Yêu cầu hàng loạt cho dữ liệu ước tính số người tiếp cận

Bạn có thể yêu cầu tối đa 50 dữ liệu ước tính số người tiếp cận trong một yêu cầu hàng loạt. Ví dụ dưới đây minh họa cách yêu cầu dữ liệu ước tính số người tiếp cận cho 2 quy cách nhắm mục tiêu khác nhau:

curl -F 'access_token=____' 
  -F 'batch=[
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['US']}}"
             },
             {
              "method": "GET",
              "relative_url": "<API_VERSION>/act_600335/reachestimate?targeting_spec={'geo_locations': {'countries':['FR']}}"
             }
            ]' https://graph.facebook.com

API Hàng loạt

Với API Hàng loạt, bạn có thể tạo hàng loạt yêu cầu rồi gửi các yêu cầu đó theo kiểu không đồng bộ. Bạn có thể nhóm một số lệnh gọi API Đồ thị thành một yêu cầu HTTP rồi thực thi chúng theo cách không đồng bộ mà không cần phải chặn. Ngoài ra, bạn có thể chỉ định phần phụ thuộc giữa các hoạt động có liên quan.

Facebook sẽ xử lý từng hoạt động độc lập theo quy trình song song và xử lý các hoạt động phụ thuộc của bạn theo tuần tự. Mỗi lệnh gọi API có thể chứa tối đa 1.000 yêu cầu.

Thực hiện lệnh gọi API Hàng loạt

Cách thực hiện lệnh gọi API Hàng loạt như sau:

curl \
-F "access_token=___" \
-F "name=asyncbatchreqs" \
-F "adbatch=<an array of requests>"\
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/async_batch_requests"

Hãy cung cấp một mảng gồm các yêu cầu HTTP POST dưới dạng mảng JSON. Mỗi yêu cầu có:

  • name
  • relative_url - phần URL sau graph.facebook.com
  • body

API này sẽ trả về một ID mà bạn dùng để truy vấn tiến độ của các yêu cầu.

Ví dụ: tạo một chiến dịch bằng nhóm quảng cáo có Định dạng JSONPath để tham chiếu đến các yêu cầu trước đó như sau:

curl \
-F "access_token=___" \
-F "name=batchapiexample" \
-F "adbatch=[
  {
    'name': 'create-campaign',
    'relative_url': 'act_123456/campaigns',
    'body': 'name%3DTest+Campaign%26objective%3DLINK_CLICKS%26status%3DPAUSED%26buying_type%3DAUCTION',
  },
  {
    'name': 'create-adset',
    'relative_url': 'act_123456/adsets',
    'body': 'targeting%3D%7B%22geo_locations%22%3A%7B%22countries%22%3A%5B%22US%22%5D%7D%7D%26daily_budget%3D5000%26campaign_id%3D%7Bresult%3Dcreate-campaign%3A%24.id%7D%26bid_amount%3D2%26name%3DFirst%2BAd%2BSet%20Test%26billing_event%3DLINK_CLICKS',
  },
]" \
https://graph.facebook.com/<API_VERSION>/act_123456/async_batch_requests

Cách lấy trạng thái nhóm yêu cầu như sau:

curl –G \
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v19.0/<REQUEST_SET_ID>"

Lệnh gọi này sẽ trả về trạng thái chung của các nhóm yêu cầu không đồng bộ dưới dạng đối tượng JSON. Không phải trường nào cũng được trả về theo mặc định. Nếu bạn muốn thêm các trường đó, hãy chỉ định fields, chẳng hạn như fields=id,owner_id,name,total_count,success_count,error_count,is_completed

Tên Mô tả

id

loại: số nguyên

Hiển thị theo mặc định.

id của nhóm yêu cầu không đồng bộ hiện tại.

owner_id

loại: số nguyên

Hiển thị theo mặc định.

Đối tượng sở hữu nhóm yêu cầu không đồng bộ này. Nếu bạn tạo quảng cáo, owner_id sẽ là ID tài khoản quảng cáo.

name

loại: chuỗi

Hiển thị theo mặc định.

Tên của nhóm yêu cầu không đồng bộ này

is_completed

loại: boolean

Hiển thị theo mặc định.

Mọi yêu cầu không đồng bộ trong nhóm đã hoàn tất

total_count

loại: số nguyên

Không hiển thị theo mặc định.

Tổng số lượng yêu cầu cho nhóm yêu cầu này

initial_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu chưa được phân phối

in_progress_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu đang xử lý

success_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu đã hoàn tất và thành công

error_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu đã hoàn tất và không thành công

canceled_count

loại: số nguyên

Không hiển thị theo mặc định.

Số lượng yêu cầu bị người dùng hủy

notification_uri

loại: chuỗi

Không hiển thị theo mặc định.

URI thông báo cho nhóm yêu cầu không đồng bộ này.

notification_mode

loại: chuỗi

Không hiển thị theo mặc định.

Cách nhận thông báo. Giá trị hợp lệ:

  • OFF - Không có thông báo
  • ON_COMPLETE - Gửi thông báo khi toàn bộ nhóm hoàn tất.

notification_result

loại: chuỗi

Không hiển thị theo mặc định.

Kết quả gửi thông báo.

notification_status

loại: chuỗi

Không hiển thị theo mặc định.

Trạng thái thông báo: not_sent, sending hoặc sent

Sau khi lấy trạng thái chung, bạn có thể lấy thông tin chi tiết về từng yêu cầu như sau:

curl –G \   
-d "access_token=___" \
-d "fields=<comma separated list of fields>" \
"https://graph.facebook.com/v19.0/<REQUEST_SET_ID>/requests"

Lệnh gọi này sẽ trả về thông tin chi tiết dưới dạng mảng JSON. Nếu bạn muốn thêm các trường không phải trường mặc định, hãy chỉ định những trường đó trong fields, chẳng hạn như fields=id,scope_object_id,status,result,input,async_request_set.

Tên Mô tả

id

loại: số nguyên

Hiển thị theo mặc định.

ID của yêu cầu không đồng bộ riêng lẻ

scope_object_id

loại: số nguyên

Hiển thị theo mặc định.

ID chính của đối tượng mà yêu cầu này tạo. Nếu bạn tạo quảng cáo, đây sẽ là ID nhóm quảng cáo cho quảng cáo mới.

status

loại: chuỗi

Hiển thị theo mặc định.

Trạng thái của yêu cầu không đồng bộ này:

  • Initial - Chưa được xử lý
  • In_progress - Yêu cầu đang xử lý
  • Success - Yêu cầu đã hoàn tất và thành công
  • Error - Yêu cầu đã hoàn tất và không thành công
  • Canceled - Yêu cầu bị người dùng hủy

result

loại: mảng

Không hiển thị theo mặc định.

Nếu yêu cầu hoàn tất, kết quả sẽ hiển thị. Trong trường hợp thành công, kết quả này sẽ giống như API không phải API không đồng bộ. Ví dụ: nếu bạn tạo quảng cáo, kết quả sẽ là ID quảng cáo mới. Trong trường hợp gặp lỗi:

  • error_code - Mã lỗi được trả về
  • error_message - Thông báo lỗi

input

loại: đối tượng

Không hiển thị theo mặc định.

Đầu vào gốc cho yêu cầu này. Nếu bạn tạo một quảng cáo, đầu vào sẽ là adgroup_spec.

async_request_set

loại: đối tượng

Không hiển thị theo mặc định.

Nhóm yêu cầu không đồng bộ chứa yêu cầu này.

Liệt kê các yêu cầu API Hàng loạt cho tài khoản quảng cáo

Bạn có thể tạo nhiều nhóm yêu cầu API Hàng loạt. Cách truy vấn mọi nhóm yêu cầu trong một tài khoản quảng cáo như sau:

curl –G \ 
-d "access_token=___" \
"https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/async_requests"

ETag

API Marketing hỗ trợ ETag. Nhờ vậy, bạn có thể biết liệu dữ liệu mình truy vấn có thay đổi so với lần kiểm tra gần đây nhất hay không. Cách hoạt động:

  1. Khi bạn thực hiện lệnh gọi, tiêu đề phản hồi sẽ bao gồm một ETag có giá trị là hash của dữ liệu được trả về trong lệnh gọi API. Hãy lưu giá trị ETag này để sử dụng trong bước tiếp theo.
  2. Lần tới khi bạn thực hiện lệnh gọi API tương tự, hãy đưa giá trị ETag bạn đã lưu vào tiêu đề yêu cầu If-None-Match.
  3. Nếu dữ liệu không thay đổi, mã trạng thái phản hồi sẽ là 304 – Not Modified và không có dữ liệu nào được trả về.
  4. Nếu dữ liệu có thay đổi so với lần truy vấn gần đây nhất, dữ liệu sẽ được trả về như bình thường kèm theo một ETag mới. Hãy lưu giá trị ETag mới này và dùng cho các lệnh gọi tiếp theo.

Mặc dù ETag giúp giảm lưu lượng truy cập dữ liệu, nhưng If-None-Match GET vẫn sẽ tính vào giới hạn tốc độ cho ứng dụng của bạn.

ETag được tính dựa trên toàn bộ phản hồi từ lệnh gọi API, bao gồm cả định dạng của phản hồi. Định dạng này có thể chịu ảnh hưởng từ chuỗi tác nhân người dùng. Do đó, bạn cần duy trì sự nhất quán của tác nhân người dùng giữa các lệnh gọi được thực hiện từ cùng một máy khách.

Ví dụ về ETag

Dưới đây là cách kiểm tra xem tài khoản quảng cáo của người dùng có thay đổi hay không.

Bước 1: Xác định ETag cho dữ liệu hiện tại

curl -i "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Phản hồi sẽ như sau:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
ETag: "7776cdb01f44354af8bfa4db0c56eebcb1378975"
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.149.204
X-FB-Debug: CWbHcogdwUE8saMv6ML+8FacXFrE8ufhjjwxU2dQWaA=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:07:44 GMT
Content-Length: 3273

{"data":[{"id":"act.......

Trong ví dụ này, ETag là "7776cdb01f44354af8bfa4db0c56eebcb1378975". Lưu ý rằng ETag có dấu ngoặc kép (").

Bước 2: Xác định xem dữ liệu có thay đổi gì hay không

curl -i -H "If-None-Match: \"7776cdb01f44354af8bfa4db0c56eebcb1378975\"" "https://graph.beta.facebook.com/me/adaccounts?access_token=___"

Nếu không có gì thay đổi, phản hồi sẽ như sau:

HTTP/1.1 304 Not Modified
Access-Control-Allow-Origin: *
Cache-Control: private, no-cache, no-store, must-revalidate
Content-Type: text/javascript; charset=UTF-8
Expires: Sat, 01 Jan 2000 00:00:00 GMT
Pragma: no-cache
X-FB-Rev: 495685
X-FB-Server: 10.30.177.190
X-FB-Debug: ImBhat3k07Nez5FvuS2lPWU0U2xxmxD4B3k9ua4Sk7Q=
X-Cnection: close
Date: Mon, 16 Jan 2012 12:09:17 GMT
Content-Length: 0

Lưu ý phản hồi 304 Not Modified. Nếu dữ liệu có thay đổi, hệ thống sẽ trả về một phản hồi API thông thường.

Dưới đây là ví dụ về yêu cầu hàng loạt để kiểm tra xem quảng cáo của người dùng có thay đổi hay không.

Bước 1: Xác định ETag cho dữ liệu hiện tại

curl -i "curl -F 'access_token=___' -F 'batch=[ 
  {"method":"GET", "relative_url": "?ids=6003356308839,6004164369439" }, 
  {"method":"GET", "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]'
 https://graph.facebook.com"

Phản hồi sẽ chứa các giá trị ETag như sau:

...{"name":"ETag","value":"\"21d371640127490b2ed0387e8af3f0f8c9eff012\""}...      
...{"name":"ETag","value":"\"410e53bb257f116e8716e4ebcc76df1c567b87f4\""}...

Trong ví dụ này, các ETag là "21d371640127490b2ed0387e8af3f0f8c9eff012""410e53bb257f116e8716e4ebcc76df1c567b87f4". Lưu ý rằng ETag có dấu ngoặc kép (").

Bước 2: Xác định xem dữ liệu có thay đổi gì hay không như sau:

curl -F 'access_token=___' -F 'batch=[
  {"method":"GET", "headers":["If-None-Match: \"21d371640127490b2ed0387e8af3f0f8c9eff012\""], "relative_url": "?ids=6003356308839,6004164369439" },
  {"method":"GET",  "headers":["If-None-Match: \"410e53bb257f116e8716e4ebcc76df1c567b87f4\""], "relative_url": "act_12345678/ads?campaign_ids=[6003356307839, 6004164259439]"}]' 
https://graph.facebook.com

Nếu không có gì thay đổi, phản hồi sẽ như sau:

[{
    "code": 304,
    .
    .
    .
    "body": null
},
{
    "code": 304,
    .
    .
    .
    "body": null
}]

Lưu ý phản hồi 304 Not Modified. Nếu dữ liệu có thay đổi, chúng tôi sẽ trả về một phản hồi API thông thường.