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 một 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 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 cho dù yêu cầu đó là bắt buộc đối với Kiểm thử cục bộ hay Dịch vụ tổng hợp.

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

Để sử dụng các API Hộp cát về quyền riêng tư, hãy xác minh 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 Ad privacy API (Kiểm thử cục bộ và Dịch vụ tổng hợp)

Vì sẽ 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 của Hộp cát về quyền riêng tư.

Trên trình duyệt, hãy chuyển đến chrome://settings/adPrivacy rồi bật tất cả các API Quyền riêng tư liên quan đến quảng cáo.

Đồng thời, hãy xác minh rằng bạn đã bật cookie của bên thứ ba.

Trên chrome://settings/cookies, hãy đảm bảo rằng bạn KHÔNG chặn cookie của bên thứ ba. Tuỳ thuộc vào phiên bản Chrome, bạn có thể thấy các lựa chọn khác nhau trong 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 thử cục bộ (Kiểm thử cục bộ) xuống

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

Bạn có thể tải công cụ Kiểm thử cục bộ trong Kho lưu trữ JAR của Hàm trên đám mây trong GitHub. Bạn nên đặt tên là LocalTestingTool_{version}.jar.

1.4. Xác minh rằng bạn đã cài đặt JAVA JRE (Dịch vụ kiểm thử và tổng hợp cục bộ)

Mở "Terminal" (Thiết bị đầu cuối) rồi dùng java --version để kiểm tra xem máy của bạn đã cài đặt Java hay openJDK hay 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 openJDK.

1.5. Tải aggregatable_report_converter xuống (Thử nghiệm cục bộ và Dịch vụ tổng hợp)

Bạn có thể tải bản sao của aggregatable_report_converter xuống từ kho lưu trữ GitHub của Giải pháp minh hoạ Hộp cát về quyền riêng tư. Kho lưu trữ GitHub đề cập đến việc sử dụng IntelliJ hoặc Eclipse, nhưng không bắt buộc. Nếu bạn không sử dụng các công cụ này, hãy tải tệp JAR xuống môi trường cục bộ.

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

Aggregation Service yêu cầu sử dụng Môi trường thực thi đáng tin cậy 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 Google Cloud, nhưng AWS cũng được hỗ trợ.

Làm theo Hướng dẫn triển khai trong GitHub để thiết lập Google Cloud CLI, tải các tệp nhị phân và mô-đun Terraform xuống, đồng thời tạo tài nguyên Google Cloud 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 giao diện dòng lệnh "gcloud" và Terraform 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 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 ví dụ về tệp adtech_setup.auto.tfvars. Ghi lại tên của nhóm dữ liệu được tạo ở đây – tên này sẽ được dùng trong lớp học lập trình để lưu trữ các tệp mà chúng ta tạo.
5. Cập nhật dev.auto.tfvars, mạo danh tài khoản dịch vụ triển khai và chạy dev Terraform. Hãy xem Phụ lục để biết ví dụ về tệp dev.auto.tfvars.
6. Sau khi quá trình triển khai hoàn tất, hãy ghi lại frontend_service_cloudfunction_url từ đầu ra của Terraform. Bạn sẽ cần thông tin này để đưa ra yêu cầu cho Dịch vụ tổng hợp ở các bước sau.

1.7. Hoàn tất quy trình 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 tham gia vào các điều phối viên để có thể sử dụng dịch vụ này. Hoàn tất biểu mẫu Thiết lập ban đầu cho Dịch vụ tổng hợp bằng cách cung cấp Trang web báo cáo và 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 trong điều kiện tiên quyết trước đó (1.6. Thiết lập một môi trường Google Cloud). (Lưu ý: 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@").

Chờ tối đa 2 tuần để hoàn tất quy trình tham gia.

1.8. Xác định phương thức gọi các điểm cuối 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ừ Terminal, vì cách này chỉ yêu cầu thiết lập tối thiểu và không cần phần mềm bổ sung. Tuy nhiên, nếu không muốn sử dụng cURL, bạn có thể sử dụng Postman để thực thi và lưu các yêu cầu API cho lần sử dụng sau.

Trong phần 3.2. Sử dụng Dịch vụ tổng hợp, bạn sẽ thấy 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 các phương thức này ngay bây giờ để xác định phương thức mà bạn sẽ sử dụng. Nếu bạn chọn Postman, hãy thực hiện quy 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ẽ tự động được tạo cho bạn.

Một không gian làm việc trên Postman.

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

Chọn "Blank workspace" (Không gian làm việc trống), nhấp vào Next (Tiếp theo) rồi đặt tên là "GCP Privacy Sandbox" (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 của không gian làm việc được định cấu hình sẵn và các tệp Môi trường chung xuống.

Nhập cả hai tệp JSON vào "Không gian làm việc của tôi" bằng 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 lệnh 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 Terminal, hãy chạy lệnh này và sao chép đầu ra.

gcloud auth print-identity-token

Sau đó, hãy 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 Postman:

Trường "Mã thông báo".

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

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

Nút xem nhanh 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 "environment", "region" và "cloud-function-id":

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

Bạn có thể để trống "request-id" (mã yêu cầu) ở thời điểm hiện tại vì chúng ta sẽ điền mã này sau. Đối với các trường khác, hãy sử dụng các giá trị từ frontend_service_cloudfunction_url, được trả về 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. URL có định dạng như 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 thử cục bộ trên máy để thực hiện quy trình tổng hợp và tạo báo cáo tóm tắt bằng cách sử dụng các báo cáo gỡ lỗi chưa mã hoá. Trước khi bắt đầu, hãy xác minh rằng bạn đã hoàn thành tất cả các Điều kiện tiên quyết được gắn nhãn "Kiểm thử cục bộ".

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

Bước 2.1. Báo cáo điều kiện kích hoạt: Kích hoạt báo cáo Private Aggregation để 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ác 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 thành báo cáo có định dạng AVRO.

Bước 2.3. Truy xuất Khoá nhóm: Khoá nhóm do 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 các 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á nhóm, 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 thử 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 xét Báo cáo tóm tắt: Xem xét Báo cáo tóm tắt do Công cụ kiểm thử cục bộ tạo.

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

Để kích hoạ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 sử 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ư quy trình Bắt đầu sử dụng Dịch vụ tổng hợp, bạn sẽ cần sử dụng cờ Chrome và công tắc CLI.

Trong bản minh hoạ này, chúng ta sẽ sử dụng trang web minh hoạ Hộp cát về quyền riêng tư. Truy cập vào trang web bằng cách nhấp vào đường liên kết, sau đó, bạn có thể xem 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 có thể tổng hợp dành riêng cho Google Cloud và do điểm 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 này: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Báo cáo gỡ lỗi của Google Cloud.

2.2. Tạo Báo cáo gỡ lỗi có thể tổng hợp

Sao chép báo cáo 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 ở Điều kiện tiên quyết 1.5).

Trong ví dụ này, chúng ta sẽ sử dụng vim vì đang dùng Linux. Tuy nhiên, 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.

Mã JSON của báo cáo.

Sau khi có được thông tin đó, hãy dùng aggregatable_report_converter.jar để giúp tạo báo cáo gỡ lỗi có thể tổng hợp. Thao tác này sẽ tạo một báo cáo có thể 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á nhóm 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 từ báo cáo.

Khoá nhóm được thiết kế bởi công nghệ quảng cáo. Tuy nhiên, trong trường hợp này, trang web Bản minh hoạ Hộp cát về quyền riêng tư sẽ tạo khoá nhóm. 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á nhóm.

Bạn có thể 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 vào hộp "INPUT" (ĐẦU VÀO) và nhấp vào "Decode" (Giải mã).

Nút giải mã.

Trang này trả về giá trị thập phân của khoá nhóm. Sau đây là khoá nhóm mẫu.

Khoá mẫu của một nhóm.

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

Giờ đây, khi đã có khoá nhóm, hãy tạo output_domain.avro trong cùng thư mục mà chúng ta đang làm việc. Xác minh rằng bạn thay thế khoá nhóm bằng khoá nhóm mà bạn đã truy xuất.

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

Tập lệnh này 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 thử cục bộ

Chúng ta sẽ sử dụng LocalTestingTool_{version}.jar đã 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 sau. 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 .

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

Đầu ra AVRO

2.6. Xem Báo cáo tóm tắt

Báo cáo tóm tắt được tạo ở định dạng AVRO. Để có thể đọc dữ liệu này, bạn cần chuyển đổi dữ liệu này từ AVRO sang định dạng JSON. Tốt nhất là công nghệ quảng cáo nên viết mã để chuyển đổi báo cáo AVRO trở lại JSON.

Chúng ta sẽ dùng aggregatable_report_converter.jar để chuyển đổi báo cáo AVRO trở lại 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ư sau. Cùng với báo cáo output.json được tạo trong cùng một thư mục.

Xuất JSON

Bạn đã hoàn thành lớp học lập trình!

Tóm tắt: Bạn đã thu thập một báo cáo gỡ lỗi, tạo một tệp miền đầu ra và tạo một báo cáo tóm tắt bằng công cụ kiểm thử cục bộ mô phỏng hành vi tổng hợp của Aggregation Service.

Các bước tiếp theo: Giờ đây, sau khi thử nghiệm với công cụ Kiểm thử cục bộ, bạn có thể thử thực hiện thao tác tương tự với việc triển khai trực tiếp Dịch vụ tổng hợp trong môi trường của riêng mình. Xem lại các điều kiện tiên quyết để đảm bảo bạn đã thiết lập mọi thứ cho chế độ "Dịch vụ tổng hợp", sau đó chuyển sang bước 3.

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 xác minh rằng bạn đã hoàn tất tất cả các Điều kiện tiên quyết được gắn nhãn "Dịch vụ tổng hợp".

Các bước trong 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 của Dịch vụ tổng hợp được xử lý 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 sang AVRO
• Bước 3.1.4. Tạo AVRO output_domain
• Bước 3.1.5. Di chuyển báo cáo sang bộ chứa Cloud Storage

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

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

3.1. Tạo dữ liệu đầu vào cho Aggregation Service

Tiến hành tạo báo cáo AVRO để gộp nhóm vào Aggregation Service. Bạn có thể chạy các lệnh shell trong những bước này trong Cloud Shell của Google Cloud (miễn là các phần phụ thuộc trong phần Điều kiện tiên quyết được sao chép vào môi trường Cloud Shell của bạn) 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

Truy cập vào trang web bằng cách nhấp vào đường liên kết, sau đó, bạn có thể xem 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 có thể tổng hợp dành riêng cho Google Cloud và do điểm 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 này: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Báo cáo gỡ lỗi của Google Cloud.

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 đã biết của API tương ứng.

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

Trong 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 quá trình sản xuất, các công nghệ quảng cáo dự kiến sẽ thu thập và chuyển đổi báo cáo theo phương thức lập trình.

Hãy 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 sử dụng Linux. Tuy nhiên, 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 sang AVRO

Báo cáo nhận được từ các điểm cuối .well-known 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 nơi lưu trữ report.json và sử dụng aggregatable_report_converter.jar để giúp tạo báo cáo gỡ lỗi có thể tổng hợp. Thao tác này sẽ tạo một báo cáo có thể 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 output_domain

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

Khoá nhóm được thiết kế bởi công nghệ quảng cáo. Tuy nhiên, trong trường hợp này, trang web Bản minh hoạ Hộp cát về quyền riêng tư sẽ tạo khoá nhóm. 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á nhóm.

Bạn có thể 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 vào hộp "INPUT" (ĐẦU VÀO) và nhấp vào "Decode" (Giải mã).

Nút giải mã.

Trang này trả về giá trị thập phân của khoá nhóm. Sau đây là khoá nhóm mẫu.

Khoá mẫu của một nhóm.

Bây giờ chúng ta đã có khoá nhóm, hãy tạo output_domain.avro trong cùng thư mục mà chúng ta đang làm việc. Xác minh rằng bạn thay thế khoá nhóm bằng khoá nhóm mà bạn đã truy xuất.

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

Tập lệnh này 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 sang bộ chứa Cloud Storage

Sau khi bạn tạo báo cáo AVRO và miền đầu ra, hãy chuyển các báo cáo và miền đầu ra vào bộ chứa trong Cloud Storage (mà bạn đã ghi chú 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 dùng các lệnh sau để 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 vùng lưu trữ theo cách thủ công. Tạo một thư mục có tên là "reports" (báo cáo) rồi tải tệp report.avro lên thư mục đó. Tạo một thư mục có tên là "output_domains" rồi tải tệp output_domain.avro lên thư mục đó.

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 rằng bạn đã chọn curl hoặc Postman để đưa ra các yêu cầu API đến các điểm cuối của Dịch vụ tổng hợp. Sau đây là hướng dẫn cho cả hai lựa chọn.

Nếu công việc của bạn gặp lỗi, hãy xem tài liệu khắc phục sự cố của chúng tôi trên GitHub để biết thêm thông tin về cách tiếp tục.

3.2.1. Sử dụng Điểm cuối createJob để xử lý theo lô

Hãy sử dụng một trong các hướng dẫn sau đây về curl hoặc Postman để tạo một 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 đối tượng JSON sau đây vào. Hãy nhớ cập nhật các giá trị phần giữ chỗ. Hãy tham khảo tài liệu về API này để biết thêm thông tin về ý nghĩa của từng trường.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<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>",
      "reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "report_error_threshold_percentage": "10",
      "debug_run": "true"
    }
}

Thực hiện yêu cầu sau. Thay thế các phần giữ chỗ trong URL của yêu cầu curl bằng các giá trị từ frontend_service_cloudfunction_url. Giá trị này sẽ được xuất sau khi quá trình triển khai Terraform hoàn tất thành công 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 API.

Postman

Đối với điểm cuối createJob, bạn phải có nội dung yêu cầu để cung cấp cho Dịch vụ tổng hợp vị trí và tên tệp của các báo cáo có thể 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ế các phần giữ chỗ trong JSON được cung cấp. Để biết thêm thông tin về các trường này và ý nghĩa của chúng, hãy tham khảo tài liệu về API.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/",
    "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<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>",
      "reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "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 API.

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

Hãy sử dụng một trong hai hướng dẫn về curl hoặc Postman sau đây để nhận một công việc.

curl

Thực thi yêu cầu sau đây trong Terminal. Thay thế các phần giữ chỗ trong URL bằng các giá trị từ frontend_service_cloudfunction_url. Đây là URL giống với URL bạn đã 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 mà 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 của yêu cầu công việc của bạn với trạng thái HTTP là 200. "Nội dung" của yêu cầu chứa thông tin cần thiết như job_status, return_message và error_messages (nếu công việc gặp lỗi).

Postman

Để 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" 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 của yêu cầu công việc của bạn với trạng thái HTTP là 200. "Nội dung" của yêu cầu chứa thông tin cần thiết như job_status, return_message và error_messages (nếu công việc gặp lỗi).

JSON phản hồi

3.2.3. Xem xét 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 ở định dạng AVRO và có thể được chuyển đổi lại thành JSON. Bạn có thể dùng aggregatable_report_converter.jar để đọc báo cáo bằng lệnh này.

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

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

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

Nếu yêu cầu createJob của bạn có 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 có định dạng AVRO và có thể được chuyển đổi sang JSON bằng lệnh trước đó.

Báo cáo này chứa khoá nhóm, chỉ số chưa được làm nhiễu và nhiễu được thêm vào chỉ số chưa được làm nhiễu để tạo báo cáo tóm tắt. Báo cáo sẽ có dạng như sau.

Báo cáo có âm thanh

Chú thích cũng chứa "in_reports" hoặc "in_domain" (hoặc cả hai), có nghĩa là:

• in_reports – khoá nhóm có trong báo cáo có thể tổng hợp.
• in_domain – khoá bộ chứa có trong tệp AVRO output_domain.

Bạn đã hoàn thành lớp học lập trình!

Tóm tắt: Bạn đã triển khai Dịch vụ tổng hợp trong môi trường đám mây của riêng mình, thu thập một báo cáo gỡ lỗi, tạo một tệp miền đầu ra, lưu trữ các tệp này trong một bộ chứa Cloud Storage và chạy thành công một công việc!

Các bước tiếp theo: Tiếp tục sử dụng Dịch vụ tổng hợp trong môi trường của bạn hoặc xoá các tài nguyên đám mây mà bạn vừa tạo theo hướng dẫn dọn dẹp ở bước 4.

4. 4. Dọn dẹp

Để xoá các tài nguyên được tạo cho Dịch vụ tổng hợp bằng Terraform, hãy dùng lệnh destroy 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á nhóm Cloud Storage chứa báo cáo tổng hợp và báo cáo tóm tắt:

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

Bạn cũng có thể chọn khôi phụ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