使用匯總服務部署及管理要求

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

Aggregation Service API 總覽
圖 1.匯總服務 API 總覽

如要進一步瞭解 createJobgetJob 端點,請參閱 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_siteattribution_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 字典 必填欄位。這個欄位包含不同的欄位,例如:
  • 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 類似,這是 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_codereturn_messagefinished_aterror_summary 值。
result_info.return_code 字串 工作結果傳回代碼。如果匯入服務發生問題,您需要使用這些資訊進行疑難排解。
result_info.return_message 字串 工作結果傳回的成功或失敗訊息。這項資訊也適用於疑難排解匯集服務問題。
result_info.error_summary 字典 工作傳回的錯誤。這項資料包含報表數量,以及發生的錯誤類型。
result_info.finished_at 時間戳記 指示工作完成時間戳記。
result_info.error_summary.error_counts 清單 這會傳回錯誤訊息清單,以及因相同錯誤訊息而失敗的報表數量。每個錯誤計數都包含一個類別、error_countdescription
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」)。