অ্যাগ্রিগেশন সার্ভিসের সাথে অনুরোধগুলি স্থাপন এবং পরিচালনা করুন

Aggregation Service সফলভাবে স্থাপন করার পর, আপনি createJob এবং getJob endpoints ব্যবহার করে পরিষেবাটির সাথে ইন্টারঅ্যাক্ট করতে পারেন। নিম্নলিখিত চিত্রটি এই দুটি endpoints এর জন্য স্থাপনার আর্কিটেকচারের একটি দৃশ্যমান উপস্থাপনা প্রদান করে:

একত্রীকরণ পরিষেবা API ওভারভিউ
চিত্র ১. সমষ্টি পরিষেবা API সংক্ষিপ্ত বিবরণ

আপনি Aggregation Service API ডকুমেন্টেশনে createJob এবং getJob এন্ডপয়েন্ট সম্পর্কে আরও পড়তে পারেন।

একটি চাকরি তৈরি করুন

একটি চাকরি তৈরি করতে, createJob এন্ডপয়েন্টে একটি POST অনুরোধ পাঠান। bash 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>"
  }
}

একটি সফল কর্মসংস্থান সৃষ্টির ফলে একটি 202 HTTP স্ট্যাটাস কোড পাওয়া যায়।

মনে রাখবেন যে 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 স্ট্রিং এটি একটি অ্যাড টেক জেনারেটেড ইউনিক আইডেন্টিফায়ার যা ASCII অক্ষরের হতে হবে যার মধ্যে ১২৮টি বা তার কম অক্ষর থাকবে। এটি ব্যাচ জব রিকোয়েস্ট শনাক্ত করে এবং অ্যাড টেক-এর ক্লাউড স্টোরেজে হোস্ট করা `input_data_bucket_name`-এ উল্লেখিত ইনপুট বাকেট থেকে `input_data_blob_prefix`-এ উল্লেখিত সমস্ত অ্যাগ্রিগেটেবল AVRO রিপোর্ট নেয়।
অক্ষর: `az, AZ, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix স্ট্রিং এটি হল বাকেট পাথ। একক ফাইলের জন্য, আপনি পাথটি ব্যবহার করতে পারেন। একাধিক ফাইলের জন্য, আপনি পাথে প্রিফিক্স ব্যবহার করতে পারেন।
উদাহরণ: ফোল্ডার/ফাইল 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`-এর সাথে পারস্পরিকভাবে একচেটিয়া। এটি হল রিপোর্টিং URL অথবা রিপোর্টিং অরিজিন যেখানে রিপোর্টটি গৃহীত হয়েছিল। সাইট অরিজিনটি অ্যাগ্রিগেশন সার্ভিস অনবোর্ডিং-এ নিবন্ধিত।
job_parameters.reporting_site স্ট্রিং attribution_report_to এর সাথে পারস্পরিকভাবে একচেটিয়া। এটি হল রিপোর্টিং URL বা রিপোর্টিং অরিজিনের হোস্টনেম যেখানে রিপোর্টটি গৃহীত হয়েছিল। সাইট অরিজিনটি অ্যাগ্রিগেশন সার্ভিস অনবোর্ডিং-এ নিবন্ধিত। দ্রষ্টব্য: আপনি একটি অনুরোধের মধ্যে বিভিন্ন অরিজিন সহ একাধিক প্রতিবেদন জমা দিতে পারেন, তবে শর্ত থাকে যে সমস্ত অরিজিন এই প্যারামিটারে নির্দিষ্ট করা একই রিপোর্টিং সাইটের অন্তর্গত।
job_parameters.debug_privacy_epsilon ভাসমান বিন্দু, দ্বিগুণ ঐচ্ছিক ক্ষেত্র। যদি কোনও মান পাস না করা হয়, তাহলে ডিফল্ট মান হল 10। 0 থেকে 64 পর্যন্ত মান ব্যবহার করা যেতে পারে।
job_parameters.report_error_threshold_percentage দ্বিগুণ ঐচ্ছিক ক্ষেত্র। কাজটি ব্যর্থ হওয়ার আগে এটি অনুমোদিত ব্যর্থ প্রতিবেদনের সর্বাধিক শতাংশ। যদি খালি থাকে, তাহলে ডিফল্ট মান হল ১০%।
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" ফ্ল্যাগ থাকে। v2.10.0 অনুযায়ী, ডিবাগ রান > গোপনীয়তা বাজেট ব্যবহার করে না ।

চাকরি নাও।

যখন কোনও বিজ্ঞাপন প্রযুক্তিবিদ অনুরোধকৃত ব্যাচের অবস্থা জানতে চান, তখন তারা getJob এন্ডপয়েন্টে কল করতে পারেন। job_request_id প্যারামিটারের সাথে একটি HTTPS GET অনুরোধ ব্যবহার করে getJob এন্ডপয়েন্টটি কল করা হয়।

  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 এর সাথে পারস্পরিকভাবে একচেটিয়া। এটি হল রিপোর্টিং URL অথবা রিপোর্টটি যেখান থেকে পাওয়া গেছে তার উৎস। উৎস হল সেই সাইটের অংশ যা Aggregation Service Onboarding-এ নিবন্ধিত। এটি createJob অনুরোধে উল্লেখ করা আছে।
job_parameters.reporting_site স্ট্রিং attribution_report_to এর সাথে পারস্পরিকভাবে একচেটিয়া। এটি হল রিপোর্টিং URL এর হোস্টনেম অথবা রিপোর্টটি যেখানে পাওয়া গেছে তার অরিজিন। অরিজিন হল Aggregation Service Onboarding-এ নিবন্ধিত সাইটের অংশ। মনে রাখবেন যে আপনি একই অনুরোধে একাধিক রিপোর্টিং অরিজিন সহ রিপোর্ট জমা দিতে পারেন যতক্ষণ না সমস্ত রিপোর্টিং অরিজিন এই প্যারামিটারে উল্লিখিত একই সাইটের অন্তর্গত। এটি createJob অনুরোধে নির্দিষ্ট করা আছে। অতিরিক্তভাবে, যাচাই করুন যে বাকেটে কেবল সেই প্রতিবেদনগুলি রয়েছে যা আপনি চাকরি তৈরির সময় একত্রিত করতে চান। ইনপুট ডেটা বাকেটে যোগ করা যেকোনো প্রতিবেদন যা চাকরির প্যারামিটারে নির্দিষ্ট রিপোর্টিং সাইটের সাথে মেলে এমন রিপোর্টিং অরিজিন প্রক্রিয়া করা হয়। অ্যাগ্রিগেশন পরিষেবা কেবলমাত্র ডেটা বাকেটের মধ্যে থাকা প্রতিবেদনগুলি বিবেচনা করে যা কাজের নিবন্ধিত রিপোর্টিং অরিজিনের সাথে মেলে। উদাহরণস্বরূপ, যদি নিবন্ধিত অরিজিন https://exampleabc.com হয়, তবে শুধুমাত্র https://exampleabc.com থেকে রিপোর্টগুলি অন্তর্ভুক্ত করা হয়, এমনকি যদি বাকেটে সাবডোমেন ( https://1.exampleabc.com , ইত্যাদি) বা সম্পূর্ণ ভিন্ন ডোমেন ( https://3.examplexyz.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"।)