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

瞭解匯總服務 API

部署完成後，匯總服務會公開兩個端點供廣告技術使用：createJob 和 getJob。

AgS 圖表

如要進一步瞭解 createJob 和 getJob 端點，請參閱匯總服務 API 說明文件。

createJob

系統會透過 HTTP POST 要求呼叫 createJob 端點，而且需要要求主體。發出 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 互斥，而且只需要使用一個。

您也可以將 debug_run 新增至 job_parameters，以要求偵錯工作。如要瞭解偵錯模式，請參閱匯總偵錯執行作業說明文件。

{
  "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`	字串	這是值區中的路徑。如果是單一檔案，您可以使用路徑。如果是多個檔案，您可以在路徑中使用前置字串。 (範例) 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`	字典	必填欄位。當中包含不同欄位，例如： `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"` 旗標的報表，且偵錯執行作業會消耗預算。

getJob

廣告技術人員如要瞭解要求批次的狀態，可以呼叫 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://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」)。