इस गाइड में बताया गया है कि एन्क्रिप्ट (सुरक्षित) की गई मेज़रमेंट रिपोर्ट, विज्ञापन टेक्नोलॉजी से जुड़ी सेवा देने वाली कंपनियों को कैसे डिलीवर की जाती हैं. Chrome ब्राउज़र और क्लाइंट, इन रिपोर्ट को तय किए गए रिपोर्टिंग एंडपॉइंट पर भेजते हैं. यहां विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म को एग्रीगेट की जा सकने वाली रिपोर्ट मिलती हैं और उन्हें सेव किया जाता है. ये एंडपॉइंट, प्लैटफ़ॉर्म पर होस्ट किए जाते हैं. ये एंडपॉइंट, विज्ञापन टेक्नोलॉजी से जुड़ी सेवा देने वाली कंपनियों को Attribution Reporting API या Private Aggregation API का इस्तेमाल करके, उन्हें ऐक्सेस करने की सुविधा देते हैं. ये एंडपॉइंट, विज्ञापन टेक्नोलॉजी से जुड़ी सेवा देने वाली कंपनियों के रिपोर्टिंग ऑरिजिन में .well-known यूआरएल पर मौजूद होते हैं.
यहां एग्रीगेशन सेवा की प्रोसेस के बारे में बताया गया है. इस प्रोसेस में, एग्रीगेट की जा सकने वाली रिपोर्ट को पाने और सेव करने की जानकारी शामिल है:
- ट्रिगर होने पर, ब्राउज़र ऐसी रिपोर्ट भेजता है जिन्हें इकट्ठा किया जा सकता है. इन रिपोर्ट में, क्रॉस-साइट और कन्वर्ज़न डेटा, दोनों की जानकारी होती है.
- ब्राउज़र, एन्क्रिप्ट (सुरक्षित) की गई रिपोर्ट को विज्ञापन टेक्नोलॉजी रिपोर्टिंग डोमेन में मौजूद
.well-knownयूआरएल पर डिलीवर करता है. - सिस्टम, प्रोसेस करने के लिए रिपोर्ट के बैच को एग्रीगेशन सेवा को फ़ॉरवर्ड करता है.
- एग्रीगेशन सेवा, आंकड़ों के हिसाब से रिपोर्ट की खास जानकारी देती है.
- एग्रीगेशन सेवा, उपयोगकर्ता की निजता को बेहतर बनाने के लिए, खास जानकारी वाले डेटा में ग़ैर-ज़रूरी आवाज़ें जोड़ती है.
- सिस्टम, विज्ञापन टेक्नोलॉजी कंपनी को विश्लेषण और मेज़रमेंट के लिए रिपोर्ट उपलब्ध कराता है.
नीचे दी गई टेबल में, निजी एग्रीगेशन एपीआई और Attribution Reporting API के लिए डीबग और लाइव एंडपॉइंट के बारे में बताया गया है:
| एपीआई | एंडपॉइंट | ब्यौरा |
|---|---|---|
| Private Aggregation API |
|
|
| Attribution Reporting API |
|
|
रिपोर्टिंग ऑरिजिन को POST कॉल के ज़रिए JSON रिपोर्ट मिलती हैं. इसके बाद, सिस्टम इन रिपोर्ट को Avro फ़ॉर्मैट में बदल देता है और उन्हें क्लाउड स्टोरेज में डाल देता है. बैच प्रोसेसिंग के बाद, सिस्टम खास जानकारी देने के लिए Avro रिपोर्ट को एग्रीगेशन सेवा को भेजता है.
जब Avro रिपोर्ट का कोई बैच प्रोसेस करने के लिए तैयार हो जाता है, तब विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म, एग्रीगेशन सेवा के लिए एग्रीगेशन जॉब का अनुरोध ट्रिगर करते हैं. विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म के क्लाउड एनवायरमेंट में होस्ट की जाने वाली यह सेवा, स्टोरेज की एक ही जगह से ज़रूरी Avro रिपोर्ट को वापस लाती है. सुरक्षा के मकसद से, एग्रीगेशन सेवा को मंज़ूरी वाली कंटेनर इमेज का इस्तेमाल करने के लिए कॉन्फ़िगर किया जाना चाहिए. उपलब्ध कंटेनर इमेज के लिए, Privacy Sandbox/एग्रीगेशन-सेवा GitHub रिपॉज़िटरी देखें.
यहां हर एपीआई से मिलने वाली रिपोर्ट के उदाहरण दिए गए हैं:
- Private Aggregation API की रिपोर्ट का उदाहरण:
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
"payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
} ],
"debug_key": "1234",
"shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
}
- Attribution Reporting API रिपोर्ट का उदाहरण
{
"aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
"aggregation_service_payloads": [ {
"key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
"payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
} ],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
"source_debug_key": "123456789",
"trigger_debug_key": "123456789"
}
JSON को Avro रिपोर्ट में बदलना
एक साथ कई रिपोर्ट भेजने के लिए, उन रिपोर्ट का डेटा Apache Avro डेटा सीरियलाइज़ेशन फ़ॉर्मैट में होना चाहिए. Avro रिपोर्ट बनाने के लिए, आपको AVSC स्कीमा का इस्तेमाल करना होगा. AVSC स्कीमा फ़ाइल, Avro रिकॉर्ड के स्ट्रक्चर और डेटा टाइप के बारे में बताती है. AVSC स्कीमा का उदाहरण देखने के लिए, avrodoc/schemata GitHub डेटा स्टोर करने की जगह में example.avsc फ़ाइल देखें.
आपको JavaScript कोड का उदाहरण, privacysandbox/aggregation-service GitHub रिपॉज़िटरी में मौजूद इकट्ठा की जा सकने वाली रिपोर्ट को इकट्ठा और एक साथ इकट्ठा करने पेज के रिपोर्ट इकट्ठा करना, बदलाव करना, और एक साथ इकट्ठा करना सेक्शन में मिलेगा.
आपके पास सभी रिपोर्ट को एक ही Avro फ़ाइल में सेव करने या उन्हें कई फ़ाइलों में बांटने का विकल्प होता है. AVRO फ़ाइलों के साइज़ की कोई सीमा नहीं है. हालांकि, आम तौर पर सबसे अच्छी परफ़ॉर्मेंस तब मिलती है, जब फ़ाइलों की संख्या आपके क्लाउड इंस्टेंस में मौजूद सीपीयू की संख्या से लेकर 1,000 तक हो.
यहां दिए गए कोड के उदाहरण में, एग्रीगेट की जा सकने वाली रिपोर्ट के लिए Avro स्कीमा दिखाया गया है. रिपोर्ट फ़ील्ड में payload, key_id, और shared_info शामिल हैं.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| पैरामीटर | टाइप | ब्यौरा |
|---|---|---|
payload |
बाइट |
लाइव या प्रोडक्शन रिपोर्ट के लिए, payload को base64 से डिकोड करके बाइट कलेक्शन में बदलना होगा.
|
debug_cleartext_payload |
बाइट |
डीबग रिपोर्ट के लिए, पेलोड को base64 से डिकोड करके debug_cleartext_payload से बाइट कलेक्शन में बदला जाना चाहिए.
|
key_id |
स्ट्रिंग | यह रिपोर्ट में मिली key_id स्ट्रिंग है. key_id एक 128-बिट यूनिवर्सल यूनीक आइडेंटिफ़ायर है. |
shared_info |
स्ट्रिंग | यह रिपोर्ट के shared_info फ़ील्ड में मौजूद, बिना बदलाव वाली और बिना छेड़छाड़ वाली स्ट्रिंग है. |
JSON रिपोर्ट का एक उदाहरण यहां दिया गया है:
{
"aggregation_coordinator_identifier": "aws-cloud",
"aggregation_service_payloads": [{
"debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX",
"key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
"payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq"
}],
"debug_key": "1234",
"shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}
डोमेन फ़ाइल की जानकारी
एग्रीगेशन सेवा की मदद से खास जानकारी वाली रिपोर्ट जनरेट करने के लिए, एग्रीगेट की जा सकने वाली रिपोर्ट (Avro में बदली गई JSON रिपोर्ट) और उससे जुड़ी डोमेन फ़ाइल की ज़रूरत होती है. सिस्टम, एग्रीगेट की जा सकने वाली रिपोर्ट से पहले से एलान की गई कुंजियों को निकालता है और उन्हें आउटपुट डोमेन में खास जानकारी वाली रिपोर्ट में शामिल करता है. आपको इन अहम एग्रीगेशन कुंजियों के बारे में जानकारी, एट्रिब्यूशन रिपोर्टिंग के लिए एग्रीगेशन कुंजियों को समझना और निजी एग्रीगेशन एपीआई के बुनियादी सिद्धांतों के एग्रीगेशन कुंजी सेक्शन में मिलेगी. आउटपुट डोमेन में bucket फ़ील्ड भी शामिल होता है, जो आपकी बकेट की मुख्य वैल्यू दिखाता है.
डोमेन फ़ाइल, Avro फ़ॉर्मैट में होनी चाहिए. इसके लिए, नीचे दिए गए स्कीमा का इस्तेमाल करें:
{
"type": "record",
"name": "AggregationBucket",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
}
]
}
बकेट की कुंजी
आउटपुट डोमेन में मौजूद बकेट कुंजी को हेक्स बाइट स्ट्रिंग के तौर पर दिखाया जाना चाहिए.
उदाहरण के लिए:
अगर बकेट की कुंजी की वैल्यू दशमलव वाली 1369 है, तो:
1369 को हैक्साडेसिमल में बदलें: 559
हैक्साडेसिमल स्ट्रिंग "559" को बाइट स्ट्रिंग में बदलें.
इसके बाद, बकेट की कुंजी की इस बाइट स्ट्रिंग को आउटपुट डोमेन Avro स्कीमा में शामिल किया जाना चाहिए.
ध्यान देने वाली ज़रूरी बातें:
डेटा टाइप: Avro स्कीमा में बकेट बटन को बाइट टाइप के तौर पर तय किया जाना चाहिए, ताकि हेक्स बाइट स्ट्रिंग को दिखाया जा सके.
कन्वर्ज़न: दशमलव से हेक्स और फिर बाइट स्ट्रिंग में कन्वर्ज़न करने के लिए, Python या Java का इस्तेमाल किया जा सकता है.
इस तरीके से यह पक्का किया जाता है कि बकेट की कुंजी का फ़ॉर्मैट सही है और वह आउटपुट डोमेन के Avro स्कीमा में मौजूद डेटा टाइप के साथ काम करती है.
एक साथ कई रिपोर्ट जनरेट करना
निजता बजट और एक साथ कई टास्क करने की रणनीतियों के बारे में जानकारी पाने के लिए, एक साथ कई टास्क करने की रणनीतियों का दस्तावेज़ देखें. ध्यान दें कि एग्रीगेट की जा सकने वाली रिपोर्ट के scheduled_report_time और बैच के चलने की तारीख के बीच, MAX_REPORT_AGE की सीमा (फ़िलहाल 90 दिन) होती है.
खास जानकारी वाली रिपोर्ट
बैच करने के बाद, एग्रीगेशन सेवा results.avsc स्कीमा का इस्तेमाल करके, Avro फ़ॉर्मैट में खास जानकारी वाली रिपोर्ट बनाती है.
जॉब पूरा होने के बाद, खास जानकारी वाली रिपोर्ट को output_data_bucket_name बकेट में output_data_blob_prefix में सेव किया जाता है, जैसा कि createJob अनुरोध में बताया गया है.
debug_run चालू होने पर, एग्रीगेशन सेवा के उन बैच के लिए दो रिपोर्ट बनाई जाती हैं: समरी रिपोर्ट और डीबग समरी रिपोर्ट. डीबग की खास जानकारी वाली रिपोर्ट, output_data_blob_prefix/debug फ़ोल्डर में मौजूद होती है. डीबग की खास जानकारी वाली रिपोर्ट में, debug_results.avsc स्कीमा का इस्तेमाल किया जाता है.
खास जानकारी और डीबग रिपोर्ट, दोनों का नाम [output_data_blob_prefix]-1-of-1.avro है. अगर आपका output_data_blob_prefix summary/summary.avro है, तो रिपोर्ट summary-1-of-1.avro नाम वाले समरी फ़ोल्डर में मौजूद होगी.
उदाहरण: results.avsc
यहां results.avsc के लिए Avro स्कीमा का उदाहरण दिया गया है:
{
"type": "record",
"name": "AggregatedFact",
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
},
{
"name": "metric",
"type": "long",
"doc": "The metric associated with the bucket"
}
]
}
Avro स्कीमा के उदाहरण में, AggregatedFact नाम का एक रिकॉर्ड बताया गया है.
उदाहरण: debug_results.avsc
यहां debug_results.avsc के लिए Avro स्कीमा का उदाहरण दिया गया है:
{
"type": "record",
"name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
"fields": [
{
"name": "bucket",
"type": "bytes",
"doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
},
{
"name": "unnoised_metric",
"type": "long",
"doc": "The raw metric for the bucket."
},
{
"name": "noise",
"type": "long",
"doc": "The noise applied to the metric in the regular result."
}
{
"name":"annotations",
"type": {
"type": "array",
"items": {
"type":"enum",
"name":"bucket_tags",
"symbols":["in_domain","in_reports"]
}
}
]
}
बदलने के बाद, आपकी खास जानकारी वाली रिपोर्ट, results.json उदाहरण जैसी दिखती है. debug_run चालू होने पर, डीबग की खास जानकारी वाली रिपोर्ट, debug_results.jsonउदाहरण की तरह ही दिखती है.
Avro रिपोर्ट फ़ॉर्मैट
एग्रीगेशन सेवा से मिली Avro रिपोर्ट, आम तौर पर एक ही फ़ॉर्मैट में होती हैं. Avro रिपोर्ट फ़ॉर्मैट में ये फ़ील्ड शामिल होते हैं:
bucket: डेटा इकट्ठा करने के लिए यूनीक आइडेंटिफ़ायर (उदाहरण के लिए, "\u0005Y").
मेट्रिक: उससे जुड़ी बकेट के लिए एग्रीगेट की गई वैल्यू. निजता को बेहतर बनाने के लिए, इस वैल्यू में अक्सर नॉइज़ जोड़ा जाता है.
उदाहरण के लिए:
{
"bucket": "\u0005Y",
"metric": 26308
}
उदाहरण: debug_results.json
एग्रीगेशन सेवा से मिली Avro रिपोर्ट को डीबग करने के लिए, यहां दिए गए debug_results.json उदाहरण का इस्तेमाल किया जा सकता है. इन रिपोर्ट में बकेट की, unnoised_metric (गड़बड़ी जोड़ने से पहले बकेट की खास जानकारी), और उस मेट्रिक में जोड़ी गई गड़बड़ी शामिल होती है.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
एनोटेशन में ये वैल्यू भी शामिल होती हैं:
in_reports: अलग-अलग डेटा को मिलाकर तैयार की गई रिपोर्ट में मौजूद बकेट कुंजीin_domain:output_domainAvro फ़ाइल में मौजूद बकेट की कुंजी