ทำงานร่วมกับบริการรวบรวมใน 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 เปิดใช้ 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

หากยังไม่ได้ติดตั้ง คุณจะดาวน์โหลดและติดตั้งได้จากเว็บไซต์ 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

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

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

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

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

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

สำหรับการสาธิตนี้ เราจะใช้เว็บไซต์เดโม 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 (ในที่เก็บที่ดาวน์โหลดใน Prequisite 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" แล้วคลิก "ถอดรหัส"

ปุ่มถอดรหัส

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

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

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 เอาต์พุต

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

หน้าภายในของ 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" แล้วคลิก "ถอดรหัส"

ปุ่มถอดรหัส

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

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

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

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

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