Aggregation Service を使用してリクエストをデプロイして管理する

Aggregation Service が正常にデプロイされたら、createJob エンドポイントと getJob エンドポイントを使用してサービスを操作できます。次の図は、これらの 2 つのエンドポイントのデプロイ アーキテクチャを視覚的に示しています。

Aggregation Service API の概要
図 1. Aggregation Service API の概要

createJob エンドポイントと getJob エンドポイントの詳細については、Aggregation Service API のドキュメントをご覧ください。

ジョブを作成する

ジョブを作成するには、createJob エンドポイントに POST リクエストを送信します。bash POST https://<api-gateway>/stage/v1alpha/createJob -+ createJob のリクエスト本文の例:

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<host name of reporting origin>"
  }
}

ジョブの作成が成功すると、202 HTTP ステータス コードが返されます。

reporting_siteattribution_report_to相互に排他的であり、どちらか一方のみが必要です。

job_parametersdebug_run を追加して、デバッグジョブをリクエストすることもできます。デバッグモードの詳細については、集計デバッグ実行のドキュメントをご覧ください。

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>"
    "debug_run": "true"
  }
}

リクエスト フィールド

パラメータ 説明
job_request_id 文字列 これは広告テクノロジーによって生成された一意の識別子で、ASCII 文字で 128 文字以内にする必要があります。これにより、バッチジョブ リクエストが識別され、広告テクノロジーのクラウド ストレージでホストされている「input_data_bucket_name」で指定された入力バケットから、「input_data_blob_prefix」で指定された集計可能なすべての AVRO レポートが取得されます。
文字数: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix 文字列 これはバケットパスです。単一のファイルの場合は、パスを使用できます。複数のファイルの場合は、パスの接頭辞を使用できます。
例: folder/file は、folder/file1.avro、folder/file/file1.avro、folder/file1/test/file2.avro のすべてのレポートを収集します。
input_data_bucket_name 文字列 これは、入力データまたは集計可能なレポートのストレージ バケットです。これは広告テクノロジーのクラウド ストレージにあります。
output_data_blob_prefix 文字列 これはバケット内の出力パスです。サポートされている出力ファイルは 1 つです。
output_data_bucket_name 文字列 これは、output_data が送信されるストレージ バケットです。これは、広告テクノロジーのクラウド ストレージに存在します。
job_parameters Dictionary 必須項目です。このフィールドには、次のようなさまざまなフィールドが含まれています。
  • output_domain_blob_prefix
  • output_domain_bucket_name
  • attribution_report_to
  • reporting_site
  • debug_privacy_epsilon
  • report_error_threshold_percentage
job_parameters.output_domain_blob_prefix 文字列 input_data_blob_prefix と同様に、これは出力ドメインの AVRO が配置されている output_domain_bucket_name 内のパスです。複数のファイルの場合は、パスの接頭辞を使用できます。Aggregation Service がバッチを完了すると、概要レポートが作成され、output_data_blob_prefix という名前で出力バケット output_data_bucket_name に配置されます。
job_parameters.output_domain_bucket_name 文字列 これは、出力ドメインの AVRO ファイルのストレージ バケットです。これは広告テクノロジーのクラウド ストレージにあります。
job_parameters.attribution_report_to 文字列 この値は「reporting_site」と相互に排他的です。これは、報告が受信された報告 URL または報告元です。サイトのオリジンが集計サービスのオンボーディングに登録されている。
job_parameters.reporting_site 文字列 attribution_report_to とは相互に排他的です。これは、レポートが受信されたレポート URL またはレポート元のホスト名です。サイトのオリジンが集計サービスのオンボーディングに登録されている。 注: すべてのオリジンがこのパラメータで指定された同じレポートサイトに属している場合、1 つのリクエスト内で異なるオリジンの複数のレポートを送信できます。
job_parameters.debug_privacy_epsilon 浮動小数点、倍精度 省略可能フィールド。値が渡されない場合、デフォルト値は 10 です。0 ~ 64 の値を使用できます。
job_parameters.report_error_threshold_percentage ダブル 省略可能フィールド。ジョブが失敗する前に許容される失敗レポートの最大割合です。空白のままにすると、デフォルト値は 10% になります。
job_parameters.input_report_count 長い値 省略可能フィールド。ジョブの入力データとして指定されたレポートの合計数。この値を report_error_threshold_percentage と組み合わせると、エラーが原因でレポートが除外されたときに、ジョブの早期失敗が可能になります。
job_parameters.filtering_ids 文字列 省略可能フィールド。未署名のフィルタ ID のカンマ区切りのリスト。一致するフィルタ ID 以外のすべての寄付は除外されます。(例: "filtering_ids": "12345,34455,12")。デフォルト値は 0 です。
job_parameters.debug_run ブール値 省略可能フィールド。デバッグ実行時に、ノイズありとノイズなしのデバッグ概要レポートとアノテーションが追加され、ドメイン入力またはレポートに存在するキーが示されます。また、バッチ間で重複するデータも適用されません。デバッグ実行では、フラグ "debug_mode": "enabled" が設定されているレポートのみが考慮されます。v2.10.0 以降、デバッグ実行ではプライバシー バジェットが消費されません。

ジョブの取得

広告テクノロジーがリクエストされたバッチのステータスを確認するには、getJob エンドポイントを呼び出します。getJob エンドポイントは、job_request_id パラメータとともに HTTPS GET リクエストを使用して呼び出されます。

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

ジョブのステータスとエラー メッセージが返されます。

{
    "job_status": "FINISHED",
    "request_received_at": "2023-07-17T19:15:13.926530Z",
    "request_updated_at": "2023-07-17T19:15:28.614942839Z",
    "job_request_id": "PSD_0003",
    "input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
    "input_data_bucket_name": "ags-report-bucket",
    "output_data_blob_prefix": "summary/summary.avro",
    "output_data_bucket_name": "ags-report-bucket",
    "postback_URL": "",
    "result_info": {
        "return_code": "SUCCESS",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-07-17T19:15:28.607802354Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "ags-report-bucket",
        "output_domain_blob_prefix": "output_domain/output_domain.avro",
        "attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
    },
    "request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}

レスポンスのフィールド

パラメータ 説明
job_request_id 文字列 これは、createJob リクエストで指定された一意のジョブ ID またはバッチ ID です。
job_status 文字列 これはジョブ リクエストのステータスです。
request_received_at 文字列 リクエストを受信した時刻。
request_updated_at 文字列 ジョブが最後に更新された時刻。
input_data_blob_prefix 文字列 これは、createJob で設定された入力データの接頭辞です。
input_data_bucket_name 文字列 これは、集計可能レポートが保存される広告テクノロジーの入力データ バケットです。このフィールドは createJob に設定されています。
output_data_blob_prefix 文字列 これは、createJob で設定された出力データの接頭辞です。
output_data_bucket_name 文字列 これは、生成された概要レポートが保存される広告テクノロジーの出力データ バケットです。このフィールドは createJob に設定されています。
request_processing_started_at 文字列 最新の処理の試行が開始された時刻。これには、ジョブキューで待機している時間は含まれません。(合計処理時間 = request_updated_at - request_processing_started_at
result_info Dictionary これは createJob リクエストの結果であり、利用可能なすべての情報で構成されています。 return_codereturn_messagefinished_aterror_summary の値が表示されます。
result_info.return_code 文字列 ジョブ結果の戻りコード。この情報は、集計サービスに問題がある場合にトラブルシューティングを行うために必要です。
result_info.return_message 文字列 ジョブの結果として返された成功または失敗のメッセージ。この情報は、Aggregation Service の問題のトラブルシューティングにも必要です。
result_info.error_summary Dictionary ジョブから返されるエラー。これには、報告の数と発生したエラーの種類が含まれます。
result_info.finished_at タイムスタンプ ジョブの完了を示すタイムスタンプ。
result_info.error_summary.error_counts リスト これにより、エラー メッセージのリストと、同じエラー メッセージで失敗したレポートの数が表示されます。各エラー数には、カテゴリ error_countdescription が含まれます。
result_info.error_summary.error_messages リスト これにより、処理に失敗したレポートのエラー メッセージのリストが返されます。
job_parameters Dictionary これには、createJob リクエストで指定されたジョブ パラメータが含まれます。関連するプロパティ(output_domain_blob_prefix や output_domain_bucket_name など)。
job_parameters.attribution_report_to 文字列 reporting_site とは相互に排他的です。報告の URL または報告の送信元です。オリジンは、集計サービスのオンボーディングで登録されたサイトの一部です。これは createJob リクエストで指定します。
job_parameters.reporting_site 文字列 attribution_report_to とは相互に排他的です。これは、レポート URL のホスト名またはレポートが受信された送信元です。オリジンは、集計サービスのオンボーディングで登録されたサイトの一部です。なお、すべてのレポート送信元がこのパラメータで指定された同じサイトに属している限り、1 つのリクエストで複数のレポート送信元のレポートを送信できます。これは createJob リクエストで指定します。また、バケットには、ジョブの作成時に集計するレポートのみが含まれていることを確認してください。入力データバケットに追加されたレポートで、レポート送信元がジョブ パラメータで指定されたレポートサイトと一致する場合、そのレポートは処理されます。 Aggregation Service は、ジョブの登録済みレポート送信元と一致するデータバケット内のレポートのみを考慮します。たとえば、登録されたオリジンが https://exampleabc.com の場合、バケットにサブドメイン(https://1.exampleabc.com など)またはまったく異なるドメイン(https://3.examplexyz.com)からのレポートが含まれていても、https://exampleabc.com からのレポートのみが含まれます。
job_parameters.debug_privacy_epsilon 浮動小数点、倍精度 省略可能フィールド。値が渡されなかった場合は、デフォルト値の 10 が使用されます。値は 0 ~ 64 です。この値は createJob リクエストで指定します。
job_parameters.report_error_threshold_percentage ダブル 省略可能フィールド。これは、ジョブが失敗する前に失敗する可能性があるレポートのしきい値の割合です。値が割り当てられていない場合は、デフォルト値の 10% が使用されます。これは createJob リクエストで指定します。
job_parameters.input_report_count 長い値 省略可能フィールド。このジョブの入力データとして提供されたレポートの合計数。report_error_threshold_percentage とこの値を組み合わせると、エラーが原因で大量のレポートが除外された場合に、ジョブの早期失敗がトリガーされます。この設定は、createJob リクエストで指定します。
job_parameters.filtering_ids 文字列 省略可能フィールド。未署名のフィルタ ID のカンマ区切りのリスト。一致するフィルタ ID 以外のすべての寄付は除外されます。これは createJob リクエストで指定します。(例: "filtering_ids":"12345,34455,12"。デフォルト値は「0」です)。