1. 1. ข้อกำหนดเบื้องต้น
เวลาที่ใช้โดยประมาณ: 1-2 ชั่วโมง
การดำเนินการ Codelab นี้มี 2 โหมด ได้แก่ การทดสอบในพื้นที่หรือบริการรวบรวมข้อมูล โหมดการทดสอบภายในต้องใช้เครื่องภายในและเบราว์เซอร์ Chrome (ไม่มีการสร้าง/ใช้งานทรัพยากร Google Cloud) โหมดบริการรวมข้อมูลกำหนดให้มีการติดตั้งใช้งานบริการรวบรวมข้อมูลบน Google Cloud อย่างเต็มรูปแบบ
หากต้องการใช้ Codelab นี้ในโหมดใดโหมดหนึ่ง คุณต้องมีข้อกำหนดเบื้องต้น 2-3 อย่าง ระบบจะทำเครื่องหมายข้อกำหนดแต่ละข้อว่าจำเป็นสำหรับการทดสอบในพื้นที่หรือบริการรวบรวมข้อมูล
1.1 ดำเนินการลงทะเบียนและเอกสารรับรอง (บริการรวม)
หากต้องการใช้ Privacy Sandbox API โปรดตรวจสอบว่าคุณได้ลงทะเบียนและเอกสารรับรองสำหรับทั้ง Chrome และ Android แล้ว
1.2 เปิดใช้ API ความเป็นส่วนตัวเกี่ยวกับโฆษณา (การทดสอบและบริการรวมข้อมูลในพื้นที่)
เนื่องจากเราจะใช้ Privacy Sandbox เราจึงขอแนะนําให้คุณเปิดใช้ Privacy Sandbox Ads API
ในเบราว์เซอร์ ให้ไปที่ chrome://settings/adPrivacy
แล้วเปิดใช้ API ความเป็นส่วนตัวเกี่ยวกับโฆษณาทั้งหมด
และตรวจสอบว่าได้เปิดใช้คุกกี้ของบุคคลที่สามแล้ว
ตั้งแต่วันที่ chrome://settings/cookies
เป็นต้นไป ให้ตรวจสอบว่าไม่ได้บล็อกคุกกี้ของบุคคลที่สามอยู่ คุณอาจเห็นตัวเลือกที่แตกต่างออกไปในเมนูการตั้งค่านี้ ทั้งนี้ขึ้นอยู่กับเวอร์ชันของ Chrome แต่การกำหนดค่าที่ยอมรับได้มีดังนี้
- "บล็อกคุกกี้ของบุคคลที่สามทั้งหมด" = ปิดใช้งาน
- "บล็อกคุกกี้ของบุคคลที่สาม" = ปิดใช้งาน
- "บล็อกคุกกี้ของบุคคลที่สามในโหมดไม่ระบุตัวตน" = เปิดใช้งาน
1.3 ดาวน์โหลดเครื่องมือทดสอบในพื้นที่ (การทดสอบในพื้นที่)
การทดสอบในพื้นที่จะต้องดาวน์โหลดเครื่องมือทดสอบในพื้นที่ เครื่องมือจะสร้างรายงานสรุปจากรายงานการแก้ไขข้อบกพร่องที่ไม่ได้เข้ารหัส
ดาวน์โหลดเครื่องมือทดสอบในเครื่องได้ที่ที่เก็บข้อมูล JAR สำหรับ Cloud Function ใน GitHub ควรตั้งชื่อว่า LocalTestingTool_{version}.jar
1.4 ตรวจสอบว่าติดตั้ง JAVA JRE แล้ว (บริการทดสอบและรวบรวมข้อมูลในพื้นที่)
เปิด "Terminal" และใช้ java --version
เพื่อตรวจสอบว่าเครื่องมี Java หรือ openJDK ติดตั้งอยู่
หากยังไม่ได้ติดตั้ง คุณจะดาวน์โหลดและติดตั้งได้จากเว็บไซต์ Java หรือเว็บไซต์ OpenJDK
1.5. ดาวน์โหลด aggregatable_report_converter (การทดสอบในพื้นที่และบริการรวบรวมข้อมูล)
คุณดาวน์โหลดสำเนา aggregatable_report_converter ได้จากที่เก็บ GitHub แบบ Privacy Sandbox ของ Privacy Sandbox ที่เก็บ GitHub ระบุว่าใช้ IntelliJ หรือ Eclipse แต่ก็ไม่ได้ดำเนินการทั้งคู่ หากคุณไม่ใช้เครื่องมือเหล่านี้ ให้ดาวน์โหลดไฟล์ JAR ไปยังสภาพแวดล้อมในเครื่องแทน
1.6. ตั้งค่าสภาพแวดล้อม GCP (บริการรวบรวมข้อมูล)
บริการรวมข้อมูลต้องใช้สภาพแวดล้อมการดำเนินการที่เชื่อถือได้ซึ่งใช้ผู้ให้บริการคลาวด์ Codelab นี้จะมีการทำให้บริการ Aggregation ใช้งานได้ใน GCP แต่ก็รองรับ AWS เช่นกัน
ทำตามวิธีการทำให้ใช้งานได้ใน GitHub เพื่อตั้งค่า gcloud CLI, ดาวน์โหลดไบนารีและโมดูลของ Terraform และสร้างทรัพยากร GCP สำหรับบริการ Aggregation
ขั้นตอนสำคัญในวิธีการทำให้ใช้งานได้มีดังนี้
- ตั้งค่า "gcloud" CLI และ terform ในสภาพแวดล้อมของคุณ
- สร้างที่เก็บข้อมูล Cloud Storage เพื่อจัดเก็บสถานะ Terraform
- ดาวน์โหลดทรัพยากร Dependency
- อัปเดต
adtech_setup.auto.tfvars
และเรียกใช้ Terraform ของadtech_setup
โปรดดูไฟล์adtech_setup.auto.tfvars
ในภาคผนวก จดชื่อของที่เก็บข้อมูลที่สร้างขึ้นที่นี่ ซึ่งจะใช้ใน Codelab เพื่อจัดเก็บไฟล์ที่เราสร้าง - อัปเดต
dev.auto.tfvars
โดยสวมบทบาทเป็นบัญชีบริการให้ใช้งานได้ และเรียกใช้dev
Terraform โปรดดูไฟล์dev.auto.tfvars
ในภาคผนวก - เมื่อการติดตั้งใช้งานเสร็จสมบูรณ์ ให้บันทึก
frontend_service_cloudfunction_url
จากเอาต์พุต Terraform ซึ่งจำเป็นต้องใช้เพื่อส่งคำขอไปยังบริการรวมข้อมูลในขั้นตอนถัดไป
1.7 การเริ่มต้นใช้งานบริการรวมข้อมูลแบบสมบูรณ์ (บริการรวบรวมข้อมูล)
บริการรวมข้อมูลต้องมีการเริ่มต้นใช้งานกับผู้ประสานงานจึงจะใช้บริการได้ กรอกแบบฟอร์มเริ่มต้นใช้งานบริการรวบรวมข้อมูลโดยระบุเว็บไซต์การรายงานและข้อมูลอื่นๆ แล้วเลือก "Google Cloud" แล้วป้อนที่อยู่ของบัญชีบริการ บัญชีบริการนี้สร้างขึ้นในข้อกำหนดเบื้องต้นก่อนหน้า (1.6. ตั้งค่าสภาพแวดล้อม GCP) (คำแนะนำ: หากคุณใช้ชื่อเริ่มต้นที่ระบุ บัญชีบริการนี้จะขึ้นต้นด้วย "worker-sa@")
การเริ่มต้นใช้งานจะใช้เวลาไม่เกิน 2 สัปดาห์
1.8 กำหนดวิธีเรียกใช้ปลายทาง API (บริการรวบรวมข้อมูล)
Codelab นี้มี 2 ตัวเลือกในการเรียกใช้ปลายทาง Aggregation Service API ได้แก่ cURL และ Postman cURL เป็นวิธีที่ง่ายและรวดเร็วในการเรียกใช้ปลายทาง API จากเทอร์มินัลเนื่องจากต้องมีการตั้งค่าเพียงเล็กน้อยและไม่ต้องใช้ซอฟต์แวร์เพิ่มเติม อย่างไรก็ตาม หากไม่ต้องการใช้ cURL คุณสามารถใช้ Postman เพื่อดำเนินการและบันทึกคำขอ API ไว้ใช้ในอนาคตแทนได้
ในส่วน 3.2 การใช้บริการรวมข้อมูล คุณจะเห็นวิธีการโดยละเอียดในการใช้ทั้ง 2 ตัวเลือก คุณดูตัวอย่างได้เลยตอนนี้เพื่อพิจารณาว่าจะใช้วิธีการใด หากคุณเลือก Postman ให้ทำการตั้งค่าเริ่มต้นต่อไปนี้
1.8.1. ตั้งค่าพื้นที่ทำงาน
ลงชื่อสมัครใช้บัญชี Postman เมื่อลงชื่อสมัครใช้แล้ว ระบบจะสร้างพื้นที่ทำงานให้คุณโดยอัตโนมัติ
หากไม่ได้สร้างพื้นที่ทำงานให้คุณ ให้ไปที่ "พื้นที่ทำงาน" รายการการนําทางด้านบน แล้วเลือก "สร้างพื้นที่ทำงาน"
เลือก "พื้นที่ทำงานเปล่า" จากนั้นคลิกถัดไปและตั้งชื่อว่า "GCP Privacy Sandbox" เลือก "ส่วนตัว" แล้วคลิก "สร้าง"
ดาวน์โหลดการกำหนดค่า JSON และไฟล์สภาพแวดล้อมส่วนกลางของพื้นที่ทำงานที่กำหนดค่าล่วงหน้า
นําเข้าไฟล์ JSON ทั้ง 2 ไฟล์ไปยัง "พื้นที่ทํางานของฉัน" ผ่านปุ่ม "นำเข้า"
การดำเนินการนี้จะสร้าง "GCP Privacy Sandbox" ให้คุณ ตลอดจนคำขอ HTTP createJob
และ getJob
1.8.2. ตั้งค่าการให้สิทธิ์
คลิก "GCP Privacy Sandbox" และไปที่ "การให้สิทธิ์"
คุณจะใช้ "โทเค็นสำหรับผู้ถือ" เรียกใช้คำสั่งนี้และคัดลอกเอาต์พุตจากสภาพแวดล้อมเทอร์มินัล
gcloud auth print-identity-token
จากนั้นวางค่าโทเค็นนี้ลงใน "โทเค็น" ของแท็บการอนุมัติ Postman
1.8.3. ตั้งค่าสภาพแวดล้อม
ไปที่ "ดูสภาพแวดล้อมคร่าวๆ" ที่มุมบนขวาให้ทำดังนี้
คลิก "แก้ไข" และอัปเดต "มูลค่าปัจจุบัน" ของ "สภาพแวดล้อม" "ภูมิภาค" และ "cloud-function-id"
คุณสามารถเลือก "request-id" ได้ เว้นว่างไว้ ตอนนี้เราจะกรอกให้ภายหลัง สำหรับช่องอื่นๆ ให้ใช้ค่าจาก frontend_service_cloudfunction_url
ซึ่งส่งคืนจากการติดตั้งใช้งาน Terraform ใน Prerequisite 1.6 ที่สำเร็จ URL มีรูปแบบดังนี้ https://
2. 2. Codelab การทดสอบในเครื่อง
เวลาที่ใช้โดยประมาณ: <1 ชั่วโมง
คุณสามารถใช้เครื่องมือทดสอบในเครื่องเพื่อรวบรวมข้อมูลและสร้างรายงานสรุปโดยใช้รายงานการแก้ไขข้อบกพร่องที่ไม่เข้ารหัส ก่อนเริ่มต้น โปรดตรวจสอบว่าคุณได้ปฏิบัติตามข้อกำหนดเบื้องต้นทั้งหมดที่มีป้ายกำกับว่า "การทดสอบในพื้นที่" แล้ว
ขั้นตอนของ Codelab
ขั้นตอนที่ 2.1 ทริกเกอร์รายงาน: ทริกเกอร์การรายงานการรวมข้อมูลส่วนตัวเพื่อให้รวบรวมรายงานได้
ขั้นตอนที่ 2.2 สร้างรายงาน AVRO แก้ไขข้อบกพร่อง: แปลงรายงาน JSON ที่เก็บรวบรวมไว้เป็นรายงานในรูปแบบ AVRO ขั้นตอนนี้จะคล้ายกับเวลาที่ adTech รวบรวมรายงานจากอุปกรณ์ปลายทางการรายงาน API และแปลงรายงาน JSON เป็นรายงานที่มีรูปแบบ AVRO
ขั้นตอนที่ 2.3 ดึงข้อมูลคีย์ที่เก็บข้อมูล: คีย์ที่เก็บข้อมูลออกแบบโดย adTechs ใน Codelab นี้ เนื่องจากที่เก็บข้อมูลกำหนดไว้ล่วงหน้า ให้เรียกข้อมูลคีย์ที่เก็บข้อมูลตามที่ให้ไว้
ขั้นตอนที่ 2.4 สร้าง AVRO โดเมนเอาต์พุต: เมื่อเรียกข้อมูลคีย์ที่เก็บข้อมูลแล้ว ให้สร้างไฟล์ AVRO โดเมนเอาต์พุต
ขั้นตอนที่ 2.5 สร้างรายงานสรุป: ใช้เครื่องมือทดสอบในพื้นที่เพื่อให้สามารถสร้างรายงานสรุปในสภาพแวดล้อมในเครื่องได้
ขั้นตอนที่ 2.6 ตรวจสอบรายงานสรุป: ตรวจสอบรายงานสรุปที่สร้างโดยเครื่องมือทดสอบในพื้นที่
2.1 ทริกเกอร์รายงาน
หากต้องการทริกเกอร์รายงานการรวมข้อมูลส่วนตัว คุณสามารถใช้เว็บไซต์เดโม Privacy Sandbox (https://privacy-sandbox-demos-news.dev/?env=gcp) หรือเว็บไซต์ของคุณเอง (เช่น https://adtechexample.com) หากคุณใช้เว็บไซต์ของตนเองและยังลงทะเบียนไม่เสร็จสิ้นและ การรับรองและการเริ่มต้นใช้งานบริการรวบรวมข้อมูล คุณจะต้องใช้แฟล็ก Chrome และสวิตช์ CLI
สำหรับการสาธิตนี้ เราจะใช้เว็บไซต์เดโม Privacy Sandbox ตามลิงก์เพื่อไปยังเว็บไซต์ ดูรายงานได้ที่ chrome://private-aggregation-internals
รายงานที่ส่งไปยังปลายทาง {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage
จะอยู่ใน "เนื้อหารายงาน" ด้วย รายงานที่แสดงในหน้า Chrome Internals
คุณอาจเห็นรายงานจำนวนมากที่นี่ แต่สำหรับ Codelab นี้ ให้ใช้รายงานที่รวบรวมได้ซึ่งเกี่ยวกับ GCP โดยเฉพาะและสร้างขึ้นโดยปลายทางการแก้ไขข้อบกพร่อง "URL ของรายงาน" จะมี "/debug/" และ aggregation_coordinator_origin field
ของ "เนื้อความของรายงาน" จะมี URL นี้: https://publickeyservice.msmt.gcp.privacysandboxservices.com
2.2 สร้างรายงานแบบรวมการแก้ไขข้อบกพร่อง
คัดลอกรายงานที่อยู่ใน "เนื้อความของรายงาน" ของ chrome://private-aggregation-internals
และสร้างไฟล์ JSON ในโฟลเดอร์ privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar
(ในที่เก็บที่ดาวน์โหลดใน Prequisite 1.5)
ในตัวอย่างนี้ เราใช้ vim เนื่องจากเราใช้ Linux แต่คุณสามารถใช้เครื่องมือแก้ไขข้อความใดก็ได้
vim report.json
วางรายงานใน report.json
แล้วบันทึกไฟล์
เมื่อได้รับแล้ว ให้ใช้ aggregatable_report_converter.jar
ช่วยสร้างรายงานที่รวบรวมการแก้ไขข้อบกพร่องได้ การดำเนินการนี้จะสร้างรายงานที่รวบรวมได้ชื่อ report.avro
ในไดเรกทอรีปัจจุบันของคุณ
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3 ดึงข้อมูลคีย์ที่เก็บข้อมูลจากรายงาน
หากต้องการสร้างไฟล์ output_domain.avro
คุณต้องมีคีย์ที่เก็บข้อมูลที่ดึงมาจากรายงานได้
คีย์ที่เก็บข้อมูลออกแบบโดย adTech อย่างไรก็ตาม ในกรณีนี้ เว็บไซต์เดโม Privacy Sandbox จะสร้างคีย์ที่เก็บข้อมูล เนื่องจากการรวมข้อมูลส่วนตัวสำหรับเว็บไซต์นี้อยู่ในโหมดแก้ไขข้อบกพร่อง เราจึงใช้ debug_cleartext_payload
จาก "รายงานส่วนเนื้อหา" ได้ เพื่อรับคีย์ที่เก็บข้อมูล
คัดลอก debug_cleartext_payload
จากเนื้อความของรายงานได้เลย
เปิด goo.gle/ags-payload-decoder แล้ววาง debug_cleartext_payload
ใน "INPUT" แล้วคลิก "ถอดรหัส"
หน้านี้จะแสดงค่าทศนิยมของคีย์ที่เก็บข้อมูล ด้านล่างคือตัวอย่างคีย์ที่เก็บข้อมูล
2.4 สร้าง AVRO โดเมนเอาต์พุต
ตอนนี้เรามีคีย์ที่เก็บข้อมูลแล้ว เรามาสร้าง output_domain.avro
ในโฟลเดอร์เดียวกับที่เรากำลังทำอยู่กัน ตรวจสอบว่าคุณได้แทนที่คีย์ที่เก็บข้อมูลด้วยคีย์ที่เก็บข้อมูลที่ดึงมา
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
สคริปต์จะสร้างไฟล์ output_domain.avro
ในโฟลเดอร์ปัจจุบัน
2.5 สร้างรายงานสรุปโดยใช้เครื่องมือทดสอบในพื้นที่
เราจะใช้ LocalTestingTool_{version}.jar
ที่ดาวน์โหลดมาในข้อกำหนดเบื้องต้น 1.3 เพื่อสร้างรายงานสรุปโดยใช้คำสั่งด้านล่าง โปรดแทนที่ {version}
ด้วยเวอร์ชันที่คุณดาวน์โหลด อย่าลืมย้าย LocalTestingTool_{version}.jar
ไปยังไดเรกทอรีปัจจุบัน หรือเพิ่มเส้นทางแบบสัมพัทธ์เพื่ออ้างอิงตำแหน่งปัจจุบัน
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
คุณจะเห็นสิ่งที่คล้ายกับด้านล่างเมื่อเรียกใช้คำสั่งแล้ว ระบบจะสร้างรายงาน output.avro
เมื่อการดำเนินการนี้เสร็จสมบูรณ์
2.6 ดูรายงานสรุป
รายงานสรุปที่สร้างจะอยู่ในรูปแบบ AVRO คุณต้องแปลง AVRO เป็นรูปแบบ JSON จึงจะอ่านได้ โดยหลักการแล้ว adTech ควรเขียนโค้ดเพื่อแปลงรายงาน AVRO กลับไปเป็น JSON
เราจะใช้ aggregatable_report_converter.jar
เพื่อแปลงรายงาน AVRO กลับเป็น JSON
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
ซึ่งจะแสดงรายงานที่คล้ายกับด้านล่าง พร้อมด้วยรายงาน output.json
ที่สร้างขึ้นในไดเรกทอรีเดียวกัน
Codelab เสร็จสมบูรณ์
สรุป: คุณได้รวบรวมรายงานการแก้ไขข้อบกพร่อง สร้างไฟล์โดเมนเอาต์พุต และสร้างรายงานสรุปโดยใช้เครื่องมือทดสอบในเครื่องซึ่งจำลองลักษณะการรวมของบริการรวมข้อมูล
ขั้นตอนถัดไป: เมื่อคุณได้ทดลองใช้เครื่องมือทดสอบในพื้นที่แล้ว คุณก็ลองทำแบบฝึกหัดเดียวกันนี้กับการติดตั้งใช้งานบริการรวบรวมข้อมูลแบบเรียลไทม์ในสภาพแวดล้อมของคุณเองได้ ตรวจสอบข้อกำหนดเบื้องต้นอีกครั้งเพื่อให้แน่ใจว่าคุณได้ตั้งค่าทุกอย่างสำหรับ "บริการรวบรวมข้อมูล" แล้ว จากนั้นให้ดำเนินการต่อในขั้นตอนที่ 3
3. 3. Codelab ของบริการรวมข้อมูล
เวลาที่ใช้โดยประมาณ: 1 ชั่วโมง
ก่อนเริ่มต้น โปรดตรวจสอบว่าคุณได้ปฏิบัติตามข้อกำหนดเบื้องต้นทั้งหมดที่ติดป้ายกำกับว่า "บริการรวบรวมข้อมูล" แล้ว
ขั้นตอนของ Codelab
ขั้นตอนที่ 3.1 การสร้างอินพุตบริการการรวม: สร้างรายงานบริการรวมข้อมูลที่มีการรวมกลุ่มสำหรับบริการรวมข้อมูล
- ขั้นตอนที่ 3.1.1 รายงานทริกเกอร์
- ขั้นตอนที่ 3.1.2 รวบรวมรายงานที่รวบรวมได้
- ขั้นตอนที่ 3.1.3 แปลงรายงานเป็น AVRO
- ขั้นตอนที่ 3.1.4 สร้าง AVRO ของoutput_domain
- ขั้นตอนที่ 3.1.5 ย้ายรายงานไปยังที่เก็บข้อมูล Cloud Storage
ขั้นตอนที่ 3.2 การใช้บริการรวบรวมข้อมูล: ใช้ API บริการรวมข้อมูลเพื่อสร้างรายงานสรุปและตรวจสอบรายงานสรุป
- ขั้นตอนที่ 3.2.1 กำลังใช้ปลายทาง
createJob
เพื่อจัดกลุ่ม - ขั้นตอนที่ 3.2.2 กำลังใช้ปลายทาง
getJob
เพื่อเรียกข้อมูลสถานะแบบกลุ่ม - ขั้นตอนที่ 3.2.3 การตรวจสอบรายงานสรุป
3.1 การสร้างอินพุตบริการการรวม
ดำเนินการต่อเพื่อสร้างรายงาน AVRO สำหรับการจัดกลุ่มตามบริการ คำสั่ง Shell ในขั้นตอนเหล่านี้สามารถเรียกใช้ภายใน Cloud Shell ของ GCP ได้ (ตราบเท่าที่มีการโคลนทรัพยากร Dependency จากข้อกำหนดเบื้องต้นลงในสภาพแวดล้อม Cloud Shell) หรือในสภาพแวดล้อมการดำเนินการภายใน
3.1.1. รายงานทริกเกอร์
ตามลิงก์เพื่อไปยังเว็บไซต์ ดูรายงานได้ที่ chrome://private-aggregation-internals
รายงานที่ส่งไปยังปลายทาง {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage
จะอยู่ใน "เนื้อหารายงาน" ด้วย รายงานที่แสดงในหน้า Chrome Internals
คุณอาจเห็นรายงานจำนวนมากที่นี่ แต่สำหรับ Codelab นี้ ให้ใช้รายงานที่รวบรวมได้ซึ่งเกี่ยวกับ GCP โดยเฉพาะและสร้างขึ้นโดยปลายทางการแก้ไขข้อบกพร่อง "URL ของรายงาน" จะมี "/debug/" และ aggregation_coordinator_origin field
ของ "เนื้อความของรายงาน" จะมี URL นี้: https://publickeyservice.msmt.gcp.privacysandboxservices.com
3.1.2. รวบรวมรายงานที่รวบรวมได้
รวบรวมรายงานที่รวบรวมได้จากปลายทาง .well-known ของ API ที่เกี่ยวข้อง
- การรวมแบบส่วนตัว:
{reporting-origin}/.well-known/private-aggregation/report-shared-storage
- การรายงานการระบุแหล่งที่มา - รายงานสรุป:
{reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution
สำหรับ Codelab นี้ เราจะทำการรวบรวมรายงานด้วยตนเอง ในเวอร์ชันที่ใช้งานจริง คาดว่า AdTech จะรวบรวมและแปลงรายงานแบบเป็นโปรแกรม
ลองคัดลอกรายงาน JSON ใน "เนื้อความของรายงาน" กันเลย จาก chrome://private-aggregation-internals
ในตัวอย่างนี้ เราใช้ vim เนื่องจากเราใช้ Linux แต่คุณสามารถใช้เครื่องมือแก้ไขข้อความใดก็ได้
vim report.json
วางรายงานใน report.json
แล้วบันทึกไฟล์
3.1.3. แปลงรายงานเป็น AVRO
รายงานที่ได้รับจากปลายทาง .well-known
อยู่ในรูปแบบ JSON และจำเป็นต้องแปลงเป็นรูปแบบรายงาน AVRO เมื่อมีรายงาน JSON ให้ไปยังตําแหน่งที่จัดเก็บ report.json
และใช้ aggregatable_report_converter.jar
เพื่อช่วยสร้างรายงานที่รวบรวมข้อมูลการแก้ไขข้อบกพร่องได้ การดำเนินการนี้จะสร้างรายงานที่รวบรวมได้ชื่อ report.avro
ในไดเรกทอรีปัจจุบันของคุณ
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
3.1.4. สร้าง AVRO ของoutput_domain
หากต้องการสร้างไฟล์ output_domain.avro
คุณต้องมีคีย์ที่เก็บข้อมูลที่ดึงมาจากรายงานได้
คีย์ที่เก็บข้อมูลออกแบบโดย adTech อย่างไรก็ตาม ในกรณีนี้ เว็บไซต์เดโม Privacy Sandbox จะสร้างคีย์ที่เก็บข้อมูล เนื่องจากการรวมข้อมูลส่วนตัวสำหรับเว็บไซต์นี้อยู่ในโหมดแก้ไขข้อบกพร่อง เราจึงใช้ debug_cleartext_payload
จาก "รายงานส่วนเนื้อหา" ได้ เพื่อรับคีย์ที่เก็บข้อมูล
คัดลอก debug_cleartext_payload
จากเนื้อความของรายงานได้เลย
เปิด goo.gle/ags-payload-decoder แล้ววาง debug_cleartext_payload
ใน "INPUT" แล้วคลิก "ถอดรหัส"
หน้านี้จะแสดงค่าทศนิยมของคีย์ที่เก็บข้อมูล ด้านล่างคือตัวอย่างคีย์ที่เก็บข้อมูล
ตอนนี้เรามีคีย์ที่เก็บข้อมูลแล้ว เรามาสร้าง output_domain.avro
ในโฟลเดอร์เดียวกับที่เรากำลังทำอยู่กัน ตรวจสอบว่าคุณได้แทนที่คีย์ที่เก็บข้อมูลด้วยคีย์ที่เก็บข้อมูลที่ดึงมา
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
สคริปต์จะสร้างไฟล์ output_domain.avro
ในโฟลเดอร์ปัจจุบัน
3.1.5. ย้ายรายงานไปยังที่เก็บข้อมูล Cloud Storage
เมื่อสร้างรายงาน AVRO และโดเมนเอาต์พุตแล้ว ให้ดำเนินการต่อเพื่อย้ายโดเมนรายงานและโดเมนเอาต์พุตไปยังที่เก็บข้อมูลใน Cloud Storage (ซึ่งคุณระบุไว้ในข้อกำหนดเบื้องต้น 1.6)
หากคุณมีการตั้งค่า gcloud CLI ในสภาพแวดล้อมในเครื่องของคุณ ให้ใช้คำสั่งด้านล่างเพื่อคัดลอกไฟล์ไปยังโฟลเดอร์ที่เกี่ยวข้อง
gcloud storage cp report.avro gs://<bucket_name>/reports/
gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/
หรือจะอัปโหลดไฟล์ลงในที่เก็บข้อมูลด้วยตนเองก็ได้ สร้างโฟลเดอร์ชื่อ "รายงาน" แล้วอัปโหลดไฟล์ report.avro
จากที่นั่น สร้างโฟลเดอร์ชื่อ "output_domains" แล้วอัปโหลดไฟล์ output_domain.avro
จากที่นั่น
3.2 การใช้บริการรวมข้อมูล
การเรียกคืนในข้อกำหนดเบื้องต้น 1.8 ว่าคุณได้เลือก cURL หรือ Postman สำหรับการส่งคำขอ API ไปยังปลายทางบริการรวบรวมข้อมูล ด้านล่างนี้คุณจะพบคำแนะนำเกี่ยวกับทั้ง 2 ตัวเลือก
หากงานของคุณล้มเหลวเนื่องจากข้อผิดพลาด โปรดดูเอกสารการแก้ปัญหาใน GitHub สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีดำเนินการต่อ
3.2.1. กำลังใช้ปลายทาง createJob
เพื่อจัดกลุ่ม
ใช้คำแนะนำของ cURL หรือ Postman ด้านล่างเพื่อสร้างงาน
cURL
ใน "เทอร์มินัล" ให้สร้างไฟล์เนื้อหาของคำขอ (body.json
) แล้ววางไฟล์ด้านล่าง ดังนั้นอย่าลืมอัปเดตค่าตัวยึดตำแหน่ง ดูข้อมูลเพิ่มเติมเกี่ยวกับความหมายของแต่ละช่องได้ในเอกสารประกอบของ 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"
}
}
ดำเนินการตามคำขอด้านล่าง แทนที่ตัวยึดตำแหน่งใน URL ของคำขอ cURL ด้วยค่าจาก frontend_service_cloudfunction_url
ซึ่งเอาต์พุตหลังจากการติดตั้งใช้งาน Terraform ใน Prequisite 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
คุณควรได้รับการตอบกลับ HTTP 202 เมื่อบริการรวบรวมข้อมูลยอมรับคำขอแล้ว ส่วนโค้ดตอบกลับที่เป็นไปได้อื่นๆ จะมีการระบุไว้ในข้อกำหนดของ API
Postman
สำหรับปลายทาง createJob
คุณต้องระบุเนื้อหาคำขอเพื่อให้บริการการรวมมีตำแหน่งที่ตั้งและชื่อไฟล์ของรายงานที่รวบรวมได้ โดเมนเอาต์พุต และรายงานสรุป
ไปที่ "เนื้อความ" ของคำขอ createJob
ให้ทำดังนี้
แทนที่ตัวยึดตำแหน่งภายใน JSON ที่ให้ไว้ ดูข้อมูลเพิ่มเติมเกี่ยวกับช่องเหล่านี้และความหมายของช่องเหล่านั้นได้ในเอกสารประกอบเกี่ยวกับ 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"
}
}
"ส่ง" คำขอ API createJob
:
โค้ดตอบกลับจะอยู่ในครึ่งล่างของหน้า
คุณควรได้รับการตอบกลับ HTTP 202 เมื่อบริการรวบรวมข้อมูลยอมรับคำขอแล้ว ส่วนโค้ดตอบกลับที่เป็นไปได้อื่นๆ จะมีการระบุไว้ในข้อกำหนดของ API
3.2.2 กำลังใช้ปลายทาง getJob
เพื่อเรียกข้อมูลสถานะแบบกลุ่ม
ใช้คำแนะนำของ cURL หรือ Postman ด้านล่างนี้เพื่อสมัครงาน
cURL
ดำเนินการตามคำขอด้านล่างในเทอร์มินัล แทนที่ตัวยึดตำแหน่งใน URL ด้วยค่าจาก frontend_service_cloudfunction_url
ซึ่งเป็น URL เดียวกันกับที่คุณใช้สำหรับคำขอ createJob
สำหรับ "job_request_id" ให้ใช้ค่าจากงานที่คุณสร้างด้วยปลายทาง 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>
ผลลัพธ์ควรแสดงสถานะคำของานด้วยสถานะ HTTP 200 คำขอ "เนื้อความ" มีข้อมูลที่จำเป็น เช่น job_status
, return_message
และ error_messages
(หากงานมีข้อผิดพลาด)
Postman
หากต้องการตรวจสอบสถานะของคำของาน คุณสามารถใช้ปลายทาง getJob
ได้ ใน "พระราชวัง" ของคำขอ getJob
ให้อัปเดตค่า job_request_id
เป็น job_request_id
ที่ส่งมาในคำขอ createJob
"ส่ง" คำขอ getJob
:
ผลลัพธ์ควรแสดงสถานะคำของานด้วยสถานะ HTTP 200 คำขอ "เนื้อความ" มีข้อมูลที่จำเป็น เช่น job_status
, return_message
และ error_messages
(หากงานมีข้อผิดพลาด)
3.2.3 การตรวจสอบรายงานสรุป
เมื่อได้รับรายงานสรุปในที่เก็บข้อมูล Cloud Storage เอาต์พุตแล้ว คุณจะดาวน์โหลดรายงานนี้ลงในสภาพแวดล้อมภายในได้ รายงานสรุปอยู่ในรูปแบบ AAVRO และแปลงกลับเป็น JSON ได้ คุณใช้ aggregatable_report_converter.jar
เพื่ออ่านรายงานโดยใช้คำสั่งด้านล่างได้
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
การดำเนินการนี้จะแสดงผลไฟล์ JSON ของค่ารวมของคีย์ที่เก็บข้อมูลแต่ละคีย์ซึ่งมีลักษณะคล้ายคลึงกับด้านล่าง
หากคำขอ createJob
มี debug_run
เป็นจริง คุณจะได้รับรายงานสรุปในโฟลเดอร์แก้ไขข้อบกพร่องที่อยู่ใน output_data_blob_prefix
รายงานอยู่ในรูปแบบ AVRO และแปลงได้โดยใช้คำสั่งข้างต้นเป็นไฟล์ JSON
รายงานจะประกอบด้วยคีย์ที่เก็บข้อมูล เมตริกที่ไม่มีสัญญาณรบกวน และเสียงที่เพิ่มลงในเมตริกที่ไม่มีสัญญาณรบกวนเพื่อสร้างรายงานสรุป รายงานจะคล้ายกับรายการด้านล่างนี้
คำอธิบายประกอบยังมี "in_reports" ด้วย และ/หรือ "in_domain" ซึ่งหมายความว่า
- in_reports - คีย์ที่เก็บข้อมูลจะอยู่ในรายงานที่รวบรวมได้
- in_domain - คีย์ที่เก็บข้อมูลมีอยู่ในไฟล์ AVRO ของ exit_domain
Codelab เสร็จสมบูรณ์
สรุป: คุณได้ทำให้บริการรวมใช้งานได้ในสภาพแวดล้อมระบบคลาวด์ของคุณเอง รวบรวมรายงานแก้ไขข้อบกพร่อง สร้างไฟล์โดเมนเอาต์พุต จัดเก็บไฟล์เหล่านี้ในที่เก็บข้อมูล Cloud Storage และเรียกใช้งานได้สำเร็จ
ขั้นตอนถัดไป: ใช้บริการรวมข้อมูลในสภาพแวดล้อมของคุณต่อไป หรือลบทรัพยากรระบบคลาวด์ที่คุณเพิ่งสร้างตามวิธีการล้างข้อมูลในขั้นตอนที่ 4
4. 4. การจัดระเบียบ
หากต้องการลบทรัพยากรที่สร้างขึ้นสำหรับบริการรวมข้อมูลผ่าน Terraform ให้ใช้คำสั่งทำลายในโฟลเดอร์ adtech_setup
และ dev
(หรือสภาพแวดล้อมอื่น) ดังนี้
$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy
หากต้องการลบที่เก็บข้อมูล Cloud Storage ที่มีรายงานที่รวบรวมได้และรายงานสรุปไว้ ให้ทำดังนี้
$ gcloud storage buckets delete gs://my-bucket
คุณอาจเลือกที่จะเปลี่ยนการตั้งค่าคุกกี้ของ Chrome จากข้อกำหนดเบื้องต้น 1.2 กลับไปเป็นสถานะก่อนหน้าได้
5. 5. ภาคผนวก
ตัวอย่างไฟล์ adtech_setup.auto.tfvars
/**
* 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>"
ตัวอย่างไฟล์ dev.auto.tfvars
/**
* 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