استقرار و مدیریت درخواست ها با سرویس Aggregation

پس از اینکه سرویس تجمیع (Aggregation Service) را با موفقیت مستقر کردید، می‌توانید از نقاط پایانی createJob و getJob برای تعامل با سرویس استفاده کنید. نمودار زیر نمایش بصری از معماری استقرار برای این دو نقطه پایانی را ارائه می‌دهد:

بررسی اجمالی API سرویس تجمیع
شکل 1. نمای کلی API سرویس تجمیع

می‌توانید اطلاعات بیشتر در مورد نقاط پایانی createJob و getJob را در مستندات API سرویس تجمیع مطالعه کنید.

ایجاد شغل

برای ایجاد یک شغل، یک درخواست POST به نقطه پایانی createJob ارسال کنید. 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>"
  }
}

ایجاد شغل موفق منجر به کد وضعیت HTTP 202 می‌شود.

توجه داشته باشید که reporting_site و attribution_report_to منحصر به فرد هستند و فقط یکی از آنها مورد نیاز است.

همچنین می‌توانید با اضافه کردن debug_run به job_parameters ، یک کار اشکال‌زدایی درخواست کنید. برای اطلاعات بیشتر در مورد حالت اشکال‌زدایی، مستندات اجرای اشکال‌زدایی تجمیعی ما را بررسی کنید.

{
  "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 با ۱۲۸ کاراکتر یا کمتر باشد. این شناسه، درخواست کار دسته‌ای را شناسایی می‌کند و تمام گزارش‌های AVRO قابل جمع‌آوری مشخص شده در `input_data_blob_prefix` را از سطل ورودی مشخص شده در `input_data_bucket_name` که در فضای ذخیره‌سازی ابری فناوری تبلیغات میزبانی می‌شود، دریافت می‌کند.
کاراکترها: `az, AZ, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix رشته این مسیر سطل است. برای فایل‌های تکی، می‌توانید از مسیر استفاده کنید. برای چندین فایل، می‌توانید از پیشوند در مسیر استفاده کنید.
مثال: پوشه/فایل تمام گزارش‌ها را از پوشه/file1.avro، پوشه/file/file1.avro و پوشه/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_bucket_name با نام output_data_blob_prefix قرار می‌گیرد.
job_parameters.output_domain_bucket_name رشته این سطل ذخیره‌سازی برای فایل AVRO دامنه خروجی شماست. این در فضای ذخیره‌سازی ابری شرکت فناوری تبلیغات قرار دارد.
job_parameters.attribution_report_to رشته این مقدار منحصراً مختص به `reporting_site` است. این URL گزارش یا منبع گزارش‌دهی است که گزارش از آنجا دریافت شده است. منبع سایت در سرویس تجمیع ثبت شده است.
job_parameters.reporting_site رشته منحصر به فرد برای attribution_report_to . این نام میزبان URL گزارش یا منبع گزارش است که گزارش از آنجا دریافت شده است. منبع سایت در Onboarding Service Aggregation ثبت شده است. توجه: می‌توانید چندین گزارش با منابع مختلف را در یک درخواست واحد ارسال کنید، مشروط بر اینکه همه منابع متعلق به یک سایت گزارش‌دهی مشخص شده در این پارامتر باشند.
job_parameters.debug_privacy_epsilon ممیز شناور، دابل فیلد اختیاری. اگر هیچ مقداری ارسال نشود، مقدار پیش‌فرض ۱۰ است. می‌توان از مقداری بین ۰ تا ۶۴ استفاده کرد.
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" باشند. از نسخه ۲.۱۰.۰، اجرای اشکال‌زدایی > بودجه حریم خصوصی را مصرف نمی‌کند .

شغل پیدا کنید

وقتی یک تکنسین تبلیغات می‌خواهد از وضعیت یک دسته درخواستی مطلع شود، می‌تواند نقطه پایانی getJob را فراخوانی کند. نقطه پایانی getJob با استفاده از یک درخواست HTTPS GET به همراه پارامتر 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 رشته این شناسه منحصر به فرد job/batch است که در درخواست 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 فرهنگ لغت این شامل پارامترهای job ارائه شده در درخواست createJob است. ویژگی‌های مرتبط مانند `output_domain_blob_prefix` و `output_domain_bucket_name`.
job_parameters.attribution_report_to رشته منحصر به reporting_site . این آدرس گزارش یا مبدا دریافت گزارش است. مبدا بخشی از سایتی است که در 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 ممیز شناور، دابل فیلد اختیاری. اگر مقداری ارسال نشود، مقدار پیش‌فرض ۱۰ استفاده می‌شود. مقادیر می‌توانند از ۰ تا ۶۴ باشند. این مقدار در درخواست createJob مشخص شده است.
job_parameters.report_error_threshold_percentage دو برابر فیلد اختیاری. این درصد آستانه گزارش‌هایی است که می‌توانند قبل از شکست کار، با شکست مواجه شوند. اگر هیچ مقداری اختصاص داده نشود، از مقدار پیش‌فرض ۱۰٪ استفاده می‌شود. این مقدار در درخواست createJob مشخص شده است.
job_parameters.input_report_count ارزش خرید فیلد اختیاری. تعداد کل گزارش‌های ارائه شده به عنوان داده‌های ورودی برای این کار. `report_error_threshold_percentage`، همراه با این مقدار، در صورت حذف تعداد قابل توجهی از گزارش‌ها به دلیل خطا، باعث شکست زودهنگام کار می‌شود. این تنظیم در درخواست `createJob` مشخص شده است.
job_parameters.filtering_ids رشته فیلد اختیاری. فهرستی از شناسه‌های فیلترینگ بدون علامت که با کاما از هم جدا شده‌اند. تمام مشارکت‌ها به جز شناسه فیلترینگ منطبق، فیلتر می‌شوند. این مورد در درخواست createJob مشخص شده است. (مثلاً "filtering_ids":"12345,34455,12" . مقدار پیش‌فرض "0" است.)