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

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

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

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

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

1.1. पंजीकरण और पुष्टि (एग्रीगेशन सेवा)

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

1.2. विज्ञापन देखने वाले की निजता बनाए रखने से जुड़े एपीआई (लोकल टेस्टिंग और एग्रीगेशन सेवा) चालू करना

हम Privacy Sandbox का इस्तेमाल करेंगे. इसलिए, हमारा सुझाव है कि आप Privacy Sandbox Ads API चालू करें.

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

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

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

  • "तीसरे पक्ष की सभी कुकी ब्लॉक करें" = DISABLED
  • "तीसरे पक्ष की कुकी ब्लॉक करें" = DISABLED
  • "गुप्त मोड में, तीसरे पक्ष की कुकी ब्लॉक करें" = ENABLED

कुकी चालू करना कुकी चालू करना

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

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

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

1.4. पुष्टि करें कि JAVA JRE इंस्टॉल है (लोकल टेस्टिंग और एग्रीगेशन सेवा)

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

Java का वर्शन देखें. Java का वर्शन देखें.

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

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

Privacy Sandbox के डेमो के GitHub रिपॉज़िटरी से, aggregatable_report_converter की कॉपी डाउनलोड की जा सकती है. GitHub रिपॉज़िटरी में IntelliJ या Eclipse का इस्तेमाल करने के बारे में बताया गया है. हालांकि, इनमें से किसी का भी इस्तेमाल करना ज़रूरी नहीं है. अगर आपको इन टूल का इस्तेमाल नहीं करना है, तो JAR फ़ाइल को अपने लोकल एनवायरमेंट में डाउनलोड करें.

1.6. Cloud Platform Environment (Aggregation Service) सेट अप करना

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

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

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

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

1.7. एग्रीगेशन सेवा का इस्तेमाल शुरू करना (एग्रीगेशन सेवा)

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

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

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

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

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

1.8.1. Workspace सेट अप करना

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

Postman वर्कस्पेस. Postman वर्कस्पेस.

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

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

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

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

'इंपोर्ट करें' बटन. 'इंपोर्ट करें' बटन.

इससे आपके लिए "GCP Privacy Sandbox" कलेक्शन बन जाएगा. साथ ही, createJob और getJob एचटीटीपी अनुरोध भी बन जाएंगे.

1.8.2. अनुमति सेट अप करना

"GCP Privacy Sandbox" कलेक्शन पर क्लिक करें और "Authorization" टैब पर जाएं.

अनुमति बटन. पुष्टि के लिए अस्थायी शुल्क लेने का बटन.

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

gcloud auth print-identity-token

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

कॉन्टेंट "टोकन" फ़ील्ड.

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

सबसे ऊपर दाएं कोने में मौजूद, "पर्यावरण की खास जानकारी" पर जाएं:

एनवायरमेंट की झलक दिखाने वाला बटन. Environment quick look बटन.

"बदलाव करें" पर क्लिक करें. इसके बाद, "environment", "region", और "cloud-function-id" की "मौजूदा वैल्यू" अपडेट करें:

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

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

2. 2. लोकल टेस्टिंग कोडलैब

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

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

कोडलैब के चरण

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

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

दूसरा चरण.3. बकेट की वापस पाएं: बकेट की, विज्ञापन टेक्नोलॉजी कंपनियां डिज़ाइन करती हैं. इस कोडलैब में, बकेट पहले से तय हैं. इसलिए, बकेट की कुंजियां उसी तरह से पाएं जिस तरह से दी गई हैं.

चरण 2.4. Output Domain AVRO बनाएं: बकेट की कुंजियां वापस पाने के बाद, Output Domain AVRO फ़ाइल बनाएं.

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

चरण 2.6. खास जानकारी वाली रिपोर्ट की समीक्षा करें: Local Testing Tool से बनाई गई खास जानकारी वाली रिपोर्ट की समीक्षा करें.

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

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

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

Chrome Internals पेज. Chrome Internals पेज.

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

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

Google Cloud Debug Report. Google Cloud की डीबग रिपोर्ट.

2.2. डबग करने लायक एग्रीगेट की गई रिपोर्ट बनाना

chrome://private-aggregation-internals के "रिपोर्ट बॉडी" में मौजूद रिपोर्ट को कॉपी करें. इसके बाद, privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar फ़ोल्डर में एक JSON फ़ाइल बनाएं. यह फ़ोल्डर, ज़रूरी शर्तें 1.5 में डाउनलोड किए गए डेटाबेस में मौजूद होता है.

इस उदाहरण में, हम vim का इस्तेमाल कर रहे हैं, क्योंकि हम Linux का इस्तेमाल कर रहे हैं. हालांकि, अपनी पसंद के किसी भी टेक्स्ट एडिटर का इस्तेमाल किया जा सकता है.

vim report.json

रिपोर्ट को report.json में चिपकाएं और अपनी फ़ाइल सेव करें.

रिपोर्ट का 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 फ़ाइल बनाने के लिए, आपको बकेट कुंजियों की ज़रूरत होती है. इन्हें रिपोर्ट से वापस पाया जा सकता है.

बकेट की, विज्ञापन टेक्नोलॉजी से जुड़ी कंपनी बनाती है. हालांकि, इस मामले में साइट Privacy Sandbox Demo, बकेट की बनाती है. इस साइट के लिए Private Aggregation, डीबग मोड में है. इसलिए, हम "Report Body" से debug_cleartext_payload का इस्तेमाल करके, बकेट कुंजी पा सकते हैं.

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

क्लियरटेक्स्ट पेलोड को डीबग करें. Debug Cleartext Payload.

goo.gle/ags-payload-decoder खोलें. इसके बाद, "INPUT" बॉक्स में अपना debug_cleartext_payload चिपकाएं और "Decode" पर क्लिक करें.

डिकोड बटन. डिकोड करने का बटन.

यह पेज, बकेट कुंजी की दशमलव वैल्यू दिखाता है. यहां बकेट की का एक सैंपल दिया गया है.

बकेट की का सैंपल. सैंपल बकेट की कुंजी.

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

अब हमारे पास बकेट की है. इसलिए, आइए उसी फ़ोल्डर में output_domain.avro बनाएं जिसमें हम काम कर रहे हैं. पुष्टि करें कि आपने बकेट की कुंजी को उस कुंजी से बदल दिया है जिसे आपने वापस पाया था.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

यह स्क्रिप्ट, आपके मौजूदा फ़ोल्डर में output_domain.avro फ़ाइल बनाती है.

2.5. लोकल टेस्टिंग टूल का इस्तेमाल करके खास जानकारी वाली रिपोर्ट बनाना

हम LocalTestingTool_{version}.jar का इस्तेमाल करके खास जानकारी वाली रिपोर्ट बनाएंगे. इसे ज़रूरी शर्त 1.3 में डाउनलोड किया गया था. इसके लिए, हम यहां दिया गया कमांड इस्तेमाल करेंगे. {version} को डाउनलोड किए गए वर्शन से बदलें. LocalTestingTool_{version}.jar को मौजूदा डायरेक्ट्री में ले जाना न भूलें. इसके अलावा, इसकी मौजूदा जगह का रेफ़रंस देने के लिए, कोई रिलेटिव पाथ भी जोड़ा जा सकता है.

java -jar LocalTestingTool_{version}.jar \
  --input_data_avro_file report.avro \
  --domain_avro_file output_domain.avro \
  --output_directory .

कमांड चलाने के बाद, आपको कुछ ऐसा दिखेगा. यह प्रोसेस पूरी होने के बाद, एक रिपोर्ट output.avro जनरेट हो जाती है.

AVRO फ़ाइल के तौर पर आउटपुट AVRO फ़ॉर्मैट में आउटपुट

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

खास जानकारी वाली रिपोर्ट, AVRO फ़ॉर्मैट में बनाई जाती है. इसे पढ़ने के लिए, आपको इसे AVRO से JSON फ़ॉर्मैट में बदलना होगा. आदर्श रूप से, विज्ञापन टेक्नोलॉजी को AVRO रिपोर्ट को वापस JSON में बदलने के लिए कोड लिखना चाहिए.

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

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

इससे आपको इस तरह की रिपोर्ट मिलेगी. साथ ही, उसी डायरेक्ट्री में बनाई गई रिपोर्ट output.json भी शामिल है.

JSON फ़ॉर्मैट में आउटपुट JSON आउटपुट

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

खास जानकारी: आपने डीबग रिपोर्ट इकट्ठा की है, आउटपुट डोमेन फ़ाइल बनाई है, और लोकल टेस्टिंग टूल का इस्तेमाल करके खास जानकारी वाली रिपोर्ट जनरेट की है. यह टूल, Aggregation Service के एग्रीगेशन के तरीके को सिम्युलेट करता है.

अगले चरण: अब जब आपने लोकल टेस्टिंग टूल का इस्तेमाल कर लिया है, तो अपने एनवायरमेंट में एग्रीगेशन सेवा के लाइव डिप्लॉयमेंट के साथ भी यही तरीका आज़माएं. ज़रूरी शर्तें फिर से देखें. इससे यह पक्का किया जा सकेगा कि आपने "Aggregation Service" मोड के लिए सब कुछ सेट अप कर लिया है. इसके बाद, तीसरे चरण पर जाएं.

3. 3. Aggregation Service Codelab

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

शुरू करने से पहले, पुष्टि करें कि आपने "Aggregation Service" के तौर पर लेबल की गई सभी ज़रूरी शर्तें पूरी कर ली हों.

कोडलैब के चरण

तीसरा चरण. एग्रीगेशन सेवा के लिए इनपुट बनाना: एग्रीगेशन सेवा के लिए बैच की गई एग्रीगेशन सेवा की रिपोर्ट बनाएं.

  • चरण 3.1.1. ट्रिगर रिपोर्ट
  • चरण 3.1.2. एग्रीगेट की जा सकने वाली रिपोर्ट इकट्ठा करना
  • चरण 3.1.3. रिपोर्ट को AVRO फ़ॉर्मैट में बदलना
  • तीसरा चरण.1.4. output_domain AVRO फ़ाइल बनाना
  • चरण 3.1.5. रिपोर्ट को Cloud Storage बकेट में ले जाना

तीसरा चरण.2. Aggregation Service का इस्तेमाल: खास जानकारी वाली रिपोर्ट बनाने और उनकी समीक्षा करने के लिए, Aggregation Service API का इस्तेमाल करें.

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

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

एग्रीगेशन सेवा को बैच में भेजने के लिए, AVRO रिपोर्ट बनाएं. इन चरणों में दी गई शेल कमांड, Google Cloud के Cloud Shell में चलाई जा सकती हैं. हालांकि, इसके लिए ज़रूरी है कि Cloud Shell एनवायरमेंट में, ज़रूरी शर्तें पूरी करने वाले कॉम्पोनेंट क्लोन किए गए हों. इसके अलावा, इन कमांड को लोकल एक्ज़ीक्यूशन एनवायरमेंट में भी चलाया जा सकता है.

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

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

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

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

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

Google Cloud Debug Report. Google Cloud की डीबग रिपोर्ट.

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

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

  • Private Aggregation: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
  • Attribution Reporting - खास जानकारी वाली रिपोर्ट: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

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

आइए, अब chrome://private-aggregation-internals से "रिपोर्ट बॉडी" में मौजूद JSON रिपोर्ट को कॉपी करें.

इस उदाहरण में, हम vim का इस्तेमाल कर रहे हैं, क्योंकि हम Linux का इस्तेमाल कर रहे हैं. हालांकि, अपनी पसंद के किसी भी टेक्स्ट एडिटर का इस्तेमाल किया जा सकता है.

vim report.json

रिपोर्ट को report.json में चिपकाएं और अपनी फ़ाइल सेव करें.

रिपोर्ट का 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. output_domain AVRO फ़ाइल बनाना

output_domain.avro फ़ाइल बनाने के लिए, आपको बकेट कुंजियों की ज़रूरत होती है. इन्हें रिपोर्ट से वापस पाया जा सकता है.

बकेट की, विज्ञापन टेक्नोलॉजी से जुड़ी कंपनी बनाती है. हालांकि, इस मामले में साइट Privacy Sandbox Demo, बकेट की बनाती है. इस साइट के लिए Private Aggregation, डीबग मोड में है. इसलिए, हम "Report Body" से debug_cleartext_payload का इस्तेमाल करके, बकेट कुंजी पा सकते हैं.

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

क्लियरटेक्स्ट पेलोड को डीबग करें. Debug Cleartext Payload.

goo.gle/ags-payload-decoder खोलें. इसके बाद, "INPUT" बॉक्स में अपना debug_cleartext_payload चिपकाएं और "Decode" पर क्लिक करें.

डिकोड बटन. डिकोड करने का बटन.

यह पेज, बकेट कुंजी की दशमलव वैल्यू दिखाता है. यहां बकेट की का एक सैंपल दिया गया है.

बकेट की का सैंपल. सैंपल बकेट की कुंजी.

अब हमारे पास बकेट की है. इसलिए, आइए उसी फ़ोल्डर में output_domain.avro बनाएं जिसमें हम काम कर रहे हैं. पुष्टि करें कि आपने बकेट की कुंजी को उस कुंजी से बदल दिया है जिसे आपने वापस पाया था.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

यह स्क्रिप्ट, आपके मौजूदा फ़ोल्डर में output_domain.avro फ़ाइल बनाती है.

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

AVRO रिपोर्ट और आउटपुट डोमेन बनाने के बाद, रिपोर्ट और आउटपुट डोमेन को Cloud Storage में मौजूद उस बकेट में ले जाएं जिसके बारे में आपने ज़रूरी शर्तें 1.6 में बताया था.

अगर आपके लोकल एनवायरमेंट में gcloud CLI सेटअप है, तो फ़ाइलों को उनसे जुड़े फ़ोल्डर में कॉपी करने के लिए, इन कमांड का इस्तेमाल करें.

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

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

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

3.2. एग्रीगेशन सेवा के इस्तेमाल से जुड़ी जानकारी

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

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

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

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

curl

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

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<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>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "report_error_threshold_percentage": "10",
      "debug_run": "true"
    }
}

यह अनुरोध पूरा करें. कर्ल अनुरोध के यूआरएल में मौजूद प्लेसहोल्डर को frontend_service_cloudfunction_url से मिली वैल्यू से बदलें. यह वैल्यू, ज़रूरी शर्तें 1.6 में Terraform डिप्लॉयमेंट के पूरा होने के बाद मिलती है.

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>/",
    "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<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>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "report_error_threshold_percentage": "10",
      "debug_run": "true"
    }
}

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

भेजें बटन भेजें बटन

जवाब का कोड, पेज के निचले हिस्से में देखा जा सकता है:

जवाब कोड रिस्पॉन्स कोड

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

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

नौकरी पाने के लिए, curl या Postman के इन निर्देशों में से किसी एक का इस्तेमाल करें.

curl

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

Postman

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

जॉब के अनुरोध का आईडी जॉब के अनुरोध का आईडी

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

भेजें बटन भेजें बटन

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

JSON फ़ॉर्मैट में जवाब रिस्पॉन्स 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 - बकेट की, output_domain AVRO फ़ाइल में उपलब्ध है.

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

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

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

4. 4. मिटाना

Terraform का इस्तेमाल करके, Aggregation Service के लिए बनाए गए संसाधनों को मिटाने के लिए, adtech_setup और dev (या अन्य एनवायरमेंट) फ़ोल्डर में destroy कमांड का इस्तेमाल करें:

$ 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