> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# バージョン
X Ads API の過去バージョンに関する最新情報は、以下を参照してください。
| Version | Path | Introduction Date (導入日) | Deprecated Date (非推奨化日) | End of Life Date (サポート終了日) |
| :------------------------------------------------------------- | :--- | :---------------------- | :---------------------- | :------------------------- |
| [12.0](#) | /12/ | 2022年10月27日 | 未定 | 未定 |
| [11.0](https://devcommunity.x.com/t/ads-api-version-11/168814) | /11/ | 2022年3月31日 | 未定 | 未定 |
| [10.0](#v9) | /10/ | 2021年8月31日 | 2022年3月31日 | 2022年10月27日 |
| [9.0](#v9) | /9/ | 2021年3月2日 | 2021年8月31日 | 2022年3月31日 |
| [8.0](#v8) | /8/ | 2020年9月8日 | 2021年3月2日 | 2021年8月31日 |
| [7.0](#v7) | /7/ | 2020年3月3日 | 2020年9月1日 | 2021年3月2日 |
| [6.0](#v6) | /6/ | 2019年8月28日 | 2020年3月3日 | 2020年9月1日 |
| [5.0](#v5) | /5/ | 2019年2月28日 | 2019年8月28日 | 2020年3月3日 |
| [4.0](#v4) | /4/ | 2018年8月28日 | 2019年2月28日 | 2019年8月28日 |
| [3.0](#v3) | /3/ | 2018年2月1日 | 2018年8月28日 | 2019年2月28日 |
| [2.0](#v2) | /2/ | 2017年7月10日 | 2018年2月1日 | 2018年8月1日 |
| [1.0](#v1) | /1/ | 2016年3月31日 | 2017年7月7日 | 2018年1月10日 |
| [0.0](#v0) | /0/ | 2013年2月21日 | 該当なし | 2016年10月31日 |
## 概要
毎月、X Ads API に変更を加え、いくつかの新機能をリリースしています。これらの変更はほとんどの場合、後方互換性がありますが、年間を通じて少数の後方互換性を損なう (ブレイキング) 変更が発生する傾向があります。Ads API に対するこのような変更ペースの速さが、新機能の実装、廃止予定機能への対応、変更のテストといった開発サイクルに与える影響について、開発者の皆さんからフィードバックを受けてきました。私たちは Ads プラットフォームを利用する開発者の体験を向上させたいと考えており、そのためにエンドポイントのバージョニングという概念を導入しました。
ここで扱ういくつかの概念について定義しておきます。
**バージョン (Version) **: Ads API リクエストの URL パスに含まれるバージョン番号を指します。例: GET /{version_number}/accounts。この形式のバージョニングは URI バージョニングとして知られています。
**ブレイキング変更 (Breaking Changes) **: ブレイキング変更とは、既存の機能を維持するために開発リソースを要するあらゆる変更を指します。これには、必要な変更内容の調査、廃止予定となる機能やエンドポイントの特定、これらすべての変更の最終的な実装に要するリソースが含まれます。ブレイキング変更の例としては、次のようなものがあります。
* API リクエストまたはレスポンスからパラメータを削除すること
* パラメータ名またはエンドポイント名を変更すること
* 値の表現方法を変更すること (preview\_url → card\_uri)
* エンドポイントの動作を変更すること (例: 非同期 vs 同期の統計)
* オプションまたは必須パラメータを追加/変更すること (例: リクエスト内で name を必須フィールドにする)
**非推奨 (Deprecation) **: 非推奨となったバージョンやプロダクトはサポート対象外となり、開発者にはそれらの API の利用を中止することを推奨します。
**サンセット (Sunset) **: プロダクトまたは API がサンセットに到達すると、そのプロダクトに対応する一連のエンドポイントには API 経由でアクセスできなくなります。
## バージョニング戦略
この戦略の主な原則は次のとおりです。
1. すべての破壊的変更は新しいバージョンにまとめて反映されます
2. 新しいバージョンがアナウンスされた場合、既存バージョンの非推奨期間は 6 か月です
3. 常に 2 つのバージョンからのリクエストを同時に API が受け付けられるようにしますが、そのうち古いほうのバージョンはサポート対象外となります
4. 新しいプロダクトをより早く導入できるようにするため、これらはバージョニングのサイクルとは別に、継続的にリリースされます
5. すべての API レスポンスには、API の現在のバージョンを示す `x-current-api-version` が含まれ、さらに、非推奨の API エンドポイントを呼び出した場合には `x-api-warn` ヘッダーが含まれます。
複数の年齢バケットターゲティングの非推奨化のような、API に破壊的変更を必要とする根本的なプロダクト要件の変更が発生した場合には、この破壊的変更を告知する 90 日前通知を送信し、通知の発出から少なくとも 90 日が経過した後に、その破壊的変更をデプロイします。
### v9
本日、2021年3月3日、X Ads API のバージョン 9 (v9) が利用可能になりました。このリリースは、機能差の解消、キャンペーン作成プロセスの簡素化、そして Cards および Mobile App Promotion エンドポイントにおける重要な更新の導入を目的としています。
これまでのバージョンと同様に、v9 への移行に向けて 6 か月の移行期間が設けられます。2021年8月31日をもって、既存の Ads API バージョン 8 (v8) は利用できなくなります。サービス中断を回避するため、すべての開発者の皆様には、できるだけ早く最新バージョンの Ads API へ移行していただくことを推奨します。
**注:** このリリース時点で、Ads API のバージョン 7 (v7) はサポート終了となり、利用できなくなっています。
詳細については、[developer forum 上でのアナウンス](https://devcommunity.x.com/t/ads-api-version-9/150316)をご覧ください。
### v8
本日 2020 年 9 月 20 日、X Ads API のバージョン 8 をリリースします。新しい Tailored Audiences 機能の導入、ads.x.com との機能差の解消、そして開発者エクスペリエンスの向上を目的として設計されたバージョンです。
これまでのバージョンと同様に、v8 への移行期間として 6 か月の猶予期間があります。2021-03-02 をもって Ads API のバージョン 7 は利用できなくなります。サービスの中断を避けるため、すべての開発者の方に、できるだけ早く最新バージョンの API への移行をお願いいたします。
詳細については、[developer forum 上のお知らせ](https://devcommunity.x.com/t/ads-api-version-8/141914)をご覧ください。
### v7
本日 2020 年 3 月 20 日、[ads.x.com](http://ads.x.com/) と機能面でのパリティをさらに高めることを目的とした X Ads API のバージョン 7 をリリースします。
これまでの[バージョン](https://developer.x.com/en/docs/ads/general/overview/versions)と同様に、v7 への移行のため 6 か月間の移行期間が設けられます。2020 年 9 月 1 日以降、Ads API のバージョン 6 は利用できなくなります。サービスの中断を回避するため、すべての開発者の方に対し、できるだけ早く最新バージョンの API へ移行することを推奨します。Ads API のバージョン 5 はすでにサポート終了となっており、利用できません。
詳細については、[developer フォーラムでのアナウンス](https://devcommunity.x.com/t/ads-api-version-7/135093)を参照してください。
### v6
本日 2019 年 8 月 28 日、X は Ads API v6 をリリースしました。このバージョンでは、一貫性の向上と開発者エクスペリエンスの改善に重点を置いた更新を行っています。
このリリースには、ツイートを取得するための新しいエンドポイント、プロモーションアカウント用の統計情報、名前でエンティティを検索する機能、現在の非同期アナリティクスジョブの処理数に関する情報が含まれます。加えて、メディアを使用するエンドポイントおよびターゲティング条件に関するエンドポイントに対して、一貫性を重視した更新を行いました。最後に、一部のパラメータ名とレスポンス属性を軽微に更新し、Scoped Timeline エンドポイントを非推奨としました。
詳細については、[Developer Forum のお知らせ](https://devcommunity.x.com/t/ads-api-version-6/129060)をご覧ください。
### v5
本日、2019年2月28日、X はスケールと効率性の向上に焦点を当てた更新を含む Ads API v5 を導入しました。
このリリースには、指定した期間内にどのエンティティがアクティブであったかを判定するための新しいエンドポイント、Media Creatives (例：X Audience Platform 上のインストリーム動画および画像) の統計情報、カード URI を指定して\_複数\_のカードを取得する機能、ターゲティング条件やその他のエンティティの取得に関する柔軟性の向上が含まれます。加えて、いくつかのバグ修正と、パラメータ名およびレスポンス属性の更新を行いました。最後に、メディア以外の App カードと、POST `accounts/:account_id/account_media` エンドポイントは非推奨となりました。
これまでのバージョンと同様に、v5 への移行には 6 か月間の移行期間を設けています。**2019-08-28** をもって、Ads API のバージョン 4 は利用できなくなります。サービス中断を回避するため、すべてのパートナーの皆さまには、できるだけ早く最新バージョンの API へ移行いただくことを推奨します。*Ads API バージョン 3 はサポート終了に達しており、すでに利用できません。*
#### New
**どのエンティティがアクティブだったかの判定**
[Active Entities](/ja/x-ads-api/analytics#active-entities-2) エンドポイントは、広告エンティティのアナリティクス指標が変更されたかどうかを示します。アナリティクスエンドポイントと併用することを前提として設計されており、Active Entities はエンティティ type と日付範囲 (最大 90 日) を指定すると、ご利用のプラットフォームがアナリティクスを取得すべきエンティティ ID の配列を返します。返却されたもの以外の ID については、その後のアナリティクスリクエストで問い合わせるべきではありません。
このエンドポイントは次のエンティティ type をサポートします：`CAMPAIGN`、`FUNDING_INSTRUMENT`、`LINE_ITEM`、`MEDIA_CREATIVE`、`PROMOTED_TWEET`。
**`MEDIA_CREATIVE` 指標**
Ads API のアナリティクスエンドポイントは、Media Creative エンティティ向けの指標も提供するようになりました。Media Creative は、インストリーム広告や X Audience Platform 上の画像をプロモーションするためのエンティティです。X Ads UI では、Media Creative の指標は「In-stream videos」タブおよび「Display creatives」タブに表示されます。[同期](/ja/x-ads-api/analytics#get-stats-accounts-account-id) と [非同期](/ja/x-ads-api/analytics#asynchronous-analytics) の両方のアナリティクスエンドポイントが、`MEDIA_CREATIVE` エンティティ enum をサポートするようになりました。
**複数カードの取得**
カード URI の値で単一のカードを取得するために設計されたエンドポイントの [v3 リリース](https://devcommunity.x.com/t/ads-api-version-3/100732) から改善され、[GET accounts/:account\_id/cards/all](/ja/x-ads-api/creatives#cards-fetch) エンドポイントを使って *複数* のカードを取得できるようになりました。これにより、カードごとにリクエストを行う代わりに、1 回のリクエストで最大 200 枚のカードを取得できます。
注意点は 2 つあります。
1. URL パスは `accounts/:account_id/cards/all` になりました。 (以前のパスは利用できません。) これは、ID でカードを取得するように設計された [エンドポイント](/ja/x-ads-api/creatives#cards-fetch) と整合性を取るためです。
2. 必須リクエストパラメータの名前は、card\_uris (複数形) になりました。
**取得の柔軟性向上**
[GET accounts/:account\_id/targeting\_criteria](/ja/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) エンドポイントは、複数の line item ID をサポートするようになりました。最大 200 個の ID を受け付ける line\_item\_ids パラメータが必須です。従来は単一の line item のみが受け付けられていたため、同期が困難でした。この変更により、より多くのターゲティング情報をより短時間で取得できるようになります。
次のエンドポイントも複数の line item ID をサポートするようになりましたが、これらについては line\_item\_ids パラメータは任意です。
* [GET accounts/:account\_id/line\_item\_apps](https://developer.x.com/en/docs/x-ads-api/campaign-management/api-reference/line-item-apps#get-accounts-account-id-line-item-apps)
* [GET accounts/:account\_id/media\_creatives](/ja/x-ads-api/campaign-management#get-accounts-account-id-media-creatives)
* [GET accounts/:account\_id/promoted\_accounts](/ja/x-ads-api/campaign-management#get-accounts-account-id-promoted-accounts)
* [GET accounts/:account\_id/preroll\_call\_to\_actions](/ja/x-ads-api/creatives#preroll-call-to-actions)
#### 変更点
**ドラフトキャンペーンおよびラインアイテムの取得**
ドラフトキャンペーンおよびラインアイテムの取得方法が更新されました。`with_draft(boolean)` パラメータを `true` に設定すると、ドラフトと非ドラフトのエンティティの *両方* が返されるようになりました。これは、削除済みエンティティの取得方法 (`with_deleted` の使用) と一貫した動作です。これまでは、ドラフトと非ドラフトの両方のエンティティを取得するには少なくとも 2 回のリクエストが必要でしたが、現在は 1 回の API 呼び出しで実行できます。
\| **v4** | **v5** |
\| :--- | :--- | :--- |
\| `draft_only` | `with_draft` | |
**Network activation duration ターゲティング**
Ads API は、Network Activation Duration ターゲティングを追加した後、レスポンス内のターゲティング type に `_IN_SEC` というサフィックスが含まれてしまう表示に関する問題を解消しました。Network Activation Duration は常に月単位で表現されるため、秒を示すサフィックスが含まれていることは紛らわしいものでした。この修正により、表現が一貫し、混乱が軽減されます。
\| **v4** | **v5** |
\| :--- | :--- | :--- |
\| `NETWORK_ACTIVATION_DURATION_IN_SEC` | `NETWORK_ACTIVATION_DURATION` | |
**総件数とカーソル**
v5 では、`with_total_count` と `cursor` は排他的です。リクエストで両方を指定すると、`EXCLUSIVE_PARAMETERS` エラーコードが返されます。v5 以前は、`cursor` が指定されている場合、`with_total_count` は無視されていました。この変更により、両者の関係が明示的になりました。
#### 削除
Ads API レスポンスから、preview\_url、account\_id、parent\_ids の 3 つのフィールドが削除されます。これら 3 つに対するエンジニアリング上の対応は最小限で済みます。
* v4 では、カード用の preview\_url レスポンスパラメータは常に null であると告知されていました。この移行の最終ステップとして、すべてのカードのレスポンスから preview\_url を削除します。
* 次のリソースについては、ads アカウント ID が URL 内および request.params 内に既に存在しているため、account\_id レスポンス属性が削除されます。 (ファンディングインストルメントをこの一覧から意図的に除外しているのは、可能な場合にはレスポンスオブジェクトに親 ID が存在すべきであり、アカウント ID はファンディングインストルメントの親エンティティであるためです。)
* アカウントメディア
* App イベントプロバイダー
* App イベントタグ
* キャンペーン
* カード
* ラインアイテム
* プロモート対象ユーザー
* ターゲティング条件
* [GET accounts/:account\_id/targeting\_criteria](/ja/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) リクエストでは、parent\_ids フィールドは常に空配列であったため、今後は返されません。
**非メディア App カード**
v5 では、非メディア App カードはサポートされなくなります。以前に、非メディア App カードを作成または編集する機能は[すでに](https://devcommunity.x.com/t/deprecation-announcement-app-download-cards/87807)削除されています。今回、このリソース用に残っているエンドポイントが非推奨となります。
* 注: これは画像および動画の App ダウンロードカードには**影響しません**。
**アカウントメディアの作成**
POST accounts/:account\_id/account\_media エンドポイントは v5 では利用できなくなります。このリソース向けの他のエンドポイントには**影響はありません**。この変更の理由は、[Media Library](/ja/x-ads-api/creatives#media-library) にメディアを追加する際、場合によってはそれらのアセットが *自動的に* アカウントメディアエンティティとして追加され、既に存在するアセットをアカウントメディアリソースに追加しようとするとエラーになるためです。これは次のケースで発生します。
* Media Library に追加された `AMPLIFY_VIDEO` アセットは、自動的に `PREROLL` クリエイティブ type を持つアカウントメディアアセットとして追加されます。
* 特定のサイズの画像を Media Library に追加すると、自動的にアカウントメディアアセットとして追加されます。クリエイティブ type (例: `INTERSTITIAL`) は画像のサイズに依存します。 (サイズについては、[Enumerations](/ja/x-ads-api/introduction) ページを参照してください。)
### v4
Ads API のバージョン 4 は本日 (2018 年 8 月 28 日) リリースされました。
このリリースでは、より堅牢なオーディエンス処理バックエンド上に構築された新しい API インターフェースを含む、[Audiences](/ja/x-ads-api/audiences) プロダクトの改善を行いました。バージョン 4 では、ユーザー、アカウント、税務設定を管理するための一連のエンドポイントも提供します。さらに、accounts/:account\_id/videos エンドポイントは非推奨となります。このリリースには、そのほかにもいくつかのマイナーなパラメーターおよびレスポンス名の変更が含まれます。
バージョン 3 と同様に、6 か月間の移行期間を提供します。**2019-02-28** 以降、Ads API のバージョン 3 は利用できなくなります。サービスの中断を回避するため、すべてのパートナーの皆さまには、できるだけ早く最新バージョンの API へ移行いただくことを推奨します。バージョン管理戦略の詳細については、[Versions](/ja/x-ads-api/introduction) ページをご覧ください。
#### New
***Audience API***
新しい Audiences API は、堅牢性と信頼性が強化された新しいオーディエンス処理バックエンド上に構築されています。この新しいエンドポイントでは、パートナーが 1 人のユーザーに対して複数のユーザー識別子の種類を提供できるようになり、これによりマッチングのために追加のシグナルを利用できるようになります。新しい Audience エンドポイントのリファレンスドキュメントは [こちら](/ja/x-ads-api/audiences) にあります。今年残りの期間を通じて、このプロダクトに対するアップデートや改善を継続的にリリースしていく予定です。
以下のエンドポイントは、機能が重複しているため v4 では利用できなくなります (v3 では引き続き動作し、v3 が利用できなくなった時点で完全に**廃止**されます) 。
* TON Upload:
* GET accounts/:account\_id/tailored\_audience\_changes
* GET accounts/:account\_id/tailored\_audience\_changes/:tailored\_audience\_change\_id
* POST accounts/:account\_id/tailored\_audience\_changes
* PUT accounts/:accounti\_d/tailored\_audiences/global\_opt\_out
* Real Time Audiences:
* POST tailored\_audience\_memberships
最後に、バージョン 4 では、*すべての* [Tailored Audiences エンドポイント](/ja/x-ads-api/audiences) のリクエストおよびレスポンスから `list_type` パラメータが削除されます。
***Settings Endpoints***
アカウント管理者は、ユーザー設定、アカウント設定、および税設定を行い、更新できるようになりました。[User settings](/ja/x-ads-api/campaign-management#get-accounts-account-id-user-settings-user-id) は、特定の広告アカウントに対するユーザー固有の連絡先に関する設定に対応します。[PUT accounts/:account\_id](/ja/x-ads-api/campaign-management#put-accounts-account-id) エンドポイントを使用することで、広告主はアカウント名と業種区分を更新できるようになりました。最後に、[tax settings](/ja/x-ads-api/campaign-management#get-accounts-account-id-tax-settings) エンドポイントを使用すると、付加価値税 (VAT) が課される国の広告主は、会社名、住所、VAT ID、アカウントが広告主本人所有か、広告主に代わって広告を行う代理店所有かといった情報を更新できます。
#### 変更点
***Universal Lookalike の名称変更***
[POST accounts/:account\_id/line\_items](/ja/x-ads-api/campaign-management#post-accounts-account-id-line-items) および [PUT accounts/:accountit/line\_items/:line\_item\_id](/ja/x-ads-api/campaign-management#put-accounts-account-id-line-items-line-item-id) エンドポイントにおける `lookalike_expansion` パラメータの enum 値を更新します。
| **v3** | **v4** |
| :--------- | :--------- |
| `NARROW` | `DEFINED` |
| `BALANCED` | `EXPANDED` |
**あらゆる箇所で `country_code` を使用**
Ads API における[一貫性](https://devcommunity.x.com/t/feedback-ads-api-consistency/109145)向上の一環として、以下のエンドポイントにおけるパラメータ名を `app_country_code` から `country_code` に変更します。
* [POST accounts/:account\_id/cards/image\_app\_download](https://devcommunity.x.com/t/ads-api-version-11/168814)
* [PUT accounts/:account\_id/cards/image\_app\_download/:card\_id](https://developer.x.com/content/developer-twitterhttps://developer.x.com/en/docs/ads/creatives/api-reference/image-app-download#put-accounts-account-id-cards-image-app-download-card-id)
* [POST accounts/:account\_id/cards/video\_app\_download](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/video-app-download#post-accounts-account-id-cards-video-app-download)
* [PUT accounts/:account\_id/cards/video\_app\_download/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/video-app-download#put-accounts-account-id-cards-video-app-download-card-id)
この変更は、これらのパラメータの動作や許容される値には影響せず、名称のみの変更です。
**`preview_url` は常に null**
v3 のアナウンスでお伝えしたとおり、既存のすべてのカードには `card_uri` が設定されています。その結果、`preview_url` の値は常に `null` になります。
念のため、カードをツイートに関連付ける際は、そのカードの `card_uri` 値を使用してください。以下のリクエスト例を参照してください。
\$ twurl -X POST -H ads-api.x.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4\&card\_uri=card://958225772740714496"
#### 削除された項目
**動画エンドポイント**
`accounts/:account_id/videos` エンドポイントは v4 では利用できなくなります。このエンドポイントは、[Media Library](/ja/x-ads-api/creatives#get-accounts-account-id-media-library) エンドポイントの導入により廃止されました。以下に利用方法の比較を示します。
* v3 videos エンドポイント: `twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"`
* v4 の動画向け media library エンドポイント: `twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"`
Media Library エンドポイントは videos エンドポイントと完全互換であり、さらに画像や GIF の取り扱いなどの追加機能もサポートしています。パートナーの皆さまには、メディア管理には Media Library を一元的に利用していただくようお願いします。
**ツイート表示における `as_user_id`**
[GET accounts/:account\_id/tweet/preview/:tweet\_id](/ja/x-ads-api/creatives#get-accounts-account-id-tweets) エンドポイントで利用可能だった `as_user_id` パラメータは、今後は受け付けられません。プレビューは常にツイートの投稿者として表示されます。
### v3
Ads API バージョン 3 は、2018 年 2 月 1 日に[リリースされました](https://devcommunity.x.com/t/ads-api-version-3/100732)。Ads API バージョン 2 は 2018 年 8 月 1 日にサポート終了となります。
このリリースには、新しい Audience Intelligence 製品、Media Library へのアクセス、カードワークフローの改善が含まれています。また、[PUT accounts/:account\_id/targeting\_criteria](/ja/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) エンドポイントの非推奨化も発表します。最後に、バージョン 3 では、いくつかのマイナーなパラメータおよびレスポンスの変更と、バッチサイズ上限の引き下げが行われています。
[バージョン 2](https://devcommunity.x.com/t/ads-api-version-2/90360) と同様に、パートナーの皆様には移行期間として **6 か月** を提供します。**2018-08-01** に Ads API v2 は停止されます。すべてのパートナーおよび開発者の方には、できるだけ早く v3 への移行を推奨します。
**Audience Intelligence**
Audience Intelligence は、特定の X オーディエンスにとって最も関連性の高い主要なハッシュタグ、@ハンドル、およびイベントに関するリアルタイムのインサイトを提供します。たとえば、米国の「18〜34 歳・男性」と入力すると、このオーディエンスでトレンドとなっている #nintendoswitch、#cardinal、@ricegum などが表示されます。
Audience Intelligence の[エンドポイント](/ja/x-ads-api/audiences)は、以下の機能を提供します。
* 入力オーディエンスを指定して、関連性の高いハッシュタグ、@ハンドル、およびイベントの上位を取得する。
* 入力オーディエンスを指定して、主要なデモグラフィック情報 (年齢、性別、世帯収入など) を取得する。
* キーワードを指定して、ツイート数の時系列データを取得する。
**Media Library**
[Media Library](/ja/x-ads-api/creatives#get-accounts-account-id-media-library) は、広告アカウント向けに画像、GIF、動画を管理する機能を提供します。これらのメディアオブジェクトは、ツイートやカードの作成に利用できます。また、複数のクリエイティブで再利用できるため、同じアセットを何度もアップロードする必要がなくなります。
ライブラリ内のオブジェクトは media\_key によって識別されます。media\_key は、たとえば 13\_875943225764098048 のような形式の文字列です。Ads API では、あらゆるメディアに対して media\_key を使用する方向に移行しています。
**カードワークフローの改善**
すべてのカード用エンドポイントで media\_key がサポートされるようになりました。これにより、Media Library 内のオブジェクトを使用してカードを作成または更新できるようになります。
さらに、[カード詳細の取得](/ja/x-ads-api/creatives#fetching-cards)用の 2 つの新しいエンドポイントを導入しました。これらのエンドポイントは、たとえば card\_uri または id のいずれかを指定することで、ツイートや予約ツイートで使用されているカードを検索するために利用できます。これは、従来はできませんでした。
#### その他の変更点
これらの新機能に加えて、バージョン 3 には次の変更が含まれます。
**新規**
* [GET insights/keywords/search](/ja/x-ads-api/audiences) エンドポイントのレスポンスに、入力されたキーワードに関連する 30 個の用語を含む related\_keywords 属性が追加されました。
**変更**
* ターゲティング条件のバッチの最大サイズが 500 になりました。
* card\_uri と preview\_url のレスポンス属性は相互排他的になりました。カードに card\_uri がある場合、preview\_url は null になります。カードに card\_uri がない場合は、preview\_url のみが返されます。
* 2018-01-29 以降に作成されたすべてのカードには card\_uri があります。
* バージョン 4 までに、既存のすべてのカードに card\_uri が付与されます。
* 5:2 画像を使用したカードを新規に *作成* することはできなくなりました。既存の 5:2 画像ベースのカードは引き続き動作しますが、パートナーの皆さまには、 (サポートされている場合) パフォーマンスの高い 1.91:1 または 1:1 のアスペクト比への切り替えを推奨します。
**削除**
* [PUT accounts/:account\_id/targeting\_criteria](/ja/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) エンドポイントは利用できなくなりました。この変更は、このエンドポイントの置換動作が広告主の混乱を招き、1 回に 1 つのリソースを更新する他の PUT エンドポイントとの一貫性がなかったために実施しました。代わりに、[POST batch/accounts/:account\_id/targeting\_criteria](/ja/x-ads-api/campaign-management#post-batch-accounts-account-id-targeting-criteria) エンドポイントを使用してください。これにより、1 回のリクエストでターゲティングの追加と削除の両方が可能になるなど、より柔軟な操作が可能になります。
* funding instrument に対しては、paused レスポンス属性は返されなくなりました。代わりに、その funding instrument が一時停止されているかどうかを判断するには、entity\_status レスポンス属性を参照してください。加えて、paused と cancelled が同じ値に対応しているため、cancelled もレスポンスでは返されなくなりました。
* [GET accounts/:account\_id/tweet/preview](/ja/x-ads-api/creatives#get-accounts-account-id-tweets) エンドポイントからは、card\_id パラメータを削除しました。
* 削除された予約ツイートを取得することはできないため、with\_deleted パラメータはサポートされなくなりました。
* 以下のエンドポイントから draft\_only パラメータを削除しました。これらのエンティティはドラフト状態になり得ないためです。
* [GET accounts/:account\_id/targeting\_criteria](/ja/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria)
* [GET accounts/:account\_id/promoted\_tweets](/ja/x-ads-api/campaign-management#get-accounts-account-id-promoted-tweets)
* [GET accounts/:account\_id/promoted\_accounts](/ja/x-ads-api/campaign-management#get-accounts-account-id-promoted-accounts)
* [GET accounts/:account\_id/media\_creatives](/ja/x-ads-api/campaign-management#get-accounts-account-id-media-creatives)
* [GET accounts/:account\_id/preroll\_call\_to\_actions](/ja/x-ads-api/creatives#get-accounts-account-id-preroll-call-to-actions)
**注意**
Video Website Card と予約ツイートは、いずれもベータ版を終了しました。ローンチ以降に予約ツイートに対して行った変更については、[このスレッド](https://devcommunity.x.com/t/announcement-update-to-scheduled-tweets/94869) を参照してください。これには、予約ツイート用の HTML [プレビュー](https://devcommunity.x.com/t/announcement-tweet-preview-improvements/96577) を生成できる機能も含まれます。
### v2
Ads API のバージョン 2 は 2017 年 7 月 10 日に[リリース](https://devcommunity.x.com/t/ads-api-version-2/90360)されました。Ads API のバージョン 1 は 2018 年 1 月 10 日にサポート終了となります。
**互換性のない変更 / 廃止予定事項[¶](#breaking-changes-deprecations "Permalink to this headline")**
* `total_count` はレスポンス属性としてオプションになりました。`with_total_count` が `true` に設定されている場合にのみ返されます
* `line_items` および `campaigns` のリクエストおよびレスポンスオブジェクト上の `paused` と `draft_only` フィールドは、単一の `entity_status` パラメータに置き換えられました
* [POST accounts/:account\_id/tweet](/ja/x-ads-api/creatives) および [GET accounts/:account\_id/tweet/preview](/ja/x-ads-api/creatives#get-accounts-account-id-tweets) エンドポイントでは、`status` パラメータは `text` に名称変更されました
* [GET targeting\_criteria/locations](/ja/x-ads-api/campaign-management#get-targeting-criteria-locations) エンドポイントの `location_type` enum は複数形になりました。`COUNTRY` は `COUNTRIES`、`REGION` は `REGIONS` などです。唯一の例外として、v2 では `CITY` は `METROS` になり、このロケーション type が Designated Marker Areas (DMA) または「metros」を指していることを正しく反映します。
* PUT accounts/:account\_id/promoted\_tweets エンドポイントにおける `display_properties` は廃止されました。この値はレスポンスの一部としても返されなくなります
* 前項の結果として、promoted\_tweets エンティティを更新 (PUT) することはできなくなりました
* [GET accounts/:account\_id/promoted\_tweets](/ja/x-ads-api/campaign-management#get-accounts-account-id-promoted-tweets) エンドポイント上の `line_item_id` パラメータは削除されました
* v2 エンドポイントでは 5:2 Website Card を作成することはできなくなります
* `data_type` レスポンス属性は返されなくなりました
**新機能[¶](#new-features "Permalink to this headline")**
1. Cards v2
2. ドラフトキャンペーン / ラインアイテムの作成と有効化
3. スケジュール済みツイート
4. 非同期ジョブのサマリー
**Cards v2[¶](#cards-v2 "Permalink to this headline")**
* ツイートにカードを関連付ける際には、ツイートテキストに `preview_url` を追加するのではなく、`card_uri` リクエストパラメータを使用してください
* レスポンス内で (カード作成ステップ中に) `card_uri` パラメータが返されない場合は、`preview_url` を使用してください
* すべての新しいカード形式は、`card_uri` パラメータを活用しつつ、API 上でネイティブに利用可能になります。
**新しいカード形式:[¶](#new-card-formats "Permalink to this headline")**
* Video Website Cards:
* [GET accounts/:account\_id/cards/video\_website](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#get-accounts-account-id-cards-video-website)
* [GET accounts/:account\_id/cards/video\_website/:card\_id](https://developer.x.comhttps://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#get-accounts-account-id-cards-video-website-card-id)
* [POST accounts/:account\_id/cards/video\_website](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#post-accounts-account-id-cards-video-website)
* [PUT accounts/:account\_id/cards/video\_website/:card\_id](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#put-accounts-account-id-cards-video-website-card-id)
* [DELETE accounts/:account\_id/cards/video\_webiste/:card\_id](https://developer.x.com/en/docs/ads/creatives/api-reference/video-website.html#delete-accounts-account-id-cards-video-website-card-id)
**ドラフトキャンペーン[¶](#draft-campaigns "Permalink to this headline")**
ドラフトキャンペーンは [GET accounts/:account\_id/camapaigns](/ja/x-ads-api/campaign-management#get-accounts-account-id-campaigns) エンドポイント経由で参照可能でした。v2 では、API を通じてドラフトキャンペーンを作成 / 有効化できるようになりました。
* [POST accounts/:account\_id/line\_items](/ja/x-ads-api/campaign-management#post-accounts-account-id-line-items) および [POST accounts/:account\_id/campaigns](/ja/x-ads-api/campaign-management#post-accounts-account-id-campaigns) エンドポイントでは、新しいドラフトキャンペーンまたはラインアイテムを作成するために、`entity_status` パラメータの値を `DRAFT` に設定できます。
* 新しく作成されるドラフトに必須のパラメータのセット:
| Draft Campaign | Draft Line Item |
| :---------------------- | :-------------- |
| `funding_instrument_id` | `campaign_id` |
| `name` | `objective` |
| `start_time` | `product_type` |
| | `placements` |
**Notes[¶](#notes "Permalink to this headline")**
* ドラフトのラインアイテムまたはキャンペーンは、`entity_status` を `DRAFT` から `PAUSED` または `ACTIVE` にのみ変更できます。
* 複数のラインアイテムを含むキャンペーン全体を有効化するには、そのキャンペーン配下の各ラインアイテムとキャンペーン本体の `entity_status` をいずれも `ACTIVE` に設定する必要があります。
* いずれかのキャンペーンまたはラインアイテムの `entity_status` を変更するには、対応する PUT エンドポイントを使用します。
**Scheduled Tweets[¶](#scheduled-tweets "Permalink to this headline")**
* 予約投稿ツイートは、以下の新しいエンドポイントで扱われます。
* Scheduled Tweets:
* [GET accounts/:account\_id/scheduled\_tweets](/ja/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets)
* [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#scheduled-tweets)
* [POST accounts/:account\_id/scheduled\_tweets](/ja/x-ads-api/creatives#post-accounts-account-id-scheduled-tweets)
* [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#scheduled-tweet-management)
* [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/ja/x-ads-api/creatives#scheduled-tweet-management)
* Campaign Management:
* [GET accounts/:account\_id/scheduled\_promoted\_tweets](/ja/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets)
* [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/ja/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id)
* [POST accounts/:account\_id/scheduled\_promoted\_tweets](/ja/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets)
* [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/ja/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id)
* 新規に予約されたツイートは、将来の任意の日付にスケジュールできます。
* 現在、予約投稿ツイートをプレビューする機能はありません。
* `SCHEDULED` 状態にある予約投稿ツイートのみが編集・削除可能です。
* 予約投稿ツイートは、`scheduled_at` の日時になるまで、エンタープライズ Firehose やその他のデータ API には配信されません。
### v1
Ads API のバージョン 1 は 2016 年 3 月 31 日に提供開始され、2018 年 1 月 10 日に提供終了となります。
**バージョン 1 の変更点:[¶](#changes-in-version-1 "Permalink to this headline")**
* [バージョン管理のサポート](https://blog.x.com/2016/versioning-is-coming-to-twitter-s-ads-apis)
* `CUSTOM` [objective](/ja/x-ads-api/campaign-management#objective-based-campaigns) はサポート対象外となりました
* [バッチエンドポイント](/ja/x-ads-api/campaign-management#post-batch-accounts-account-id-campaigns) が一般提供されました
* [リーチ推定の変更点](https://developer.x.com/en/docs/ads/campaign-management/api-reference/reach-estimate.html#get-accounts-account-id-reach-estimate):
* より正確なリーチ見積もりを提供するために、このエンドポイントは予算を考慮するようになりました。次のパラメータが必須です。
* \[新規] `campaign_daily_budget_amount_local_micro`
* `currency`
* `bid`
* `objective`
* レスポンスオブジェクトが変更され、レスポンス値の範囲を返すようになりました。
* `infinite_count` は、その意図をわかりやすくするために `infinite_bid_count` に名称変更されました
* `count` と `infinite_bid_count` に加え、以下の新しいデータポイントも返されるようになります：
* `impressions`
* `engagements`
* `estimated_daily_spend_local_micro`
* テーラードオーディエンスのデータ type の変更
* Tailored Audiences の `data_type` は、当社のすべてのレスポンスで `tailored_audiences` から `tailored_audience` に変更されました。
* Shared Tailored Audiences は現在、*API 限定* のベータ版として利用できます。Shared Tailored Audiences を使用すると、1 つのオーディエンスを複数の広告アカウント間で共有できます。[POST accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions](/ja/x-ads-api/audiences) (および関連エンドポイント) を使用して、広告アカウント間で共有したい Tailored Audience のアクセス権限を管理します。
* 広告主アカウントのパフォーマンス[アナリティクス](/ja/x-ads-api/analytics)取得方法の大幅な改善：
* 当社の[ベストプラクティス](/ja/x-ads-api/analytics#best-practices)に合わせて、[同期型統計エンドポイント](/ja/x-ads-api/analytics#get-stats-accounts-account-id)から取得できるデータ期間は、今後は最大 **7 日分** のデータにのみ制限されます。
* メトリクスの取得を簡素化するために、`metrics` パラメータを新しい `metric_groups` パラメータに置き換えました。開発者は、特定のリクエストに対してどのメトリクスグループをレスポンスとして受け取りたいかを指定してリクエストするだけです。
* 特定のエンティティに対して適切でないメトリクスをリクエストした場合、それらはレスポンスから除外され、`null` 値として返されます。*これらのメトリクスはアナリティクスのコスト上限には含まれません。*
* レスポンスは**大幅に簡素化**され、今後は UI におけるメトリクスの表示方法に、これまでよりも近い形になります。
* 以前はプレースメントごと (検索の Promoted Tweets、タイムラインの Promoted Tweets、プロフィール＆ツイート詳細の Promoted Tweets、X Audience Platform) に個別のメトリクスを公開していました。今後は、それぞれについて標準化されたメトリクスのセットを返します (`promoted_tweet_timeline_impressions`、`promoted_tweet_search_impressions`、`promoted_tweets_profile_impressions`、`promoted_tweets_tpn_impressions` の代わりに) 。これらは、リクエスト時に次のいずれかのカテゴリで、単一のメトリクス `impressions` として返されます (これはすべてのメトリクスに適用されます) 。
* `ALL_ON_TWITTER`
* `PUBLISHER_NETWORK`
* リクエストを行うと、UI 上の値と一致させやすくするために、単一の `impressions` メトリクスが返されます。
* `ALL_ON_TWITTER` と `PUBLISHER_NETWORK` の両方のデータを取得するには、それぞれを取得する 2 つのクエリを実行する必要があります。これらをまとめて取得することはできません。
* 開発者の皆様から寄せられたフィードバックを受けて、[非同期統計エンドポイント](/ja/x-ads-api/analytics#asynchronous-analytics) が利用可能になりました。
* 統計情報を*非同期的に*リクエストするための新しいエンドポイント群。すぐに必要ではないデータや、過去データの取得に利用できます。
* 新しい単一のエンドポイントを使って統計ジョブをキューに追加できます。リソースが許すかぎり、リクエストされたデータを取得します。
* ジョブステータス用エンドポイントを呼び出して、データが利用可能かどうかを確認できます。
* データが利用可能になると、同期エンドポイントからのレスポンスを反映した JSON レスポンスをダウンロードするための取得用 ID を提供します。
* 1 件のジョブで、最大**90 日分**のデータを最大**20 エンティティ**についてリクエストできます。
* v0 メトリクスから v1 メトリクスへのマッピングが記載されている Analytics v1 の移行ガイドをご覧ください
* Sandbox の改善点 \* Sandbox 環境で[複数のテスト広告アカウントを作成](/ja/x-ads-api/campaign-management#post-accounts)できるようになりました。 \* Sandbox 環境に限り、テスト広告アカウントに対して複数の資金手段 (funding instrument) を作成できるようになりました。これにより、すべての funding instrument type を使ってテストできます。以前はテストに利用できる資金手段は `CREDIT_CARD` のみでした。 \* ベータ版機能をテストしたい場合は、テスト要件に合わせて Sandbox 環境内のアカウントで機能をオン／オフ切り替えできるようになりました。
### v0
Ads API のバージョン 0 は 2013 年 2 月 21 日に正式にリリースされ、2016 年 10 月 31 日までサポートされました。
バージョン 0 のすべての analytics エンドポイントは非推奨となり、2016 年 10 月 31 日以降は提供されなくなります。これらのエンドポイントは、バージョン 1 の 3 つの analytics エンドポイントに置き換えられました。
reach estimation エンドポイントは、バージョン 1 で新しい動作になります。