本頁面由 Cloud Translation API 翻譯而成。

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

這個頁面中的內容
建立工作
取得工作

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

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

如要進一步瞭解 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`	字典	必填欄位。這個欄位包含不同的欄位，例如： `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_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」)。