Управление версиями
Текущая версия Marketing API: v21.0.
На платформе Facebook используются две модели управления версиями: основная и расширенная. Когда нужно внести в работу Marketing API срочные изменения, мы выпускаем новую версию. Одновременно может существовать несколько версий Marketing API или SDK рекламы с разными функциями.
Разработчикам нужно следить за планируемыми изменениями в Marketing API и SDK рекламы. Обычно их необходимо внедрять в течение 90 дней, но вы самостоятельно решаете, как и когда перейти на новую версию.
График выпуска новых версий
После выхода новой версии Marketing API мы поддерживаем предыдущую в течение как минимум 90 дней, чтобы разработчики успели перейти на новую версию. В этот период вызовы принимают обе версии API. Через 90 дней старая версия прекращает работать. Если версия недоступна, все вызовы, выполненные с этим номером версии, могут завершаться ошибкой или автоматически переводиться на следующую доступную версию.
Например, версия Marketing API 17.0 вышла 23 мая 2023 г., а срок действия версии Marketing API 16.0 закончился 6 февраля 2024 г., что оставляет 90 дней для перехода на новую версию.
Ниже приведен пример графика выпуска новых версий и упразднения старых. Обратите внимание: мы не всегда выпускаем новую версию в конце 90-дневного периода, когда срок действия предыдущей версии истекает. В этом примере срок действия версии 16.0 истек несколько раньше, чем мы выпустили версию 18.0:
Старые версии SDK всегда остаются доступными для скачивания, но со временем могут перестать работать, поскольку они обращаются к устаревшим методам или версиям Marketing API.
Отправка запросов с указанием версии
Чтобы получить доступ к какой-либо конечной точке API Marketing, нужно указать его версию в начале пути запроса. Пример:
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v21.0/me/adaccounts"
Общий формат запроса, который подходит для всех версий:
https://graph.facebook.com/v{n}/{request-path}Вместо n подставьте номер версии. Полный список доступных версий см. в журнале изменений. Информация в справке по Marketing API представлена по версиям.
Миграция
Миграция используется только в особых случаях, когда нужно внедрить изменения, которые нельзя включить в новую версию. Обычно так бывает, если меняется базовая модель обработки данных. Миграция применяется ко всем версиям.
Ещё не завершенные миграции перечислены на странице миграций. Окно, в течение которого нужно выполнить миграцию приложения, составляет как минимум 90 дней. Как только начинается этот отсчет, новая послемиграционная модель поведения становится стандартной для всех новых приложений. Когда окно миграции закроется, старая модель поведения будет полностью недоступна.
Управление миграцией с помощью API Graph
Для управления миграцией можно воспользоваться полем migrations в узле /app:
Чтобы активировать или отключить миграцию, выполните вызов обновления на границе контекста.
Управление миграцией с помощью Панели приложений
Доступные миграции можно активировать или деактивировать в панели приложений (в меню Настройки > Миграции). Ваш список может отличаться от показанного на изображении ниже, поскольку он зависит от ваших приложений и текущего периода. Кроме того, в списке может быть миграция Use Graph API v2.0 by default, которая предназначена только для Graph API и не используется для Marketing API.
Временная активация миграции на стороне клиента
Можно не активировать миграцию на Панели приложений или через Marketing API, а добавить в вызовы Marketing API особый флаг для настройки миграции: migrations_override. Для него необходимо указать BLOB-объект JSON с данными о том, какие миграции нужно включить или отключить. Например, при отправке необработанного вызова можно передавать следующие данные:
http://graph.facebook.com/path?
migrations_override={"migration1":true, "migration2":false}Так можно вызывать новую версию Marketing API посредством обновлений клиента, и тогда всем, кто отправляет вызов, не потребуется обновлять его одновременно. Эта функция также очень полезна для отладки.
Названия миграций см. в узле /app, упомянутом выше.
Автоматическое обновление версии
С учетом быстрого обновления версий Marketing API (примерно раз в четыре месяца) мы оптимизируем процесс обновления. С мая 2024 г. мы включим автоматическое обновление версии для конечных точек Marketing API, не претерпевших изменений в новой версии. Если конечная в устаревшей версией и следующей доступной версии не изменилась, платформа обновит вызов до следующей доступной версии, чтобы он не завершался ошибкой. Это изменение должно обеспечить более плавную и эффективную работу API.
Например, 14 мая 2024 г. будет упразднена версия 17.0. Согласно журналу изменений версии 18.0, это затронет следующие конечные точки:
POST /act_{ad-account-id}/reachfrequencypredictions;GET /act_{ad-account-id}/reachestimate;GET /act_{ad-account-id}/delivery_estimate;POST /act_{ad-account-id}/adsets;POST /{adset-id};POST /act_{ad-account-id}/saved_audiences;POST /{saved-audience-id};POST /act_{ad-account-id}/credit_cards.
Если после упразднения 14 мая 2024 г. ваше приложение вызовет конечную точку POST /{adset-id} версии 17.0, этот запрос API завершится ошибкой, поскольку автоматическое обновление не применяется к конечным точкам, которые изменились в следующей доступной версии (18.0).
Если после упразднения ваше приложение вызовет конечную точку GET /{ad-account-id}/insights версии 17.0, платформа обновит ваш вызов и переведет его на следующую доступную версию (18.0).
Примечание. Если ваше приложение уже делает вызовы версий старше 17.0, в день упразднения старой версии ничего не произойдет.
Проверить конечные точки, которые изменяются в каждой конкретной версии, можно в журнале изменений Marketing API.
Часто задаваемые вопросы
График выпуска новых версий
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.
Отправка запросов с указанием версии
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.
Автоматическое обновление версии
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''