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 các API về quyền riêng tư trong quảng cáo (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 chuyển đến chrome://settings/adPrivacy rồi bật tất cả Ad Privacy API.
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 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 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.
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ư. 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 dùng những công cụ này, hãy tải tệp JAR xuống môi trường cục bộ của bạn.
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ợ.
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:
- Thiết lập "gcloud" CLI và Terraform trong môi trường của bạn.
- Tạo một bộ chứa Cloud Storage để lưu trữ trạng thái Terraform.
- Tải các phần phụ thuộc xuống.
- Cập nhật
adtech_setup.auto.tfvarsvà chạyadtech_setupTerraform. Hãy xem Phụ lục để biết tệpadtech_setup.auto.tfvarsmẫu. 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 này để lưu trữ các tệp mà chúng ta tạo. - Cập nhật
dev.auto.tfvars, mạo danh tài khoản dịch vụ triển khai rồi chạy Terraformdev. Hãy xem Phụ lục để biết tệpdev.auto.tfvarsmẫu. - Sau khi triển khai xong, hãy ghi lại
frontend_service_cloudfunction_urltừ 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.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 của API 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ách này 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 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.
Nếu bạn không tạo không gian làm việc cho mình, hãy chuyển đến mục "Không gian làm việc" mục điều hướng trên cùng và 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" thông qua quy tắc "Nhập" .
Thao tác này sẽ tạo "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 "Hộp cát về quyền riêng tư của GCP" thu thập và chuyển đến phần "Uỷ quyền" .
Bạn sẽ sử dụng "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 "Mã thông báo" trường của tab Uỷ quyền Người đưa thư:
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" và cập nhật "Giá trị hiện tại" về "environment", "region" và "cloud-function-id":
Bạn có thể để lại "request-id" để trống, chúng tôi sẽ điền vào 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://
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 bạn đang dùng trang web của riêng mình và chưa hoàn tất quy trình Đăng ký và Giới thiệu dịch vụ Chứng thực và tổng hợp, bạn sẽ cần sử dụng nút chuyển CLI và cờ Chrome.
Đố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ư. Truy cập vào trang web theo đường liên kết này; thì 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 "Nội dung báo cáo" của các báo cáo xuất hiện trên trang Nội bộ của Chrome.
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.
2.2. Tạo báo cáo tổng hợp gỡ lỗi
Sao chép báo cáo tìm thấy trong "Nội dung báo cáo" 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 repo được tải xuống trong Prerequisite 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.
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.
Mở goo.gle/ags-payload-decoder rồi dán debug_cleartext_payload của bạn vào "INPUT" và nhấp vào "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.
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.
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.
Đã 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, xây dựng 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 Dịch vụ tổng hợp.
Các bước tiếp theo: Giờ đây, khi đã thử nghiệm Công cụ kiểm thử cục bộ, bạn có thể thử bài tập tương tự bằng cách 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 "Dịch vụ tổng hợp" chế độ xem, 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 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
Truy cập vào trang web theo đường liên kết này; thì 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 "Nội dung báo cáo" của các báo cáo xuất hiện trên trang Nội bộ của Chrome.
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.
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.
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.
Mở goo.gle/ags-payload-decoder rồi dán debug_cleartext_payload của bạn vào "INPUT" và nhấp vào "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.
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 tiến hành 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 đã nêu 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 thư mục có tên "báo cáo" và tải tệp report.avro lên đó. Tạo một thư mục có tên là "output_domains" và 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.
Nếu công việc của bạn không thành công do gặp lỗi, hãy xem tài liệu về cách khắc phục sự cố của chúng tôi trong GitHub để biết thêm thông tin về cách xử lý.
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>",
"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 (đượ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.
Postman
Đố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 phần "Nội dung" của yêu cầu createJob :
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>",
"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ể 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 "Nội dung" chứa thông tin cần thiết như job_status, return_message và error_messages (nếu công việc bị 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 phần "Thông số" trong phần 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 yêu cầu công việc của bạn với trạng thái HTTP 200. Yêu cầu "Nội dung" chứa thông tin cần thiết như job_status, return_message và error_messages (nếu công việc bị lỗ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.
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.
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á bộ chứa có sẵn trong tệp AVRO output_domain.
Đã 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 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 bộ chứa Cloud Storage và chạy thành công!
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 bạn vừa tạo theo hướng dẫn dọn dẹp trong bước 4.
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