Sử dụng Dịch vụ tổng hợp trên Google Cloud Platform (GCP)

1. 1. Điều kiện tiên quyết

Thời gian hoàn thành ước tính: 1 đến 2 giờ

Có 2 chế độ để thực hiện lớp học lập trình này: Kiểm thử cục bộ hoặc Dịch vụ tổng hợp. Chế độ Kiểm thử cục bộ yêu cầu bạn phải có máy cục bộ và trình duyệt Chrome (không tạo/sử dụng tài nguyên Google Cloud). Chế độ Dịch vụ tổng hợp yêu cầu bạn phải triển khai đầy đủ Dịch vụ tổng hợp trên Google Cloud.

Để thực hiện lớp học lập trình này ở một trong hai chế độ, bạn cần đáp ứng một số điều kiện tiên quyết. Mỗi yêu cầu đều được đánh dấu tương ứng để xem đó là yêu cầu bắt buộc cho hoạt động Kiểm thử cục bộ hay Dịch vụ tổng hợp.

1.1. Hoàn tất đăng ký và chứng thực (Dịch vụ tổng hợp)

Để sử dụng API Hộp cát về quyền riêng tư, hãy đảm bảo rằng bạn đã hoàn tất quy trình Đăng ký và chứng thực cho cả Chrome và Android.

1.2. Bật API Hộp cát về quyền riêng tư (Kiểm thử cục bộ và Dịch vụ tổng hợp)

Vì chúng ta sẽ dùng Hộp cát về quyền riêng tư, nên bạn nên bật API Quảng cáo trong Hộp cát về quyền riêng tư.

Trên trình duyệt, hãy truy cập chrome://flags/#privacy-sandbox-ads-apis rồi bật các API Hộp cát về quyền riêng tư.

Bật API hộp cát về quyền riêng tư

Ngoài ra, hãy đảm bảo rằng bạn đã bật Cookie của bên thứ 3.

Trên trình duyệt, hãy truy cập chrome://settings/cookies. Hãy đảm bảo cookie của bên thứ ba KHÔNG bị chặn. Tuỳ thuộc vào phiên bản Chrome, bạn có thể thấy các tuỳ chọn khác nhau trên trình đơn cài đặt này nhưng các cấu hình được chấp nhận bao gồm:

  • "Chặn tất cả cookie của bên thứ ba" = TẮT
  • "Chặn cookie của bên thứ ba" = TẮT
  • "Chặn cookie của bên thứ ba ở Chế độ ẩn danh" = ĐÃ BẬT

Bật cookie

1.3. Tải Công cụ kiểm tra cục bộ xuống (Kiểm thử cục bộ)

Kiểm thử cục bộ sẽ yêu cầu bạn tải Công cụ kiểm thử cục bộ xuống. Công cụ này sẽ tạo các báo cáo tóm tắt từ các báo cáo gỡ lỗi chưa được mã hoá.

Bạn có thể tải công cụ kiểm thử cục bộ xuống trong Kho lưu trữ JAR của Cloud Function trên GitHub. Tệp này phải được đặt tên là LocalTestingTool_{version}.jar.

1,4. Đảm bảo bạn đã cài đặt JAVA JRE (Dịch vụ tổng hợp và kiểm thử cục bộ)

Mở "Terminal" và sử dụng java --version để kiểm tra xem máy của bạn đã cài đặt Java hoặc openJDK chưa.

Kiểm tra phiên bản Java

Nếu chưa cài đặt, bạn có thể tải xuống và cài đặt từ trang web Java hoặc trang web của openJDK.

1.5. Tải tổng hợp_report_converter xuống (Kiểm thử cục bộ và Dịch vụ tổng hợp)

Bạn có thể tải một bản sao của tổng hợp_report_converter xuống qua kho lưu trữ GitHub về Hộp cát về quyền riêng tư.

1.6. Thiết lập Môi trường GCP (Dịch vụ tổng hợp)

Dịch vụ tổng hợp yêu cầu sử dụng một Môi trường thực thi đáng tin cậy (có sử dụng một nhà cung cấp dịch vụ đám mây). Trong lớp học lập trình này, Dịch vụ tổng hợp sẽ được triển khai trong GCP, tuy nhiên AWS cũng được hỗ trợ.

1.6.1. Triển khai

Làm theo Hướng dẫn triển khai trong GitHub để thiết lập gcloud CLI, tải các mô-đun và tệp nhị phân Terraform xuống, cũng như tạo tài nguyên GCP cho Dịch vụ tổng hợp.

Các bước chính trong Hướng dẫn triển khai:

  1. Thiết lập CLI và Terraform của "gcloud" trong môi trường của bạn.
  2. Tạo một bộ chứa Cloud Storage để lưu trữ trạng thái Terraform.
  3. Tải các phần phụ thuộc xuống.
  4. Cập nhật adtech_setup.auto.tfvars và chạy adtech_setup Terraform. Hãy xem Phụ lục để biết tệp adtech_setup.auto.tfvars mẫu.
  5. Cập nhật dev.auto.tfvars, mạo danh tài khoản dịch vụ triển khai rồi chạy Terraform dev. Hãy xem Phụ lục để biết tệp dev.auto.tfvars mẫu.
  6. Sau khi triển khai xong, hãy ghi lại frontend_service_cloudfunction_url từ dữ liệu đầu ra Terraform. Đây là dữ liệu cần thiết để gửi yêu cầu đến Dịch vụ tổng hợp trong các bước sau.

1.6.2. Bộ chứa báo cáo

Sau khi thiết lập dự án, bạn sẽ tạo một bộ chứa trong Cloud Storage để lưu trữ các báo cáo tổng hợp và báo cáo tóm tắt của lớp học lập trình này. Đây là một lệnh gcloud mẫu để tạo một bộ chứa. Thay thế phần giữ chỗ bằng tên và vị trí bạn chọn.

gcloud storage buckets create gs://<bucket-name> --location=<location>

1.7. Hoàn tất giai đoạn giới thiệu dịch vụ tổng hợp (Dịch vụ tổng hợp)

Dịch vụ tổng hợp yêu cầu bạn phải làm quen với điều phối viên thì mới có thể sử dụng dịch vụ này. Hoàn tất Biểu mẫu giới thiệu dịch vụ tổng hợp bằng cách cung cấp Trang web báo cáo và các thông tin khác, chọn "Google Cloud" rồi nhập địa chỉ tài khoản dịch vụ của bạn. Tài khoản dịch vụ này được tạo theo điều kiện tiên quyết trước đó (1.6. Thiết lập một Môi trường GCP). (Gợi ý: nếu bạn sử dụng tên mặc định được cung cấp, tài khoản dịch vụ này sẽ bắt đầu bằng "worker-sa@").

Vui lòng chờ tối đa 2 tuần để quy trình tham gia hoàn tất.

1,8. Xác định phương thức gọi các điểm cuối của API (Dịch vụ tổng hợp)

Lớp học lập trình này cung cấp 2 lựa chọn để gọi các điểm cuối API của Dịch vụ tổng hợp: cURL và Postman. cURL là cách nhanh chóng và dễ dàng hơn để gọi các điểm cuối API từ Thiết bị đầu cuối của bạn, vì công cụ này yêu cầu thiết lập ở mức tối thiểu và không cần phần mềm bổ sung. Tuy nhiên, nếu không muốn dùng cURL, bạn có thể dùng Postman để thực thi và lưu các yêu cầu API nhằm sử dụng sau này.

Trong phần 3.2. Mức sử dụng dịch vụ tổng hợp, bạn sẽ xem được hướng dẫn chi tiết về cách sử dụng cả hai lựa chọn. Bạn có thể xem trước chúng ngay bây giờ để xác định phương thức mình sẽ dùng. Nếu bạn chọn Postman, hãy thực hiện quá trình thiết lập ban đầu sau đây.

1.8.1. Thiết lập không gian làm việc

Đăng ký tài khoản Postman. Sau khi bạn đăng ký, một không gian làm việc sẽ được tạo tự động cho bạn.

Không gian làm việc của Postman

Nếu bạn không tạo không gian làm việc, hãy chuyển đến mục điều hướng trên cùng của "Không gian làm việc" rồi chọn "Tạo không gian làm việc".

Chọn "Không gian làm việc trống", nhấp vào mục tiếp theo rồi đặt tên cho mục này là "Hộp cát về quyền riêng tư của GCP". Chọn "Cá nhân" rồi nhấp vào "Tạo".

Tải cấu hình JSON và tệp Môi trường chung của không gian làm việc định cấu hình sẵn xuống.

Nhập cả hai tệp JSON vào "Không gian làm việc của tôi" qua nút "Nhập".

Nút nhập

Thao tác này sẽ tạo bộ sưu tập "Hộp cát về quyền riêng tư của GCP" cho bạn cùng với các yêu cầu HTTP createJob và getJob.

1.8.2. Thiết lập yêu cầu uỷ quyền

Nhấp vào bộ sưu tập "Hộp cát về quyền riêng tư của GCP" rồi chuyển đến thẻ "Uỷ quyền".

Nút uỷ quyền

Bạn sẽ sử dụng phương thức "Bearer Token". Trong môi trường dòng lệnh, hãy chạy lệnh này rồi sao chép kết quả.

gcloud auth print-identity-token

Sau đó, dán giá trị mã thông báo này vào trường "Mã thông báo" của thẻ uỷ quyền Người đăng:

Trường mã thông báo

1.8.3. Thiết lập môi trường

Di chuyển đến mục "Xem nhanh môi trường" ở góc trên cùng bên phải:

Nút Môi trường

Nhấp vào "Chỉnh sửa" rồi cập nhật "Giá trị hiện tại" của "môi trường", "khu vực" và "mã-chức năng đám mây":

Đặt giá trị hiện tại

Bạn hiện có thể để trống trường "request-id" vì chúng tôi sẽ điền thông tin này sau. Đối với các trường khác, hãy sử dụng giá trị từ frontend_service_cloudfunction_url. Giá trị này được trả về khi hoàn tất thành công quá trình triển khai Terraform trong Điều kiện tiên quyết 1.6. URL tuân theo định dạng sau: https://--frontend-service--uc.a.run.app

2. 2. Lớp học lập trình kiểm thử cục bộ

Thời gian hoàn thành ước tính: <1 giờ

Bạn có thể sử dụng công cụ kiểm tra cục bộ trên máy của mình để tổng hợp và tạo báo cáo tóm tắt bằng báo cáo gỡ lỗi chưa mã hoá. Trước khi bắt đầu, hãy đảm bảo bạn đã hoàn thành mọi điều kiện tiên quyết có nhãn "Thử nghiệm cục bộ".

Các bước của lớp học lập trình

Bước 2.1. Báo cáo về điều kiện kích hoạt: Kích hoạt báo cáo Tổng hợp riêng tư để có thể thu thập báo cáo.

Bước 2.2. Tạo báo cáo gỡ lỗi AVRO: Chuyển đổi báo cáo JSON đã thu thập thành báo cáo có định dạng AVRO. Bước này sẽ tương tự như khi công nghệ quảng cáo thu thập báo cáo từ các điểm cuối báo cáo API và chuyển đổi báo cáo JSON sang báo cáo có định dạng AVRO.

Bước 2.3. Truy xuất khoá bộ chứa: Khoá bộ chứa do các công nghệ quảng cáo thiết kế. Trong lớp học lập trình này, vì các bộ chứa được xác định trước, hãy truy xuất khoá bộ chứa như được cung cấp.

Bước 2.4. Tạo AVRO miền đầu ra: Sau khi truy xuất các khoá bộ chứa, hãy tạo tệp AVRO miền đầu ra.

Bước 2.5. Tạo báo cáo tóm tắt: Sử dụng Công cụ kiểm tra cục bộ để có thể tạo Báo cáo tóm tắt trong môi trường cục bộ.

Bước 2.6. Xem lại Báo cáo tóm tắt: Xem lại Báo cáo tóm tắt do Công cụ kiểm tra cục bộ tạo.

2.1. Báo cáo điều kiện kích hoạt

Để kích hoạt một báo cáo tổng hợp riêng tư, bạn có thể sử dụng trang web minh hoạ Hộp cát về quyền riêng tư (https://privacy-sandbox-demos-news.dev/?env=gcp) hoặc trang web của riêng bạn (ví dụ: https://adtechexample.com). Nếu đang dùng trang web của riêng mình và chưa hoàn tất quy trình Đăng ký và chứng thực cũng như Giới thiệu dịch vụ tổng hợp, bạn sẽ cần sử dụng nút Chrome và nút chuyển CLI.

Đối với bản minh hoạ này, chúng ta sẽ dùng trang web minh hoạ của Hộp cát về quyền riêng tư. Đi theo đường liên kết để truy cập vào trang web đó, sau đó bạn có thể xem các báo cáo tại chrome://private-aggregation-internals:

Trang Nội bộ của Chrome

Báo cáo được gửi đến điểm cuối {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage cũng có trong "Nội dung báo cáo" của các báo cáo xuất hiện trên trang Chrome Internals.

Bạn có thể thấy nhiều báo cáo ở đây, nhưng đối với lớp học lập trình này, hãy sử dụng báo cáo tổng hợp dành riêng cho GCP và do điểm cuối gỡ lỗi tạo. "URL báo cáo" sẽ chứa "/debug/" và aggregation_coordinator_origin field của "Nội dung báo cáo" sẽ chứa URL sau: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Báo cáo gỡ lỗi GCP

2.2. Tạo báo cáo tổng hợp gỡ lỗi

Sao chép báo cáo có trong "Nội dung báo cáo" của chrome://private-aggregation-internals và tạo một tệp JSON trong thư mục privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (trong kho lưu trữ đã tải xuống trong Điều kiện tiên quyết 1.5).

Trong ví dụ này, chúng ta dùng vim vì chúng ta đang dùng Linux. Nhưng bạn có thể sử dụng bất kỳ trình chỉnh sửa văn bản nào bạn muốn.

vim report.json

Dán báo cáo vào report.json rồi lưu tệp.

Báo cáo JSON

Sau khi có, hãy sử dụng aggregatable_report_converter.jar để tạo báo cáo tổng hợp gỡ lỗi. Thao tác này sẽ tạo một báo cáo tổng hợp có tên là report.avro trong thư mục hiện tại của bạn.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json \
  --debug

2.3. Truy xuất Khoá bộ chứa từ báo cáo

Để tạo tệp output_domain.avro, bạn cần có các khoá nhóm có thể truy xuất được từ báo cáo.

Khoá bộ chứa do công nghệ quảng cáo thiết kế. Tuy nhiên, trong trường hợp này, Bản minh hoạ Hộp cát về quyền riêng tư của trang web sẽ tạo khoá bộ chứa. Vì tính năng tổng hợp riêng tư cho trang web này đang ở chế độ gỡ lỗi, nên chúng ta có thể sử dụng debug_cleartext_payload từ "Nội dung báo cáo" để lấy khoá bộ chứa.

Hãy tiếp tục và sao chép debug_cleartext_payload từ nội dung báo cáo.

Gỡ lỗi tải trọng văn bản thô

Mở goo.gle/ags-payload-decoder rồi dán debug_cleartext_payload của bạn vào hộp "INPUT" và nhấp vào "Giải mã".

Nút giải mã

Trang trả về giá trị thập phân của khoá bộ chứa. Dưới đây là một khoá nhóm mẫu.

Khoá bộ chứa

2.4. Tạo AVRO miền đầu ra

Giờ chúng ta đã có khoá bộ chứa, hãy tạo output_domain.avro trong chính thư mục mà chúng ta đang xử lý. Đảm bảo rằng bạn thay thế khoá bộ chứa bằng khoá bộ chứa mà bạn đã truy xuất.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

Tập lệnh sẽ tạo tệp output_domain.avro trong thư mục hiện tại của bạn.

2.5. Tạo báo cáo tóm tắt bằng Công cụ kiểm tra cục bộ

Chúng ta sẽ sử dụng LocalTestingTool_{version}.jar đã được tải xuống trong Điều kiện tiên quyết 1.3 để tạo báo cáo tóm tắt bằng lệnh bên dưới. Thay thế {version} bằng phiên bản bạn đã tải xuống. Hãy nhớ di chuyển LocalTestingTool_{version}.jar đến thư mục hiện tại hoặc thêm một đường dẫn tương đối để tham chiếu đến vị trí hiện tại của thư mục đó.

java -jar LocalTestingTool_{version}.jar \
  --input_data_avro_file report.avro \
  --domain_avro_file output_domain.avro \
  --output_directory .

Bạn sẽ thấy nội dung tương tự như bên dưới sau khi chạy lệnh. Báo cáo output.avro sẽ được tạo sau khi hoàn tất.

AVRO đầu ra

2.6. Xem lại báo cáo Tóm tắt

Báo cáo tóm tắt được tạo sẽ có định dạng AVRO. Để có thể đọc mã này, bạn cần chuyển đổi mã này từ AVRO sang định dạng JSON. Tốt nhất là adTech nên viết mã để chuyển đổi báo cáo AVRO về định dạng JSON.

Chúng tôi sẽ sử dụng aggregatable_report_converter.jar để chuyển đổi báo cáo AVRO về định dạng JSON.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file output.avro

Thao tác này sẽ trả về một báo cáo tương tự như bên dưới. Cùng với một báo cáo output.json được tạo trong cùng thư mục.

Đầu ra JSON

3. 3. Lớp học lập trình về Dịch vụ tổng hợp

Thời gian hoàn thành ước tính: 1 giờ

Trước khi bắt đầu, hãy đảm bảo rằng bạn đã hoàn thành mọi điều kiện tiên quyết có nhãn "Dịch vụ tổng hợp".

Các bước của lớp học lập trình

Bước 3.1. Tạo dữ liệu đầu vào cho dịch vụ tổng hợp: Tạo các báo cáo Dịch vụ tổng hợp được phân theo lô cho Dịch vụ tổng hợp.

  • Bước 3.1.1. Báo cáo điều kiện kích hoạt
  • Bước 3.1.2. Thu thập báo cáo tổng hợp
  • Bước 3.1.3. Chuyển đổi báo cáo thành AVRO
  • Bước 3.1.4. Tạo AVRO đầu ra
  • Bước 3.1.5. Di chuyển báo cáo vào bộ chứa Cloud Storage

Bước 3.2. Mức sử dụng dịch vụ tổng hợp: Sử dụng API Dịch vụ tổng hợp để tạo Báo cáo tóm tắt và xem Báo cáo tóm tắt.

  • Bước 3.2.1. Sử dụng điểm cuối createJob để phân lô
  • Bước 3.2.2. Sử dụng Điểm cuối getJob để truy xuất trạng thái lô
  • Bước 3.2.3. Xem lại báo cáo Tóm tắt

3.1. Tạo dữ liệu đầu vào cho dịch vụ tổng hợp

Tiếp tục tạo các báo cáo AVRO để phân lô cho Dịch vụ tổng hợp. Bạn có thể chạy các lệnh shell trong các bước này trong Cloud Shell của GCP (miễn là các phần phụ thuộc từ Điều kiện tiên quyết được sao chép vào môi trường Cloud Shell) hoặc trong môi trường thực thi cục bộ.

3.1.1. Báo cáo điều kiện kích hoạt

Đi theo đường liên kết để truy cập vào trang web đó, sau đó bạn có thể xem các báo cáo tại chrome://private-aggregation-internals:

Trang Nội bộ của Chrome

Báo cáo được gửi đến điểm cuối {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage cũng có trong "Nội dung báo cáo" của các báo cáo xuất hiện trên trang Chrome Internals.

Bạn có thể thấy nhiều báo cáo ở đây, nhưng đối với lớp học lập trình này, hãy sử dụng báo cáo tổng hợp dành riêng cho GCP và do điểm cuối gỡ lỗi tạo. "URL báo cáo" sẽ chứa "/debug/" và aggregation_coordinator_origin field của "Nội dung báo cáo" sẽ chứa URL sau: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Báo cáo gỡ lỗi GCP

3.1.2. Thu thập báo cáo tổng hợp

Thu thập các báo cáo tổng hợp từ các điểm cuối .well-known của API tương ứng.

  • Tổng hợp riêng tư: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
  • Báo cáo phân bổ – Báo cáo tóm tắt: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

Đối với lớp học lập trình này, chúng ta sẽ thu thập báo cáo theo cách thủ công. Trong thực tế, các công nghệ quảng cáo dự kiến sẽ thu thập và chuyển đổi các báo cáo theo cách có lập trình.

Hãy tiếp tục và sao chép báo cáo JSON trong "Nội dung báo cáo" từ chrome://private-aggregation-internals.

Trong ví dụ này, chúng ta sử dụng vim vì đang dùng Linux. Nhưng bạn có thể sử dụng bất kỳ trình chỉnh sửa văn bản nào bạn muốn.

vim report.json

Dán báo cáo vào report.json rồi lưu tệp.

Báo cáo JSON

3.1.3. Chuyển đổi báo cáo thành AVRO

Báo cáo nhận được từ điểm cuối của .well-known sẽ có định dạng JSON và cần được chuyển đổi sang định dạng báo cáo AVRO. Sau khi bạn đã có báo cáo JSON, hãy chuyển đến vị trí lưu trữ report.json và dùng aggregatable_report_converter.jar để giúp tạo báo cáo tổng hợp gỡ lỗi. Thao tác này sẽ tạo một báo cáo tổng hợp có tên là report.avro trong thư mục hiện tại của bạn.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json

3.1.4. Tạo AVRO đầu ra

Để tạo tệp output_domain.avro, bạn cần có các khoá nhóm có thể truy xuất được từ báo cáo.

Khoá bộ chứa do công nghệ quảng cáo thiết kế. Tuy nhiên, trong trường hợp này, Bản minh hoạ Hộp cát về quyền riêng tư của trang web sẽ tạo khoá bộ chứa. Vì tính năng tổng hợp riêng tư cho trang web này đang ở chế độ gỡ lỗi, nên chúng ta có thể sử dụng debug_cleartext_payload từ "Nội dung báo cáo" để lấy khoá bộ chứa.

Hãy tiếp tục và sao chép debug_cleartext_payload từ nội dung báo cáo.

Gỡ lỗi tải trọng văn bản thô

Mở goo.gle/ags-payload-decoder rồi dán debug_cleartext_payload của bạn vào hộp "INPUT" và nhấp vào "Giải mã".

Nút giải mã

Trang trả về giá trị thập phân của khoá bộ chứa. Dưới đây là một khoá nhóm mẫu.

Khoá bộ chứa

Giờ chúng ta đã có khoá bộ chứa, hãy tạo output_domain.avro trong chính thư mục mà chúng ta đang xử lý. Đảm bảo rằng bạn thay thế khoá bộ chứa bằng khoá bộ chứa mà bạn đã truy xuất.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

Tập lệnh sẽ tạo tệp output_domain.avro trong thư mục hiện tại của bạn.

3.1.5. Di chuyển báo cáo vào bộ chứa Cloud Storage

Sau khi tạo báo cáo AVRO và miền đầu ra, hãy di chuyển các báo cáo và miền đầu ra vào bộ chứa trong Cloud Storage (mà bạn đã tạo ở bước cuối cùng trong Điều kiện tiên quyết 1.6).

Nếu bạn đã thiết lập gcloud CLI trên môi trường cục bộ, hãy sử dụng các lệnh dưới đây để sao chép tệp vào các thư mục tương ứng.

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

Nếu không, hãy tải tệp lên bộ chứa của bạn theo cách thủ công. Tạo một thư mục có tên là "báo cáo" rồi tải tệp report.avro lên đó. Tạo một thư mục có tên là "output_domains" rồi tải tệp output_domain.avro lên đó.

3.2. Mức sử dụng dịch vụ tổng hợp

Hãy nhớ lại trong Điều kiện tiên quyết 1.8, bạn đã chọn cURL hoặc Postman để gửi yêu cầu API đến các điểm cuối của Dịch vụ tổng hợp. Bên dưới là hướng dẫn cho cả hai lựa chọn.

3.2.1. Sử dụng điểm cuối createJob để phân lô

Hãy sử dụng hướng dẫn bằng cURL hoặc Người đưa thư bên dưới để tạo công việc.

cURL

Trong "Terminal", hãy tạo một tệp nội dung yêu cầu (body.json) rồi dán vào ô bên dưới. Hãy nhớ cập nhật các giá trị phần giữ chỗ. Hãy tham khảo tài liệu API này để biết thêm thông tin về nội dung đại diện của từng trường.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Thực thi yêu cầu bên dưới. Thay thế phần giữ chỗ trong URL của yêu cầu cURL bằng các giá trị từ frontend_service_cloudfunction_url (được xuất sau khi hoàn tất thành công việc triển khai Terraform) trong Điều kiện tiên quyết 1.6.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -d @body.json \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/createJob

Bạn sẽ nhận được phản hồi HTTP 202 sau khi Dịch vụ tổng hợp chấp nhận yêu cầu đó. Các mã phản hồi khác có thể có được ghi lại trong thông số kỹ thuật của API.

Người đưa thư

Đối với điểm cuối createJob, bạn phải có nội dung yêu cầu để cung cấp Dịch vụ tổng hợp có vị trí và tên tệp của các báo cáo tổng hợp, miền đầu ra và báo cáo tóm tắt.

Chuyển đến thẻ "Nội dung" của yêu cầu createJob:

Thẻ Nội dung

Thay thế phần giữ chỗ trong JSON đã cung cấp. Để biết thêm thông tin về các trường này và nội dung mà các trường đó đại diện, hãy tham khảo tài liệu về API.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

"Gửi" yêu cầu API createJob:

Nút gửi

Bạn có thể tìm thấy mã phản hồi ở nửa dưới của trang:

Mã phản hồi

Bạn sẽ nhận được phản hồi HTTP 202 sau khi Dịch vụ tổng hợp chấp nhận yêu cầu đó. Các mã phản hồi khác có thể có được ghi lại trong thông số kỹ thuật của API.

3.2.2. Sử dụng Điểm cuối getJob để truy xuất trạng thái lô

Hãy sử dụng hướng dẫn của cURL hoặc Người đưa thư bên dưới để nhận được việc làm.

cURL

Thực thi yêu cầu bên dưới trong dòng lệnh của bạn. Thay thế phần giữ chỗ trong URL bằng các giá trị từ frontend_service_cloudfunction_url, cũng chính là URL mà bạn đã sử dụng cho yêu cầu createJob. Đối với "job_request_id", hãy sử dụng giá trị từ công việc bạn đã tạo bằng điểm cuối createJob.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/getJob?job_request_id=<job_request_id>

Kết quả sẽ trả về trạng thái yêu cầu công việc của bạn với trạng thái HTTP 200. Yêu cầu "Body" chứa các thông tin cần thiết như job_status, return_message và error_messages (nếu công việc bị lỗi).

Người đưa thư

Để kiểm tra trạng thái của yêu cầu công việc, bạn có thể sử dụng điểm cuối getJob. Trong mục "Params" (Tham số) của yêu cầu getJob, hãy cập nhật giá trị job_request_id thành job_request_id đã được gửi trong yêu cầu createJob.

Mã yêu cầu công việc

"Gửi" yêu cầu getJob:

Nút gửi

Kết quả sẽ trả về trạng thái yêu cầu công việc của bạn với trạng thái HTTP 200. Yêu cầu "Body" chứa các thông tin cần thiết như job_status, return_message và error_messages (nếu công việc bị lỗi).

JSON phản hồi

3.2.3. Xem lại báo cáo Tóm tắt

Sau khi nhận được báo cáo tóm tắt trong bộ chứa Cloud Storage đầu ra, bạn có thể tải báo cáo này xuống môi trường cục bộ. Báo cáo tóm tắt sẽ ở định dạng AVRO và có thể chuyển đổi lại thành tệp JSON. Bạn có thể dùng aggregatable_report_converter.jar để đọc báo cáo bằng lệnh bên dưới.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file <summary_report_avro>

Thao tác này sẽ trả về tệp json gồm các giá trị tổng hợp của từng khoá nhóm trông tương tự như bên dưới.

Báo cáo tóm tắt

Nếu yêu cầu createJob của bạn bao gồm debug_run là true, thì bạn có thể nhận báo cáo tóm tắt trong thư mục gỡ lỗi nằm trong output_data_blob_prefix. Báo cáo ở định dạng AVRO và có thể được chuyển đổi bằng lệnh trên sang JSON.

Báo cáo này chứa khoá nhóm, chỉ số không bị nhiễu và dữ liệu nhiễu được thêm vào chỉ số không bị nhiễu để tạo thành báo cáo tóm tắt. Báo cáo tương tự như bên dưới.

Báo cáo có âm thanh

Các chú thích cũng chứa "in_reports" và/hoặc "in_domain" có nghĩa là:

  • in_reports – khoá nhóm có sẵn trong báo cáo tổng hợp.
  • in_domain – khoá nhóm có sẵn trong tệp AVRO output_domain.

4. 4. Dọn dẹp

Để xoá tài nguyên được tạo cho Dịch vụ tổng hợp qua Terraform, hãy sử dụng lệnh huỷ trong thư mục adtech_setup và dev (hoặc môi trường khác):

$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy

Cách xoá bộ chứa Cloud Storage đang chứa các báo cáo tổng hợp và báo cáo tóm tắt của bạn:

$ gcloud storage buckets delete gs://my-bucket

Bạn cũng có thể chọn chuyển các chế độ cài đặt cookie của Chrome từ Điều kiện tiên quyết 1.2 về trạng thái trước đó.

5. 5. Phụ lục

Tệp adtech_setup.auto.tfvars mẫu

/**
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

project = "my-project-id"

# Required to generate identity token for access of Adtech Services API endpoints
service_account_token_creator_list = ["user:me@email.com"]

# Uncomment the below line if you like Terraform to create an Artifact registry repository
# for self-build container artifacts. "artifact_repo_location" defaults to "us".
artifact_repo_name     = "my-ags-artifacts"

# Note: Either one of [1] or [2] must be uncommented.

# [1] Uncomment below lines if you like Terraform grant needed permissions to
# pre-existing service accounts
# deploy_service_account_email = "<YourDeployServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"
# worker_service_account_email = "<YourWorkerServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"

# [2] Uncomment below lines if you like Terraform to create service accounts
# and needed permissions granted e.g "deploy-sa" or "worker-sa"
deploy_service_account_name = "deploy-sa"
worker_service_account_name = "worker-sa"
# Uncomment the below line if you want Terraform to create the
# below bucket. "data_bucket_location" defaults to "us".
data_bucket_name     = "my-ags-data"

# Uncomment the below lines if you want to specify service account customer role names
# deploy_sa_role_name = "<YourDeploySACustomRole>"
# worker_sa_role_name = "<YourWorkerSACustomRole>"

Tệp dev.auto.tfvars mẫu

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

# Example values required by job_service.tf
#
# These values should be modified for each of your environments.
region      = "us-central1"
region_zone = "us-central1-c"

project_id  = "my-project-id"
environment = "operator-demo-env"

# Co-locate your Cloud Spanner instance configuration with the region above.
# https://cloud.google.com/spanner/docs/instance-configurations#regional-configurations
spanner_instance_config = "regional-us-central1"

# Adjust this based on the job load you expect for your deployment.
# Monitor the spanner instance utilization to decide on scale out / scale in.
# https://console.cloud.google.com/spanner/instances
spanner_processing_units = 100

# Uncomment the line below at your own risk to disable Spanner database protection.
# This needs to be set to false and applied before destroying all resources is possible.
spanner_database_deletion_protection = false

instance_type = "n2d-standard-8" # 8 cores, 32GiB

# Container image location that packages the job service application
# If not set otherwise, uncomment and edit the line below:
#worker_image = "<location>/<project>/<repository>/<image>:<tag or digest>"

# Service account created and onboarded for worker
user_provided_worker_sa_email = "worker-sa@my-project-id.iam.gserviceaccount.com"

min_worker_instances = 1
max_worker_instances = 20