1. Điều kiện tiên quyết
Để thực hiện lớp học lập trình này, 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 với việc liệu đó có phải là yêu cầu bắt buộc cho hoạt động "Thử nghiệm tại địa phương" hay không hay "Dịch vụ tổng hợp".
1.1. 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 lambda trên GitHub. Tệp này phải được đặt tên là LocalTestingTool_{version}.jar
.
1.2. Đả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.3. Tải trình chuyển đổi báo cáo tổng hợp 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 trình chuyển đổi báo cáo tổng hợp xuống qua kho lưu trữ GitHub về cách minh hoạ Hộp cát về quyền riêng tư.
1,4. Bật các Ad Privacy API (Kiểm thử cục bộ và Dịch vụ tổng hợp)
Trên trình duyệt, hãy chuyển đến chrome://settings/adPrivacy
rồi bật tất cả Ad Privacy API.
Hãy đảm bảo rằng bạn đã bật cookie của bên thứ ba.
Trên trình duyệt, hãy truy cập vào chrome://settings/cookies
rồi chọn "Chặn cookie của bên thứ ba ở Chế độ ẩn danh".
1.5. Đăng ký web và Android (Dịch vụ tổng hợp)
Để sử dụng API Hộp cát về quyền riêng tư trong môi trường phát hành chính thức, hãy đảm bảo bạn đã hoàn tất quy trình đăng ký và chứng thực cho cả Chrome và Android.
Đối với kiểm thử cục bộ, bạn có thể tắt tính năng đăng ký bằng cờ Chrome và nút chuyển CLI.
Để sử dụng cờ Chrome cho bản minh hoạ, hãy truy cập chrome://flags/#privacy-sandbox-enrollment-overrides
rồi cập nhật chế độ ghi đè bằng trang web của bạn hoặc nếu bạn đang sử dụng trang web minh hoạ của chúng tôi thì bạn không cần cập nhật gì.
1.6. 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 địa chỉ trang web báo cáo, mã tài khoản AWS và các thông tin khác.
1.7. Nhà cung cấp dịch vụ đám mây (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 (môi trường này dùng một môi trường đám mây). Dịch vụ tổng hợp được hỗ trợ trên Amazon Web Services (AWS) và Google Cloud (GCP). Lớp học lập trình này sẽ chỉ đề cập đến việc tích hợp AWS.
AWS cung cấp một Môi trường thực thi đáng tin cậy có tên là Nitro Enclaves. Đảm bảo bạn có tài khoản AWS và làm theo hướng dẫn cài đặt và cập nhật AWS CLI để thiết lập môi trường AWS CLI.
Nếu AWS CLI là mới, bạn có thể định cấu hình AWS CLI bằng cách sử dụng hướng dẫn Cấu hình CLI.
1.7.1. Tạo bộ chứa AWS S3
Tạo một Bộ chứa AWS S3 để lưu trữ trạng thái Terraform và một bộ chứa S3 khác để lưu trữ các báo cáo và báo cáo tóm tắt. Bạn có thể sử dụng lệnh CLI được cung cấp. Hãy thay thế trường trong <>
bằng các biến phù hợp.
aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1
1.7.2. Tạo khoá truy cập cho người dùng
Tạo khoá truy cập cho người dùng theo hướng dẫn về ACS. API này sẽ được dùng để gọi các điểm cuối API createJob
và getJob
được tạo trên AWS.
1.7.3. Quyền của nhóm và người dùng AWS
Để triển khai Dịch vụ tổng hợp trên AWS, bạn sẽ cần cung cấp một số quyền nhất định cho người dùng được dùng để triển khai dịch vụ. Đối với lớp học lập trình này, hãy đảm bảo người dùng có Quyền quản trị để đảm bảo có đầy đủ quyền khi triển khai.
1,8. Terraform (Dịch vụ tổng hợp)
Lớp học lập trình này sử dụng Terraform để triển khai Dịch vụ tổng hợp. Đảm bảo tệp nhị phân Teraform được cài đặt vào môi trường cục bộ của bạn.
Tải tệp nhị phân Teraform xuống môi trường cục bộ của bạn.
Sau khi tải tệp nhị phân Terraform xuống, hãy giải nén tệp và di chuyển tệp nhị phân Terraform sang /usr/local/bin
.
cp <directory>/terraform /usr/local/bin
Kiểm tra để đảm bảo rằng Terraform có trên classpath.
terraform -v
1,9. Người đưa thư (Đối với dịch vụ tổng hợp AWS)
Đối với lớp học lập trình này, hãy sử dụng Postman để quản lý yêu cầu.
Tạo không gian làm việc bằng cách chuyển đến phần "Không gian làm việc" mục điều hướng trên cùng 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 là "Hộp cát về quyền riêng tư". Chọn "Cá nhân" rồi nhấp vào "Tạo".
Tải các tệp Cấu hình JSON và Môi trường toàn cầu xuống cho không gian làm việc định cấu hình sẵn.
Nhập tệp JSON vào "Không gian làm việc của tôi" bằng cách sử dụng lệnh "Nhập" .
Thao tác này sẽ tạo tập hợp Hộp cát về quyền riêng tư cho bạn cùng với các yêu cầu HTTP createJob
và getJob
.
Cập nhật "Khoá truy cập" của AWS và "Khoá bí mật" thông qua "Môi trường xem nhanh".
Nhấp vào "Chỉnh sửa" và cập nhật "Giá trị hiện tại" của cả "access_key" và "secret_key". Lưu ý rằng frontend_api_id
sẽ được cung cấp trong mục 3.1.4 của tài liệu này. Bạn nên sử dụng khu vực us-east-1. Tuy nhiên, nếu muốn triển khai ở một khu vực khác, hãy nhớ sao chép AMI đã phát hành vào tài khoản của bạn hoặc tự tạo bằng tập lệnh được cung cấp.
2. Lớp học lập trình kiểm thử cục bộ
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á.
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 tổng hợp gỡ lỗi: 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. Phân tích cú pháp khoá bộ chứa từ báo cáo gỡ lỗi: 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 miền đầu ra AVRO: Sau khi truy xuất các khoá bộ chứa, hãy tạo tệp AVRO của miền đầu ra.
Bước 2.5. Tạo báo cáo tóm tắt bằng Công cụ kiểm tra cục bộ: 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
Truy cập trang web minh hoạ hộp cát về quyền riêng tư. Thao tác này sẽ kích hoạt một báo cáo tổng hợp riêng tư. Bạn có thể xem báo cáo tại chrome://private-aggregation-internals
.
Nếu báo cáo của bạn ở trạng thái "Đang chờ xử lý" trạng thái, bạn có thể chọn báo cáo và nhấp vào "Gửi báo cáo đã chọn".
2.2. Tạo báo cáo tổng hợp gỡ lỗi
Trong chrome://private-aggregation-internals
, hãy sao chép "Nội dung báo cáo" đã nhận trong điểm cuối [reporting-origin]/.well-known/private-aggregation/report-shared-storage
.
Đảm bảo rằng trong "Nội dung báo cáo", aggregation_coordinator_origin
chứa https://publickeyservice.msmt.aws.privacysandboxservices.com
, nghĩa là báo cáo đó là một báo cáo tổng hợp của AWS.
Đặt "Nội dung báo cáo" JSON trong tệp JSON. Trong ví dụ này, bạn có thể sử dụng vim. 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 đó, hãy chuyển đến thư mục báo cáo rồi 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 \
--debug
2.3. Phân tích cú pháp khoá bộ chứa từ báo cáo gỡ lỗi
Dịch vụ tổng hợp yêu cầu 2 tệp khi phân lô. Báo cáo tổng hợp và tệp miền đầu ra. Tệp miền đầu ra chứa các khoá mà bạn muốn truy xuất qua báo cáo tổng hợp. Để 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 được thiết kế bởi phương thức gọi của API và bản minh hoạ chứa khoá bộ chứa mẫu được tạo trước. Vì bản minh hoạ đã bật chế độ gỡ lỗi cho tính năng Tổng hợp riêng tư, nên bạn có thể phân tích cú pháp tải trọng văn bản thô gỡ lỗi từ "Nội dung báo cáo" để truy xuất khoá bộ chứa. 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 bạn có thể sử dụng debug_cleartext_payload
từ "Nội dung báo cáo" để lấy khoá bộ chứa.
Sao chép debug_cleartext_payload
từ nội dung báo cáo.
Mở công cụ Trình giải mã tải trọng gỡ lỗi cho tính năng Tổng hợp riêng tư rồi dán debug_cleartext_payload
của bạn vào mục "INPUT" rồi nhấp vào "Giải mã".
Trang trả về giá trị thập phân của khoá bộ chứa. Sau đây là một khoá nhóm mẫu.
2.4. Tạo miền đầu ra AVRO
Giờ chúng ta đã có khoá bộ chứa, hãy tiếp tục và sao chép giá trị thập phân của khoá bộ chứa. Tiếp tục tạo output_domain.avro
bằng khoá nhóm. Đảm bảo rằng bạn thay thế
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 Phần 1.1 để tạo báo cáo tóm tắt. Sử dụng lệnh sau. Bạn nên thay thế LocalTestingTool_{version}.jar
bằng phiên bản đã tải xuống cho LocalTestingTool.
Chạy lệnh sau để tạo báo cáo tóm tắt trong môi trường phát triển cục bộ của bạn:
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ư hình ảnh sau đây 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 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à công nghệ quảng cáo nên mã hoá để chuyển đổi báo cáo AVRO về lại JSON.
Trong lớp học lập trình này, chúng ta sẽ sử dụng công cụ aggregatable_report_converter.jar
được cung cấp để chuyển đổi báo cáo AVRO về 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ư hình ảnh sau đây. Cùng với một báo cáo output.json
được tạo trong cùng thư mục.
Mở tệp JSON trong trình chỉnh sửa mà bạn chọn để xem báo cáo tóm tắt.
3. Triển khai Dịch vụ tổng hợp
Để triển khai Dịch vụ tổng hợp, hãy làm theo các bước sau:
Bước 3. Triển khai dịch vụ tổng hợp: Triển khai Dịch vụ tổng hợp trên AWS
Bước 3.1. Sao chép Kho lưu trữ dịch vụ tổng hợp
Bước 3.2. Tải các phần phụ thuộc tạo sẵn xuống
Bước 3.3. Tạo môi trường phát triển
Bước 3.4. Triển khai dịch vụ tổng hợp
3.1. Sao chép kho lưu trữ Dịch vụ tổng hợp
Trong môi trường cục bộ, hãy sao chép kho lưu trữ GitHub của Dịch vụ tổng hợp.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. Tải phần phụ thuộc tạo sẵn xuống
Sau khi bạn sao chép kho lưu trữ Dịch vụ tổng hợp, hãy chuyển đến thư mục Terraform của kho lưu trữ đó rồi tìm thư mục đám mây tương ứng. Nếu cloud_provider là AWS, bạn có thể tiếp tục truy cập
cd <repository_root>/terraform/aws
Trong
, hãy thực thi download_prebuilt_dependencies.sh
.
bash download_prebuilt_dependencies.sh
3.3. Tạo môi trường phát triển
Tạo môi trường nhà phát triển trong
. Tạo một thư mục có tên là dev
.
mkdir dev
Sao chép nội dung thư mục demo
vào thư mục dev
.
cp -R demo/* dev
Chuyển vào thư mục dev
của bạn.
cd dev
Cập nhật tệp main.tf
rồi nhấn i
cho input
để chỉnh sửa tệp.
vim main.tf
Huỷ nhận xét mã trong hộp màu đỏ bằng cách xoá # và cập nhật tên nhóm và tên khoá.
Đối với AWS main.tf:
Mã không được nhận xét sẽ có dạng như sau.
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Sau khi cập nhật xong, hãy lưu nội dung cập nhật rồi thoát khỏi trình chỉnh sửa bằng cách nhấn phím esc
-> :wq!
. Thao tác này sẽ lưu nội dung cập nhật trên main.tf
.
Tiếp theo, hãy đổi tên example.auto.tfvars
thành dev.auto.tfvars
.
mv example.auto.tfvars dev.auto.tfvars
Cập nhật dev.auto.tfvars
rồi nhấn i
cho input
để chỉnh sửa tệp.
vim dev.auto.tfvars
Cập nhật các trường trong hộp màu đỏ dưới đây bằng các tham số AWS ARN chính xác được cung cấp trong quá trình giới thiệu Dịch vụ tổng hợp, môi trường và email thông báo.
Sau khi cập nhật xong, nhấn esc
-> :wq!
. Thao tác này sẽ lưu tệp dev.auto.tfvars
và tệp này sẽ có dạng như hình sau.
3.4. Triển khai dịch vụ tổng hợp
Để triển khai Dịch vụ tổng hợp, trong cùng thư mục
, hãy khởi chạy Terraform.
terraform init
Thao tác này sẽ trả về nội dung tương tự như hình ảnh sau:
Sau khi khởi động Terraform, hãy tạo kế hoạch thực thi Terraform. Trường hợp trả về số lượng tài nguyên cần thêm và thông tin bổ sung khác tương tự như hình sau.
terraform plan
Bạn có thể xem trong phần "Kế hoạch" sau tóm tắt. Nếu đây là đợt triển khai mới, bạn sẽ thấy số lượng tài nguyên sẽ được thêm vào với 0 để thay đổi và 0 để huỷ bỏ.
Sau khi hoàn tất, bạn có thể tiếp tục áp dụng Terraform.
terraform apply
Khi được nhắc xác nhận việc thực hiện các hành động theo Terraform, hãy nhập yes
vào giá trị.
Sau khi terraform apply
kết thúc, các điểm cuối createJob
và getJob
sau đây sẽ được trả về. frontend_api_id
mà bạn cần cập nhật trong Postman ở mục 1.9 cũng được trả về.
4. 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ô trong Dịch vụ tổng hợp.
Bước 4. 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 4.1. Báo cáo điều kiện kích hoạt
Bước 4.2. Thu thập báo cáo tổng hợp
Bước 4.3. Chuyển đổi báo cáo thành AVRO
Bước 4.4. Tạo miền đầu ra AVRO
4.1. Báo cáo điều kiện kích hoạt
Truy cập trang web minh hoạ Hộp cát về quyền riêng tư. Thao tác này sẽ kích hoạt một báo cáo tổng hợp riêng tư. Bạn có thể xem báo cáo tại chrome://private-aggregation-internals
.
Nếu báo cáo của bạn ở trạng thái "Đang chờ xử lý" trạng thái, bạn có thể chọn báo cáo và nhấp vào "Gửi báo cáo đã chọn".
4.2. Thu thập các 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, bạn sẽ thu thập báo cáo theo cách thủ công. Trong phiên bản chính thức, 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.
Trong chrome://private-aggregation-internals
, hãy sao chép "Nội dung báo cáo" đã nhận trong điểm cuối [reporting-origin]/.well-known/private-aggregation/report-shared-storage
.
Đảm bảo rằng trong "Nội dung báo cáo", aggregation_coordinator_origin
chứa https://publickeyservice.msmt.aws.privacysandboxservices.com
, nghĩa là báo cáo đó là một báo cáo tổng hợp của AWS.
Đặt "Nội dung báo cáo" JSON trong tệp JSON. Trong ví dụ này, bạn có thể sử dụng vim. 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.
4.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 thư mục báo cáo rồi 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
4.4. Tạo miền đầu ra AVRO
Để 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 bạn 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" rồi nhấp vào "Giải mã".
Trang trả về giá trị thập phân của khoá bộ chứa. Sau đây là một khoá nhóm mẫu.
Giờ chúng ta đã có khoá nhóm, hãy tiếp tục và tạo output_domain.avro
. Đảm bảo rằng bạn thay thế
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.
4.5. Di chuyển báo cáo sang bộ chứa AWS
Khi các báo cáo AVRO (từ phần 3.2.3) và miền đầu ra (từ phần 3.2.4) được tạo, hãy tiến hành di chuyển các báo cáo và miền đầu ra vào các bộ chứa S3 báo cáo.
Nếu bạn đã thiết lập AWS CLI trên môi trường cục bộ, hãy sử dụng các lệnh sau để sao chép báo cáo vào bộ chứa và thư mục báo cáo S3 tương ứng.
aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/
5. Mức sử dụng Dịch vụ tổng hợp
Từ terraform apply
, bạn sẽ được trả về create_job_endpoint
, get_job_endpoint
và frontend_api_id
. Sao chép frontend_api_id
rồi đặt biến này vào biến toàn cục của người đưa thư frontend_api_id
mà bạn thiết lập trong phần điều kiện tiên quyết 1.9.
Bước 5. 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 xét các báo cáo tóm tắt.
Bước 5.1. Sử dụng createjob Endpoint để tạo lô
Bước 5.2. Dùng getjob Endpoint để truy xuất trạng thái của lô
Bước 5.3. Xem lại báo cáo Tóm tắt
5.1. Sử dụng điểm cuối createJob
để phân lô
Trong Postman, hãy mở "Hộp cát về quyền riêng tư" rồi chọn "createJob".
Chọn "Nội dung" và chọn "thô" để đặt tải trọng yêu cầu của bạn.
Giản đồ tải trọng createJob
có trong github và có dạng như sau. Thay thế <>
bằng các trường thích hợp.
{
"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"
}
}
Sau khi bạn nhấp vào "Gửi", thao tác này sẽ tạo công việc bằng job_request_id
. 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 đó. Bạn có thể tìm thấy mã trả lại hàng khác trong mã phản hồi HTTP
5.2. Sử dụng getjob Endpoint để truy xuất trạng thái của lô
Để 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
. Chọn "getJob" trong "Hộp cát về quyền riêng tư" bộ sưu tập.
Trong phần "Params", 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
.
Kết quả của getJob
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).
Vì trang web báo cáo của báo cáo minh hoạ được tạo khác với trang web mà bạn tham gia trên mã nhận dạng AWS của bạn, nên có thể bạn sẽ nhận được phản hồi có Return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR
. Điều này là bình thường vì báo cáo trang web của nguồn gốc báo cáo không khớp với trang web báo cáo có trong mã nhận dạng AWS.
{
"job_status": "FINISHED",
"request_received_at": "2023-12-07T22:50:58.830956Z",
"request_updated_at": "2023-12-07T22:51:10.526326456Z",
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"postback_url": "",
"result_info": {
"return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-12-07T22:51:10.517730898Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
"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
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.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 S3 đầu ra, bạn có thể tải báo cáo này xuống môi trường cục bộ của mình. 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 sau.
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 chứa các giá trị tổng hợp của mỗi khoá nhóm trông giống như hình sau.
Nếu yêu cầu createJob
của bạn bao gồm debug_run
dưới dạng 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 bằng lệnh trước đó 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ư hình ảnh sau.
Các chú giải này cũng chứa in_reports
và in_domain
, 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.