成功部署匯總服務後,您可以使用 createJob
和 getJob
端點與服務互動。下圖以視覺化方式呈現這兩個端點的部署架構:

如要進一步瞭解 createJob
和 getJob
端點,請參閱 Aggregation Service API 說明文件。
建立工作
如要建立工作,請將 POST 要求傳送至 createJob
端點。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 |
字串 |
這是廣告技術產生的專屬 ID,應為 ASCII 字母,長度不得超過 128 個半形字元。這會識別批次工作要求,並從廣告技術雲端儲存空間中 `input_data_bucket_name` 指定的輸入值區中,取得 `input_data_blob_prefix` 中指定的所有可匯總 AVRO 報表。 字元: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
|
input_data_blob_prefix |
字串 |
這是桶的路徑。如要處理單一檔案,您可以使用路徑。如果是多個檔案,您可以在路徑中使用前置字串。 (範例) 資料夾/檔案會收集資料夾/file1.avro、資料夾/檔案/file1.avro 和資料夾/檔案 1/測試/file2.avro 中的所有報表。 |
input_data_bucket_name |
字串 | 這是輸入資料或可匯總報表的儲存空間值區。這會儲存在廣告技術的雲端儲存空間。 |
output_data_blob_prefix |
字串 | 這是值區中的輸出路徑。支援單一輸出檔案。 |
output_data_bucket_name |
字串 |
這是 output_data 傳送的儲存空間值區。這項資訊位於廣告技術的雲端儲存空間中。
|
job_parameters |
字典 |
必填欄位。這個欄位包含不同的欄位,例如:
|
job_parameters.output_domain_blob_prefix |
字串 |
與 input_data_blob_prefix 類似,這是 output_domain_bucket_name 中輸出網域 AVRO 所在的路徑。如果是多個檔案,您可以在路徑中使用前置字串。匯總服務完成批次作業後,系統會建立摘要報表,並將其放入名為 output_data_blob_prefix 的輸出值區 output_data_bucket_name 。 |
job_parameters.output_domain_bucket_name |
字串 | 這是輸出網域 AVRO 檔案的儲存值區。這會儲存在廣告技術的雲端儲存空間。 |
job_parameters.attribution_report_to |
字串 | 這個值與 `reporting_site` 互斥。這是報表的報表網址或報表來源。網站來源會在匯總服務新手上路程序中註冊。 |
job_parameters.reporting_site |
字串 |
與 attribution_report_to 互斥。這是報表網址的主機名稱,或收到報表的報表來源。網站來源會在匯總服務新手上路程序中註冊。
注意:您可以在單一要求中提交多份來源不同的報表,前提是所有來源都屬於此參數中指定的相同報表網站。 |
job_parameters.debug_privacy_epsilon |
浮點,Double | 選填欄位。如未傳遞任何值,則預設值為 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" 標記的報表。自 2.10.0 版起,偵錯執行作業「不會」消耗隱私預算。 |
取得工作
廣告技術人員如要瞭解要求批次的狀態,可以呼叫 getJob
端點。使用 HTTPS GET 要求搭配 job_request_id
參數呼叫 getJob
端點。
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 |
字典 |
這是 createJob 要求的結果,包含所有可用的資訊。這會顯示 return_code 、return_message 、finished_at 和 error_summary 值。 |
result_info.return_code |
字串 | 工作結果傳回代碼。如果匯入服務發生問題,您需要使用這些資訊進行疑難排解。 |
result_info.return_message |
字串 | 工作結果傳回的成功或失敗訊息。這項資訊也適用於疑難排解匯集服務問題。 |
result_info.error_summary |
字典 | 工作傳回的錯誤。這項資料包含報表數量,以及發生的錯誤類型。 |
result_info.finished_at |
時間戳記 | 指示工作完成時間戳記。 |
result_info.error_summary.error_counts |
清單 |
這會傳回錯誤訊息清單,以及因相同錯誤訊息而失敗的報表數量。每個錯誤計數都包含一個類別、error_count 和 description 。 |
result_info.error_summary.error_messages |
清單 | 這會傳回無法處理的報表錯誤訊息清單。 |
job_parameters |
字典 |
此參數包含 createJob 要求中提供的工作參數。相關屬性,例如 `output_domain_blob_prefix` 和 `output_domain_bucket_name`。
|
job_parameters.attribution_report_to |
字串 |
與 reporting_site 互斥。這是報表網址或收到報表的來源。來源是匯總服務新手上路功能中註冊的網站一部分。這會在 createJob 要求中指定。 |
job_parameters.reporting_site |
字串 |
與 attribution_report_to 互斥。這是報表網址的主機名稱,或報表來源的來源。來源是匯總服務新手上路功能中註冊的網站一部分。請注意,只要所有報表來源都屬於這個參數中提及的網站,您就可以在同一個要求中提交含有多個報表來源的報表。這項資訊會在 createJob 要求中指定。此外,請確認分類中只包含您要在工作建立時匯總的報表。系統會處理新增至輸入資料集的報表,只要報表來源與工作參數中指定的報表網站相符即可。
匯總服務只會考量與工作已註冊報表來源相符的資料值區內報表。舉例來說,如果註冊的來源是 https://exampleabc.com,則系統只會納入 https://exampleabc.com 的報表,即使分類包含子網域 (https://1.exampleabc.com 等) 或完全不同的網域 (https://3.examplexyz.com ) 的報表,也是如此。
|
job_parameters.debug_privacy_epsilon |
浮點,Double |
選填欄位。如果未傳遞任何值,系統會使用預設值 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」)。 |