おすすめの方法

Data Manager API を使用する際は、次のベスト プラクティスを念頭に置いてください。

すべてのユーザー識別子を送信する

UserData を使用してオーディエンス メンバーまたはイベントを送信する場合は、同じタイプの複数の識別子を送信するなど、できるだけ多くの user_identifiers を含めます。

たとえば、ユーザーに複数のメールアドレスがある場合は、メールアドレスごとに個別の UserIdentifier を含めます。同様に、ユーザーに異なるタイプの識別子（メールアドレス、電話番号、住所など）がある場合は、識別子ごとに個別の UserIdentifier を追加します。追加できる識別子の数は、最大識別子数までです。

リクエストを最適化する

1 日あたりのリクエスト数の上限を超える可能性を減らすには、各リクエストでできるだけ多くのアイテムをバッチ処理します（リクエストごとの上限まで）。

たとえば、10,000 人のオーディエンス メンバーをオーディエンスに追加する場合は、1 つの IngestAudienceMembersRequest の audience_members リストに 10,000 人のメンバーをすべて追加します。10,000 人のメンバーを 1 つのリクエストにまとめてバッチ処理する方が、各オーディエンス メンバーを追加するリクエストを個別に送信するよりも効率的です。

同時リクエストを送信する

データの取り込みに必要な全体的な時間を短縮するには、IngestionService に同時リクエストを送信します。1 分あたりのリクエスト数の上限を超えないように、同時に送信するリクエストは 10 件までにすることをおすすめします。

リクエストに同じ destinations が含まれている場合でも、同時リクエストを送信できます。

クライアントサイドでデータを検証する

Data Manager API はファストフェイル モデルを使用します。リクエスト内のいずれかのレコードが同期検証に失敗すると、リクエスト全体が失敗し、どのレコードも処理されません。また、API はリクエストを順次レイヤで検証するため、1 つのエラーを修正すると、後続の検証レイヤでエラーが発生することがあります。

往復の繰り返しやリクエストの拒否を回避するには、データを送信する前に検証とサニタイズを行います。

• ハッシュ化する前に空の値を削除する: SHA-256 ハッシュを計算する前に、email_address や phone_number などのフィールドに空の文字列や空白のみの文字列がないか確認します。空の文字列をハッシュ化すると、構文チェックに合格する有効なハッシュが生成されますが、マッチ率が低下します。

• 不完全な複合オブジェクトを削除する: 複合オブジェクトをレコードに追加する前に、必要なフィールドがすべて揃っていることを確認します。たとえば、AddressInfo オブジェクトに 4 つの必須フィールド（given_name、family_name、region_code、postal_code）のいずれかが欠落している場合は、REQUIRED_FIELD_MISSING エラーを回避するために address 識別子全体を削除します。

• エンコード フィールドと平文フィールドを検証する: ハッシュ化されたフィールドが、未加工の平文を送信するのではなく、宣言された encoding と一致することを確認します。また、平文のままにする必要があるフィールド（mobile_ids など）がハッシュ化されていないことを確認します。

• 範囲外のタイムスタンプをフィルタする: タイムスタンプが、将来の日付や、リンク先のコンバージョンのルックバック ウィンドウよりも古い日付になっていないことを確認します。

  JSON を使用してリクエストを送信する場合は、タイムスタンプ文字列でタイムゾーン オフセット付きの RFC 3339 形式を使用してください。

• 電話番号をクリーンアップする: 電話番号に国コードが含まれていることを確認し、ハッシュ化する前に E.164 形式を使用します。

• 空のレコードまたはサイズ超過のレコードを削除する: user_identifiers をレコードあたりの上限（10 個の識別子）に制限し、空のカスタム パラメータを削除して、有効な識別子が含まれていないレコードを省略します。

• ユースケースの要件を確認する: 各イベントに、宛先とユースケースのすべての必須フィールド（Google 広告のオンライン コンバージョンの transaction_id など）が含まれていることを確認します。ユースケース別の必須フィールドの完全なリストについては、イベントの概要で、送信先のイベント送信ガイドをご覧ください。

• validateOnly を使用してリクエストをテストする: validateOnly を true に設定してリクエストを送信し、データの取り込みや削除を行わずにファストフェイル エラーをキャッチします。検証のみのリクエストが成功しても、非同期処理中にエラーが発生しないとは限りません。通常のリクエストを送信した後も、リクエストのステータスと診断を確認してください。

正規化とハッシュ化のルールの詳細については、ユーザーデータをフォーマットするをご覧ください。

リクエストのステータスと診断を確認する

重要: 各取り込みリクエストのリクエスト ステータスと診断を確認して、オーディエンスまたはイベントの処理でエラーや警告が発生していないか確認します。

各 IngestAudienceMembersResponse または IngestEventsResponse から request_id をキャプチャして収集し、リクエスト ID を使用してリクエストのステータスと診断を確認します。

割り当てのモニタリングとアラート

予期しないリクエストの拒否を回避するには、Google Cloud コンソールで割り当てアラートとモニタリングを設定します。割り当て使用量をモニタリングすると、アプリケーションが1 日あたりの上限または 1 分あたりの上限に達する前に、消費パターンを追跡してリクエストのバッチ処理を最適化できます。

本番環境にデプロイする

ローカルテストから本番環境のワークロードに移行する場合は、サービス アカウントまたは Workload Identity 連携が関連付けられたアプリケーションのデフォルト認証情報を使用して、非対話型で安全に認証します。

さまざまな本番環境の認証を構成する方法については、本番環境にデプロイするをご覧ください。