Giới hạn và cách làm tốt nhất

API Thông tin chi tiết của Facebook cung cấp dữ liệu về hiệu quả từ các chiến dịch marketing trên Facebook. Để bảo vệ tính ổn định và hiệu quả của hệ thống, chúng tôi có các biện pháp phòng ngừa để phân bổ đồng đều tài nguyên hệ thống giữa các ứng dụng. Tất cả chính sách chúng tôi mô tả bên dưới đều chịu sự thay đổi.

Giới hạn dữ liệu trên mỗi lệnh gọi

Chúng tôi sử dụng giới hạn dữ liệu trên mỗi lệnh gọi để ngăn truy vấn truy xuất quá nhiều dữ liệu vượt quá giới hạn mà hệ thống có thể xử lý. Có 2 loại giới hạn dữ liệu:

1. Theo số hàng trong phản hồi và
2. Theo số điểm dữ liệu được cần có để tính tổng số, chẳng hạn như hàng tóm tắt.

Các giới hạn này áp dụng cho cả lệnh gọi /insights đồng bộ lẫn không đồng bộ và chúng tôi sẽ trả về lỗi sau đây:

error_code = 100,  CodeException (error subcode: 1487534)

Cách làm tốt nhất, giới hạn dữ liệu trên mỗi lệnh gọi

• Giới hạn truy vấn của bạn bằng cách giới hạn khoảng ngày hoặc số lượng ID quảng cáo. Bạn cũng có thể giới hạn truy vấn của mình ở các số liệu cần thiết hoặc chia nhỏ thành nhiều truy vấn với mỗi truy vấn yêu cầu một nhóm số liệu nhỏ.
• Tránh các truy vấn ở cấp tài khoản bao gồm số liệu chia nhỏ có nhiều giá trị riêng biệt, chẳng hạn như action_target_id hoặc product_id và các khoảng ngày rộng hơn như trọn đời.
• Sử dụng cạnh /insights trực tiếp với các đối tượng quảng cáo cấp thấp hơn để truy xuất dữ liệu chi tiết cho cấp đó. Ví dụ: trước tiên, hãy sử dụng truy vấn cấp tài khoản để tìm nạp danh sách ID đối tượng cấp thấp hơn với các thông số level và filtering. Trong ví dụ này, chúng tôi tìm nạp tất cả chiến dịch đã ghi một số lượt hiển thị:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=campaign' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0}]' \
'https://graph.facebook.com/v2.7/act_<ACCOUNT_ID>/insights'

• Sau đó, chúng tôi có thể sử dụng /<campaign_id>/insights với mỗi giá trị được trả về để truy vấn và nhóm các yêu cầu thông tin chi tiết cho những chiến dịch này trong một lệnh gọi:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'batch=[ \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_1>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_2>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  }, \
  { \
    "method": "GET", \
    "relative_url": "v21.0/<CAMPAIGN_ID_3>/insights?fields=impressions,spend,ad_id,adset_id&level=ad" \
  } \
]' \
'https://graph.facebook.com'

• Chỉ sử dụng thông số filtering để truy xuất thông tin chi tiết cho các đối tượng quảng cáo có dữ liệu. Giá trị trường đã chỉ định trong filtering sử dụng ký hiệu DOT để biểu thị các trường thuộc đối tượng. Vui lòng lưu ý rằng việc lọc bằng STARTS_WITH và CONTAIN sẽ không thay đổi dữ liệu tóm tắt. Trong trường hợp này, hãy sử dụng toán tử IN. Hãy xem ví dụ dưới đây về yêu cầu filtering:

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'level=ad' \
-d 'filtering=[{field:"ad.impressions",operator:"GREATER_THAN",value:0},]' \
'https://graph.facebook.com/v21.0/act_<ACCOUNT_ID>/insights'

• Sử dụng date_preset nếu có thể. Khoảng ngày tùy chỉnh ít hiệu quả hơn khi chạy trong hệ thống của chúng tôi.
• Sử dụng yêu cầu hàng loạt cho nhiều lệnh gọi đồng bộ và không đồng bộ để truy vấn lượng dữ liệu lớn nhằm tránh hết thời gian chờ.
• Trước tiên, thử dùng lệnh gọi đồng bộ, sau đó sử dụng lệnh gọi không đồng bộ trong trường hợp lệnh gọi đồng bộ hết thời gian chờ
• Thông tin chi tiết làm mới 15 phút một lần và không thay đổi sau 28 ngày từ khi được báo cáo

Giới hạn tải lệnh gọi thông tin chi tiết

Trong vòng 90 ngày kể từ khi phát hành phiên bản 3.3 và có hiệu lực đối với tất cả phiên bản công khai, chúng tôi sẽ thay đổi giới hạn tốc độ ở cấp tài khoản quảng cáo để thể hiện chính xác hơn lượng lệnh gọi API cần thiết. Chúng tôi sẽ tính hạn mức giới hạn tốc độ này dựa trên cấp truy cập API Marketing bạn có và doanh nghiệp sở hữu ứng dụng của bạn. Hãy xem bài viết Truy cập và xác thực. Thay đổi này áp dụng cho tất cả điểm cuối API Thông tin chi tiết về quảng cáo: GET {adaccount_ID}/insights, GET {campaign_ID}/insights, GET {adset_ID}/insights, GET {ad_ID}/insights, POST {adaccount_ID}/insights, POST {campaign_ID}/insights, POST {adset_ID}/insights, POST {ad_ID}/insights.

Chúng tôi sử dụng giới hạn tải để mang đến trải nghiệm báo cáo tối ưu. Chúng tôi đo lường các lệnh gọi API để biết tốc độ của chúng cũng như mức tài nguyên mà các lệnh này cần. Chúng tôi cho phép giới hạn tải cố định cho mỗi ứng dụng mỗi giây. Khi bạn vượt quá giới hạn đó, yêu cầu sẽ không thực hiện được.

Kiểm tra tiêu đề HTTP x-fb-ads-insights-throttle trong mỗi phản hồi API để biết ứng dụng của bạn sắp đạt đến giới hạn chưa, cũng như ước tính kích thước của một truy vấn cụ thể. Các lệnh gọi thông tin chi tiết cũng phải chịu giới hạn mặc định cho tài khoản quảng cáo được hiển thị trong tiêu đề HTTP x-ad-account-usage. Bạn có thể tìm thêm thông tin chi tiết tại đây API Marketing, Cách làm tốt nhất

Sau khi một ứng dụng đạt đến giới hạn, lệnh gọi sẽ nhận được một phản hồi lỗi với error_code = 4, CodedException. Bạn nên giữ ổn định ở dưới mức giới hạn. Nếu ứng dụng của bạn đạt đến giới hạn cho phép, chỉ một tỷ lệ phần trăm yêu cầu nhất định mới được thông qua, tùy theo truy vấn và tốc độ.

Chúng tôi áp dụng giới hạn tốc độ cho từng ứng dụng gửi kết hợp cả lệnh gọi /insights đồng bộ và không đồng bộ. 2 giới hạn thông số chính được tính theo ứng dụng và theo tài khoản quảng cáo.

Dưới đây là ví dụ về tiêu đề HTTP với điểm số tích lũy của một ứng dụng tính theo tỷ lệ phần trăm của giới hạn:

X-FB-Ads-Insights-Throttle: { "app_id_util_pct": 100, "acc_id_util_pct": 10, "ads_api_access_tier": "standard_access" }

Tiêu đề "x-fb-ads-insights-throttle" là một giá trị JSON chứa các thông tin sau đây:

• app_id_util_pct - Tỷ lệ phần trăm dung lượng được phân bổ cho app_id liên kết đã sử dụng.
• acc_id_util_pct - Tỷ lệ phần trăm dung lượng được phân bổ cho account_id quảng cáo liên kết đã sử dụng.
• ads_api_access_tier - Cấp truy cập cho phép ứng dụng của bạn truy cập vào API Marketing. standard_access hỗ trợ giới hạn tốc độ thấp hơn.

Giới hạn tốc độ trên toàn cầu

Trong khoảng thời gian mà dung lượng tải trên toàn cầu đến điểm cuối /insights tăng cao, hệ thống có thể giới hạn số lượng yêu cầu để bảo vệ môi trường phụ trợ. Việc này có thể xảy ra trong một số ít trường hợp khi có quá nhiều truy vấn với độ phức tạp cao (khoảng thời gian lớn, số liệu phức tạp và/hoặc nhiều ID đối tượng quảng cáo) xuất hiện cùng một lúc. Khi đó, hệ thống sẽ biểu thị bằng một lỗi có dạng như sau:

error_code = 4,  CodeException (error subcode: 1504022), error_title: Too many API requests

Trong những khoảng thời gian như vậy, bạn nên giảm bớt số lệnh gọi, chờ một chút rồi truy vấn lại.

Cách làm tốt nhất đối với giới hạn tốc độ

• Nếu bạn gửi một vài truy vấn cùng lúc, giới hạn tốc độ của chúng tôi có nhiều khả năng sẽ bị kích hoạt. Hãy cố truyền các truy vấn /insights bằng cách điều tiết chúng theo thời gian chờ trong tác vụ.
• Sử dụng thông tin về tốc độ trong tiêu đề phản hồi HTTP để điều tiết lệnh gọi của bạn. Hãy thêm cơ chế chờ để truyền nhằm giảm hoặc tạm dừng các truy vấn /insights khi bạn sắp đạt đến mức sử dụng 100% của ứng dụng hoặc tài khoản quảng cáo.
• Chúng tôi báo cáo dữ liệu thông tin chi tiết về quảng cáo theo múi giờ của tài khoản quảng cáo. Để truy xuất dữ liệu thông tin chi tiết cho tài khoản quảng cáo được liên kết hàng ngày, hãy xem xét thời gian trong ngày bằng múi giờ của tài khoản. Điều này sẽ giúp điều tiết truy vấn trong ngày.
• Kiểm tra ads_api_access_tier cho phép bạn truy cập vào API Marketing. Theo mặc định, ứng dụng của bạn ở cấp development_access và Standard_access hỗ trợ giới hạn tốc độ thấp hơn. Nếu muốn tăng giới hạn tốc độ và có cấp tiêu chuẩn, bạn có thể đăng ký "Quyền truy cập tiêu chuẩn" cho tính năng Quyền quản lý quảng cáo tiêu chuẩn.

Tác vụ không đồng bộ của API Thông tin chi tiết

Tìm nạp số liệu thống kê về nhiều đối tượng, áp dụng tính năng lọc và sắp xếp. Chúng tôi đã tinh giản quy trình không đồng bộ:

1. Gửi yêu cầu POST đến điểm cuối <AD_OBJECT>/insights. Thao tác này sẽ trả về id cho một Lượt chạy báo cáo quảng cáo.

{
  "report_run_id": 6023920149050,
}
    

Không lưu trữ report_run_id để sử dụng lâu dài. ID đó sẽ hết hạn sau 30 ngày.

1. Lượt chạy báo cáo quảng cáo chứa thông tin về tác vụ không đồng bộ này, chẳng hạn như async_status. Hãy thăm dò trường này cho đến khi async_status là Job Completed và async_percent_completion là 100.

{
  "id": "6044775548468",
  "account_id": "1010035716096012",
  "time_ref": 1459788928,
  "time_completed": 1459788990,
  "async_status": "Job Completed",
  "async_percent_completion": 100
}
    

1. Sau đó, bạn có thể truy vấn cạnh <AD_REPORT_RUN_ID>/insights để tìm nạp kết quả cuối cùng.

{
  "data": [
    {
      "impressions": "9708",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    },
    {
      "impressions": "18841",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}
    

Tác vụ này lấy tất cả số liệu thống kê cho tài khoản và trả về ID tác vụ không đồng bộ:

curl \
  -F 'level=campaign' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/<CAMPAIGN_ID>/insights
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000002
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/1000003/insights

Trạng thái tác vụ không đồng bộ

Xuất báo cáo

Chúng tôi cung cấp một điểm cuối thuận tiện để xuất <AD_REPORT_RUN_ID> thành một định dạng bản địa hóa mà con người có thể đọc được.

Lưu ý: điểm cuối này không thuộc API Đồ thị được lập phiên bản của chúng tôi và do đó không tuân thủ chính sách về thay đổi quan trọng của API này. Các tập lệnh và chương trình không nên dựa vào định dạng của kết quả vì định dạng này có thể thay đổi bất ngờ.

  curl -G \
  -d 'report_run_id=<AD_REPORT_RUN_ID>' \
  -d 'name=myreport' \
  -d 'format=xls' \
'https://www.facebook.com/ads/ads_insights/export_report/'