Sau khi triển khai thành công Dịch vụ tổng hợp, bạn có thể sử dụng các điểm cuối createJob và getJob để tương tác với dịch vụ này. Sơ đồ sau đây minh hoạ trực quan cấu trúc triển khai cho hai điểm cuối này:
Bạn có thể đọc thêm về các điểm cuối createJob và getJob trong tài liệu về Aggregation Service API.
Tạo một công việc
Để tạo một công việc, hãy gửi yêu cầu POST đến điểm cuối createJob.
bash
POST https://<api-gateway>/stage/v1alpha/createJob
-+
Ví dụ về nội dung yêu cầu cho 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>"
}
}
Việc tạo công việc thành công sẽ dẫn đến mã trạng thái HTTP 202.
Xin lưu ý rằng reporting_site và attribution_report_to loại trừ lẫn nhau và bạn chỉ cần một trong hai.
Bạn cũng có thể yêu cầu một tác vụ gỡ lỗi bằng cách thêm debug_run vào job_parameters.
Để biết thêm thông tin về chế độ gỡ lỗi, hãy xem tài liệu về lượt chạy gỡ lỗi tổng hợp.
{
"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"
}
}
Trường yêu cầu
| Tham số | Loại | Mô tả |
|---|---|---|
job_request_id |
Chuỗi |
Đây là giá trị nhận dạng duy nhất do công nghệ quảng cáo tạo ra và phải là các chữ cái ASCII có độ dài tối đa 128 ký tự. Thao tác này xác định yêu cầu công việc hàng loạt và lấy tất cả báo cáo AVRO có thể tổng hợp được chỉ định trong `input_data_blob_prefix` từ nhóm đầu vào được chỉ định trong `input_data_bucket_name` được lưu trữ trên bộ nhớ đám mây của công nghệ quảng cáo.
Ký tự: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
|
input_data_blob_prefix |
Chuỗi |
Đây là đường dẫn đến nhóm. Đối với các tệp riêng lẻ, bạn có thể sử dụng đường dẫn. Đối với nhiều tệp, bạn có thể sử dụng tiền tố trong đường dẫn.
Ví dụ: Thư mục/tệp thu thập tất cả báo cáo từ thư mục/tệp1.avro, thư mục/tệp/tệp1.avro và thư mục/tệp1/test/tệp2.avro. |
input_data_bucket_name |
Chuỗi | Đây là vùng lưu trữ cho dữ liệu đầu vào hoặc báo cáo có thể tổng hợp. Đây là bộ nhớ trên đám mây của công nghệ quảng cáo. |
output_data_blob_prefix |
Chuỗi | Đây là đường dẫn đầu ra trong nhóm. Hệ thống hỗ trợ một tệp đầu ra. |
output_data_bucket_name |
Chuỗi |
Đây là vùng lưu trữ nơi output_data được gửi đến. Dữ liệu này nằm trong bộ nhớ trên đám mây của công nghệ quảng cáo.
|
job_parameters |
Từ điển |
Trường bắt buộc. Trường này chứa các trường khác nhau, chẳng hạn như:
|
job_parameters.output_domain_blob_prefix |
Chuỗi |
Tương tự như input_data_blob_prefix, đây là đường dẫn trong output_domain_bucket_name nơi đặt AVRO miền đầu ra của bạn. Đối với nhiều tệp, bạn có thể sử dụng tiền tố trong đường dẫn. Sau khi Dịch vụ tổng hợp hoàn tất lô, báo cáo tóm tắt sẽ được tạo và đặt trong vùng chứa đầu ra output_data_bucket_name có tên output_data_blob_prefix.
|
job_parameters.output_domain_bucket_name |
Chuỗi | Đây là vùng lưu trữ cho tệp AVRO miền đầu ra của bạn. Đây là bộ nhớ trên đám mây của công nghệ quảng cáo. |
job_parameters.attribution_report_to |
Chuỗi | Giá trị này không bao gồm `reporting_site`. Đây là URL báo cáo hoặc nguồn báo cáo nơi nhận được báo cáo. Nguồn gốc của trang web được đăng ký trong quy trình Bắt đầu sử dụng Dịch vụ tổng hợp. |
job_parameters.reporting_site |
Chuỗi |
Loại trừ lẫn nhau với attribution_report_to. Đây là tên máy chủ của URL báo cáo hoặc nguồn báo cáo nơi nhận được báo cáo. Nguồn gốc của trang web được đăng ký trong quy trình Bắt đầu sử dụng Dịch vụ tổng hợp.
Lưu ý: Bạn có thể gửi nhiều báo cáo có nguồn gốc khác nhau trong một yêu cầu duy nhất, miễn là tất cả nguồn gốc đều thuộc cùng một trang web báo cáo được chỉ định trong tham số này.
|
job_parameters.debug_privacy_epsilon |
Dấu phẩy động, Độ chính xác gấp đôi | Trường không bắt buộc. Nếu không có giá trị nào được truyền, giá trị mặc định sẽ là 10. Bạn có thể dùng giá trị từ 0 đến 64. |
job_parameters.report_error_threshold_percentage |
Đôi | Trường không bắt buộc. Đây là tỷ lệ phần trăm tối đa của các báo cáo không thành công được phép trước khi công việc không thành công. Nếu để trống, giá trị mặc định là 10%. |
job_parameters.input_report_count |
giá trị dài |
Trường không bắt buộc. Tổng số báo cáo được cung cấp dưới dạng dữ liệu đầu vào cho công việc. Giá trị này, cùng với report_error_threshold_percentage, cho phép thất bại sớm khi các báo cáo bị loại trừ do lỗi.
|
job_parameters.filtering_ids |
Chuỗi |
Trường không bắt buộc. Danh sách mã lọc chưa ký được phân tách bằng dấu phẩy. Tất cả nội dung đóng góp khác với mã nhận dạng lọc trùng khớp sẽ bị lọc ra. (ví dụ:"filtering_ids": "12345,34455,12"). Giá trị mặc định là "0".
|
job_parameters.debug_run |
Boolean |
Trường không bắt buộc. Khi thực thi một lần chạy gỡ lỗi, các chú thích và báo cáo tóm tắt gỡ lỗi có tiếng ồn và không có tiếng ồn sẽ được thêm vào để cho biết những khoá nào có trong đầu vào và/hoặc báo cáo miền. Ngoài ra, các mặt hàng trùng lặp trên các lô cũng không được thực thi. Xin lưu ý rằng quá trình chạy gỡ lỗi chỉ xem xét những báo cáo có cờ "debug_mode": "enabled". Kể từ phiên bản 2.10.0, các lần chạy gỡ lỗi không tiêu tốn ngân sách quyền riêng tư.
|
Tìm việc làm
Khi muốn biết trạng thái của một lô được yêu cầu, công nghệ quảng cáo có thể gọi điểm cuối getJob. Điểm cuối getJob được gọi bằng yêu cầu HTTPS GET cùng với tham số job_request_id.
GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>
Bạn sẽ nhận được một phản hồi trả về trạng thái của lệnh cùng với mọi thông báo lỗi:
{
"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"
}
Trường phản hồi
| Tham số | Loại | Mô tả |
|---|---|---|
job_request_id |
Chuỗi |
Đây là mã nhận dạng duy nhất của công việc/lô được chỉ định trong yêu cầu createJob.
|
job_status |
Chuỗi | Đây là trạng thái của yêu cầu công việc. |
request_received_at |
Chuỗi | Thời gian nhận được yêu cầu. |
request_updated_at |
Chuỗi | Thời gian cập nhật gần đây nhất của công việc. |
input_data_blob_prefix |
Chuỗi |
Đây là tiền tố dữ liệu đầu vào được đặt tại createJob.
|
input_data_bucket_name |
Chuỗi |
Đây là vùng chứa dữ liệu đầu vào của công nghệ quảng cáo, nơi lưu trữ các báo cáo có thể tổng hợp. Trường này được đặt tại createJob.
|
output_data_blob_prefix |
Chuỗi |
Đây là tiền tố dữ liệu đầu ra được đặt tại createJob.
|
output_data_bucket_name |
Chuỗi |
Đây là vùng chứa dữ liệu đầu ra của công nghệ quảng cáo, nơi lưu trữ các báo cáo tóm tắt được tạo. Trường này được đặt tại createJob.
|
request_processing_started_at |
Chuỗi |
Thời gian bắt đầu lần xử lý gần đây nhất. Điều này không bao gồm thời gian chờ trong hàng đợi công việc.
(Tổng thời gian xử lý = request_updated_at – request_processing_started_at)
|
result_info |
Từ điển |
Đây là kết quả của yêu cầu createJob và bao gồm tất cả thông tin có sẵn.
Thao tác này sẽ cho thấy các giá trị return_code, return_message, finished_at và error_summary.
|
result_info.return_code |
Chuỗi | Mã kết quả trả về của lệnh. Thông tin này là cần thiết để khắc phục sự cố nếu có vấn đề xảy ra trong Dịch vụ tổng hợp. |
result_info.return_message |
Chuỗi | Thông báo thành công hoặc không thành công được trả về do công việc. Thông tin này cũng cần thiết để khắc phục các vấn đề về Dịch vụ tổng hợp. |
result_info.error_summary |
Từ điển | Các lỗi trả về từ công việc. Báo cáo này chứa số lượng báo cáo cùng với loại lỗi đã gặp phải. |
result_info.finished_at |
Dấu thời gian | Dấu thời gian cho biết thời điểm hoàn thành công việc. |
result_info.error_summary.error_counts |
Danh sách |
Thao tác này sẽ trả về danh sách thông báo lỗi cùng với số lượng báo cáo không thành công có cùng thông báo lỗi. Mỗi lỗi đều có một danh mục, error_count và description.
|
result_info.error_summary.error_messages |
Danh sách | Thao tác này trả về danh sách thông báo lỗi từ những báo cáo không xử lý được. |
job_parameters |
Từ điển |
Tham số này chứa các tham số công việc được cung cấp trong yêu cầu createJob. Các thuộc tính liên quan như `output_domain_blob_prefix` và `output_domain_bucket_name`.
|
job_parameters.attribution_report_to |
Chuỗi |
Loại trừ lẫn nhau với reporting_site. Đây là URL báo cáo hoặc nguồn gốc của nơi nhận được báo cáo. Nguồn gốc là một phần của trang web được đăng ký trong quy trình Bắt đầu sử dụng Dịch vụ tổng hợp. Tham số này được chỉ định trong yêu cầu createJob.
|
job_parameters.reporting_site |
Chuỗi |
Loại trừ lẫn nhau với attribution_report_to. Đây là tên máy chủ của URL báo cáo hoặc nguồn gốc nơi nhận được báo cáo. Nguồn gốc là một phần của trang web được đăng ký trong quy trình Bắt đầu sử dụng Dịch vụ tổng hợp. Xin lưu ý rằng bạn có thể gửi báo cáo có nhiều nguồn báo cáo trong cùng một yêu cầu, miễn là tất cả nguồn báo cáo đều thuộc cùng một trang web được đề cập trong tham số này. Tham số này được chỉ định trong yêu cầu createJob. Ngoài ra, hãy xác minh rằng nhóm chỉ chứa những báo cáo mà bạn muốn tổng hợp tại thời điểm tạo công việc. Mọi báo cáo được thêm vào nhóm dữ liệu đầu vào có nguồn gốc báo cáo khớp với trang web báo cáo được chỉ định trong tham số công việc đều được xử lý.
Dịch vụ tổng hợp chỉ xem xét các báo cáo trong nhóm dữ liệu khớp với nguồn báo cáo đã đăng ký của công việc. Ví dụ: nếu nguồn gốc đã đăng ký là https://exampleabc.com, thì chỉ những báo cáo từ https://exampleabc.com mới được đưa vào, ngay cả khi nhóm chứa báo cáo từ các miền con (https://1.exampleabc.com, v.v.) hoặc các miền hoàn toàn khác (https://3.examplexyz.com).
|
job_parameters.debug_privacy_epsilon |
Dấu phẩy động, Độ chính xác gấp đôi |
Trường không bắt buộc. Nếu không có giá trị nào được truyền, giá trị mặc định là 10 sẽ được sử dụng. Giá trị có thể từ 0 đến 64. Giá trị này được chỉ định trong yêu cầu createJob.
|
job_parameters.report_error_threshold_percentage |
Đôi |
Trường không bắt buộc. Đây là tỷ lệ phần trăm ngưỡng của các báo cáo có thể không thành công trước khi tác vụ không thành công. Nếu bạn không chỉ định giá trị, thì giá trị mặc định là 10% sẽ được sử dụng. Tham số này được chỉ định trong yêu cầu createJob.
|
job_parameters.input_report_count |
Giá trị dài | Trường không bắt buộc. Tổng số báo cáo được cung cấp dưới dạng dữ liệu đầu vào cho công việc này. `report_error_threshold_percentage` kết hợp với giá trị này sẽ kích hoạt lỗi sớm của công việc nếu một số lượng đáng kể báo cáo bị loại trừ do lỗi. Chế độ cài đặt này được chỉ định trong yêu cầu `createJob`. |
job_parameters.filtering_ids |
Chuỗi |
Trường không bắt buộc. Danh sách mã lọc chưa ký được phân tách bằng dấu phẩy. Tất cả nội dung đóng góp khác ngoài mã nhận dạng lọc trùng khớp sẽ bị lọc ra. Tham số này được chỉ định trong yêu cầu createJob.
(ví dụ: "filtering_ids":"12345,34455,12". Giá trị mặc định là "0".)
|