Xをデータパイプラインソースとして設定する ​

Xをデータパイプラインソースとして設定し、X Ads APIから広告アカウント、キャンペーン、および分析データを抽出して同期先に同期します。

このガイドを使用して、機能と前提条件を確認し、Xをデータパイプラインソースとして接続し、パイプラインを設定し、サポートされるオブジェクト、同期モード、スキーマ処理、機密データ処理、および既知の制限について理解します。

サポートされている機能 ​

Xをパイプラインソースとして使用する場合、次の機能がサポートされます。

• クラウド接続：https://ads-api.x.comを通じてHTTPS経由でX Ads APIに接続します。
• マルチアカウントサポート：コネクションがアクセスできるすべての広告アカウントを同期するか、IDで特定の広告アカウントを選択します。
• オブジェクトレベルの選択：キャンペーン階層、クリエイティブアセット、ターゲティング、および分析レポート全体でサポートされるオブジェクトから選択します。完全なリストについては、サポート対象オブジェクトを参照してください。
• 増分同期：ほとんどのキャンペーン階層、クリエイティブ、および分析オブジェクトは増分同期されます。詳細については、同期モードを参照してください。
• 削除追跡：サポートされるオブジェクトで削除されたレコードを検出し、同期先で論理削除フラグを使用してマークします。詳細については、削除追跡を参照してください。
• スキーマドリフトの検出と処理: 新しいフィールドを自動同期でスキーマの変更を自動的に検出して適用するか、新しいフィールドをブロックでスキーマを固定します。
• フィールドレベルのデータ保護：機密フィールドが同期先に到達する前に、ハッシュ化するか、そのままレプリケートします。
• 構成可能な同期頻度: 時間ベースの間隔またはcron式を使用して同期をスケジュールします。サポートされる最小間隔は15分です。
• 設定可能な分析ウィンドウ：パイプラインが分析履歴をバックフィルする日数、および各実行で再取得する直近の日数を設定します。詳細については、パイプラインの設定を参照してください。

前提条件 ​

Xをデータパイプラインソースとして接続するには、次が必要です。

• 同期する予定の広告アカウントが少なくとも1つあるXアカウント。
• X Ads APIアクセスが承認されたX Developer App。 Ads APIアクセスは一般的なX APIアクセスとは別に制限され、X Ads APIチームによって審査されるため、承認には時間がかかる場合があります。当日中の有効化は期待しないでください。設定手順については、X Ads APIアプリを生成するを参照してください。
• OAuth 1.0a認証の認証情報：承認済みの開発者アプリから生成されたコンシューマーキー、コンシューマーシークレット、アクセストークン、およびアクセストークンシークレット。

X Ads APIアプリを生成する ​

次の手順を実行して、X Developer Appを作成し、Ads APIアクセスを申請し、Xコネクションに必要な認証情報を生成します。

コンシューマーキーとシークレットを生成する ​

Xでコンシューマーキーとシークレットを生成するには、次の手順を実行します。

アクセストークンとシークレットを生成する ​

Xでアクセストークンとシークレットを生成するには、次の手順を実行します：

サポートされるコネクションタイプ ​

XデータパイプラインはOAuth 1.0a認証をサポートしています。

• OAuth 1.0a：Ads APIアクセスが承認されたX Developer Appのコンシューマーキー、コンシューマーシークレット、アクセストークン、およびアクセストークンシークレットを使用して認証します。組織が登録して直接承認を受けたアプリ、またはAds APIアクセスが既に承認されている共有アプリの認証情報のいずれかを使用できます。コネクションフォームではどちらも受け入れられるためです。これらのトークンは、OAuth 2.0コネクションとは異なり、自動的に期限切れになったり更新されたりしません。トークンは、X Developer Consoleで取り消すまで有効なままです。

Xに接続する ​

Xに接続するには、次の手順を実行します。

パイプラインの設定 ​

Xをデータパイプラインソースとして設定するには、次の手順を実行します。

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

サポートされるオブジェクト ​

XデータパイプラインはX Ads API（バージョン12）からデータを同期します。次の表に、サポートされているオブジェクトをカテゴリー別に示します。各オブジェクトは宛先内の個別のテーブルとして同期されます:

アカウントとキャンペーンの階層 ​

次のオブジェクトはX広告階層を反映しています。AccountsレコードはFunding InstrumentsとCampaignsの親であり、これらはLine Itemsの親であり、Line ItemsはPromoted TweetsとPromoted Accountsの親です。 Line Item Placements、Line Item Categories、Campaign Reason、およびFunding Instrument Reasonは、親レコードの配列フィールドであり、リレーショナルモデリングのために独自のテーブルに正規化されます。

クリエイティブアセット ​

次のオブジェクトには、プロモツイートおよび広告枠によって参照されるクリエイティブコンテンツとリッチメディアアセットが含まれます。

Promoted Tweet Contentは、各実行でPromoted TweetsおよびScheduled Promoted Tweetsレコードによって参照されるツイートテキストとメディアを再取得するため、行数はこれらのオブジェクトに依存します。

ターゲティングとオーディエンス ​

次のオブジェクトは、広告枠がXユーザーをターゲティングする方法を定義します。

Custom Audiencesは、名前、サイズ、タイプなどのオーディエンスメタデータのみを同期します。 Xでは、メール、電話番号、デバイスIDなどのオーディエンスメンバーリストがXに到達する前にハッシュ化されている必要があります。Workatoはこのメンバーデータを抽出しません。

スケジュール済みコンテンツ ​

次のオブジェクトは、公開前のツイートと動画のコールトゥアクションのスケジュール設定をサポートします。

Scheduled Tweetsは削除フラグを返しません。 Xは代わりに各レコードのステータス列を通じてキャンセルを公開します。

アカウント管理と参照データ ​

Referenced User Profilesは、Promoted Accountsレコードによって参照される任意のユーザーIDの公開Xプロフィールデータのエンリッチメントテーブルです。

パフォーマンス分析 ​

次の各オブジェクトは、アカウント、資金提供手段、キャンペーン、広告枠、プロモツイート、またはプロモアカウントなど、1つのエンティティレベルの日次パフォーマンスメトリクスを返します。

セグメント化されたパフォーマンス分析 ​

Xデータパイプラインでは、同じ日次パフォーマンスメトリクスを、年齢、性別、プラットフォーム、またはコンバージョンタグなどの追加ディメンション別にも分類します。年齢、性別、およびプラットフォームのセグメンテーションは、前のセクションに記載されたすべてのエンティティレベルで利用できます。コンバージョンタグのセグメンテーションは、キャンペーン、広告枠、プロモツイート、およびプロモアカウントでのみ利用できます。これらが基盤となるWebコンバージョンメトリクスグループをサポートする唯一のレベルであるためです。

セグメント化された値は、対応する非セグメント化合計と正確に一致するとは限りません。これはXプラットフォームで想定される動作であり、データ品質の問題ではありません。

リーチと平均フリークエンシー ​

これらのオブジェクトは、パフォーマンス分析の標準パフォーマンスメトリクスではなく、ユニークリーチと平均フリークエンシーのメトリクスを返します。同期ごとの最大日付範囲については、制限を参照してください。

同期モード ​

Xデータパイプラインは完全同期と増分同期をサポートしています。同期モードは、パイプラインに追加する際にオブジェクトごとに設定されます。

フル同期 ​

フル同期では、実行ごとにオブジェクトの完全なレコードセットを再読み取りし、同期先テーブルを上書きします。 Media Library、Promoted Tweet Content、Scheduled Tweets、およびReferenced User Profilesは完全同期を使用します。これは、X APIがこれらのオブジェクトに対して信頼できる変更時刻シグナルを公開していないためです。

増分同期 ​

増分同期では、前回の実行以降に変更されたレコードのみを抽出します。ほとんどのキャンペーン階層、クリエイティブ、ターゲティング、および管理オブジェクトは、Xのupdated_atフィールドをカーソルとして使用します。

分析オブジェクトとリーチオブジェクトは別のメカニズムを使用します。これは、Xメトリクスが時間の経過とともに再計算され、行レベルのリソースではないためです。各実行で、パイプラインは前回成功した同期日から現在時刻までを抽出し、Analytics backfill windowを使用して初期履歴取得のサイズを決定します。代わりに、Reach & Average Frequencyオブジェクトは設定済みの日付ウィンドウ全体を再取得します。分析ウィンドウの設定については、パイプラインを設定するを参照してください。

各オブジェクトの同期モードを確認するには、サポートされるオブジェクトの表を参照してください。

削除追跡 ​

"Yes (soft)"とマークされたオブジェクトの場合、Xは各レコードでdeletedフラグを直接返し、Workatoはそれを同期先に反映します。

Promoted Tweet ContentおよびReferenced User Profilesは削除追跡をサポートしていません。これらは個別に一覧表示されるのではなく、親オブジェクトから参照によって再取得されるためです。 Scheduled Tweetsも削除フラグを返しません。 Xは代わりにステータス列を通じてキャンセルを表します。分析オブジェクトとリーチオブジェクトも削除追跡をサポートしていません。これは、パフォーマンスメトリクス行がクエリのたびに再計算され、独自のライフサイクルで永続化されないためです。削除または一時停止された親エンティティのメトリクスは、引き続き完全にクエリできます。

スキーマとデータ型の処理 ​

Xからデータを同期する場合、スキーマとデータ型には次の考慮事項が適用されます。

金額 ​

予算および請求料金フィールドは、アカウントの現地通貨のマイクロ単位で表されます。たとえば、1,000,000マイクロ=通貨の1単位です。 Workatoはこれらの値を整数として保存し、取り込み時に変換しません。

タイムスタンプとアカウントのタイムゾーン ​

分析オブジェクトは、日次メトリクスをUTCではなく広告アカウント自身のタイムゾーンの午前0時に揃え、その結果の時点をUTCとして保存します。たとえば、米国太平洋時間のアカウントの2026-01-05行は、2026-01-05T08:00:00Zとして保存されます。

ネストされたフィールドと配列フィールド ​

Xにはユーザー定義のカスタムフィールドはありません。 Workatoは次の配列フィールドとネストされたフィールドを処理します。

• Line Items.placementsおよびLine Items.categoriesは、Line Items上のJSON文字列列として保存され、WorkatoはリレーショナルモデリングのためにそれらをLine Item PlacementsおよびLine Item Categoriesテーブルにも展開します。
• Campaigns.reasons_not_servableは、Campaigns上のJSON文字列列として保存され、WorkatoはそれをCampaign Reasonテーブルにも展開します。
• Funding Instruments.reasons_not_able_to_fundは、Funding Instruments上のJSON文字列列として保存され、WorkatoはそれをFunding Instrument Reasonテーブルにも展開します。
• Cards.componentsは、対応する子テーブルのないJSON文字列列として保存されます。
• Webコンバージョン、モバイルコンバージョン、ライフタイムバリューなど、分析オブジェクト上のコンバージョンメトリクスは、フラット化されずにJSON文字列列として保存されます。

動画メトリクスの定義 ​

Xはvideo_total_viewsを再定義し、3秒以上100%表示された、または手動で再生ボタンがクリックされたことを意味するようにしました。以前の定義は、同じ分析オブジェクト上の別のvideo_3s100pct_views列として引き続き利用できます。必要な定義に一致する列を使用してください。 video_total_viewsが元の意味を持つと想定しないでください。

合成列 ​

Workatoは、削除トラッキングがあるオブジェクトの同期先テーブルに、次の合成列を追加します。

機密データの処理 ​

Xオブジェクトには個人を特定できる情報（PII）が含まれる場合があります。次のオブジェクトには、一般的に機密フィールドが含まれています。

Custom Audiencesは個々のオーディエンスメンバーを公開しません。 Xでは、メンバーリストがアップロード者によって既にハッシュ化されている必要があり、Workatoはそのメンバーレベルのデータを一切抽出しません。

パイプライン設定中にフィールドレベルのデータ保護でHashオプションを使用し、PIIが宛先に到達する前に保護します。詳細については、パイプラインを構成手順を参照してください。

制限事項 ​

Xをデータパイプラインソースとして使用する場合、次の制限が適用されます。

分析には広告主認証の完了が必要 ​

広告アカウントがAds ManagerでX広告主認証を完了するまで、分析オブジェクトとリーチオブジェクトは0行を返します。キャンペーンが有効で予算も有効であっても、認証が完了するまで配信メトリクスが生成されない場合があります。

リーチと平均フリークエンシーのウィンドウは7日に制限される ​

Reach & Average Frequencyオブジェクトは、7日を超えるリクエストウィンドウを拒否します。パイプラインは、これらのオブジェクトについて各実行でローリング7日ウィンドウを再取得します。

履歴分析バックフィルはジョブごとに制限される ​

X Ads APIは、90日を超える履歴にまたがる分析ジョブ、およびセグメント化されたオブジェクトの場合は45日を超える分析ジョブを拒否します。 Analytics backfill windowフィールドをこれらの制限より高く設定しないでください。設定すると同期が失敗します。詳細については、パイプラインの設定を参照してください。

都市圏レベルのセグメンテーションはサポートされていない ​

Xデータパイプラインは、年齢、性別、プラットフォーム、およびコンバージョンタグのセグメンテーションをサポートしています。都市圏レベル（Nielsen指定市場エリア）のセグメンテーションは利用できません。

最小同期頻度 ​

サポートされる最小同期間隔は15分です。