data-manager-api-event-ingestion

Data Manager API イベント取り込み

実装ワークフロー

前提条件

• 認証とライブラリのインストール：Data Manager API へのアクセスを設定する必要がある場合、またはクライアントライブラリやユーティリティライブラリをインストールする場合は、data-manager-api-setup スキルを参照してください。

ステップ 1：ユースケースを特定してドキュメントを読む

• 宛先アカウントの種類を特定する：[重要] ユーザーのコンテキストから判断できない場合は、コードを生成する前に、イベントの取り込み先となる宛先を確認してください。これは Destination の operating_account にある account_type フィールドに対応し、有効なイベント識別子と要件も決定します。
• ユーザーの意図を特定する：
  • 取り込みコードを実装する場合：該当する宛先とユースケースに対応する、以下の実装ガイド列に記載された実装ガイドに従ってください。フィールド要件を満たし、宛先が正しく設定されていることを確認するうえで重要です。
  • リクエストのステータス確認またはエラーの調査を行う場合：以下のエラー処理とトラブルシューティングセクションを参照してください。
  • 別の Google API から移行する場合：以下のステップ 3：移行ガイドを取得するを参照し、該当するフィールドマッピングガイドの全内容を取得してください。

宛先（operating_account.account_type）	ユースケース	実装ガイド
Google Ads（GOOGLE_ADS）	オフライン コンバージョン、リードの拡張コンバージョン	イベントを送信
Google Ads（GOOGLE_ADS）	Google タグを補完する複数ソースのコンバージョン	イベントを送信
Google Ads（GOOGLE_ADS）	店舗販売コンバージョン	イベントを送信
Google Analytics（GOOGLE_ANALYTICS_PROPERTY）	推奨イベントとカスタム GA4 イベント	イベントを送信
Google Analytics（GOOGLE_ANALYTICS_PROPERTY）	トランザクション ID を含む複数ソースのイベント	イベントを送信
Floodlight（FLOODLIGHT_CONFIG）	Floodlight オフライン コンバージョン	イベントを送信
Floodlight（FLOODLIGHT_CONFIG）	Google タグまたは Floodlight タグを補完する複数ソースのコンバージョン	イベントを送信

リクエストがどの行にも該当しない場合は、推測せずに イベントの概要 を取得して、適切なガイドを確認してください。

ステップ 2：コードサンプルを取得する

重要

インジェストスクリプトを作成または更新する場合は、参照用として必ず 該当するコードサンプルを取得してください。

言語	サンプル
Python	ingest_events.py
Java	IngestEvents.java
PHP	ingest_events.php
Node	ingest_events.ts
.NET	IngestEvents.cs

ステップ 3：移行ガイドを取得する

重要

別の Google API からアップグレードするためにコードをリファクタリングする場合は、 該当するフィールドマッピングガイドの全文を必ず抽出してください。

Google Ads

• オフラインコンバージョン、見込み顧客向け拡張コンバージョン（Google Ads API から移行する場合）： Google Ads のオフラインコンバージョン移行用フィールドマッピング
• 店舗販売コンバージョン（Google Ads API から移行する場合）： Google Ads の店舗販売移行用フィールドマッピング

Google Analytics

• 推奨イベントとカスタム GA4 イベント（Google Analytics Measurement Protocol から移行する場合）： Google Analytics Measurement Protocol の移行用フィールドマッピング

Floodlight

• Floodlight のオフラインコンバージョン（Campaign Manager 360 API から移行する場合）： Campaign Manager 360 のオフラインコンバージョン移行用フィールドマッピング

ステップ 4：実装

以下のチェックポイントに沿って、取り込みロジックを実装します。

• クライアントを初期化する：Data Manager クライアント （IngestionServiceClient）をインスタンス化します。
• 送信先を定義する：product_destination_id と適切なアカウント設定を使って Destination オブジェクトを構築します： operating_account（データを受け取る対象アカウント）、login_account（マネージャーアカウントまたは データパートナーアカウントで認証する場合）、および linked_account（データパートナーがマネージャーアカウントへのパートナーリンクを介して アカウントにアクセスする場合）。強く推奨：送信先の設定について詳しくは、 送信先とヘッダーの設定 ガイドを参照してください。
• イベントデータを準備する：ユーティリティライブラリのヘルパーを使って、 ユーザー識別子を正しくフォーマットし、正規化します。
• ペイロードを構築する：送信先、イベントレコード、同意の許可を含むリクエストペイロード （IngestEventsRequest）を構築します。
• 検証に対応する：IngestEventsRequest の validate_only ブール値オプションの送信に対応し、 データを実際にアップロードせずにスキーマを検証できるようにします。
• リクエストを送信する：ingest_events を実行し、後で診断に使えるよう返された request_id を記録します。
• 取り込み警告を確認する：必須ではないフィールドで検証に失敗した場合、 ingest_events のレスポンスには問題の詳細を示す FieldWarning オブジェクトのリスト field_warnings も含まれます。
• リクエストのステータスを取得する：診断機能を使って、取り込みリクエストのステータスを確認します。 リクエストの処理は非同期であるため、取り込み成功のレスポンス（request_id を返す HTTP 200 OK）は、 ペイロードが受信されたことだけを示します。レコードの処理が成功、一部成功、または失敗したかを確認するには、 request_id を使って client.retrieve_request_status エンドポイントに問い合わせます。 この手順を省略するのは、よくあるユーザーの誤りです。

フォーマット

• ユーザーデータのフォーマット ガイドを取得し、フォーマットと正規化のルールの基準として使用します。

• ユーティリティライブラリを使って、ユーザーデータ（メールアドレス、電話番号、住所）をフォーマットし、 ハッシュ化および暗号化します。

  Python の例：

  from google.ads.datamanager_util import Formatter
  from google.ads.datamanager_util.format import Encoding
  
  formatter: Formatter = Formatter()
  
  processed_email: str = formatter.process_email_address(
      email, Encoding.HEX
  )
  

重要な注意点

• product_destination_id は数値文字列としてフォーマットします。リソース名のパスではありません。
• event_timestamp は RFC 3339 形式で厳密にフォーマットします。使用可能な場合は、生の文字列ではなく SDK の型付きタイムスタンプオブジェクトを使用します。
• クリック識別子（gclid、gbraid、wbraid）は、ベースイベントペイロードに直接指定するのではなく、 ad_identifiers ブロック内にネストします。
• ConsentStatus の列挙値は CONSENT_GRANTED と CONSENT_DENIED です。 GRANTED と DENIED は使用しないでください。
• consent は、IngestEventsRequest 全体に設定することも、個々の Event に設定することもできます。
• UserIdentifier では email_address と phone_number を使用することを確認してください。 Google Ads API のフィールド hashed_email と hashed_phone_number は使用しないでください。
• イベントの通貨フィールド名は currency であり、currency_code ではないことを確認してください。
• validate_only が true に設定されている場合、診断エンドポイント（retrieve_request_status）を呼び出さないでください。

エラー処理とトラブルシューティング

エラーペイロードと取り込み時の警告を確認する

重要

エラーと警告の構造を理解する方法について詳しくは、API エラーを理解するを参照してください。 API から返されるエラーと警告の構造を理解するための詳しいガイドです。

リクエストのステータスを取得する（診断）

IngestEventsRequest を送信してから少なくとも 30 分経過した後、指数バックオフを使用してステータスを定期的にポーリングします。

1. RetrieveRequestStatusRequest(request_id=...) を使用して client.retrieve_request_status を呼び出します。
2. 応答内の request_status_per_destination をループし、 各ターゲットの request_status を確認します。
3. 処理が完了し、request_status が SUCCESS、PARTIAL_SUCCESS、または FAILED の場合は、診断値を確認します。
   • イベントレコード数：events_ingestion_status.record_count を確認します （成功と失敗の両方が含まれます）。
   • エラーの詳細：ステータスが FAILED または PARTIAL_SUCCESS の場合は、 error_info.error_counts にある各エラーの reason と record_count を確認します。
   • 警告の詳細：送信先のステータスが SUCCESS の場合も含め、 warning_info.warning_counts にある各警告の reason と record_count を確認します。

API リファレンス

• REST API リファレンス
• 診断ガイド