Tìm hiểu về Aggregation Service API

Sau khi triển khai, Dịch vụ tổng hợp sẽ hiển thị hai điểm cuối để sử dụng công nghệ quảng cáo: createJob và getJob.

Sơ đồ AgS

Bạn có thể đọc thêm về các điểm cuối createJob và getJob trong tài liệu về API Dịch vụ tổng hợp.

createJob

Điểm cuối createJob được gọi thông qua yêu cầu POST qua HTTP và cần có nội dung yêu cầu. Sau khi thực hiện yêu cầu createJob, bạn sẽ nhận được phản hồi HTTP 202 thành công.

  POST https://<api-gateway>/stage/v1alpha/createJob

Ví dụ về nội dung yêu cầu dành 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>"
  }
}

Xin lưu ý rằng reporting_site và attribution_report_to loại trừ lẫn nhau và chỉ có một trong số đó là bắt buộc.

Bạn cũng có thể yêu cầu một công việc gỡ lỗi bằng cách thêm debug_run vào job_parameters. Để hiểu chế độ gỡ lỗi, hãy xem tài liệu về cách 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

Thông số Loại Mô tả
job_request_id Chuỗi Đây là giá trị nhận dạng riêng biệt do công nghệ quảng cáo tạo và phải là chữ cái ASCII có tối đa 128 ký tự. Thao tác này sẽ xác định yêu cầu công việc hàng loạt và sẽ lấy tất cả báo cáo avro tổng hợp được chỉ định trong "input_data_blob_prefix" từ bộ chứa đầu vào được chỉ định trong input_data_bucket_name được lưu trữ trên bộ nhớ trên đá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 trong bộ chứa. Đối với các tệp đơn 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 sẽ 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, thư mục/tệp1/kiểm thử/tệp2.avro.
input_data_bucket_name Chuỗi Đây là bộ chứa lưu trữ cho dữ liệu đầu vào hoặc báo cáo tổng hợp. Dữ liệu này nằm trên 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 bộ chứa. Hỗ trợ một tệp đầu ra.
output_data_bucket_name Chuỗi Đây là bộ chứa lưu trữ nơi output_data sẽ được gửi. 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. Thao tác này sẽ chứa các trường khác nhau, chẳng hạn như:
  • 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 Chuỗi Tương tự như input_data_blob_prefix, đây sẽ là đường dẫn trong output_domain_bucket_name nơi miền đầu ra AVRO của bạn sẽ nằm. Đố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ô dữ liệu, báo cáo tóm tắt sẽ được tạo và đặt trong bộ chứa đầu ra output_data_bucket_name với tên output_data_blob_prefix.
job_parameters.output_domain_bucket_name Chuỗi Đây là bộ chứa lưu trữ cho tệp AVRO miền đầu ra của bạ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.attribution_report_to Chuỗi Dành riêng cho báo cáo_site. Đây sẽ là URL báo cáo hoặc nguồn gốc báo cáo mà báo cáo nhận được. Nguồn gốc sẽ là một phần của trang web được đăng ký trong quy trình Làm quen với 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 sẽ 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 sẽ là một phần của trang web được đăng ký trong quy trình Làm quen với Dịch vụ tổng hợp. Lưu ý: Bạn có thể gửi báo cáo có nhiều nguồn gốc báo cáo trong cùng một yêu cầu, miễn là tất cả nguồn gốc báo cáo đều thuộc về cùng một trang web báo cáo được đề cập trong thông số này.
job_parameters.debug_privacy_epsilon Dấu phẩy động, Kép 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. Bạn có thể sử dụng giá trị từ 0 đến 64. Giá trị này có thể thay đổi.
job_parameters.report_error_threshold_percentage Đôi Trường không bắt buộc. Đây là ngưỡng tỷ lệ phần trăm báo cáo có thể không thành công trước khi công việc bắt đầu không thành công. Nếu để trống, giá trị mặc định là 10%.
job_parameters.input_report_count giá trị long 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. Giá trị này kết hợp với report_error_threshold_percentage sẽ cho phép thực hiện công việc không thành công sớm khi 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ã nhận dạng bộ lọc chưa ký được phân tách bằng dấu phẩy. Tất cả các khoản đóng góp không phải là mã nhận dạng bộ 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, báo cáo và chú thích tóm tắt gỡ lỗi có tiếng và không bị nhiễu sẽ được thêm để cho biết những khoá nào có trong dữ liệu đầu vào và/hoặc báo cáo của miền. Ngoài ra, chúng tôi cũng không thực thi các trường hợp trùng lặp trong các lô. Xin lưu ý rằng quá trình chạy gỡ lỗi chỉ xem xét các báo cáo có cờ "debug_mode": "enabled" và các lần chạy gỡ lỗi sẽ sử dụng ngân sách.

getJob

Khi muốn biết trạng thái của một lô đã yêu cầu, công nghệ quảng cáo có thể gọi điểm cuối getJob. Bạn có thể gọi điểm cuối getJob bằng lệnh gọi GET HTTPS cùng với tham số job_request_id trong yêu cầu.

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

Bạn sẽ nhận được phản hồi như vậy. Thao tác này sẽ trả về trạng thái của công việc và 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

Thông số Loại Mô tả
job_request_id Chuỗi Đây là mã công việc/mã lô duy nhất đượ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 công việc lần gần đây nhất.
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à nhóm 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 tổng hợp. Trường này được đặt ở mức 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à bộ chứa dữ liệu đầu ra của công nghệ quảng cáo, nơi lưu trữ báo cáo tóm tắt sau khi tạo. Trường này được đặt ở mức createJob.
request_processing_started_at Chuỗi Thời gian bắt đầu lần xử lý gần đây nhất. Thao tác này sẽ loại trừ 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 createJob và tất cả thông tin có sẵn về công việc. Thao tác này sẽ hiển thị return_code, return_message, finished_at và error_summary.
result_info.return_code Chuỗi Mã trả về của kết quả công việc. Thông tin này sẽ cần thiết khi có sự cố xảy ra trong Dịch vụ tổng hợp để tìm hiểu xem sự cố có thể là gì.
result_info.return_message Chuỗi Thông báo (thành công hoặc không thành công) trả về do công việc. Thông tin này cũng sẽ cần thiết trong quá trình điều tra các lỗi của Dịch vụ tổng hợp.
result_info.error_summary Từ điển Các lỗi trả về cho công việc. Cột này sẽ chứa số lượng báo cáo không thành công cùng loại lỗi.
result_info.finished_at Dấu thời gian Dấu thời gian khi công việc kết thú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 và số lượng báo cáo không thành công với cùng một thông báo lỗi. Mỗi số lỗi sẽ chứa danh mục, error_count, description.
result_info.error_summary.error_messages Danh sách Thao tác này sẽ trả về danh sách thông báo lỗi của những báo cáo không xử lý được.
job_parameters Từ điển Tệp này chứa các tham số công việc được cung cấp trong yêu cầu createJob. Các tài sản có liên quan như "output_domain_blob_prefix" và "output_domain_bucket_name".
job_parameters.attribution_report_to Chuỗi Dành riêng cho reporting_site. Đây sẽ 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 này sẽ là một phần của trang web đã đăng ký tham gia chương trình Giới thiệu dịch vụ tổng hợp. Thông tin 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 sẽ là tên máy chủ của URL báo cáo hoặc nguồn gốc báo cáo nơi nhận được báo cáo. Nguồn gốc này sẽ là một phần của trang web đã đăng ký tham gia chương trình Giới thiệu dịch vụ tổng hợp. Xin lưu ý rằng bạn có thể gửi các báo cáo có nhiều nguồn gốc báo cáo trong cùng một yêu cầu, miễn là tất cả nguồn gốc báo cáo đều thuộc về cùng một trang web báo cáo được đề cập trong thông số này. Điều này được chỉ định trong yêu cầu createJob. Ngoài ra, hãy đảm bảo rằng bộ chứa này chỉ chứa những báo cáo mà bạn muốn được 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 bộ chứa 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 thông số công việc sẽ được xử lý. Ví dụ: nếu một công nghệ quảng cáo đã đăng ký nguồn gốc báo cáo https://exampleabc.com, nhưng trong bộ chứa dữ liệu đầu vào, công nghệ quảng cáo đó sẽ thêm các báo cáo từ https://1.exampleabc.com, https://2.exampleabc.com và https://3.examplexyz.com vào. Chỉ những báo cáo đã được thêm vào bộ chứa khớp với nguồn gốc báo cáo đã đăng ký trong công việc mới được tổng hợp, tức là https://exampleabc.com.
job_parameters.debug_privacy_epsilon Dấu phẩy động, Kép 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. Bạn có thể sử dụng giá trị từ 0 đến 64. Giá trị này có thể thay đổi. Thông tin 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à ngưỡng tỷ lệ phần trăm báo cáo có thể không đạt trước khi công việc bắt đầu không thành công. Nếu bạn để trống, giá trị mặc định sẽ là 10%. Thông tin 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. Giá trị này, kết hợp với report_error_threshold_percentage sẽ cho phép thực hiện công việc không thành công sớm khi báo cáo bị loại trừ do lỗi. Điều 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ã nhận dạng bộ lọc chưa ký được phân tách bằng dấu phẩy. Tất cả các khoản đóng góp không phải là mã nhận dạng bộ lọc trùng khớp sẽ bị lọc ra. Thông tin 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".)