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

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_site
と attribution_report_to
は相互に排他的であり、どちらか一方のみが必要です。
job_parameters
に debug_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 |
必須項目です。このフィールドには、次のようなさまざまなフィールドが含まれています。
|
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_code 、return_message 、finished_at 、error_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_count と description が含まれます。
|
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」です)。 |