इस पेज का अनुवाद Cloud Translation API से किया गया है.

Google Cloud Platform (GCP) पर एग्रीगेशन सेवा का इस्तेमाल करना

1. 1. ज़रूरी शर्तें

पूरा होने में लगने वाला अनुमानित समय: एक से दो घंटे

कोडलैब का यह मॉड्यूल दो तरीकों से किया जा सकता है: लोकल टेस्टिंग या एग्रीगेशन सेवा. लोकल टेस्टिंग मोड का इस्तेमाल करने के लिए, लोकल मशीन और Chrome ब्राउज़र की ज़रूरत होती है. Google Cloud के संसाधन बनाने या इस्तेमाल करने की ज़रूरत नहीं होती. एग्रीगेशन सेवा मोड का इस्तेमाल करने के लिए, Google Cloud पर एग्रीगेशन सेवा का पूरी तरह से डिप्लॉयमेंट ज़रूरी है.

इस कोडलैब को किसी भी मोड में करने के लिए, कुछ ज़रूरी शर्तें पूरी करनी होंगी. हर ज़रूरी शर्त को यह तय किया जाता है कि लोकल टेस्टिंग या एग्रीगेशन सेवा के लिए ज़रूरी है या नहीं.

1.1. रजिस्ट्रेशन और प्रमाणित करने की प्रक्रिया पूरी करें (एग्रीगेशन सेवा)

Privacy Sandbox API का इस्तेमाल करने के लिए, पक्का करें कि आपने Chrome और Android, दोनों के लिए रजिस्ट्रेशन और पुष्टि करने की प्रक्रिया पूरी कर ली हो.

1.2. Privacy Sandbox API (लोकल टेस्टिंग और एग्रीगेशन सर्विस) चालू करें

हम प्राइवसी सैंडबॉक्स का इस्तेमाल करेंगे. इसलिए, हमारा सुझाव है कि आप प्राइवसी सैंडबॉक्स के Ads के एपीआई चालू करें.

अपने ब्राउज़र पर, chrome://flags/#privacy-sandbox-ads-apis पर जाएं और Privacy Sandbox APIs को चालू करें.

प्राइवसी सैंडबॉक्स एपीआई चालू करना

यह भी पक्का करें कि तीसरे पक्ष की आपकी कुकी चालू हैं.

अपने ब्राउज़र में, chrome://settings/cookies पर जाएं. पक्का करें कि तीसरे पक्ष की कुकी ब्लॉक न की जा रही हों. आपके Chrome वर्शन के आधार पर, आपको इस सेटिंग मेन्यू में अलग-अलग विकल्प दिख सकते हैं. हालांकि, ये विकल्प स्वीकार किए जाते हैं:

"तीसरे-पक्ष की सभी कुकी ब्लॉक करें" = बंद है
"तीसरे-पक्ष की कुकी ब्लॉक करें" = बंद है
"गुप्त मोड में तीसरे पक्ष की कुकी ब्लॉक करें" = चालू है

कुकी चालू की जा रही हैं

1.3. लोकल टेस्टिंग टूल डाउनलोड करें (लोकल टेस्टिंग)

लोकल टेस्टिंग के लिए, लोकल टेस्टिंग टूल डाउनलोड करना होगा. यह टूल, एन्क्रिप्ट (सुरक्षित) नहीं की गई डीबग रिपोर्ट से खास जानकारी वाली रिपोर्ट जनरेट करेगा.

लोकल टेस्टिंग टूल, GitHub में Cloud Function JAR Archives में डाउनलोड किया जा सकता है. इसका नाम LocalTestingTool_{version}.jar होना चाहिए.

1.4. पक्का करें कि JAVA JRE इंस्टॉल किया गया हो (लोकल टेस्टिंग ऐंड एग्रीगेशन सर्विस)

"Terminal" खोलें और java --version का इस्तेमाल करके देखें कि आपकी मशीन में Java या OpenJDK इंस्टॉल है या नहीं.

Java का वर्शन जांचें

अगर इसे इंस्टॉल नहीं किया गया है, तो Java साइट या openJDK साइट से इसे डाउनलोड और इंस्टॉल किया जा सकता है.

1.5. aggregatable_report_converter (लोकल टेस्टिंग और एग्रीगेशन सेवा) डाउनलोड करें

Privacy Sandbox के डेमो GitHub रिपॉज़िटरी से aggregatable_report_converter की कॉपी डाउनलोड की जा सकती है.

1.6. GCP एनवायरमेंट (एग्रीगेशन सेवा) सेट अप करना

एग्रीगेशन सेवा के लिए ट्रस्टेड एक्ज़ीक्यूशन एनवायरमेंट का इस्तेमाल करना ज़रूरी है. यह क्लाउड प्रोवाइडर का इस्तेमाल करता है. इस कोडलैब में, एग्रीगेशन सेवा को GCP में डिप्लॉय किया जाएगा. हालांकि, इसमें AWS भी काम करती है.

1.6.1. डिप्लॉयमेंट

gcloud CLI सेटअप करने के लिए, GitHub में डिप्लॉयमेंट के निर्देशों का पालन करें. Teraform बाइनरी और मॉड्यूल डाउनलोड करें, और एग्रीगेशन सेवा के लिए GCP संसाधन बनाएं.

डिप्लॉयमेंट निर्देशों के मुख्य चरण:

अपने एनवायरमेंट में "gcloud" सीएलआई और टेराफ़ॉर्म सेट अप करें.
टेराफ़ॉर्म स्टेट को सेव करने के लिए, Cloud Storage बकेट बनाएं.
डिपेंडेंसी डाउनलोड करें.
adtech_setup.auto.tfvars को अपडेट करें और adtech_setup टेराफ़ॉर्म चलाएं. adtech_setup.auto.tfvars फ़ाइल के उदाहरण के लिए, अपेंडिक्स देखें.
dev.auto.tfvars को अपडेट करें, डिप्लॉय सेवा खाते की नकल करें, और dev टेराफ़ॉर्म को चलाएं. dev.auto.tfvars फ़ाइल के उदाहरण के लिए, अपेंडिक्स देखें.
डिप्लॉयमेंट पूरा होने के बाद, Terraform आउटपुट से frontend_service_cloudfunction_url को कैप्चर करें. इसकी ज़रूरत, बाद के चरणों में एग्रीगेशन सेवा को अनुरोध करने के लिए होगी.

1.6.2. रिपोर्ट बकेट

प्रोजेक्ट सेट अप होने के बाद, इस कोडलैब से इकट्ठा की जा सकने वाली रिपोर्ट और खास जानकारी वाली रिपोर्ट को सेव करने के लिए, Cloud Storage में एक बकेट बनानी होगी. बकेट बनाने के लिए, यह gcloud कमांड का उदाहरण है. प्लेसहोल्डर को अपनी पसंद का नाम और स्थान से बदलें.

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

1.7. एग्रीगेशन सेवा को शामिल करने की प्रक्रिया पूरी करें (एग्रीगेशन सेवा)

एग्रीगेशन सेवा का इस्तेमाल करने के लिए, कोऑर्डिनेटर से संपर्क करना ज़रूरी होता है. एग्रीगेशन सेवा को शामिल करने के लिए फ़ॉर्म भरें. इसके लिए, अपनी रिपोर्टिंग साइट और अन्य जानकारी दें. इसके बाद, "Google Cloud" चुनें और अपने सेवा खाते का पता डालें. यह सेवा खाता पिछली शर्त (1.6. GCP एनवायरमेंट सेट अप करें). (जानकारी: अगर यहां दिए गए डिफ़ॉल्ट नामों का इस्तेमाल किया जाता है, तो यह सेवा खाता "worker-sa@" से शुरू होगा).

शामिल होने की प्रोसेस को पूरा होने में दो हफ़्ते लग सकते हैं.

1.8. एपीआई एंडपॉइंट को कॉल करने का तरीका (एग्रीगेशन सेवा) तय करें

यह कोडलैब, एग्रीगेशन सर्विस एपीआई एंडपॉइंट को कॉल करने के दो विकल्प देता है: cURL और पोस्टमैन. cURL आपके टर्मिनल से एपीआई एंडपॉइंट को कॉल करने का तेज़ और आसान तरीका है. ऐसा इसलिए, क्योंकि इसके लिए बहुत कम सेटअप करना पड़ता है और इसके लिए कोई अतिरिक्त सॉफ़्टवेयर नहीं चाहिए. हालांकि, अगर आपको cURL का इस्तेमाल नहीं करना है, तो एपीआई अनुरोधों को बाद में इस्तेमाल करने के लिए, Postman का इस्तेमाल करके एक्ज़ीक्यूट किया जा सकता है.

सेक्शन 3.2 में. एग्रीगेशन सेवा का इस्तेमाल करते हैं, तो आपको दोनों विकल्पों का इस्तेमाल करने के बारे में पूरी जानकारी मिलेगी. अब उनकी झलक देखी जा सकती है, ताकि यह पता चल सके कि आपको कौनसा तरीका अपनाना है. यदि आप पोस्टमैन का चयन करते हैं, तो नीचे दिया गया शुरुआती सेटअप करें.

1.8.1. फ़ाइल फ़ोल्डर सेट अप करें

पोस्टमैन खाते के लिए साइन अप करें. साइन अप करने के बाद, आपके लिए फ़ाइल फ़ोल्डर अपने-आप बन जाता है.

पोस्टमैन वर्कस्पेस

अगर आपके लिए कोई फ़ाइल फ़ोल्डर नहीं बनाया गया है, तो सबसे ऊपर मौजूद नेविगेशन आइटम "Workspace" पर जाएं और "फ़ाइल फ़ोल्डर बनाएं" चुनें.

"खाली फ़ाइल फ़ोल्डर" चुनें. इसके बाद, आगे क्लिक करें और इसे "GCP निजता सैंडबॉक्स" नाम दें. "निजी" चुनें और "बनाएं" पर क्लिक करें.

पहले से कॉन्फ़िगर की गई, Workspace का JSON कॉन्फ़िगरेशन और ग्लोबल एनवायरमेंट फ़ाइलें डाउनलोड करें.

"इंपोर्ट करें" बटन की मदद से, दोनों JSON फ़ाइलों को "मेरा फ़ाइल फ़ोल्डर" में इंपोर्ट करें.

आयात बटन

इससे createJob और getJob एचटीटीपी अनुरोधों के साथ-साथ, आपके लिए "GCP प्राइवसी सैंडबॉक्स" कलेक्शन बनेगा.

1.8.2. अनुमति देने की सुविधा सेट अप करें

"GCP प्राइवसी सैंडबॉक्स" कलेक्शन पर क्लिक करें और "अनुमति" टैब पर जाएं.

'अनुमति दें' बटन

आपको "बियरर टोकन" तरीके का इस्तेमाल करना होगा. अपने Terminal एनवायरमेंट से, इस कमांड को चलाएं और आउटपुट को कॉपी करें.

gcloud auth print-identity-token

इसके बाद, इस टोकन वैल्यू को Postman के ऑथराइज़ेशन टैब में मौजूद "Token" फ़ील्ड में चिपकाएं:

टोकन फ़ील्ड

1.8.3. एनवायरमेंट सेट अप करें

सबसे ऊपर दाएं कोने में, "परिवेश का क्विक लुक" पर जाएं:

एनवायरमेंट बटन

"बदलाव करें" पर क्लिक करें और "एनवायरमेंट", "क्षेत्र", और "cloud-Function-id" की "मौजूदा वैल्यू" अपडेट करें:

मौजूदा वैल्यू सेट करना

फ़िलहाल, "request-id" को खाली छोड़ा जा सकता है, क्योंकि हम इसे बाद में भर देंगे. अन्य फ़ील्ड के लिए, frontend_service_cloudfunction_url से मिली वैल्यू का इस्तेमाल करें. यह वैल्यू, Prequisite 1.6 में, टेरेस पर डिप्लॉयमेंट के पूरा होने के बाद मिली है. यूआरएल इस फ़ॉर्मैट में है: https://--frontend-service--uc.a.run.app

2. 2. लोकल टेस्टिंग कोडलैब (कोड बनाना सीखना)

पूरा होने में लगने वाला अनुमानित समय: <एक घंटा

एग्रीगेशन करने के लिए, अपनी मशीन पर लोकल टेस्टिंग टूल का इस्तेमाल किया जा सकता है. साथ ही, एन्क्रिप्ट (सुरक्षित) नहीं की गई डीबग रिपोर्ट की मदद से खास जानकारी वाली रिपोर्ट जनरेट की जा सकती हैं. शुरू करने से पहले, पक्का करें कि आपने "स्थानीय टेस्टिंग" के लेबल वाली सभी ज़रूरी शर्तें पूरी कर ली हैं.

कोडलैब (कोड बनाना सीखना) के चरण

चरण 2.1. ट्रिगर रिपोर्ट: रिपोर्ट इकट्ठा करने के लिए, निजी एग्रीगेशन रिपोर्टिंग को ट्रिगर करें.

चरण 2.2. डीबग AVRO रिपोर्ट बनाएं: इकट्ठा की गई JSON रिपोर्ट को AVRO फ़ॉर्मैट वाली रिपोर्ट में बदलें. यह चरण उसी तरह होगा जैसे adTechs, एपीआई रिपोर्टिंग एंडपॉइंट से रिपोर्ट इकट्ठा करते हैं और JSON रिपोर्ट को AVRO फ़ॉर्मैट वाली रिपोर्ट में बदलते हैं.

चरण 2.3. बकेट कुंजियां वापस पाएं: बकेट कुंजियां, adTech ने डिज़ाइन की हैं. इस कोडलैब में, बकेट पहले से तय होती है. इसलिए, बकेट की कुंजियों को बताए गए तरीके से वापस पाएं.

चरण 2.4. आउटपुट डोमेन AVRO फ़ाइल बनाएं: बकेट कुंजियां वापस पाने के बाद, आउटपुट डोमेन AVRO फ़ाइल बनाएं.

चरण 2.5. समरी रिपोर्ट बनाएं: लोकल एनवायरमेंट में समरी रिपोर्ट बनाने के लिए लोकल टेस्टिंग टूल का इस्तेमाल करें.

चरण 2.6. खास जानकारी वाली रिपोर्ट देखें: लोकल टेस्टिंग टूल से बनाई गई खास जानकारी वाली रिपोर्ट देखें.

2.1. ट्रिगर रिपोर्ट

निजी एग्रीगेशन रिपोर्ट को ट्रिगर करने के लिए, Privacy Sandbox की डेमो साइट (https://privacy-sandbox-demos-news.dev/?env=gcp) या अपनी साइट (जैसे, https://adtechexample.com) का इस्तेमाल किया जा सकता है. अगर अपनी साइट का इस्तेमाल किया जा रहा है और आपने रजिस्ट्रेशन और प्रमाणित करने और एग्रीगेशन सेवा को शामिल करने की प्रक्रिया पूरी नहीं की है, तो आपको Chrome फ़्लैग और सीएलआई स्विच का इस्तेमाल करना होगा.

इस डेमो के लिए, हम प्राइवसी सैंडबॉक्स की डेमो साइट का इस्तेमाल करेंगे. साइट पर जाने के लिए लिंक पर जाएं. इसके बाद, chrome://private-aggregation-internals पर जाकर रिपोर्ट देखी जा सकती हैं:

Chrome का इंटरनल पेज

{reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage एंडपॉइंट पर भेजी जाने वाली रिपोर्ट, Chrome के इंटरनल पेज पर दिखाई गई रिपोर्ट के "रिपोर्ट के मुख्य हिस्से" में भी मौजूद होती है.

आपको यहां कई रिपोर्ट दिख सकती हैं. हालांकि, इस कोडलैब के लिए, ऐसी एग्रीगेट की जा सकने वाली रिपोर्ट इस्तेमाल करें जो खास तौर पर GCP के लिए बनाई गई हो और डीबग एंडपॉइंट से जनरेट की गई हो. "रिपोर्ट यूआरएल" में "/debug/" होगा और "रिपोर्ट के मुख्य हिस्से" के aggregation_coordinator_origin field में यह यूआरएल शामिल होगा: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

GCP डीबग रिपोर्ट

ध्यान दें: अगर आपको ऊपर दिखाई गई डीबग रिपोर्ट जैसी कोई रिपोर्ट नहीं दिखती है, तो Privacy Sandbox के डेमो पेज को रीफ़्रेश करें. इसके बाद, Chrome के इंटरनल पेज को रीफ़्रेश करें. आपको ज़्यादा रिपोर्ट दिखेंगी. इनमें डीबग एंडपॉइंट से जनरेट की गई रिपोर्ट भी शामिल है. अगर नहीं, तो दोबारा जांच लें कि तीसरे पक्ष की कुकी चालू हैं या नहीं.

2.2. डीबग की जाने वाली एग्रीगेट करने वाली रिपोर्ट बनाएं

chrome://private-aggregation-internals के "रिपोर्ट के मुख्य हिस्से" में मिली रिपोर्ट को कॉपी करें और privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar फ़ोल्डर में JSON फ़ाइल बनाएं. यह फ़ाइल, 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. स्थानीय परीक्षण टूल का उपयोग करके सारांश रिपोर्ट बनाएं

हम नीचे दिए गए निर्देश का इस्तेमाल करके, खास जानकारी वाली रिपोर्ट बनाने के लिए, ज़रूरी शर्त 1.3 में डाउनलोड किए गए LocalTestingTool_{version}.jar का इस्तेमाल करेंगे. {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 फ़ॉर्मैट में बदलना होगा. आम तौर पर, AVRO रिपोर्ट को वापस JSON में बदलने के लिए, adTech को कोड लिखना चाहिए.

हम AVRO रिपोर्ट को वापस JSON में बदलने के लिए, aggregatable_report_converter.jar का इस्तेमाल करेंगे.

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

इससे, नीचे दी गई रिपोर्ट से मिलती-जुलती रिपोर्ट मिलती है. ये दोनों, एक ही डायरेक्ट्री में बनाई गई output.json रिपोर्ट के साथ हैं.

आउटपुट JSON

3. 3. एग्रीगेशन सेवा कोडलैब (कोड बनाना सीखना)

पूरा होने में लगने वाला अनुमानित समय: 1 घंटा

शुरू करने से पहले, पक्का करें कि आपने "एग्रीगेशन सेवा" के लेबल वाली सभी ज़रूरी शर्तें पूरी कर ली हों.

कोडलैब (कोड बनाना सीखना) के चरण

चरण 3.1. एग्रीगेशन सेवा का इनपुट बनाना: एग्रीगेशन सेवा की ऐसी रिपोर्ट बनाएं जिन्हें एग्रीगेशन सेवा के लिए बैच में भेजा गया हो.

चरण 3.1.1. ट्रिगर रिपोर्ट
चरण 3.1.2. इकट्ठा की जा सकने वाली रिपोर्ट इकट्ठा करें
चरण 3.1.3. रिपोर्ट को AVRO में बदलें
चरण 3.1.4. आउटपुट_डोमेन AVRO बनाएं
चरण 3.1.5. रिपोर्ट को Cloud Storage बकेट में ले जाना

चरण 3.2. एग्रीगेशन सेवा का इस्तेमाल: खास जानकारी वाली रिपोर्ट बनाने और खास जानकारी वाली रिपोर्ट की समीक्षा करने के लिए, एग्रीगेशन सेवा एपीआई का इस्तेमाल करें.

चरण 3.2.1. बैच बनाने के लिए, createJob एंडपॉइंट का इस्तेमाल किया जा रहा है
चरण 3.2.2. बैच का स्टेटस वापस पाने के लिए, getJob एंडपॉइंट का इस्तेमाल करना
चरण 3.2.3. खास जानकारी वाली रिपोर्ट की समीक्षा करना

3.1. एग्रीगेशन सेवा का इनपुट बनाना

एग्रीगेशन सेवा में बैच बनाने के लिए, AVRO रिपोर्ट बनाएं. इन चरणों में शेल कमांड, GCP के Cloud Shell में या लोकल एक्ज़ीक्यूशन एनवायरमेंट में चलाए जा सकते हैं. हालांकि, ऐसा सिर्फ़ तब किया जा सकता है, जब ज़रूरी शर्तों की डिपेंडेंसी को आपके Cloud Shell एनवायरमेंट में क्लोन किया गया हो.

3.1.1. ट्रिगर रिपोर्ट

साइट पर जाने के लिए लिंक पर जाएं. इसके बाद, chrome://private-aggregation-internals पर जाकर रिपोर्ट देखी जा सकती हैं:

Chrome का इंटरनल पेज

GCP डीबग रिपोर्ट

3.1.2. इकट्ठा की जा सकने वाली रिपोर्ट इकट्ठा करें

अपने एपीआई के .well-known एंडपॉइंट की मदद से, एग्रीगेट की जा सकने वाली रिपोर्ट इकट्ठा करें.

निजी एग्रीगेशन: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
एट्रिब्यूशन रिपोर्टिंग - खास जानकारी वाली रिपोर्ट: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

इस कोडलैब के लिए, हम मैन्युअल तरीके से रिपोर्ट इकट्ठा करते हैं. प्रोडक्शन में, adTech को प्रोग्राम के हिसाब से रिपोर्ट इकट्ठा करने और उन्हें बदलने की उम्मीद होती है.

चलिए, chrome://private-aggregation-internals से "रिपोर्ट के मुख्य हिस्से" में JSON रिपोर्ट कॉपी करते हैं.

इस उदाहरण में, हम 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 बनाएं

रिपोर्ट के मुख्य हिस्से से debug_cleartext_payload को कॉपी करें.

क्लीयरटेक्स्ट पेलोड डीबग करें

डिकोड करने वाला बटन

बकेट कुंजी

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 सीएलआई सेटअप किया है, तो संबंधित फ़ोल्डर में फ़ाइलों को कॉपी करने के लिए नीचे दिए गए निर्देशों का इस्तेमाल करें.

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

अगर ऐसा नहीं है, तो फ़ाइलों को मैन्युअल तरीके से अपने बकेट में अपलोड करें. "रिपोर्ट" नाम का फ़ोल्डर बनाएं और उसमें report.avro फ़ाइल अपलोड करें. "आउटपुट_डोमेन" नाम का फ़ोल्डर बनाएं और output_domain.avro फ़ाइल को वहां अपलोड करें.

3.2. एग्रीगेशन सेवा का इस्तेमाल करने वाले उपयोगकर्ता

ज़रूरी 1.8 में याद करें कि आपने एग्रीगेशन सेवा के एंडपॉइंट को एपीआई अनुरोध करने के लिए, cURL या Postman में से कोई एक चुना था. नीचे आपको दोनों विकल्पों के लिए निर्देश मिलेंगे.

3.2.1. बैच बनाने के लिए, `createJob` एंडपॉइंट का इस्तेमाल किया जा रहा है

जॉब बनाने के लिए, नीचे दिए गए cURL या Postman निर्देशों का इस्तेमाल करें.

cURL

अपने "Terminal" में, अनुरोध के मुख्य हिस्से वाली फ़ाइल (body.json) बनाएं और उसे यहां चिपकाएं. प्लेसहोल्डर वैल्यू अपडेट करना न भूलें. हर फ़ील्ड के बारे में ज़्यादा जानने के लिए, यह एपीआई दस्तावेज़ देखें.

{
  "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"
  }
}

नीचे दिए गए अनुरोध पर कार्रवाई करें. cURL के अनुरोध के यूआरएल में मौजूद प्लेसहोल्डर को frontend_service_cloudfunction_url की वैल्यू से बदलें. यह वैल्यू, ज़रूरी शर्त 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

एग्रीगेशन सेवा के अनुरोध को स्वीकार करने के बाद, आपको एचटीटीपी 202 रिस्पॉन्स मिलेगा. अन्य संभावित रिस्पॉन्स कोड एपीआई की खास जानकारी में दस्तावेज़ दिए गए हैं.

डाकिया

createJob एंडपॉइंट में, एग्रीगेशन सेवा को एग्रीगेट की जा सकने वाली रिपोर्ट, आउटपुट डोमेन, और खास जानकारी वाली रिपोर्ट की जगह और फ़ाइल नामों के साथ एग्रीगेशन सेवा देने की ज़रूरत होती है.

createJob अनुरोध के "मुख्य हिस्सा" टैब पर जाएं:

मुख्य हिस्सा टैब

दिए गए JSON में प्लेसहोल्डर बदलें. इन फ़ील्ड और इनमें मौजूद चीज़ों के बारे में ज़्यादा जानने के लिए, एपीआई से जुड़े दस्तावेज़ देखें.

{
  "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"
  }
}

createJob एपीआई अनुरोध को "भेजें":

रिस्पॉन्स कोड, पेज के निचले आधे हिस्से में देखा जा सकता है:

जवाब कोड

3.2.2. बैच का स्टेटस वापस पाने के लिए, `getJob` एंडपॉइंट का इस्तेमाल करना

नौकरी पाने के लिए, यहां दिए गए cURL या Postman निर्देशों का पालन करें.

cURL

अपने Terminal में, नीचे दिया गया अनुरोध लागू करें. यूआरएल में प्लेसहोल्डर को frontend_service_cloudfunction_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>

नतीजे में, आपके जॉब अनुरोध की स्थिति और एचटीटीपी स्टेटस 200 दिखेगा. "मुख्य भाग" के अनुरोध में job_status, return_message और error_messages (अगर काम में गड़बड़ी हुई है) जैसी ज़रूरी जानकारी शामिल है.

ध्यान दें: इस कोडलैब के लिए, हम जिस रिपोर्ट का इस्तेमाल कर रहे हैं वह Privacy Sandbox की डेमो साइट के रिपोर्टिंग ऑरिजिन से जुड़ी है. हालांकि, GCP एनवायरमेंट में एग्रीगेशन सेवा का इस्तेमाल करने पर, आपने अपना रिपोर्टिंग ऑरिजिन खुद उपलब्ध कराया था. यह रिपोर्ट, शामिल की गई साइट से अलग किसी दूसरी साइट से आई है. इसलिए, आपको Return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR के साथ जवाब मिल सकता है. ऐसा होना सामान्य है और इसे अनदेखा किया जा सकता है.

डाकिया

जॉब अनुरोध की स्थिति देखने के लिए, getJob एंडपॉइंट का इस्तेमाल किया जा सकता है. getJob अनुरोध के "पैराम" सेक्शन में, job_request_id वैल्यू को createJob अनुरोध में भेजे गए job_request_id पर अपडेट करें.

नौकरी का अनुरोध आईडी

getJob अनुरोध "भेजें":

भेजें बटन

JSON में जवाब दिया गया

3.2.3. खास जानकारी वाली रिपोर्ट की समीक्षा करना

अपने आउटपुट Cloud Storage बकेट में खास जानकारी वाली रिपोर्ट मिलने के बाद, इसे अपने लोकल एनवायरमेंट में डाउनलोड किया जा सकता है. खास जानकारी वाली रिपोर्ट AVRO फ़ॉर्मैट में होती हैं और इन्हें वापस 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 - बकेट कुंजी, आउटपुट_domain AVRO फ़ाइल के अंदर उपलब्ध होती है.

4. 4. मिटाना

Turaform के ज़रिए एग्रीगेशन सेवा के लिए बनाए गए संसाधनों को मिटाने के लिए, 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

Google Cloud Platform (GCP) पर एग्रीगेशन सेवा का इस्तेमाल करना

1. 1. ज़रूरी शर्तें

1.1. रजिस्ट्रेशन और प्रमाणित करने की प्रक्रिया पूरी करें (एग्रीगेशन सेवा)

1.2. Privacy Sandbox API (लोकल टेस्टिंग और एग्रीगेशन सर्विस) चालू करें

1.3. लोकल टेस्टिंग टूल डाउनलोड करें (लोकल टेस्टिंग)

1.4. पक्का करें कि JAVA JRE इंस्टॉल किया गया हो (लोकल टेस्टिंग ऐंड एग्रीगेशन सर्विस)

1.5. aggregatable_report_converter (लोकल टेस्टिंग और एग्रीगेशन सेवा) डाउनलोड करें

1.6. GCP एनवायरमेंट (एग्रीगेशन सेवा) सेट अप करना

1.6.1. डिप्लॉयमेंट

1.6.2. रिपोर्ट बकेट

1.7. एग्रीगेशन सेवा को शामिल करने की प्रक्रिया पूरी करें (एग्रीगेशन सेवा)

1.8. एपीआई एंडपॉइंट को कॉल करने का तरीका (एग्रीगेशन सेवा) तय करें

1.8.1. फ़ाइल फ़ोल्डर सेट अप करें

1.8.2. अनुमति देने की सुविधा सेट अप करें

1.8.3. एनवायरमेंट सेट अप करें

2. 2. लोकल टेस्टिंग कोडलैब (कोड बनाना सीखना)

कोडलैब (कोड बनाना सीखना) के चरण

2.1. ट्रिगर रिपोर्ट

2.2. डीबग की जाने वाली एग्रीगेट करने वाली रिपोर्ट बनाएं

2.3. रिपोर्ट से बकेट कुंजी फिर से पाएं

2.4. आउटपुट डोमेन AVRO बनाएं

2.5. स्थानीय परीक्षण टूल का उपयोग करके सारांश रिपोर्ट बनाएं

2.6. खास जानकारी वाली रिपोर्ट की समीक्षा करना

3. 3. एग्रीगेशन सेवा कोडलैब (कोड बनाना सीखना)

कोडलैब (कोड बनाना सीखना) के चरण

3.1. एग्रीगेशन सेवा का इनपुट बनाना

3.1.1. ट्रिगर रिपोर्ट

3.1.2. इकट्ठा की जा सकने वाली रिपोर्ट इकट्ठा करें

3.1.3. रिपोर्ट को AVRO में बदलें

3.1.4. आउटपुट_डोमेन AVRO बनाएं

3.1.5. रिपोर्ट को Cloud Storage बकेट में ले जाना

3.2. एग्रीगेशन सेवा का इस्तेमाल करने वाले उपयोगकर्ता

3.2.1. बैच बनाने के लिए, createJob एंडपॉइंट का इस्तेमाल किया जा रहा है

cURL

डाकिया

3.2.2. बैच का स्टेटस वापस पाने के लिए, getJob एंडपॉइंट का इस्तेमाल करना

cURL

डाकिया

3.2.3. खास जानकारी वाली रिपोर्ट की समीक्षा करना

4. 4. मिटाना

5. 5. अन्य जानकारी

adtech_setup.auto.tfvars फ़ाइल का उदाहरण

dev.auto.tfvars फ़ाइल का उदाहरण

3.2.1. बैच बनाने के लिए, `createJob` एंडपॉइंट का इस्तेमाल किया जा रहा है

3.2.2. बैच का स्टेटस वापस पाने के लिए, `getJob` एंडपॉइंट का इस्तेमाल करना

`adtech_setup.auto.tfvars` फ़ाइल का उदाहरण

`dev.auto.tfvars` फ़ाइल का उदाहरण