Skip to main content
X Ads API の過去バージョンに関する最新情報については、以下の情報を参照してください。

​
概要

私たちは毎月、X Ads API に変更を加え、いくつかの新機能をリリースしています。これらの変更はほぼ常に後方互換ですが、毎年いくつかの破壊的変更が発生します。私たちは開発者から、新機能の実装、非推奨対応、変更のテストに関して、Ads API の速い変更サイクルが開発サイクルに与える課題についてフィードバックを受け取ってきました。私たちは Ads プラットフォームを利用する際の開発体験を改善したいと考えており、そのためにエンドポイントのバージョニングという概念を導入しました。 以下はいくつかの概念の定義です。 Version: Ads API リクエストの URL パスに含まれるバージョン番号を指します。例: GET //accounts。このバージョニングスタイルは URI versioning として知られています。 Breaking Changes: 破壊的変更とは、既存機能を維持するために開発者リソースを必要とする変更のことです。これには、行うべき変更の調査、非推奨となる機能・エンドポイントの特定、これらすべての変更の最終実装に使用されるリソースが含まれます。破壊的変更の例は次のとおりです。
  • API リクエスト/レスポンスからパラメーターを削除
  • パラメーターまたはエンドポイント名の変更
  • 値の表現の変更(preview_url → card_uri)
  • エンドポイントの動作の変更(例: async か sync の stats)
  • 任意または必須パラメーターの追加/変更(例: リクエストで name を必須フィールドにする)
Deprecation(非推奨): 非推奨となったバージョンや製品はサポート対象外となり、これらの API の使用を止めることが推奨されます。 Sunset(廃止): 製品や API が廃止されると、対応するエンドポイントのセットは API 経由でアクセスできなくなります。

​
バージョニング戦略

戦略の主な原則:
  1. すべての破壊的変更は新しいバージョンにまとめられる
  2. 新しいバージョンが発表された時点で、既存バージョンの非推奨期間は 6 か月
  3. 任意の時点で、API は 2 つのバージョンからのリクエストを同時に許可するが、2 つのうち古い方はサポート対象外
  4. 新製品の迅速な採用を可能にするため、これらは(バージョニングのケイデンス外で)継続的にリリースされる
  5. すべての API レスポンスには、現在の API バージョンに設定される x-current-api-version が含まれる。加えて、非推奨の API エンドポイントを呼び出すと x-api-warn ヘッダーも返される。
破壊的な API 変更を必要とする根本的な製品要件変更(たとえば、複数の年齢バケットターゲティングの廃止など)が発生した場合は、90 日前通知を行い、通知が公開されてから少なくとも 90 日後にその破壊的変更が展開されます。

​
v9

本日、2021 年 3 月 3 日、X Ads API の Version 9 (v9) が利用可能になりました。このリリースは機能パリティの向上、キャンペーン作成の簡素化、そして Card および Mobile App Promotion エンドポイントの重要な更新を導入することを目的としています。 以前のバージョンと同様、v9 への移行期間は 6 か月です。2021 年 8 月 31 日をもって、Ads API の既存 Version 8 (v8) は利用できなくなります。サービス中断を避けるため、すべての開発者はできるだけ早く最新バージョンの Ads API へ移行することを推奨します。
注: このリリースをもって、Ads API の Version 7 (v7) は End of Life(EOL)となり、利用できなくなりました。
詳細は、developer forum のアナウンスをご覧ください。

​
v8

本日、2020 年 9 月 20 日、私たちは X Ads API の Version 8 を導入します。新しい Tailored Audiences 機能の導入、ads.x.com との機能パリティ向上、開発体験の改善を目的としています。 以前のバージョンと同様、v8 への移行期間は 6 か月です。2021-03-02 をもって Ads API の Version 7 は利用できなくなります。サービス中断を避けるため、すべての開発者はできるだけ早く最新バージョンの API へ移行することを推奨します。 詳細は、developer forum のアナウンスをご覧ください。

​
v7

本日、2020 年 3 月 20 日、私たちは X Ads API の Version 7 を導入します。ads.x.com との機能パリティ向上を目的としています。 以前のバージョンと同様、v7 への移行期間は 6 か月です。2020-09-01 をもって Ads API の Version 6 は利用できなくなります。サービス中断を避けるため、すべての開発者はできるだけ早く最新バージョンの API へ移行することを推奨します。Ads API の Version 5 は EOL となり、利用できなくなりました。 詳細は、developer forum のアナウンスをご覧ください。

​
v6

本日、2019 年 8 月 28 日、X は Ads API v6 を導入します。一貫性と開発体験の改善に注力したアップデートを含みます。 このリリースには、Tweet を取得するための新しいエンドポイント、Promoted Account の統計、名前によるエンティティ検索、非同期 analytics ジョブの現在の処理数に関する情報が含まれます。加えて、メディアを使用するエンドポイントおよび targeting criteria エンドポイントに対し、一貫性重視のアップデートを行いました。最後に、一部のパラメーター名およびレスポンス属性を軽微に更新し、Scoped Timeline エンドポイントを非推奨にしています。 詳細は、developer forum のアナウンスをご覧ください。

​
v5

本日、2019 年 2 月 28 日、X は Ads API v5 を導入します。スケールと効率化を可能にすることに注力したアップデートを含みます。 このリリースには、指定期間中にアクティブだったエンティティを判定するための新しいエンドポイント、Media Creatives(X Audience Platform 上の In-stream 動画および画像)の統計、card URI による 複数 の card 取得機能、targeting criteria とその他のエンティティの取得における柔軟性の向上が含まれます。加えて、いくつかのバグ修正、パラメーター名とレスポンス属性の更新も行いました。最後に、non-media app card および POST accounts/:account_id/account_media エンドポイントは非推奨となっています。 以前のバージョンと同様、v5 への移行期間は 6 か月です。2019-08-28 をもって Ads API の Version 4 は利用できなくなります。サービス中断を避けるため、すべてのパートナーはできるだけ早く最新バージョンの API へ移行することを推奨します。Ads API の Version 3 は EOL となり、利用できなくなりました。

​
新機能

アクティブだったエンティティの判定 Active Entities エンドポイントは、広告エンティティの analytics 指標が変化したかどうかを示します。analytics エンドポイントと組み合わせて使用するように設計されており、エンティティタイプと日付範囲(最大 90 日間)を指定することで、プラットフォームが analytics をリクエストすべきエンティティ ID の配列を返します。返された ID 以外は、以降の analytics リクエストで問い合わせるべきではありません。 このエンドポイントは以下のエンティティタイプをサポートします: CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_TWEET。 MEDIA_CREATIVE の統計 Ads API の analytics エンドポイントで、Media Creative エンティティの指標を提供するようになりました。Media Creatives は、X Audience Platform 上での in-stream 広告または画像のプロモート方法です。X Ads UI では、Media Creative 指標は「In-stream videos」および「Display creatives」タブの下に表示されます。同期 および非同期 の analytics エンドポイントの両方が、MEDIA_CREATIVE エンティティ列挙をサポートするようになりました。 複数の card の取得 card URI 値による単一 card の取得を目的としたv3 リリースを改善し、GET accounts/:account_id/cards/all エンドポイントで 複数 の card を取得できるようになりました。これにより、card ごとにリクエストする代わりに、1 リクエストで最大 200 個の card を取得できます。 注意点は 2 つ:
  1. URL パスは accounts/:account_id/cards/all になりました(以前のパスは利用できなくなりました)。これは ID による card 取得用エンドポイントとの整合のためです。
  2. 必須リクエストパラメーターは card_uris(複数形)に変更されました。
取得における柔軟性 GET accounts/:account_id/targeting_criteria エンドポイントは複数の line item ID をサポートするようになりました。最大 200 個の ID を受け付ける line_item_ids パラメーターは必須です。以前は 1 つの line item しか受け付けられず、同期が困難でした。この変更により、より短い時間でより多くの targeting を取得できるようになりました。 以下のエンドポイントも複数の line item ID をサポートするようになりました(これらでは line_item_ids パラメーターは任意です)。

​
変更点

下書きの campaign および line item の取得 下書きの campaign および line item の取得方法が更新されました。今後、with_draft(boolean)パラメーターを true に設定すると、下書きと非下書きの 両方 のエンティティが返されます。これは削除済みエンティティの取得方法(with_deleted の使用)と一貫しています。以前は下書きと非下書きの両方を取得するには少なくとも 2 回のリクエストが必要でしたが、これで 1 回の API 呼び出しで済むようになりました。 | v4 | v5 | | :--- | :--- | :--- | | draft_only | with_draft | | Network activation duration targeting Ads API は、Network Activation Duration targeting を追加した後の表示問題を解決しました。