バージョン管理
マーケティングAPIの現行バージョンは v20.0です。
Facebookのプラットフォームは、コアと拡張のバージョン管理モデルを採用しています。マーケティングAPIのバージョン管理では、すべての重要な変更が新しいバージョンに取り入れられます。バージョンごとに異なる機能を持った複数のバージョンのマーケティングAPIやSDKが同時に存在する可能性があります。
開発者は、マーケティングAPIまたはSDKがいつ変更されるかを事前に把握しておいてください。開発者には変更を導入するために90日の猶予期間が与えられますが、新バージョンに移行する方法と時期の選択は開発者に委ねられます。
バージョンスケジュール
マーケティングAPIの新しいバージョンがリリースされた後も、少なくとも90日間は以前のバージョンのマーケティングAPIがサポートされます。新しいバージョンに移行するには、90日以上の猶予期間があります。この90日の猶予期間中は新旧両方のバージョンを呼び出すことができ、開発者はこの期間を利用して新バージョンに移行できます。90日の猶予期間が終わると、旧バージョンは機能しなくなります。バージョンが利用できなくなると、そのバージョン番号に対する呼び出しは失敗するか、次に利用可能なバージョンに自動アップグレードされる可能性があります。
たとえば、マーケティングAPI v17.0が2023年5月23日にリリースされ、マーケティングAPI v16.0が2024年2月6日に期限切れとなりました。このように、新しいバージョンに移行するまで90日以上の猶予期間が設けられました。
以下は、タイムラインの例です。必ずしも、旧バージョンが廃止される90日の猶予期間が終わる時に、新しいバージョンがリリースされるわけではありません。この例では、v18.0がリリースされる少し前にv16.0が廃止されています。
SDKはダウンロード可能なパッケージであるため、どのバージョンも常に利用可能ですが、サポート終了日を過ぎると、依存しているマーケティングAPIやメソッドが機能しなくなる可能性があるため、サポートが終了したSDKも機能しなくなると想定しておいてください。
バージョン指定リクエストの実行
マーケティングAPIのすべてのエンドポイントは、バージョン指定パスを介して使用できます。そのためには、リクエストパスの先頭にバージョンを付加します。以下はその例です。
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v20.0/me/adaccounts"
この方法はすべてのバージョンに対して機能します。一般的な形式は次のとおりです。
https://graph.facebook.com/v{n}/{request-path}ここで、nは必要なバージョンです。利用可能なバージョンの全一覧については、更新履歴をご覧ください。各バージョンの詳細な情報はマーケティングAPIリファレンスで参照できます。
マイグレーション
マイグレーションは、バージョン管理では対応できない変更を行う必要がある特殊な状況でのみ使用されます。典型的な例は、基礎となるデータモデルが変更された場合です。マイグレーションはすべてのバージョンに適用されます。
現在進行中のマイグレーションのリストは、マイグレーションページにあります。マイグレーションには最低90日間の移行期間があり、この期間中にアプリを移行する必要があります。移行期間が始まると、移行後の動作が、新しいアプリのデフォルトとなります。マイグレーション期間が終わると、マイグレーション前の動作は一切使用できなくなります。
グラフAPIでマイグレーションを管理する
マイグレーションは、/appノード内のマイグレーションフィールドで管理できます。
エッジに対してアップデート呼び出しを実行して、マイグレーションのアクティブ化と非アクティブ化ができます。
アプリダッシュボードでマイグレーションを管理する
アプリダッシュボードの[設定] > [マイグレーション]で、利用可能なマイグレーションのアクティブ化と非アクティブ化ができます。利用可能なマイグレーションはアプリと時期によって異なるため、マイグレーションのリストは以下の画像と異なる場合があります。また、マイグレーションUse Graph API v2.0 by defaultが表示される場合、それはグラフAPIのみを対象とし、マーケティングAPIを対象としていません。
クライアント側での一時的なマイグレーションのアクティベーション
アプリダッシュボードでまたはマーケティングAPIを使用してマイグレーションをアクティブ化するのではなく、マイグレーションを設定する特別なフラグをマーケティングAPI呼び出しに追加することもできます。このフラグはmigrations_overrideという名前で、どのマイグレーションをオンまたはオフにするかを定義するJSON blobを指定する必要があります。たとえば、raw呼び出しを実行する場合、次のように指定できます。
http://graph.facebook.com/path?
migrations_override={"migration1":true, "migration2":false}この方法では、すべての呼び出し元を同時に更新して新しいマーケティングAPIを呼び出すようにしなくても、クライアントアップデートによって新しいマーケティングAPIを呼び出すことができます。これはデバッグにも大変便利です。
これらのマイグレーションの名前は、上記の/appノードで参照できます。
バージョン自動アップグレード
Metaは約4か月ごとにマーケティングAPIバージョンが変更されると想定して、アップグレードプロセスを効率化しています。2024年5月より、バージョン間で影響を受けない、マーケティングAPIエンドポイントの自動バージョンアップグレード機能を有効にします。これは廃止されるバージョンと次の利用可能なバージョンとの間で、エンドポイントに影響がなかった場合、プラットフォームはリクエストを直ちに失敗にするのではなく、次の利用可能のバージョンに呼び出しをアップグレードします。この変更は、よりスムーズで効率的なAPIエクスペリエンスを確保するためのものです。
たとえば、2024年5月14日にv17.0が廃止されます。v18.0の更新履歴によれば、次のエンドポイントが影響を受けます。
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
v17.0が2024年5月14日に廃止された後、アプリがv17.0でPOST /{adset-id}を呼び出した場合、次の利用可能なバージョン(v18.0)に影響されるこのエンドポイントには自動アップグレードは適用されないため、このAPIリクエストは失敗します。
廃止後にアプリがv17.0でGET /{ad-account-id}/insightsを呼び出した場合、プラットフォームは次の利用可能なバージョン(v18.0)に呼び出しをアップグレードします。
注: アプリがすでにv17.0より高いバージョンで呼び出しを行っている場合、バージョン廃止日に変更されることは何もありません。
各バージョンで影響を受けるエンドポイントを確認するには、マーケティング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''