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-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áy cục bộ và trình duyệt Chrome (không tạo/sử dụng tài nguyên trê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.

Để tham gia 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 được đánh dấu tương ứng cho biết yêu cầu đó là bắt buộc đối với tính năng 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 đả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 quyền riêng tư trong quảng cáo (Dịch vụ tổng hợp và kiểm thử cục bộ)

Vì chúng tôi 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 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ả API Quyền riêng tư trong quảng cáo.

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

Từ chrome://settings/cookies, hãy đảm bảo rằng 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

1.3. Tải Công cụ 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 để kiểm thử cục bộ. 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ộ xuống 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. Đả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" (Dòng lệnh) và sử dụng java --version để kiểm tra xem máy của bạn đã cài đặt Java hay openJDK hay chưa.

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 (Dịch vụ tổng hợp và kiểm thử cục bộ) xuống

Bạn có thể tải một bản sao của aggregatable_report_converter xuống từ kho lưu trữ GitHub về bản 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 phải sử dụng cả hai. 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 GCP (Dịch vụ tổng hợp)

Dịch vụ tổng hợp yêu cầu sử dụng Môi trường thực thi đáng tin cậy sử dụng 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, nhưng AWS cũng được hỗ trợ.

Làm theo Hướng dẫn triển khai trong GitHub để thiết lập gcloud 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 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 "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 các phần phụ thuộc xuống.
4. Cập nhật adtech_setup.auto.tfvars và chạy Terraform adtech_setup. Hãy xem Phụ lục để biết ví dụ về tệp adtech_setup.auto.tfvars. Lưu ý tên của bộ chứa dữ liệu được tạo tại đâ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 Terraform dev. Hãy xem Phụ lục để biết ví dụ về tệp dev.auto.tfvars.
6. Sau khi triển khai xong, hãy ghi lại frontend_service_cloudfunction_url từ đầu ra Terraform. Bạn sẽ cần thông tin này để gửi yêu cầu đến Dịch vụ tổng hợp trong 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 (Aggregation Service)

Dịch vụ tổng hợp yêu cầu người điều phối phải tham gia để có thể sử dụng dịch vụ. Hoàn tất Biểu mẫu tham gia 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ô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 đợi tối đa 2 tuần để quá 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 API (Dịch vụ tổng hợp)

Lớp học lập trình này cung cấp 2 cách để gọi các điểm cuối API Dịch vụ tổng hợp: cURL và Postman. cURL là cách nhanh và dễ dàng hơn để gọi các điểm cuối API từ Terminal, vì bạn chỉ cần thiết lập tối thiểu và không cần thêm phần mềm nào. 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 để sử dụng sau này.

Trong phần 3.2. Aggregation Service Usage (Mức 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 tuỳ chọn. Bạn có thể xem trước các phương thức này ngay để xác định phương thức bạn sẽ sử dụng. Nếu bạn chọn Postman, hãy thực hiện các bước thiết lập ban đầu sau.

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

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

Nếu không gian làm việc chưa được tạo cho bạn, hãy chuyển đến mục điều hướng trên cùng "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 tiếp theo rồi đặt tên là "Hộp cát về quyền riêng tư trên 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 toàn cục của không gian làm việc được định cấu hình sẵn.

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

Thao tác này sẽ tạo tập hợ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 quyền uỷ quyền

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

Bạn sẽ sử dụng phương thức "Bearer Token" (Mã thông báo xác thực). Trong môi trường dòng lệnh, hãy chạy lệnh này và 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 Postman:

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:

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ã-hàm-đám-mây":

Hiện tại, bạn có thể để trống "request-id" vì chúng ta sẽ điền vào 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 triển khai Terraform thành công 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 về 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 để tổng hợp và tạo báo cáo tóm tắt bằng các 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 tất tất cả các điều kiện tiên quyết có 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. Kích hoạt báo cáo: Kích hoạt tính năng 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 đị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 định dạng AVRO.

Bước 2.3. Truy xuất Khoá nhóm: Khoá nhóm 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ư đã cung cấp.

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

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 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 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ư làm quen với Dịch vụ tổng hợp, bạn sẽ cần sử dụng cờ Chrome và nút chuyển CLI.

Đối với 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 đường liên kết để chuyển đến trang web; sau đó, bạn có thể xem các báo cáo tại chrome://private-aggregation-internals:

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 "Phần nội dung báo cáo" của các báo cáo hiển thị trên trang Chrome Internals.

Bạn có thể thấy nhiều báo cáo tại đâ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 ra. "URL báo cáo" sẽ chứa "/debug/" và aggregation_coordinator_origin field của "Phần nội dung báo cáo" sẽ chứa URL này: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

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

Sao chép báo cáo có trong "Report Body" (Phần 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 sẽ 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.

Sau khi có dữ liệu đó, 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á bộ chứa có thể truy xuất từ báo cáo.

Khoá nhóm do công nghệ quảng cáo thiết kế. Tuy nhiên, trong trường hợp này, trang web Privacy Sandbox Demo (Bản minh hoạ Hộp cát về quyền riêng tư) 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ừ "Phần nội dung báo cáo" để lấy khoá bộ chứa.

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

Mở goo.gle/ags-payload-decoder rồi dán debug_cleartext_payload vào hộp "INPUT" (ĐẦU VÀO) rồi nhấp vào "Decode" (Giải mã).

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

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

Giờ đây, chúng ta đã có khoá bộ chứa, hãy tạo output_domain.avro trong cùng thư mục mà chúng ta đang làm việc. Hãy đả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 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 dưới đây. Thay thế {version} bằng phiên bản bạn đã tải xuống. Hãy nhớ di chuyển LocalTestingTool_{version}.jar vào thư mục hiện tại hoặc thêm đường dẫn tương đối để tham chiếu vị trí hiện tại của tệp.

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. Một báo cáo output.avro sẽ được tạo sau khi quá trình này hoàn tất.

2.6. Xem xét 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ừ định dạng AVRO sang định dạng JSON. Lý tưởng nhất là adTech nên viết mã để chuyển đổi báo cáo AVRO trở lại JSON.

Chúng ta sẽ 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ư bên dưới. Cùng với một báo cáo output.json được tạo trong cùng một thư mục.

Lớp học lập trình đã hoàn tất!

Tóm tắt: Bạn đã thu thập báo cáo gỡ lỗi, tạo tệp miền đầu ra và tạo 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 Dịch vụ tổng hợp.

Các bước tiếp theo: Giờ đây, khi đã thử nghiệm với công cụ Kiểm thử cục bộ, bạn có thể thử thực hiện bài tập tương tự bằng cách triển khai Dịch vụ tổng hợp trực tiế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 đảm bảo bạn đã hoàn tất tất cả các điều kiện tiên quyết có 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 Dịch vụ tổng hợp được phân 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 output_domain AVRO
• Bước 3.1.5. Chuyển Báo cáo sang bộ chứa Cloud Storage

Bước 3.2. 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 lại Báo cáo tóm tắt.

• Bước 3.2.1. Sử dụng Điểm cuối createJob để tạo 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 xét 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 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 nhân bản 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 đường liên kết để chuyển đến trang web; sau đó, bạn có thể xem các báo cáo tại chrome://private-aggregation-internals:

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 "Phần nội dung báo cáo" của các báo cáo hiển thị trên trang Chrome Internals.

Bạn có thể thấy nhiều báo cáo tại đâ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 ra. "URL báo cáo" sẽ chứa "/debug/" và aggregation_coordinator_origin field của "Phần nội dung báo cáo" sẽ chứa URL này: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

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

Thu thập 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

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 môi trường sản xuất, 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 tiếp tục 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. 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.

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 ở định dạng JSON và cần được chuyển đổi sang định dạng báo cáo AVRO. Sau khi 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 để tạo báo cáo gỡ lỗi tổng hợp. 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 output_domain AVRO

Để tạo tệp output_domain.avro, bạn cần có các khoá bộ chứa có thể truy xuất từ báo cáo.

Khoá nhóm do công nghệ quảng cáo thiết kế. Tuy nhiên, trong trường hợp này, trang web Privacy Sandbox Demo (Bản minh hoạ Hộp cát về quyền riêng tư) 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ừ "Phần nội dung báo cáo" để lấy khoá bộ chứa.

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

Mở goo.gle/ags-payload-decoder rồi dán debug_cleartext_payload vào hộp "INPUT" (ĐẦU VÀO) rồi nhấp vào "Decode" (Giải mã).

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

Giờ đây, chúng ta đã có khoá bộ chứa, hãy tạo output_domain.avro trong cùng thư mục mà chúng ta đang làm việc. Hãy đả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 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. Chuyển Báo cáo sang bộ chứa Cloud Storage

Sau khi tạo báo cáo AVRO và miền đầu ra, hãy tiếp tục di chuyển 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 sử dụng các lệnh dưới đây để sao chép các tệp vào 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 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 "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ớ rằng trong Điều kiện tiên quyết 1.8, bạn đã chọn cURL hoặc Postman để tạo yêu cầu API đến các điểm cuối của Dịch vụ tổng hợp. Dưới đây là hướng dẫn cho cả hai cách.

Nếu công việc của bạn không thành công do 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 để tạo lô

Hãy sử dụng hướng dẫn về cURL hoặc Postman bên dưới để tạo công việc.

cURL

Trong "Terminal" (Dấu nhắc), hãy tạo một tệp nội dung yêu cầu (body.json) rồi dán vào phần bên dưới. Hãy nhớ cập nhật các giá trị phần giữ chỗ. Tham khảo tài liệu về API này để biết thêm thông tin về nội dung 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>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "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. Đây là giá trị đầu ra sau khi hoàn tất quá trình 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ể xảy ra được ghi lại trong thông số kỹ thuật của API.

Postman

Đối với điểm cuối createJob, bạn cần có phần 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 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ẻ "Body" ("Phần nội dung") của yêu cầu createJob:

Thay thế 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à nội dung mà các trường này đạ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>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

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

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ể xảy ra đượ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 về cURL hoặc Postman bên dưới để nhận công việc.

cURL

Thực thi yêu cầu bên dưới trong Terminal. Thay thế 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 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 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 với trạng thái HTTP là 200. "Phần 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" (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.

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

Kết quả sẽ trả về trạng thái của yêu cầu công việc với trạng thái HTTP là 200. "Phần 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).

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 trở lại thành JSON. Bạn có thể sử dụng aggregatable_report_converter.jar để đọc báo cáo bằng lệnh dưới đâ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 mỗi khoá bộ chứa tương tự như bên dưới.

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 được 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 thành JSON bằng lệnh ở trên.

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

Chú giải cũng chứa "in_reports" và/hoặc "in_domain", có nghĩa là:

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

Lớp học lập trình đã hoàn tất!

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 báo cáo gỡ lỗi, tạo tệp miền đầu ra, lưu trữ các tệp này trong bộ chứa trên 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 trê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 thông 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 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