Lập phiên bản
Phiên bản hiện tại của API Marketing là v21.0.
Nền tảng của Facebook có mô hình lập phiên bản cốt lõi và mở rộng. Với mô hình lập phiên bản API Marketing, mọi thay đổi quan trọng đều sẽ có trong phiên bản mới. Nhiều phiên bản của API Marketing hoặc SDK có thể tồn tại cùng lúc với chức năng khác nhau trong mỗi phiên bản.
Nhà phát triển cần tìm hiểu trước khi API Marketing hoặc SDK thay đổi. Mặc dù phải áp dụng thay đổi trong khoảng thời gian 90 ngày, nhưng bạn có quyền chọn cách thức và thời điểm chuyển sang phiên bản mới.
Lịch trình phiên bản
Khi phát hành một phiên bản mới của API Marketing, chúng tôi vẫn hỗ trợ phiên bản trước của API Marketing trong tối thiểu 90 ngày. Bạn phải chuyển sang phiên bản mới trong khoảng thời gian ân hạn tối thiểu là 90 ngày. Trong khoảng thời gian ân hạn 90 ngày đó, bạn có thể gọi cả phiên bản hiện tại lẫn phiên bản không dùng nữa, đồng thời phải chuyển sang phiên bản mới. Sau khi hết khoảng thời gian ân hạn 90 ngày, phiên bản không dùng nữa sẽ ngừng hoạt động. Sau khi một phiên bản không khả dụng, các lệnh gọi đến số phiên bản đó có thể không thành công hoặc được nâng cấp lên phiên bản có sẵn tiếp theo.
Ví dụ: API Marketing v17.0 được phát hành vào ngày 23/05/2023 và API Marketing v16.0 hết hạn vào ngày 06/02/2024. Vì vậy, bạn có tối thiểu 90 ngày để chuyển sang phiên bản mới.
Sau đây là lịch trình mẫu. Lưu ý rằng không phải lúc nào chúng tôi cũng phát hành phiên bản mới sau khi hết khoảng thời gian ân hạn 90 ngày ngừng sử dụng phiên bản trước. Trong ví dụ dưới đây, chúng tôi đã ngừng sử dụng v16.0 một thời gian trước khi phát hành v18.0:
Đối với SDK, một phiên bản sẽ luôn hoạt động vì đây là gói có thể tải xuống. Tuy nhiên, sau ngày hết hạn, phiên bản đó có thể dựa vào các phương thức hoặc API Marketing không còn hoạt động. Vì vậy, bạn nên giả định rằng SDK hết hạn không hoạt động nữa.
Gửi yêu cầu có phiên bản
Bạn có thể gửi yêu cầu đến tất cả điểm cuối API Marketing thông qua một đường dẫn có phiên bản. Hãy thêm phiên bản vào đầu đường dẫn yêu cầu này. Ví dụ:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"
Lệnh này hoạt động với tất cả phiên bản theo dạng chung sau:
https://graph.facebook.com/v{n}/{request-path}trong đó n là phiên bản cần thiết. Hãy xem danh sách đầy đủ các phiên bản có sẵn trong Nhật ký thay đổi của chúng tôi. Toàn bộ Tài liệu tham khảo về API Marketing của chúng tôi đều cung cấp thông tin theo phiên bản.
Hoạt động chuyển
Hoạt động chuyển chỉ dành cho các tình huống đặc biệt khi cần thay đổi mà không thể lập phiên bản. Thông thường, đây là tình huống mà mô hình dữ liệu cơ bản có sự thay đổi. Hoạt động chuyển áp dụng trên tất cả phiên bản.
Các hoạt động chuyển vẫn đang diễn ra được liệt kê trên trang hoạt động chuyển của chúng tôi. Hoạt động chuyển có khoảng thời gian tối thiểu là 90 ngày. Bạn phải chuyển ứng dụng của mình trong khoảng thời gian này. Sau khi khoảng thời gian chuyển bắt đầu, hành vi sau khi chuyển sẽ trở thành mặc định cho các ứng dụng mới. Sau đó, khi khoảng thời gian chuyển kết thúc, hành vi trước khi chuyển sẽ không còn khả dụng.
Quản lý hoạt động chuyển qua API Đồ thị
Bạn có thể quản lý hoạt động chuyển qua trường migrations trong nút /app:
Bạn có thể thực hiện lệnh gọi cập nhật trên cạnh này để kích hoạt và vô hiệu hóa hoạt động chuyển.
Quản lý hoạt động chuyển qua Bảng điều khiển ứng dụng
Bạn có thể kích hoạt và vô hiệu hóa hoạt động chuyển hiện có trong Bảng điều khiển ứng dụng ở phần Cài đặt > Chuyển. Lưu ý rằng danh sách hoạt động chuyển có thể không giống như trong hình ảnh bên dưới, vì hoạt động chuyển hiện có sẽ khác nhau tùy theo ứng dụng và thời điểm. Nếu bạn nhìn thấy hoạt động chuyển Use Graph API v2.0 by default, hoạt động đó chỉ dành cho API Đồ thị, chứ không phải API Marketing.
Kích hoạt hoạt động chuyển tạm thời phía ứng dụng
Thay vì kích hoạt hoạt động chuyển trong Bảng điều khiển ứng dụng hoặc qua API Marketing, bạn có thể thêm cờ đặc biệt vào lệnh gọi API Marketing để thiết lập hoạt động chuyển. Cờ này có tên là migrations_override và yêu cầu bạn chỉ định blob JSON để mô tả những hoạt động chuyển mà mình muốn bật hoặc tắt. Ví dụ: nếu đang thực hiện lệnh gọi thô, bạn có thể chuyển:
http://graph.facebook.com/path?
migrations_override={"migration1":true, "migration2":false}Bằng cách này, bạn có thể gọi API Marketing mới thông qua bản cập nhật ứng dụng thay vì phải cập nhật tất cả trình gọi để gọi API Marketing mới cùng lúc. Điều này cũng rất hữu ích khi gỡ lỗi.
Bạn có thể tìm thấy tên của các hoạt động chuyển này trên nút /app đã đề cập ở trên.
Tự động nâng cấp phiên bản
Do các phiên bản API Marketing xoay vòng nhanh chóng (khoảng 4 tháng/lần) nên chúng tôi đang tinh giản quy trình nâng cấp. Kể từ tháng 05/2024, chúng tôi sẽ bật tính năng tự động nâng cấp phiên bản cho những điểm cuối API Marketing không bị ảnh hưởng giữa các phiên bản. Tức là nếu một điểm cuối không bị ảnh hưởng giữa phiên bản không dùng nữa và phiên bản có sẵn tiếp theo, nền tảng sẽ nâng cấp lệnh gọi lên phiên bản có sẵn tiếp theo thay vì trực tiếp từ chối yêu cầu. Thay đổi này nhằm mục đích đảm bảo trải nghiệm API mượt mà và hiệu quả hơn.
Ví dụ: chúng tôi sẽ ngừng sử dụng v17.0 từ ngày 14/05/2024. Theo nhật ký thay đổi của v18.0, các điểm cuối sau đây sẽ bị ảnh hưởng:
POST /act_{ad-account-id}/reachfrequencypredictionsGET /act_{ad-account-id}/reachestimateGET /act_{ad-account-id}/delivery_estimatePOST /act_{ad-account-id}/adsetsPOST /{adset-id}POST /act_{ad-account-id}/saved_audiencesPOST /{saved-audience-id}POST /act_{ad-account-id}/credit_cards
Nếu ứng dụng của bạn thực hiện lệnh gọi POST /{adset-id} đến v17.0 sau khi phiên bản này ngừng hoạt động vào ngày 14/05/2024, yêu cầu API nêu trên sẽ không thành công vì tính năng tự động nâng cấp không được áp dụng cho những điểm cuối bị ảnh hưởng bởi phiên bản có sẵn tiếp theo (v18.0).
Nếu ứng dụng của bạn thực hiện lệnh gọi GET /{ad-account-id}/insights đến v17.0 sau khi phiên bản này ngừng hoạt động, nền tảng sẽ nâng cấp lệnh gọi đó lên phiên bản có sẵn tiếp theo (v18.0).
Lưu ý: Nếu ứng dụng của bạn đã thực hiện lệnh gọi đến các phiên bản cao hơn v17.0 thì không có gì thay đổi vào ngày phiên bản ngừng hoạt động.
Để xem các điểm cuối bị ảnh hưởng ở mỗi phiên bản, vui lòng tham khảo Nhật ký thay đổi của API Marketing.
Câu hỏi thường gặp
Lịch trình phiên bản
We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.
You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.
Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.
For example:
- If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
- If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
- Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.
If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:
- If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
- If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.
- Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
- Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
Gửi yêu cầu có phiên bản
With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:
https://graph.facebook.com/v{n}/{request-path}You can know what behavior to expect out without having to manually visit your app's migration panel.
Tự động nâng cấp phiên bản
The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.
No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons
- You may still need to manually upgrade endpoints being impacted by next version.
- You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
You can look up affected endpoints from Marketing API Changelog.
You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.
If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.
Example notification header
X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''