Aggregation Service API について

デプロイ後、Aggregation Service は広告テクノロジーの使用用に createJob と getJob の 2 つのエンドポイントを公開します。

AgS 図

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

createJob

createJob エンドポイントは HTTP POST リクエストを介して呼び出されます。このエンドポイントにはリクエスト本文が必要です。createJob リクエストが送信されると、HTTP 202 の成功レスポンスが返されます。

  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>"
  }
}

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 文字列 これは広告テクノロジーによって生成された一意の識別子で、128 文字以下の ASCII 文字にする必要があります。これにより、バッチジョブ リクエストが識別され、「input_data_blob_prefix」で指定されたすべての集計可能な avro レポートを、広告テクノロジーのクラウド ストレージでホストされている input_data_bucket_name で指定された入力バケットから取得します。
文字数: `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 文字列 バケット内の出力パスです。単一の出力ファイルがサポートされています。
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 内のパスです。複数のファイルの場合は、パスの接頭辞を使用できます。集計サービスがバッチを完了すると、概要レポートが作成され、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 またはレポート送信元のホスト名です。オリジンは、集計サービスのオンボーディングに登録されているサイトの一部になります。 注: すべての報告元がこのパラメータで指定された同じ報告サイトに属している限り、同じリクエストで複数の報告元を含むレポートを送信できます。
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" のレポートのみが考慮され、デバッグ実行では予算が消費されます。

getJob

広告テクノロジーがリクエストしたバッチのステータスを確認するには、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 です。
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 文字列 ジョブの結果の戻りコード。この情報は、Aggregation Service で問題が発生したときに、問題の原因を把握するために必要になります。
result_info.return_message 文字列 ジョブの結果として返されるメッセージ（成功または失敗）。この情報は、集計サービスの障害の調査時にも必要になります。
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 リクエストで指定します。また、バケットには、ジョブの作成時に集計するレポートのみが含まれていることを確認してください。その入力データバケットに追加された、レポート生成元がジョブ パラメータで指定したレポートサイトと一致するレポートがすべて処理されます。 たとえば、広告テクノロジーがレポート送信元 https://exampleabc.com を登録していて、入力データバケット内に https://1.exampleabc.com、https://2.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」です）。