Trang này được dịch bởi Cloud Translation API.

Triển khai và quản lý các yêu cầu bằng Dịch vụ tổng hợp

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ụ. Sơ đồ sau đây cung cấp hình ảnh trực quan về cấu trúc triển khai cho hai điểm cuối này:

**Hình 1.**Tổng quan về API Dịch vụ tổng hợp

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.

Tạo 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>"
  }
}

Khi tạo công việc thành công, bạn sẽ nhận được 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 công việc 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ề 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"
  }
}

Các 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 duy nhất do công nghệ quảng cáo tạo ra, phải là chữ cái ASCII có 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ừ 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 của 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 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/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 bộ nhớ nơi `output_data` được gửi. 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.
`job_parameters`	Từ điển	Trường bắt buộc. Trường này chứa nhiều 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 là đường dẫn trong `output_domain_bucket_name` nơi miền đầu ra AVRO của bạn 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` có tên là `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. 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.
`job_parameters.attribution_report_to`	Chuỗi	Giá trị này không được trùng lặp với "reporting_site". Đây là 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 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 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 Làm quen với 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, 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, 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 sẽ là 10. Bạn có thể sử 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 bạn để trống, giá trị mặc định sẽ 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. Giá trị này, kết hợp với `report_error_threshold_percentage`, cho phép công việc thất bại 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 lọc chưa ký được phân tách bằng dấu phẩy. Tất cả các đóng góp khác ngoài 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, các báo cáo tóm tắt gỡ lỗi có tiếng ồn và không có tiếng ồn cũng như chú thích sẽ được thêm vào để 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 mục trùng lặp trên các lô. 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 sử dụng ngân sách quyền riêng tư.

Tìm việc làm

Khi một công nghệ quảng cáo muốn biết trạng thái của một lô đã yêu cầu, họ có thể gọi điểm cuối getJob. Điểm cuối getJob được gọi bằng yêu cầu GET HTTPS 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ông việc 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

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 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à bộ 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 tổng hợp. Trường này được đặt ở `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ữ các báo cáo tóm tắt đã tạo. Trường này được đặt ở `createJob`.
`request_processing_started_at`	Chuỗi	Thời gian bắt đầu lần xử lý gần đây nhất. Thời gian 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ẽ hiển thị các giá trị `return_code`, `return_message`, `finished_at` và `error_summary`.
`result_info.return_code`	Chuỗi	Mã trả về kết quả công việc. Thông tin này cần thiết để khắc phục sự cố nếu có vấn đề 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. Bạn cũng cần thông tin này để khắc phục sự cố liên quan đến 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. Thẻ 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 số lỗi chứa một danh mục, `error_count` và `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 các 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 thuộc tính có 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 Làm quen với 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 là tên máy chủ của 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 Làm quen với 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 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 cùng một trang web được đề cập trong tham số này. Thông tin này được chỉ định trong yêu cầu `createJob`. Ngoài ra, hãy đảm bảo rằng bộ chứa 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 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ý. 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ỉ các báo cáo từ https://exampleabc.com mới được đưa vào, ngay cả khi bộ chứa chứa các báo cáo từ 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, Kép	Trường không bắt buộc. Nếu không có giá trị nào được truyền, hệ thống sẽ sử dụng giá trị mặc định là 10. 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 công việc không thành công. Nếu bạn không chỉ định giá trị nào, thì hệ thống sẽ sử dụng giá trị mặc định 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. `report_error_threshold_percentage`, kết hợp với giá trị này, sẽ kích hoạt lỗi công việc sớm nếu một số lượng lớn 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ã 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".)