ทำงานกับ Aggregation Service บน AWS

1. ข้อกำหนดเบื้องต้น

คุณต้องมีข้อกำหนดเบื้องต้นบางอย่างจึงจะทำ Codelab นี้ได้ ข้อกำหนดแต่ละข้อจะมีเครื่องหมายระบุว่าจำเป็นสำหรับ "การทดสอบในเครื่อง" หรือ "บริการรวบรวมข้อมูล"

1.1 ดาวน์โหลดเครื่องมือทดสอบในเครื่อง (Local Testing)

การทดสอบในพื้นที่ต้องดาวน์โหลดเครื่องมือทดสอบในพื้นที่ เครื่องมือจะสร้างรายงานสรุปจากรายงานการแก้ไขข้อบกพร่องที่ไม่ได้เข้ารหัส

เครื่องมือทดสอบในเครื่องพร้อมให้ดาวน์โหลดในที่เก็บถาวร JAR ของ Lambda ใน Github โดยควรตั้งชื่อว่า LocalTestingTool_{version}.jar

1.2 ตรวจสอบว่าได้ติดตั้ง JAVA JRE แล้ว (บริการทดสอบและการรวบรวมข้อมูลในเครื่อง)

เปิด "Terminal" แล้วใช้ java --version เพื่อตรวจสอบว่าเครื่องของคุณติดตั้ง Java หรือ openJDK หรือไม่

ตรวจสอบเวอร์ชัน JRE ของ Java โดยใช้ `java --version`

หากยังไม่ได้ติดตั้ง คุณสามารถดาวน์โหลดและติดตั้งจากเว็บไซต์ Java หรือเว็บไซต์ openJDK

1.3 ดาวน์โหลดเครื่องมือแปลงรายงานที่รวมได้ (การทดสอบในเครื่องและบริการรวมข้อมูล)

คุณสามารถดาวน์โหลดสำเนาตัวแปลงรายงานที่รวบรวมได้จากที่เก็บ GitHub ของการสาธิต Privacy Sandbox

1.4. เปิดใช้ Ad Privacy API (การทดสอบในเครื่องและบริการรวบรวมข้อมูล)

ไปที่ chrome://settings/adPrivacy ในเบราว์เซอร์และเปิดใช้ Ad Privacy API ทั้งหมด

ตรวจสอบว่าได้เปิดใช้คุกกี้ของบุคคลที่สามแล้ว

ในเบราว์เซอร์ ให้ไปที่ chrome://settings/cookies แล้วเลือก "บล็อกคุกกี้ของบุคคลที่สามในโหมดไม่ระบุตัวตน"

การตั้งค่าคุกกี้ของบุคคลที่สามใน Chrome

1.5. การลงทะเบียนเว็บและ Android (บริการรวมข้อมูล)

หากต้องการใช้ Privacy Sandbox API ในสภาพแวดล้อมการใช้งานจริง โปรดตรวจสอบว่าคุณได้ลงทะเบียนและรับรองทั้งสำหรับ Chrome และ Android แล้ว

สำหรับการทดสอบในเครื่อง คุณสามารถปิดใช้การลงทะเบียนได้โดยใช้ Chrome Flag และสวิตช์ CLI

หากต้องการใช้ฟีเจอร์ทดลองของ Chrome สำหรับการสาธิต ให้ไปที่ chrome://flags/#privacy-sandbox-enrollment-overrides แล้วอัปเดตการลบล้างด้วยเว็บไซต์ของคุณ หรือหากจะใช้เว็บไซต์สาธิตของเรา ก็ไม่จำเป็นต้องอัปเดต

ค่าสถานะ Chrome ที่ลบล้างการลงทะเบียน Privacy Sandbox

1.6. การเตรียมความพร้อมใช้งานบริการรวมข้อมูล (Aggregation Service)

บริการรวมข้อมูลกำหนดให้ต้องเริ่มต้นใช้งานกับผู้ประสานงานจึงจะใช้บริการได้ กรอกแบบฟอร์มการเริ่มต้นใช้งานบริการรวบรวมข้อมูลให้ครบถ้วนโดยระบุที่อยู่เว็บไซต์การรายงาน รหัสบัญชี AWS และข้อมูลอื่นๆ

1.7 ผู้ให้บริการคลาวด์ (บริการรวมข้อมูล)

บริการรวมข้อมูลกำหนดให้ใช้สภาพแวดล้อมการดำเนินการที่เชื่อถือได้ซึ่งใช้สภาพแวดล้อมระบบคลาวด์ บริการรวบรวมข้อมูลรองรับ Amazon Web Services (AWS) และ Google Cloud (GCP) Codelab นี้จะครอบคลุมเฉพาะการผสานรวม AWS

AWS มีสภาพแวดล้อมการดำเนินการที่เชื่อถือได้ซึ่งเรียกว่า Nitro Enclaves ตรวจสอบว่าคุณมีบัญชี AWS และทำตามวิธีการติดตั้งและอัปเดต AWS CLI เพื่อตั้งค่าสภาพแวดล้อม AWS CLI

หาก AWS CLI เป็นเวอร์ชันใหม่ คุณสามารถกำหนดค่า AWS CLI ได้โดยใช้วิธีการกำหนดค่า CLI

1.7.1. สร้าง Bucket ของ AWS S3

สร้าง Bucket AWS S3 เพื่อจัดเก็บสถานะ Terraform และสร้าง Bucket S3 อีกอันเพื่อจัดเก็บรายงานและรายงานสรุป คุณใช้คำสั่ง CLI ที่ระบุไว้ได้ แทนที่ฟิลด์ใน <> ด้วยตัวแปรที่เหมาะสม

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. สร้างคีย์การเข้าถึงของผู้ใช้

สร้างคีย์การเข้าถึงของผู้ใช้โดยใช้คำแนะนำของ AWS ซึ่งจะใช้ในการเรียกปลายทาง API ของ createJob และ getJob ที่สร้างขึ้นใน AWS

1.7.3. สิทธิ์ของผู้ใช้และกลุ่ม AWS

หากต้องการติดตั้งใช้งานบริการรวบรวมข้อมูลใน AWS คุณจะต้องให้สิทธิ์บางอย่างแก่ผู้ใช้ที่ใช้ในการติดตั้งใช้งานบริการ สำหรับ Codelab นี้ ให้ตรวจสอบว่าผู้ใช้มีสิทธิ์เข้าถึงระดับผู้ดูแลระบบเพื่อให้แน่ใจว่ามีสิทธิ์เต็มในการติดตั้งใช้งาน

1.8 Terraform (บริการรวมข้อมูล)

Codelab นี้ใช้ Terraform เพื่อติดตั้งใช้งานบริการรวมข้อมูล ตรวจสอบว่าได้ติดตั้งไบนารี Terraform ในสภาพแวดล้อมในเครื่องแล้ว

ดาวน์โหลดไบนารี Terraform ลงในสภาพแวดล้อมในเครื่อง

เมื่อดาวน์โหลดไบนารี Terraform แล้ว ให้แตกไฟล์และย้ายไบนารี Terraform ไปยัง /usr/local/bin

cp <directory>/terraform /usr/local/bin

ตรวจสอบว่า Terraform พร้อมใช้งานใน Classpath

terraform -v

1.9 Postman (สำหรับ AWS ของบริการรวมข้อมูล)

สำหรับ Codelab นี้ ให้ใช้ Postman เพื่อจัดการคำขอ

สร้างพื้นที่ทำงานโดยไปที่รายการนำทางด้านบน "พื้นที่ทำงาน" แล้วเลือก "สร้างพื้นที่ทำงาน"

พื้นที่ทำงาน Postman

เลือก "พื้นที่ทำงานเปล่า" คลิกถัดไป แล้วตั้งชื่อว่า "Privacy Sandbox" เลือก "ส่วนตัว" แล้วคลิก "สร้าง"

ดาวน์โหลดไฟล์การกำหนดค่า JSON และสภาพแวดล้อมส่วนกลางของพื้นที่ทำงานที่กำหนดค่าไว้ล่วงหน้า

นำเข้าไฟล์ JSON ไปยัง "พื้นที่ทํางานของฉัน" โดยใช้ปุ่ม "นําเข้า"

นำเข้าไฟล์ JSON ของ Postman

ซึ่งจะสร้างคอลเล็กชัน Privacy Sandbox พร้อมกับคำขอ HTTP createJob และ getJob ให้คุณ

คอลเล็กชันที่นำเข้าจาก Postman

อัปเดต "คีย์การเข้าถึง" และ "คีย์ลับ" ของ AWS ผ่าน "ภาพรวมสภาพแวดล้อม"

ดูสภาพแวดล้อมของ Postman อย่างรวดเร็ว

คลิก "แก้ไข" แล้วอัปเดต "ค่าปัจจุบัน" ของทั้ง "access_key" และ "secret_key" โปรดทราบว่าเราจะระบุ frontend_api_id ในส่วน 3.1.4 ของเอกสารนี้ และเราขอแนะนำให้ใช้ภูมิภาค us-east-1 อย่างไรก็ตาม หากต้องการติดตั้งใช้งานในภูมิภาคอื่น ให้ตรวจสอบว่าคุณคัดลอก AMI ที่เผยแพร่แล้วไปยังบัญชีของคุณ หรือสร้างด้วยตนเองโดยใช้สคริปต์ที่ให้ไว้

ตัวแปรส่วนกลางของ Postman แก้ไขตัวแปรส่วนกลางใน Postman

2. Codelab การทดสอบในเครื่อง

คุณสามารถใช้เครื่องมือทดสอบในเครื่องเพื่อทำการรวบรวมและสร้างรายงานสรุปโดยใช้รายงานการแก้ไขข้อบกพร่องที่ไม่ได้เข้ารหัส

ขั้นตอน Codelab

ขั้นตอนที่ 2.1 รายงานทริกเกอร์: ทริกเกอร์การรายงาน Private Aggregation เพื่อให้รวบรวมรายงานได้

ขั้นตอนที่ 2.2 สร้างรายงานที่รวบรวมได้สําหรับการแก้ไขข้อบกพร่อง: แปลงรายงาน JSON ที่รวบรวมแล้วเป็นรายงานรูปแบบ AVRO
ขั้นตอนนี้จะคล้ายกับเมื่อเทคโนโลยีโฆษณารวบรวมรายงานจากปลายทางการรายงาน API และแปลงรายงาน JSON เป็นรายงานรูปแบบ AVRO

ขั้นตอนที่ 2.3 แยกวิเคราะห์คีย์ Bucket จากรายงานการแก้ไขข้อบกพร่อง: เทคโนโลยีโฆษณาเป็นผู้ออกแบบคีย์ Bucket ใน Codelab นี้ เนื่องจากมีการกำหนด Bucket ไว้ล่วงหน้าแล้ว ให้ดึงคีย์ Bucket ตามที่ระบุ

ขั้นตอนที่ 2.4 สร้าง AVRO ของโดเมนเอาต์พุต: เมื่อดึงคีย์ของที่เก็บข้อมูลแล้ว ให้สร้างไฟล์ AVRO ของโดเมนเอาต์พุต

ขั้นตอนที่ 2.5 สร้างรายงานสรุปโดยใช้เครื่องมือทดสอบในเครื่อง: ใช้เครื่องมือทดสอบในเครื่องเพื่อสร้างรายงานสรุปในสภาพแวดล้อมในเครื่อง

ขั้นตอนที่ 2.6 ตรวจสอบรายงานสรุป: ตรวจสอบรายงานสรุปที่สร้างโดยเครื่องมือทดสอบในพื้นที่

2.1 รายงานทริกเกอร์

ไปที่เว็บไซต์การสาธิต Privacy Sandbox ซึ่งจะทริกเกอร์รายงานการรวบรวมข้อมูลแบบส่วนตัว คุณดูรายงานได้ที่ chrome://private-aggregation-internals

รายละเอียดการรวมข้อมูลแบบส่วนตัวของ Chrome

หากรายงานมีสถานะเป็น "รอดำเนินการ" คุณสามารถเลือกรายงานแล้วคลิก "ส่งรายงานที่เลือก"

ส่งรายงานการรวบรวมข้อมูลแบบส่วนตัว

2.2 สร้างรายงานที่รวบรวมได้สำหรับการแก้ไขข้อบกพร่อง

ใน chrome://private-aggregation-internals ให้คัดลอก "เนื้อหารายงาน" ที่ได้รับในปลายทาง [reporting-origin]/.well-known/private-aggregation/report-shared-storage

ตรวจสอบว่าใน "เนื้อหารายงาน" aggregation_coordinator_origin มี https://publickeyservice.msmt.aws.privacysandboxservices.com ซึ่งหมายความว่ารายงานเป็นรายงานที่รวบรวมได้ของ AWS

รายงานการรวบรวมข้อมูลแบบส่วนตัว

วาง "เนื้อหารายงาน" JSON ในไฟล์ JSON ในตัวอย่างนี้ คุณสามารถใช้ vim ได้ แต่คุณจะใช้โปรแกรมแก้ไขข้อความใดก็ได้

vim report.json

วางรายงานลงใน report.json แล้วบันทึกไฟล์

รายงานไฟล์ JSON

เมื่อมีรายงานดังกล่าวแล้ว ให้ไปที่โฟลเดอร์รายงานและใช้ aggregatable_report_converter.jar เพื่อช่วยสร้างรายงานที่รวบรวมได้สำหรับการแก้ไขข้อบกพร่อง ซึ่งจะสร้างรายงานที่รวบรวมได้ชื่อ report.avro ในไดเรกทอรีปัจจุบัน

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

2.3 แยกวิเคราะห์คีย์ที่จัดกลุ่มจากรายงานการแก้ไขข้อบกพร่อง

บริการรวมข้อมูลต้องใช้ไฟล์ 2 ไฟล์เมื่อประมวลผลเป็นกลุ่ม รายงานที่รวบรวมได้และไฟล์โดเมนเอาต์พุต ไฟล์โดเมนเอาต์พุตมีคีย์ที่คุณต้องการดึงข้อมูลจากรายงานที่รวบรวมได้ หากต้องการสร้างไฟล์ output_domain.avro คุณต้องมีคีย์ของ Bucket ที่ดึงข้อมูลจากรายงานได้

คีย์ของที่เก็บข้อมูลได้รับการออกแบบโดยผู้เรียก API และการสาธิตมีคีย์ของที่เก็บข้อมูลตัวอย่างที่สร้างไว้ล่วงหน้า เนื่องจากเดโมได้เปิดใช้โหมดแก้ไขข้อบกพร่องสำหรับการรวบรวมข้อมูลแบบส่วนตัว คุณจึงแยกวิเคราะห์เพย์โหลดข้อความธรรมดาที่แก้ไขข้อบกพร่องจาก "เนื้อหารายงาน" เพื่อดึงคีย์ที่จัดกลุ่มได้ แต่ในกรณีนี้ เว็บไซต์ Privacy Sandbox Demo จะสร้างคีย์กลุ่ม เนื่องจากการรวมแบบส่วนตัวสําหรับเว็บไซต์นี้อยู่ในโหมดแก้ไขข้อบกพร่อง คุณจึงใช้ debug_cleartext_payload จาก "เนื้อหารายงาน" เพื่อรับคีย์กลุ่มได้

คัดลอก debug_cleartext_payload จากเนื้อหารายงาน

แก้ไขข้อบกพร่องของเพย์โหลดข้อความธรรมดาจากเนื้อหารายงาน

เปิดเครื่องมือดีบักตัวถอดรหัสเพย์โหลดสำหรับการรวมข้อมูลแบบส่วนตัว แล้ววาง debug_cleartext_payload ในช่อง "INPUT" แล้วคลิก "Decode"

เครื่องมือถอดรหัสเพย์โหลด

หน้าเว็บจะแสดงผลค่าทศนิยมของคีย์ที่จัดเก็บข้อมูล ต่อไปนี้คือคีย์ของที่เก็บข้อมูลตัวอย่าง

ผลลัพธ์ของตัวถอดรหัสเพย์โหลด

2.4 สร้าง AVRO ของโดเมนเอาต์พุต

ตอนนี้เรามีคีย์ Bucket แล้ว ให้คัดลอกค่าทศนิยมของคีย์ Bucket ดำเนินการสร้าง output_domain.avro โดยใช้คีย์ของ Bucket ตรวจสอบว่าคุณได้แทนที่ ด้วยคีย์ที่ระดับ Bucket ที่คุณดึงมา

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

สคริปต์จะสร้างไฟล์ output_domain.avro ในโฟลเดอร์ปัจจุบัน

2.5 สร้างรายงานสรุปโดยใช้เครื่องมือทดสอบในพื้นที่

เราจะใช้ LocalTestingTool_{version}.jar ที่ดาวน์โหลดในส่วนที่ 1.1 เพื่อสร้างรายงานสรุป ใช้คำสั่งต่อไปนี้ คุณควรแทนที่ LocalTestingTool_{version}.jar ด้วยเวอร์ชันที่ดาวน์โหลดสำหรับ LocalTestingTool

เรียกใช้คำสั่งต่อไปนี้เพื่อสร้างรายงานสรุปในสภาพแวดล้อมการพัฒนาในเครื่อง

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

คุณควรเห็นข้อมูลที่คล้ายกับรูปภาพต่อไปนี้เมื่อเรียกใช้คำสั่ง ระบบจะสร้างรายงานoutput.avroเมื่อการดำเนินการนี้เสร็จสมบูรณ์

ไฟล์ Avro ของรายงานสรุปการทดสอบในเครื่อง

2.6 ตรวจสอบรายงานสรุป

รายงานสรุปที่สร้างขึ้นจะอยู่ในรูปแบบ AVRO หากต้องการอ่านข้อมูลนี้ คุณต้องแปลงจาก AVRO เป็นรูปแบบ JSON ในอุดมคติแล้ว เทคโนโลยีโฆษณาควรเขียนโค้ดเพื่อแปลงรายงาน AVRO กลับเป็น JSON

สำหรับ Codelab นี้ เราจะใช้aggregatable_report_converter.jarเครื่องมือที่ให้มาเพื่อแปลงรายงาน AVRO กลับเป็น JSON

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

ซึ่งจะแสดงรายงานที่คล้ายกับรูปภาพต่อไปนี้ พร้อมกับรายงาน output.json ที่สร้างในไดเรกทอรีเดียวกัน

แปลงไฟล์ Avro สรุปเป็น JSON

เปิดไฟล์ JSON ในเครื่องมือแก้ไขที่คุณเลือกเพื่อตรวจสอบรายงานสรุป

3. การติดตั้งใช้งานบริการรวมข้อมูล

หากต้องการติดตั้งใช้งานบริการรวมข้อมูล ให้ทำตามขั้นตอนต่อไปนี้

ขั้นตอนที่ 3 การติดตั้งใช้งานบริการรวมข้อมูล: ติดตั้งใช้งานบริการรวมข้อมูลใน AWS
ขั้นตอนที่ 3.1 โคลนที่เก็บบริการรวมข้อมูล
ขั้นตอนที่ 3.2 ดาวน์โหลดทรัพยากร Dependency ที่สร้างไว้ล่วงหน้า
ขั้นตอนที่ 3.3 สร้างสภาพแวดล้อมในการพัฒนา
ขั้นตอนที่ 3.4 ติดตั้งใช้งานบริการรวมข้อมูล

3.1 โคลนที่เก็บบริการรวมข้อมูล

ในสภาพแวดล้อมภายใน ให้โคลนที่เก็บ GitHub ของบริการรวบรวมข้อมูล

git clone https://github.com/privacysandbox/aggregation-service.git

3.2 ดาวน์โหลดทรัพยากร Dependency ที่สร้างไว้ล่วงหน้า

เมื่อโคลนที่เก็บของบริการรวมข้อมูลแล้ว ให้ไปที่โฟลเดอร์ Terraform ของที่เก็บและโฟลเดอร์ระบบคลาวด์ที่เกี่ยวข้อง หาก cloud_provider คือ AWS คุณสามารถไปที่ /terraform/aws

cd <repository_root>/terraform/aws

ใน /terraform/aws ให้เรียกใช้ download_prebuilt_dependencies.sh

bash download_prebuilt_dependencies.sh

3.3. สร้างสภาพแวดล้อมในการพัฒนาซอฟต์แวร์

สร้างสภาพแวดล้อมการพัฒนาใน /terraform/aws/environments สร้างโฟลเดอร์ชื่อ dev

mkdir dev

คัดลอกเนื้อหาโฟลเดอร์ demo ไปยังโฟลเดอร์ dev

cp -R demo/* dev

ย้ายไปที่โฟลเดอร์ dev

cd dev

อัปเดตไฟล์ main.tf แล้วกด i สำหรับ input เพื่อแก้ไขไฟล์

vim main.tf

ยกเลิกการแสดงความคิดเห็นในโค้ดในกรอบสีแดงโดยนำ # ออกและอัปเดตชื่อ Bucket และคีย์

สำหรับ main.tf ของ AWS

ไฟล์ tf หลักของ AWS

โค้ดที่ไม่ได้ยกเลิกการแสดงความคิดเห็นควรมีลักษณะดังนี้

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

เมื่ออัปเดตเสร็จแล้ว ให้บันทึกการอัปเดตและออกจากโปรแกรมแก้ไขโดยกด esc -> :wq! ซึ่งจะบันทึกการอัปเดตใน main.tf

จากนั้นเปลี่ยนชื่อ example.auto.tfvars เป็น dev.auto.tfvars

mv example.auto.tfvars dev.auto.tfvars

อัปเดต dev.auto.tfvars แล้วกด i สำหรับ input เพื่อแก้ไขไฟล์

vim dev.auto.tfvars

อัปเดตช่องในกรอบสีแดงตามรูปภาพด้วยพารามิเตอร์ ARN ของ AWS ที่ถูกต้องซึ่งได้รับในระหว่างการเริ่มต้นใช้งานบริการรวมข้อมูล สภาพแวดล้อม และอีเมลแจ้งเตือน

แก้ไขไฟล์ tfvars อัตโนมัติสำหรับนักพัฒนาแอป

เมื่ออัปเดตเสร็จแล้ว ให้กด esc -> :wq! ซึ่งจะเป็นการบันทึกไฟล์ dev.auto.tfvars และควรมีลักษณะคล้ายกับรูปภาพต่อไปนี้

อัปเดตไฟล์ dev auto tfvars

3.4. ติดตั้งใช้งานบริการรวมข้อมูล

หากต้องการติดตั้งใช้งานบริการรวมข้อมูล ให้เริ่มต้น Terraform ในโฟลเดอร์เดียวกัน /terraform/aws/environments/dev

terraform init

ซึ่งควรแสดงผลคล้ายกับรูปภาพต่อไปนี้

Terraform init

เมื่อเริ่มต้น Terraform แล้ว ให้สร้างแผนการดำเนินการ Terraform โดยจะแสดงจำนวนทรัพยากรที่จะเพิ่มและข้อมูลเพิ่มเติมอื่นๆ ที่คล้ายกับรูปภาพต่อไปนี้

terraform plan

คุณจะเห็นสรุป "แพ็กเกจ" ในข้อมูลต่อไปนี้ หากเป็นการติดตั้งใช้งานใหม่ คุณควรเห็นจำนวนทรัพยากรที่จะเพิ่มโดยมี 0 รายการที่ต้องเปลี่ยนแปลงและ 0 รายการที่ต้องทำลาย

แผน Terraform

เมื่อดำเนินการนี้เสร็จแล้ว คุณจะสมัครใช้ Terraform ได้

terraform apply

เมื่อได้รับแจ้งให้ยืนยันการดำเนินการโดย Terraform ให้ป้อน yes ในค่า

พรอมต์ Terraform apply

เมื่อ terraform apply เสร็จสิ้น ระบบจะแสดงปลายทางต่อไปนี้สำหรับ createJob และ getJob นอกจากนี้ ระบบยังแสดง frontend_api_id ที่คุณต้องอัปเดตใน Postman ในส่วนที่ 1.9 ด้วย

Terraform apply complete

4. การสร้างอินพุตของบริการรวมข้อมูล

ดำเนินการสร้างรายงาน AVRO สำหรับการจัดกลุ่มในบริการรวมข้อมูล

ขั้นตอนที่ 4 การสร้างอินพุตของบริการรวมข้อมูล: สร้างรายงานบริการรวมข้อมูลที่จัดกลุ่มไว้สำหรับบริการรวมข้อมูล
ขั้นตอนที่ 4.1 รายงานทริกเกอร์
ขั้นตอนที่ 4.2 รวบรวมรายงานที่รวบรวมได้
ขั้นตอนที่ 4.3 แปลงรายงานเป็น AVRO
ขั้นตอนที่ 4.4 สร้าง AVRO ของโดเมนเอาต์พุต

4.1 รายงานทริกเกอร์

ไปที่เว็บไซต์เดโมของ Privacy Sandbox ซึ่งจะทริกเกอร์รายงานการรวบรวมข้อมูลแบบส่วนตัว คุณดูรายงานได้ที่ chrome://private-aggregation-internals

รายละเอียดการรวมข้อมูลแบบส่วนตัวของ Chrome

หากรายงานมีสถานะเป็น "รอดำเนินการ" คุณสามารถเลือกรายงานแล้วคลิก "ส่งรายงานที่เลือก" "

ส่งรายงานการรวบรวมข้อมูลแบบส่วนตัว

4.2 รวบรวมรายงานที่รวบรวมได้

รวบรวมรายงานที่รวบรวมได้จาก.well-knownปลายทางของ API ที่เกี่ยวข้อง

• การรวมข้อมูลแบบส่วนตัว
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• Attribution Reporting - รายงานสรุป
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

สำหรับ Codelab นี้ คุณจะต้องรวบรวมรายงานด้วยตนเอง ในขั้นตอนการผลิต เทคโนโลยีโฆษณาจะต้องรวบรวมและแปลงรายงานแบบเป็นโปรแกรม

ใน chrome://private-aggregation-internals ให้คัดลอก "เนื้อหารายงาน" ที่ได้รับในปลายทาง [reporting-origin]/.well-known/private-aggregation/report-shared-storage

ตรวจสอบว่าใน "เนื้อหารายงาน" aggregation_coordinator_origin มี https://publickeyservice.msmt.aws.privacysandboxservices.com ซึ่งหมายความว่ารายงานเป็นรายงานที่รวบรวมได้ของ AWS

รายงานการรวบรวมข้อมูลแบบส่วนตัว

วาง "เนื้อหารายงาน" JSON ในไฟล์ JSON ในตัวอย่างนี้ คุณสามารถใช้ vim ได้ แต่คุณจะใช้โปรแกรมแก้ไขข้อความใดก็ได้

vim report.json

วางรายงานลงใน report.json แล้วบันทึกไฟล์

รายงานไฟล์ JSON

4.3 แปลงรายงานเป็น AVRO

รายงานที่ได้รับจากปลายทาง .well-known จะอยู่ในรูปแบบ JSON และต้องแปลงเป็นรูปแบบรายงาน AVRO เมื่อมีรายงาน JSON แล้ว ให้ไปที่โฟลเดอร์รายงานและใช้ aggregatable_report_converter.jar เพื่อช่วยสร้างรายงานที่รวบรวมได้สำหรับการแก้ไขข้อบกพร่อง ซึ่งจะสร้างรายงานที่รวบรวมได้ชื่อ report.avro ในไดเรกทอรีปัจจุบัน

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

4.4 สร้าง AVRO ของโดเมนเอาต์พุต

หากต้องการสร้างไฟล์ output_domain.avro คุณต้องมีคีย์ของ Bucket ที่ดึงข้อมูลจากรายงานได้

คีย์กลุ่มได้รับการออกแบบโดยเทคโนโลยีโฆษณา แต่ในกรณีนี้ เว็บไซต์การสาธิต Privacy Sandbox จะสร้างคีย์กลุ่ม เนื่องจากการรวมแบบส่วนตัวสําหรับเว็บไซต์นี้อยู่ในโหมดแก้ไขข้อบกพร่อง คุณจึงใช้ debug_cleartext_payload จาก "เนื้อหารายงาน" เพื่อรับคีย์กลุ่มได้

คัดลอก debug_cleartext_payload จากเนื้อหารายงาน

แก้ไขข้อบกพร่องของเพย์โหลดข้อความธรรมดาจากเนื้อหารายงาน

เปิด goo.gle/ags-payload-decoder แล้ววาง debug_cleartext_payload ในช่อง "INPUT" แล้วคลิก "Decode"

เครื่องมือถอดรหัสเพย์โหลด

หน้าเว็บจะแสดงผลค่าทศนิยมของคีย์ที่จัดเก็บข้อมูล ต่อไปนี้คือคีย์ของที่เก็บข้อมูลตัวอย่าง

ผลลัพธ์ของตัวถอดรหัสเพย์โหลด

เมื่อได้คีย์ของที่เก็บข้อมูลแล้ว ให้สร้าง output_domain.avro ตรวจสอบว่าคุณได้แทนที่ ด้วยคีย์ที่ระดับ Bucket ที่คุณดึงมา

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

สคริปต์จะสร้างไฟล์ output_domain.avro ในโฟลเดอร์ปัจจุบัน

4.5 ย้ายรายงานไปยัง Bucket ของ AWS

เมื่อสร้างรายงาน AVRO (จากส่วน 3.2.3) และโดเมนเอาต์พุต (จากส่วน 3.2.4) แล้ว ให้ย้ายรายงานและโดเมนเอาต์พุตไปยังที่เก็บข้อมูล S3 สำหรับการรายงาน

หากตั้งค่า AWS CLI ในสภาพแวดล้อมในเครื่อง ให้ใช้คำสั่งต่อไปนี้เพื่อคัดลอกรายงานไปยังที่เก็บข้อมูล S3 และโฟลเดอร์รายงานที่เกี่ยวข้อง

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. การใช้งานบริการรวมข้อมูล

จาก terraform apply คุณจะได้รับ create_job_endpoint, get_job_endpoint และ frontend_api_id คัดลอก frontend_api_id แล้ววางลงในตัวแปรส่วนกลางของ Postman frontend_api_id ที่คุณตั้งค่าไว้ในส่วนข้อกำหนดเบื้องต้น 1.9

ขั้นตอนที่ 5 การใช้งานบริการรวมข้อมูล: ใช้ Aggregation Service API เพื่อสร้างรายงานสรุปและตรวจสอบรายงานสรุป
ขั้นตอนที่ 5.1 การใช้ปลายทาง createJob เพื่อประมวลผลเป็นกลุ่ม
ขั้นตอนที่ 5.2 การใช้ปลายทาง getJob เพื่อดึงข้อมูลสถานะกลุ่ม
ขั้นตอนที่ 5.3 การตรวจสอบรายงานสรุป

5.1 การใช้ปลายทาง createJob เพื่อประมวลผลแบบกลุ่ม

ใน Postman ให้เปิดคอลเล็กชัน "Privacy Sandbox" แล้วเลือก "createJob"

เลือก "Body" แล้วเลือก "raw" เพื่อวางเพย์โหลดคำขอ

เนื้อหาคำขอ postman createJob

createJob สคีมาเพย์โหลดมีอยู่ใน github และมีลักษณะคล้ายกับตัวอย่างต่อไปนี้ แทนที่ <> ด้วยช่องที่เหมาะสม

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_blob_prefixes": [
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<report_folder>/<report_name>.avro"
    ], // Mutually exclusive to input_data_blob_prefix as of v2.11.0
    "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"
    }
}

เมื่อคลิก "ส่ง" ระบบจะสร้างงานที่มี job_request_id คุณควรได้รับการตอบกลับ HTTP 202 เมื่อบริการรวบรวมข้อมูลยอมรับคำขอ ดูรหัสการตอบกลับอื่นๆ ที่เป็นไปได้ได้ในรหัสการตอบกลับ HTTP

สถานะคำขอ postman createJob

5.2 การใช้ปลายทาง getJob เพื่อดึงข้อมูลสถานะของงานแบบกลุ่ม

หากต้องการตรวจสอบสถานะของคำของาน คุณสามารถใช้ปลายทาง getJob ได้ เลือก "getJob" ในคอลเล็กชัน "Privacy Sandbox"

ใน "Params" ให้อัปเดตค่า job_request_id เป็น job_request_id ที่ส่งในคำขอ createJob

คำขอ getJob ของ Postman

ผลลัพธ์ของ getJob ควรแสดงสถานะของคำของานพร้อมสถานะ HTTP เป็น 200 คำขอ "เนื้อหา" มีข้อมูลที่จำเป็น เช่น job_status, return_message และ error_messages (หากงานเกิดข้อผิดพลาด)

สถานะคำขอ getJob ของ Postman

เนื่องจากเว็บไซต์การรายงานของรายงานเดโมที่สร้างขึ้นแตกต่างจากเว็บไซต์ที่คุณเริ่มต้นใช้งานใน AWS ID คุณจึงอาจได้รับคำตอบที่มี PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code ซึ่งเป็นเรื่องปกติเนื่องจากเว็บไซต์ต้นทางการรายงานของรายงานไม่ตรงกับเว็บไซต์การรายงานที่เริ่มต้นใช้งานสำหรับรหัส 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_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": "<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>", // Mutually exclusive to attribution_report_to as of v2.7.0
      },
      "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

5.3 การตรวจสอบรายงานสรุป

เมื่อได้รับรายงานสรุปในที่เก็บข้อมูล S3 เอาต์พุตแล้ว คุณจะดาวน์โหลดรายงานนี้ไปยังสภาพแวดล้อมในเครื่องได้ รายงานสรุปอยู่ในรูปแบบ AVRO และสามารถแปลงกลับเป็น JSON ได้ คุณใช้ aggregatable_report_converter.jar เพื่ออ่านรายงานได้โดยใช้คำสั่งต่อไปนี้

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

ซึ่งจะแสดงผล JSON ของค่ารวมของคีย์ Bucket แต่ละรายการที่มีลักษณะคล้ายกับรูปภาพต่อไปนี้

รายงานสรุป

หากcreateJobคำขอของคุณมี debug_run เป็น true คุณจะได้รับรายงานสรุปในโฟลเดอร์การแก้ไขข้อบกพร่องซึ่งอยู่ใน output_data_blob_prefix รายงานอยู่ในรูปแบบ AVRO และสามารถแปลงเป็น JSON ได้โดยใช้คำสั่งก่อนหน้า

รายงานประกอบด้วยคีย์ที่จัดกลุ่ม เมตริกที่ไม่มีการเพิ่มสัญญาณรบกวน และสัญญาณรบกวนที่เพิ่มลงในเมตริกที่ไม่มีการเพิ่มสัญญาณรบกวนเพื่อสร้างรายงานสรุป รายงานจะคล้ายกับรูปภาพต่อไปนี้

รายงานสรุปการแก้ไขข้อบกพร่อง

คำอธิบายประกอบยังมี in_reports และ in_domain ซึ่งหมายความว่า

• in_reports - คีย์กลุ่มข้อมูลจะอยู่ในรายงานที่รวบรวมได้
• in_domain - คีย์ของ Bucket จะอยู่ในไฟล์ AVRO ของ output_domain