ทำงานร่วมกับบริการรวบรวมใน Google Cloud Platform (GCP)

1. 1. สิ่งที่ต้องดำเนินการก่อน

เวลาที่ใช้โดยประมาณ: 1-2 ชั่วโมง

การดำเนินการ Codelab นี้มี 2 โหมด ได้แก่ การทดสอบในพื้นที่หรือบริการรวบรวมข้อมูล โหมดการทดสอบภายในต้องใช้เครื่องภายในและเบราว์เซอร์ Chrome (ไม่มีการสร้าง/ใช้งานทรัพยากร Google Cloud) โหมดบริการรวมข้อมูลกำหนดให้มีการติดตั้งใช้งานบริการรวบรวมข้อมูลบน Google Cloud อย่างเต็มรูปแบบ

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

1.1 ดำเนินการลงทะเบียนและเอกสารรับรอง (บริการรวม)

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

1.2 เปิดใช้ Privacy Sandbox API (การทดสอบและบริการรวมข้อมูลในพื้นที่)

เนื่องจากเราจะใช้ Privacy Sandbox เราจึงขอแนะนําให้คุณเปิดใช้ Privacy Sandbox Ads API

ไปที่ chrome://flags/#privacy-sandbox-ads-apis ในเบราว์เซอร์ แล้วเปิดใช้ Privacy Sandbox API

การเปิดใช้ Privacy Sandbox API

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

ในเบราว์เซอร์ ให้ไปที่ chrome://settings/cookies ตรวจสอบว่าไม่ได้บล็อกคุกกี้ของบุคคลที่สามอยู่ คุณอาจเห็นตัวเลือกที่แตกต่างออกไปในเมนูการตั้งค่านี้ ทั้งนี้ขึ้นอยู่กับเวอร์ชันของ Chrome แต่การกำหนดค่าที่ยอมรับได้มีดังนี้

  • "บล็อกคุกกี้ของบุคคลที่สามทั้งหมด" = ปิดใช้อยู่
  • "บล็อกคุกกี้ของบุคคลที่สาม" = ปิดใช้อยู่
  • "บล็อกคุกกี้ของบุคคลที่สามในโหมดไม่ระบุตัวตน" = เปิดใช้งาน

การเปิดใช้งานคุกกี้

1.3 ดาวน์โหลดเครื่องมือทดสอบในพื้นที่ (การทดสอบในพื้นที่)

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

ดาวน์โหลดเครื่องมือทดสอบในเครื่องได้ที่ที่เก็บข้อมูล JAR สำหรับ Cloud Function ใน GitHub ควรตั้งชื่อว่า LocalTestingTool_{version}.jar

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

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

ตรวจสอบเวอร์ชัน Java

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

1.5. ดาวน์โหลด aggregatable_report_converter (การทดสอบในพื้นที่และบริการรวบรวมข้อมูล)

คุณดาวน์โหลดสำเนา aggregatable_report_converter ได้จากที่เก็บ GitHub แบบ Privacy Sandbox ของ Privacy Sandbox

1.6. ตั้งค่าสภาพแวดล้อม GCP (บริการรวบรวมข้อมูล)

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

1.6.1. การทำให้ใช้งานได้

ทำตามวิธีการทำให้ใช้งานได้ใน GitHub เพื่อตั้งค่า gcloud CLI, ดาวน์โหลดไบนารีและโมดูลของ Terraform และสร้างทรัพยากร GCP สำหรับบริการ Aggregation

ขั้นตอนสำคัญในวิธีการทำให้ใช้งานได้มีดังนี้

  1. ตั้งค่า CLI และ Terraform "gcloud" ในสภาพแวดล้อมของคุณ
  2. สร้างที่เก็บข้อมูล Cloud Storage เพื่อจัดเก็บสถานะ Terraform
  3. ดาวน์โหลดทรัพยากร Dependency
  4. อัปเดต adtech_setup.auto.tfvars และเรียกใช้ Terraform ของ adtech_setup โปรดดูไฟล์ adtech_setup.auto.tfvars ในภาคผนวก
  5. อัปเดต dev.auto.tfvars โดยสวมบทบาทเป็นบัญชีบริการให้ใช้งานได้ และเรียกใช้ dev Terraform โปรดดูไฟล์ dev.auto.tfvars ในภาคผนวก
  6. เมื่อการติดตั้งใช้งานเสร็จสมบูรณ์ ให้บันทึก frontend_service_cloudfunction_url จากเอาต์พุต Terraform ซึ่งจำเป็นต้องใช้เพื่อส่งคำขอไปยังบริการรวมข้อมูลในขั้นตอนถัดไป

1.6.2. ที่เก็บข้อมูลรายงาน

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

gcloud storage buckets create gs://<bucket-name> --location=<location>

1.7 การเริ่มต้นใช้งานบริการรวมข้อมูลแบบสมบูรณ์ (บริการรวบรวมข้อมูล)

บริการรวมข้อมูลต้องมีการเริ่มต้นใช้งานกับผู้ประสานงานจึงจะใช้บริการได้ กรอกแบบฟอร์มเริ่มต้นใช้งานบริการรวบรวมข้อมูลโดยระบุเว็บไซต์การรายงานและข้อมูลอื่นๆ แล้วเลือก "Google Cloud" แล้วป้อนที่อยู่ของบัญชีบริการ บัญชีบริการนี้สร้างขึ้นในข้อกำหนดเบื้องต้นก่อนหน้า (1.6. ตั้งค่าสภาพแวดล้อม GCP) (คำแนะนำ: หากคุณใช้ชื่อเริ่มต้นที่ระบุ บัญชีบริการนี้จะขึ้นต้นด้วย "worker-sa@")

การเริ่มต้นใช้งานจะใช้เวลาไม่เกิน 2 สัปดาห์

1.8 กำหนดวิธีเรียกใช้ปลายทาง API (บริการรวบรวมข้อมูล)

Codelab นี้มี 2 ตัวเลือกในการเรียกใช้ปลายทาง API ของ Aggregation Service ได้แก่ cURL และ Postman โดย cURL เป็นวิธีที่ง่ายและรวดเร็วในการเรียกปลายทาง API จากเทอร์มินัล เนื่องจากต้องใช้การตั้งค่าเพียงเล็กน้อยและไม่ต้องใช้ซอฟต์แวร์เพิ่มเติม อย่างไรก็ตาม หากไม่ต้องการใช้ cURL คุณสามารถใช้ Postman เพื่อดำเนินการและบันทึกคำขอ API ไว้ใช้ในอนาคตแทนได้

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

1.8.1. ตั้งค่าพื้นที่ทำงาน

ลงชื่อสมัครใช้บัญชี Postman เมื่อลงชื่อสมัครใช้แล้ว ระบบจะสร้างพื้นที่ทำงานให้คุณโดยอัตโนมัติ

Workspace สำหรับบุรุษไปรษณีย์

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

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

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

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

ปุ่มนำเข้า

การดำเนินการนี้จะสร้างคอลเล็กชัน "Privacy Sandbox ของ GCP" สำหรับคุณพร้อมกับคำขอ 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://--frontend-service--uc.a.run.app

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) หากใช้เว็บไซต์ของตนเองและยังลงทะเบียนและรับรองและการเริ่มต้นใช้งานบริการรวบรวมข้อมูลไม่เสร็จสิ้น คุณจะต้องใช้สวิตช์ Flag และ CLI ของ Chrome

สำหรับการสาธิตนี้ เราจะใช้เว็บไซต์เดโม Privacy Sandbox ทำตามลิงก์เพื่อไปยังเว็บไซต์ จากนั้นคุณสามารถดูรายงานได้ที่ chrome://private-aggregation-internals

หน้าภายในของ Chrome

รายงานที่ส่งไปยังปลายทาง {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

รายงานการแก้ไขข้อบกพร่อง GCP

2.2 สร้างรายงานแบบรวมการแก้ไขข้อบกพร่อง

คัดลอกรายงานที่พบใน "เนื้อความของรายงาน" ของ chrome://private-aggregation-internals และสร้างไฟล์ JSON ในโฟลเดอร์ privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (ในที่เก็บที่ดาวน์โหลดใน "ข้อกำหนดเบื้องต้น 1.5)

ในตัวอย่างนี้ เราใช้ vim เนื่องจากเราใช้ Linux แต่คุณสามารถใช้เครื่องมือแก้ไขข้อความใดก็ได้

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 ดึงข้อมูลคีย์ที่เก็บข้อมูลจากรายงาน

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

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

คัดลอก debug_cleartext_payload จากเนื้อความของรายงานได้เลย

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

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

ปุ่มถอดรหัส

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

คีย์ที่เก็บข้อมูล

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 เมื่อการดำเนินการนี้เสร็จสมบูรณ์

เอาต์พุต 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 ที่สร้างขึ้นในไดเรกทอรีเดียวกัน

JSON เอาต์พุต

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

หน้าภายในของ Chrome

รายงานที่ส่งไปยังปลายทาง {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

รายงานการแก้ไขข้อบกพร่อง GCP

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 แล้วบันทึกไฟล์

รายงาน 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" แล้วคลิก "Decode"

ปุ่มถอดรหัส

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

คีย์ที่เก็บข้อมูล

ตอนนี้เรามีคีย์ที่เก็บข้อมูลแล้ว เรามาสร้าง 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 ตัวเลือกด้านล่าง

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>",
    "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

บุรุษไปรษณีย์

สำหรับปลายทาง 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>",
    "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 (หากงานมีข้อผิดพลาด)

บุรุษไปรษณีย์

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

รหัสคำของาน

"ส่ง" คำขอ getJob:

ปุ่มส่ง

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

JSON ของการตอบกลับ

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

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