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

Aggregation Service API के बारे में जानकारी

डिप्लॉयमेंट के बाद, एग्रीगेशन सेवा विज्ञापन टेक्नोलॉजी के इस्तेमाल के लिए दो एंडपॉइंट दिखाएगी: createJob और getJob.

AgS डायग्राम

createJob और getJob एंडपॉइंट के बारे में ज़्यादा जानने के लिए, एग्रीगेशन सेवा API के दस्तावेज़ पढ़ें.

createJob

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

  POST https://<api-gateway>/stage/v1alpha/createJob

createJob के लिए अनुरोध के मुख्य हिस्से का उदाहरण:

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<host name of reporting origin>"
  }
}

ध्यान दें कि reporting_site और attribution_report_to एक-दूसरे से अलग होते हैं और सिर्फ़ एक की ज़रूरत होती है.

job_parameters में debug_run जोड़कर भी डीबग जॉब का अनुरोध किया जा सकता है. डीबग मोड को समझने के लिए, हमारा एग्रीगेशन डीबग रन दस्तावेज़ देखें.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>"
    "debug_run": "true"
  }
}

फ़ील्ड का अनुरोध करें

पैरामीटर	टाइप	ब्यौरा
`job_request_id`	स्ट्रिंग	यह विज्ञापन टेक्नोलॉजी से जनरेट किया गया यूनीक आइडेंटिफ़ायर है. यह 128 या उससे कम वर्णों वाले ASCII अक्षर होने चाहिए. यह बैच जॉब के अनुरोध की पहचान करता है. साथ ही, विज्ञापन टेक्नोलॉजी के क्लाउड स्टोरेज पर होस्ट की गई input_data_bucket_name में बताई गई इनपुट बकेट से, `input_data_blob_prefix` में बताई गई सभी एग्रीगेट की जा सकने वाली एवरो रिपोर्ट लेगा. वर्ण: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
`input_data_blob_prefix`	स्ट्रिंग	यह बकेट में मौजूद पाथ है. एक फ़ाइल के लिए, पाथ का इस्तेमाल किया जा सकता है. कई फ़ाइलों के लिए, पाथ में प्रीफ़िक्स का इस्तेमाल किया जा सकता है. उदाहरण: folder/file, folder/file1.avro, folder/file/file1.avro, folder/file1/test/file2.avro से सभी रिपोर्ट इकट्ठा करेगा.
`input_data_bucket_name`	स्ट्रिंग	यह इनपुट डेटा या एग्रीगेट की जा सकने वाली रिपोर्ट के लिए स्टोरेज बकेट है. यह विज्ञापन टेक्नोलॉजी के क्लाउड स्टोरेज में होता है.
`output_data_blob_prefix`	स्ट्रिंग	यह बकेट में आउटपुट पाथ है. एक आउटपुट फ़ाइल काम करती है.
`output_data_bucket_name`	स्ट्रिंग	यह स्टोरेज बकेट है, जहां `output_data` भेजे जाएंगे. यह विज्ञापन टेक्नोलॉजी के क्लाउड स्टोरेज में होता है.
`job_parameters`	शब्दकोश	आवश्यक फ़ील्ड. इसमें कई फ़ील्ड शामिल होंगे, जैसे कि: `output_domain_blob_prefix` `output_domain_bucket_name` `attribution_report_to` `reporting_site` `debug_privacy_epsilon` `report_error_threshold_percentage`
`job_parameters.output_domain_blob_prefix`	स्ट्रिंग	`input_data_blob_prefix` की तरह, यह `output_domain_bucket_name` में बना पाथ होगा, जहां आपका आउटपुट डोमेन AVRO मौजूद होगा. एक से ज़्यादा फ़ाइलों के लिए, पाथ में प्रीफ़िक्स का इस्तेमाल किया जा सकता है. एग्रीगेशन सेवा, बैच पूरा करने के बाद खास जानकारी वाली रिपोर्ट बनाती है और उसे `output_data_blob_prefix` नाम के साथ आउटपुट बकेट `output_data_bucket_name` में डालती है.
`job_parameters.output_domain_bucket_name`	स्ट्रिंग	यह आपके आउटपुट डोमेन की AVRO फ़ाइल का स्टोरेज बकेट है. यह मैसेज, विज्ञापन टेक्नोलॉजी के क्लाउड स्टोरेज पर मौजूद होता है.
`job_parameters.attribution_report_to`	स्ट्रिंग	reporting_site के साथ इस्तेमाल नहीं किया जा सकता. यह उस रिपोर्टिंग यूआरएल या रिपोर्टिंग का ऑरिजिन होगा जहां रिपोर्ट मिली थी. ऑरिजिन, उस साइट का हिस्सा होगा जिसे एग्रीगेशन सर्विस के ऑनबोर्डिंग में रजिस्टर किया गया है.
`job_parameters.reporting_site`	स्ट्रिंग	`attribution_report_to` के साथ इस्तेमाल नहीं किया जा सकता. यह उस रिपोर्टिंग यूआरएल या रिपोर्टिंग ऑरिजिन का होस्टनेम होगा जहां रिपोर्ट मिली थी. ऑरिजिन, उस साइट का हिस्सा होगा जिसे एग्रीगेशन सर्विस के ऑनबोर्डिंग में रजिस्टर किया गया है. ध्यान दें: आपके पास एक ही अनुरोध में कई रिपोर्टिंग ऑरिजिन वाली रिपोर्ट सबमिट करने का विकल्प है. इसके लिए, यह ज़रूरी है कि सभी रिपोर्टिंग ऑरिजिन इस पैरामीटर में बताई गई एक ही रिपोर्टिंग साइट से जुड़े हों.
`job_parameters.debug_privacy_epsilon`	फ़्लोटिंग पॉइंट, डबल	यह फ़ील्ड ज़रूरी नहीं है. अगर कोई भी संख्या पास नहीं होती है, तो डिफ़ॉल्ट वैल्यू 10 होती है. 0 से 64 के बीच की वैल्यू का इस्तेमाल किया जा सकता है. वैल्यू में अंतर हो सकता है.
`job_parameters.report_error_threshold_percentage`	डबल	यह फ़ील्ड ज़रूरी नहीं है. यह रिपोर्ट के प्रतिशत का थ्रेशोल्ड है, जो जॉब के शुरू होने से पहले ही पूरा हो सकता है. अगर इसे खाली छोड़ दिया जाता है, तो डिफ़ॉल्ट 10% होता है.
`job_parameters.input_report_count`	लंबी वैल्यू	यह फ़ील्ड ज़रूरी नहीं है. इस जॉब के लिए, इनपुट डेटा के तौर पर दी गई रिपोर्ट की कुल संख्या. `report_error_threshold_percentage` के साथ यह वैल्यू इस्तेमाल करने पर, गड़बड़ियों की वजह से रिपोर्ट हटाए जाने पर, जॉब के शुरू होने से पहले ही काम करना बंद कर देगा.
`job_parameters.filtering_ids`	स्ट्रिंग	यह फ़ील्ड ज़रूरी नहीं है. बिना हस्ताक्षर वाले फ़िल्टरिंग आईडी की सूची, जिन्हें कॉमा लगाकर अलग किया गया है. फ़िल्टर करने वाले आईडी से मेल न खाने वाले सभी योगदानों को फ़िल्टर कर दिया जाएगा. उदाहरण के लिए,`"filtering_ids": "12345,34455,12"`. डिफ़ॉल्ट मान "0" है.
`job_parameters.debug_run`	बूलियन	यह फ़ील्ड ज़रूरी नहीं है. डीबग रन करते समय, शोर और बिना नॉइज़ वाली डीबग की खास जानकारी वाली रिपोर्ट और एनोटेशन जोड़े जाते हैं. इससे पता चलता है कि डोमेन इनपुट और/या रिपोर्ट में कौनसी कुंजियां मौजूद हैं. इसके अलावा, बैच में डुप्लीकेट कॉपी को भी लागू नहीं किया जाता. ध्यान दें कि डीबग रन सिर्फ़ उन रिपोर्ट पर लागू होता है जिनमें `"debug_mode": "enabled"` फ़्लैग होता है. साथ ही, डीबग रन बजट का इस्तेमाल करते हैं.

getJob

जब विज्ञापन टेक्नोलॉजी को अनुरोध किए गए किसी बैच का स्टेटस जानना हो, तो वह getJob एंडपॉइंट को कॉल कर सकती है. getJob एंडपॉइंट को अनुरोध में, job_request_id पैरामीटर के साथ एचटीटीपीएस जीईटी कॉल का इस्तेमाल करके कॉल किया जा सकता है.

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

आपको ऐसा जवाब मिलेगा. इससे काम की स्थिति और गड़बड़ी के मैसेज दिखेंगे.

{
    "job_status": "FINISHED",
    "request_received_at": "2023-07-17T19:15:13.926530Z",
    "request_updated_at": "2023-07-17T19:15:28.614942839Z",
    "job_request_id": "PSD_0003",
    "input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
    "input_data_bucket_name": "ags-report-bucket",
    "output_data_blob_prefix": "summary/summary.avro",
    "output_data_bucket_name": "ags-report-bucket",
    "postback_URL": "",
    "result_info": {
        "return_code": "SUCCESS",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-07-17T19:15:28.607802354Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "ags-report-bucket",
        "output_domain_blob_prefix": "output_domain/output_domain.avro",
        "attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
    },
    "request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}

जवाब के फ़ील्ड

पैरामीटर	टाइप	ब्यौरा
`job_request_id`	स्ट्रिंग	यह `createJob` अनुरोध में दिया गया यूनीक जॉब / बैच आईडी है.
`job_status`	स्ट्रिंग	यह नौकरी के अनुरोध का स्टेटस है.
`request_received_at`	स्ट्रिंग	अनुरोध मिलने का समय.
`request_updated_at`	स्ट्रिंग	जॉब को आखिरी बार अपडेट किए जाने का समय.
`input_data_blob_prefix`	स्ट्रिंग	यह इनपुट डेटा प्रीफ़िक्स है, जिसे `createJob` पर सेट किया गया है.
`input_data_bucket_name`	स्ट्रिंग	यह विज्ञापन टेक्नोलॉजी की इनपुट डेटा बकेट है, जहां एग्रीगेट की जा सकने वाली रिपोर्ट सेव की जाती हैं. यह फ़ील्ड `createJob` पर सेट है.
`output_data_blob_prefix`	स्ट्रिंग	यह आउटपुट डेटा प्रीफ़िक्स है, जिसे `createJob` पर सेट किया गया था.
`output_data_bucket_name`	स्ट्रिंग	यह विज्ञापन टेक्नोलॉजी की आउटपुट डेटा बकेट है. यहां जनरेट होने के बाद, खास जानकारी वाली रिपोर्ट सेव की जाएंगी. यह फ़ील्ड `createJob` पर सेट है.
`request_processing_started_at`	स्ट्रिंग	प्रोसेस करने की पिछली कोशिश शुरू होने का समय. इसमें, जॉब की सूची में लगने वाला समय शामिल नहीं होगा. (प्रोसेस होने में लगने वाला कुल समय = `request_updated_at` - `request_processing_started_at`)
`result_info`	शब्दकोश	यह `createJob` और जॉब पर उपलब्ध सारी जानकारी का नतीजा है. इससे `return_code`, `return_message`, `finished_at`, और `error_summary` दिखेंगे.
`result_info.return_code`	स्ट्रिंग	जॉब के नतीजे का रिटर्न कोड. एग्रीगेशन सेवा में कोई समस्या होने पर, इस जानकारी की ज़रूरत होगी, ताकि यह समझा जा सके कि समस्या क्या हो सकती है.
`result_info.return_message`	स्ट्रिंग	काम के नतीजे के तौर पर दिखने वाला मैसेज (सफल या असफल). एग्रीगेशन सेवा की गड़बड़ियों की जांच के दौरान भी इस जानकारी की ज़रूरत होगी.
`result_info.error_summary`	शब्दकोश	जॉब के लिए लौटने वाली गड़बड़ियां. इसमें यह दिखाया जाएगा कि कितनी रिपोर्ट में किस तरह की गड़बड़ी की वजह से फ़ेल हो गया.
`result_info.finished_at`	टाइमस्टैंप	जॉब पूरा होने का टाइमस्टैंप.
`result_info.error_summary.error_counts`	सूची	इससे, गड़बड़ी के मैसेज की सूची और एक ही गड़बड़ी के मैसेज वाली उन रिपोर्ट की संख्या दिखेगी जो प्रोसेस नहीं हो पाई हैं. गड़बड़ी की हर गिनती में कैटगरी, `error_count`, `description` शामिल होगा.
`result_info.error_summary.error_messages`	सूची	इससे, उन रिपोर्ट के गड़बड़ी के मैसेज की सूची दिखेगी जिन्हें प्रोसेस नहीं किया जा सका.
`job_parameters`	शब्दकोश	इसमें `createJob` अनुरोध में दिए गए जॉब पैरामीटर शामिल होते हैं. काम की प्रॉपर्टी, जैसे कि `output_domain_blob_prefix` और `output_domain_bucket_name`.
`job_parameters.attribution_report_to`	स्ट्रिंग	`reporting_site` के साथ इस्तेमाल नहीं किया जा सकता. यह रिपोर्टिंग यूआरएल या रिपोर्टिंग ऑरिजिन होगा, जहां रिपोर्ट मिली थी. ऑरिजिन, उस साइट का हिस्सा होगा जिसे एग्रीगेशन सेवा के लिए रजिस्टर किया गया है. इसकी जानकारी `createJob` अनुरोध में दी गई है.
`job_parameters.reporting_site`	स्ट्रिंग	`attribution_report_to` के लिए म्यूचुअली एक्सक्लूसिव. यह उस रिपोर्टिंग यूआरएल या रिपोर्टिंग ऑरिजिन का होस्टनेम होगा जहां रिपोर्ट मिली थी. ऑरिजिन, उस साइट का हिस्सा होगा जिसे एग्रीगेशन सेवा के लिए रजिस्टर किया गया है. ध्यान रखें कि एक ही अनुरोध में कई रिपोर्टिंग ऑरिजिन वाली रिपोर्ट सबमिट की जा सकती हैं. इसके लिए, यह ज़रूरी है कि सभी रिपोर्टिंग ऑरिजिन इस पैरामीटर में बताई गई एक ही रिपोर्टिंग साइट से जुड़े हों. इसकी जानकारी `createJob` अनुरोध में दी गई है. इसके अलावा, पक्का करें कि बकेट में सिर्फ़ वे रिपोर्ट हों जिन्हें आपको जॉब बनाते समय एग्रीगेट करना है. रिपोर्टिंग ऑरिजिन के साथ उस इनपुट डेटा बकेट में जोड़ी गई सभी रिपोर्ट को प्रोसेस किया जाएगा, जो जॉब पैरामीटर में बताई गई रिपोर्टिंग साइट से मेल खाती हैं. उदाहरण के लिए, अगर किसी विज्ञापन टेक्नोलॉजी ने रिपोर्टिंग ऑरिजिन `https://exampleabc.com` रजिस्टर किया है, लेकिन इनपुट डेटा बकेट में उसे `https://1.exampleabc.com`, `https://2.exampleabc.com`, और `https://3.examplexyz.com` से मिली रिपोर्ट में जोड़ा जाता है. सिर्फ़ उन रिपोर्ट को एग्रीगेट किया जाएगा जिन्हें उस बकेट में जोड़ा गया है जो नौकरी में रजिस्टर किए गए रिपोर्टिंग ऑरिजिन से मेल खाती है. यह `https://exampleabc.com` होगा.
`job_parameters.debug_privacy_epsilon`	फ़्लोटिंग पॉइंट, डबल	यह फ़ील्ड ज़रूरी नहीं है. अगर कोई वैल्यू नहीं दी गई है, तो डिफ़ॉल्ट वैल्यू 10 होगी. इसके लिए, 0 से 64 की वैल्यू का इस्तेमाल किया जा सकता है. वैल्यू में अंतर हो सकता है. इसकी जानकारी `createJob` अनुरोध में दी गई है.
`job_parameters.report_error_threshold_percentage`	डबल	यह फ़ील्ड ज़रूरी नहीं है. यह उन रिपोर्ट के प्रतिशत का थ्रेशोल्ड है जो जॉब के पूरे होने से पहले, फ़ेल हो सकती हैं. अगर इसे खाली छोड़ा जाता है, तो डिफ़ॉल्ट रूप से 10% लागू होता है. यह जानकारी `createJob` अनुरोध में दी गई है.
`job_parameters.input_report_count`	लंबा मान	यह फ़ील्ड ज़रूरी नहीं है. इस जॉब के लिए इनपुट डेटा के तौर पर दी गई रिपोर्ट की कुल संख्या. `report_error_threshold_percentage` के साथ इस्तेमाल करने पर, यह वैल्यू गड़बड़ियों की वजह से रिपोर्ट को बाहर रखने पर, जॉब को जल्दी फ़ेल कर देगी. यह जानकारी `createJob` अनुरोध में दी गई है.
`job_parameters.filtering_ids`	स्ट्रिंग	यह फ़ील्ड ज़रूरी नहीं है. बिना हस्ताक्षर वाले फ़िल्टरिंग आईडी की सूची, जिन्हें कॉमा लगाकर अलग किया गया है. फ़िल्टर करने वाले आईडी से मेल न खाने वाले सभी योगदानों को फ़िल्टर कर दिया जाएगा. यह जानकारी `createJob` अनुरोध में दी गई है. उदाहरण के लिए, `"filtering_ids":"12345,34455,12"`. डिफ़ॉल्ट वैल्यू "0" है.)