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

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

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

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

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

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

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

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

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

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

अपने ब्राउज़र में, chrome://settings/adPrivacy पर जाएं और विज्ञापन देखने वाले की निजता बनाए रखने से जुड़े सभी एपीआई चालू करें.

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

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 की कॉपी डाउनलोड की जा सकती है. GitHub रिपॉज़िटरी में IntelliJ या Eclipse के इस्तेमाल के बारे में बताया गया है. हालांकि, इनमें से किसी का भी इस्तेमाल करना ज़रूरी नहीं है. अगर इन टूल का इस्तेमाल नहीं किया जाता है, तो JAR फ़ाइल को अपने लोकल एनवायरमेंट में डाउनलोड करें.

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

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

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.7. एग्रीगेशन सेवा को शामिल करने की प्रक्रिया पूरी करें (एग्रीगेशन सेवा)

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

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

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

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

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

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

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

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

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

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

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

दोनों JSON फ़ाइलों को "मेरा फ़ाइल फ़ोल्डर" में इंपोर्ट करना "इंपोर्ट करें" के ज़रिए बटन.

आयात बटन

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

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

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

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

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

gcloud auth print-identity-token

इसके बाद, इस टोकन की वैल्यू को "टोकन" में चिपकाएं पोस्टमैन प्राधिकरण टैब की फ़ील्ड:

टोकन फ़ील्ड

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

"परिवेश का क्विक लुक" पर जाएं क्लिक करें:

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

"बदलाव करें" पर क्लिक करें और "मौजूदा वैल्यू" को अपडेट करें "Environment", "region", और "cloud-Function-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 एंडपॉइंट पर भेजी जाने वाली रिपोर्ट, "रिपोर्ट के मुख्य हिस्से" में भी मिलती है रिपोर्ट दिखती हैं.

आपको यहां कई रिपोर्ट दिख सकती हैं. हालांकि, इस कोडलैब के लिए, ऐसी एग्रीगेट की जा सकने वाली रिपोर्ट इस्तेमाल करें जो खास तौर पर 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. 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 को प्रोग्राम के हिसाब से रिपोर्ट इकट्ठा करने और उन्हें बदलने की उम्मीद होती है.

चलिए, "रिपोर्ट के मुख्य हिस्से" में 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 बनाएं

रिपोर्ट के मुख्य हिस्से से 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_domains" नाम का फ़ोल्डर बनाएं और output_domain.avro फ़ाइल को वहां अपलोड करें.

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

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

अगर किसी गड़बड़ी की वजह से आपका काम पूरा नहीं होता है, तो आगे बढ़ने के बारे में ज़्यादा जानकारी के लिए, GitHub में समस्या हल करने वाला हमारा दस्तावेज़ देखें.

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

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

cURL

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

ध्यान दें: अगर मुमकिन हो, तो हमारा सुझाव है कि आप attribution_report_to के बजाय, job_parameters में बताए गए reporting_site का इस्तेमाल करें. एग्रीगेशन सर्विस एपीआई इंटरफ़ेस के अगले मेजर वर्शन अपग्रेड में, attribution_report_to फ़ील्ड की पहचान बंद कर दी गई है. (और पढ़ें) पैरामीटर reporting_site का इस्तेमाल किसी डिप्लॉय किए गए डोमेन में कई ऑरिजिन के लिए किया जा सकता है, जबकि attribution_report_to एक ही सर्वर ऑरिजिन के साथ काम करता है. reporting_site के लिए स्ट्रिंग की मान्य वैल्यू https://example-dsp-host.com हो सकती है. इसमें https://dspp-a.example-dsp-host.com या https://dspp-b.example-dsp-host.com जैसे रिपोर्टिंग ऑरिजिन शामिल होंगे. वहीं दूसरी ओर, attribution_report_to के लिए उदाहरण के तौर पर वैल्यू https://dsp-a.example-dsp-host.com या https://privacy-sandbox-demos-dsp.dev होगी. ध्यान दें कि एग्रीगेशन सेवा में शामिल होने के दौरान आपने जो रिपोर्टिंग साइटें उपलब्ध कराई हैं (ज़रूरी शर्तें 1.7). (उदाहरण के लिए: "https://privacy-sandbox-demos-dsp.dev")

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

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

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

Postman

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

"भेजें" 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 के साथ जवाब मिल सकता है. ऐसा होना सामान्य है और इसे अनदेखा किया जा सकता है.

Postman

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

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

"भेजें" 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 फ़ाइल के अंदर उपलब्ध होती है.

कोडलैब पूरा हुआ!

खास जानकारी: आपने एग्रीगेशन सेवा को अपने क्लाउड एनवायरमेंट में डिप्लॉय किया है, डीबग रिपोर्ट इकट्ठा की है, आउटपुट डोमेन फ़ाइल बनाई है, इन फ़ाइलों को Cloud Storage बकेट में सेव किया है, और सही काम किया है!

अगले चरण: अपने एनवायरमेंट में एग्रीगेशन सेवा का इस्तेमाल करना जारी रखें या चौथे चरण में दिए गए क्लीनअप करने के निर्देशों का पालन करके, उन क्लाउड रिसॉर्स को मिटाएं जिन्हें आपने अभी-अभी बनाया है.

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. Ad Privacy API (लोकल टेस्टिंग और एग्रीगेशन सेवा) चालू करें

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

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

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

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

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

Postman

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

cURL

Postman

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` फ़ाइल का उदाहरण