data-manager-api-audience-ingestion

Data Manager API のオーディエンスデータ取り込み

実装ワークフロー

前提条件

• 認証とライブラリのインストール：Data Manager API のアクセス設定、またはクライアントライブラリとユーティリティライブラリのインストールが必要な場合は、data-manager-api-setup スキルを参照してください。
• オーディエンスの作成（必要な場合）：既存のオーディエンスがない場合や、新しいオーディエンスを作成する必要がある場合は、オーディエンスの作成のリファレンスを使用してください。この手順では、取り込みリクエストまたは削除リクエストに必要な product_destination_id を取得できます。

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

• 送信先アカウントの種類を特定する：[重要] データの送信先（例：Google Ads、Display & Video 360 など）が明確でない場合は、コードを生成する前に作業を停止し、ユーザーに確認してください。デフォルトで Google Ads と決めつけないでください。これは、Destination 内の operating_account の account_type フィールドに対応します。
• 実装ガイドを読む：送信先とユースケースに該当するガイドを読んでください。質問に回答したりコードを書いたりする前に必ず確認してください。送信先ごとにペイロードの構造、同意に関するルール、必須フィールドが異なるためです。

送信先	オーディエンスの種類	受け付けるデータ型	アップロードガイド	すべて削除／すべて置換のガイド
Google Ads	Customer Match	composite_data.user_data（連絡先情報）、mobile_data（デバイス ID）、user_id_data（ユーザー ID）	データのアップロード	すべて削除／すべて置換
Display & Video 360（DV360）	Customer Match	composite_data.user_data（連絡先情報）、mobile_data（デバイス ID）	データのアップロード	すべて削除／すべて置換

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

重要

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

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

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

重要

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

Google Ads

• Google Ads API の Customer Match：Google Ads API から Customer Match への移行：フィールドマッピング

Display & Video 360

• Display & Video 360 API の Customer Match：Display & Video 360 API から Customer Match への移行：フィールドマッピング

Step 4: 実装

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

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

重要な注意点

• ingest_audience_members または remove_audience_members の user_data に ハッシュ化されたユーザー識別子を送信する場合は、IngestAudienceMembersRequest の encoding フィールドに HEX または BASE64 を設定する必要があります。
• Customer Match オーディエンスにアップロードする場合、ユーザーがポリシーに同意したことを示すため、 IngestAudienceMembersRequest の terms_of_service フィールドが必須です。
• UserIdentifier の address フィールドは、必須フィールド （postal_code、family_name、given_name、region_code）がすべて揃っている場合にのみ設定してください。 address フィールドが不完全だと、API リクエストは失敗します。
• product_destination_id は数値文字列である必要があります。リソース名ではありません。
• ConsentStatus の列挙値は CONSENT_GRANTED と CONSENT_DENIED です。GRANTED と DENIED は使用しないでください。
• UserIdentifier のフィールド名は email_address と phone_number です。 Google Ads API のフィールド名である hashed_email と hashed_phone_number は使用しないでください。
• validate_only が true に設定されている場合は、診断エンドポイント （retrieve_request_status）を呼び出さないでください。

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

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

重要

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

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

指数バックオフを使用して定期的にステータスをポーリングします。ポーリングはリクエスト送信後、少なくとも 30 分経ってから開始してください。

1. RetrieveRequestStatusRequest(request_id=...) を使用して、client.retrieve_request_status を呼び出します。
2. レスポンス内の request_status_per_destination をループし、各ターゲットの request_status を確認します。
3. 処理が完了し、request_status が SUCCESS、PARTIAL_SUCCESS、または FAILED の場合は、診断値を確認します。
   • オーディエンスのステータス：リクエストに固有のステータスを確認します。
     • 取り込み：audience_members_ingestion_status の下にネストされたデータ型固有のステータス（例：composite_data_ingestion_status）を確認します。
     • 個別メンバーの削除：audience_members_removal_status の下にネストされたデータ型固有のステータス（例：composite_data_removal_status）を確認します。
     • すべてのメンバーの削除：このリクエストタイプでは、ネストされたステータスフィールドや確認可能なレコード数はありません。
     • レコード数：該当する場合（取り込みまたは個別メンバーの削除）、record_count（データ型固有のステータスオブジェクト内にネストされています）を確認します。この値には成功と失敗の両方が含まれます。
     • 識別子数：該当する場合（取り込みまたは個別メンバーの削除）、ステータスオブジェクト内にネストされたデータ型固有の件数フィールド（例：コンポジットデータのアップロードまたは削除時の data_type_counts、モバイル ID のアップロードまたは削除時の mobile_id_count）を確認します。その他の件数フィールドについては、診断ガイドを参照してください。
     • マッチ率の範囲：user_data と composite_data のアップロードでは、ステータスオブジェクト内にネストされた upload_match_rate_range を確認します。
   • エラーの詳細：ステータスが FAILED または PARTIAL_SUCCESS の場合は、error_info.error_counts の下にある各エラーの reason と record_count を確認します。
   • 警告の詳細：宛先のステータスが SUCCESS の場合も含め、warning_info.warning_counts の下にある各警告の reason と record_count を確認します。

API リファレンス

• オーディエンスメンバー送信ガイド
• REST API リファレンス：取り込み
• REST API リファレンス：削除
• REST API リファレンス：すべて削除