آشنایی با API Service Aggregation

پس از استقرار، سرویس Aggregation دو نقطه پایانی را برای استفاده از فناوری تبلیغات در معرض نمایش می گذارد: createJob و getJob .

می توانید اطلاعات بیشتری در مورد نقاط پایانی createJob و getJob در مستندات Aggregation Service API بخوانید.

ایجاد شغل

نقطه پایانی createJob از طریق یک درخواست HTTP POST فراخوانی می شود و به بدنه درخواست نیاز دارد. هنگامی که درخواست createJob انجام شد، یک پاسخ موفقیت آمیز HTTP 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 متقابلاً انحصاری هستند و فقط یکی مورد نیاز است.

همچنین می‌توانید با افزودن 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 با 128 کاراکتر یا کمتر باشد. این درخواست کار دسته‌ای را مشخص می‌کند و همه گزارش‌های جمع‌آوری avro مشخص‌شده در «input_data_blob_prefix» را از سطل ورودی مشخص‌شده در input_data_bucket_name که در فضای ذخیره‌سازی ابری فناوری آگهی میزبانی می‌شود، می‌گیرد. کاراکترها: `az, AZ, 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_bucket_name با نام output_data_blob_prefix قرار می‌گیرد.
job_parameters.output_domain_bucket_name	رشته	این سطل ذخیره سازی فایل AVRO دامنه خروجی شما است. این در فضای ذخیره سازی ابری فناوری تبلیغات است.
job_parameters.attribution_report_to	رشته	به طور متقابل منحصر به Reporting_site. این نشانی وب گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است.
job_parameters.reporting_site	رشته	متقابلاً منحصر به attribution_report_to است. این نام میزبان URL گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. توجه: می‌توانید گزارش‌هایی را با چندین منبع گزارش در یک درخواست ارسال کنید تا زمانی که همه منابع گزارش‌دهی متعلق به یک سایت گزارش‌دهنده ذکر شده در این پارامتر باشند.
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 را می توان با استفاده از تماس 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	رشته	این شناسه کار / دسته منحصر به فرد است که در درخواست 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 است. این نشانی وب گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. این در درخواست createJob مشخص شده است.
job_parameters.reporting_site	رشته	متقابلاً منحصر به attribution_report_to است. این نام میزبان URL گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. توجه داشته باشید، می‌توانید گزارش‌هایی را با چندین منبع گزارش در یک درخواست ارسال کنید تا زمانی که همه منابع گزارش‌دهی متعلق به یک سایت گزارش‌دهنده ذکر شده در این پارامتر باشند. این در درخواست 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" است.)

،

پس از استقرار، سرویس Aggregation دو نقطه پایانی را برای استفاده از فناوری تبلیغات در معرض نمایش می گذارد: createJob و getJob .

می توانید اطلاعات بیشتری در مورد نقاط پایانی createJob و getJob در مستندات Aggregation Service API بخوانید.

ایجاد شغل

نقطه پایانی createJob از طریق یک درخواست HTTP POST فراخوانی می شود و به بدنه درخواست نیاز دارد. هنگامی که درخواست createJob انجام شد، یک پاسخ موفقیت آمیز HTTP 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 متقابلاً انحصاری هستند و فقط یکی مورد نیاز است.

همچنین می‌توانید با افزودن 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 با 128 کاراکتر یا کمتر باشد. این درخواست کار دسته‌ای را مشخص می‌کند و همه گزارش‌های جمع‌آوری avro مشخص‌شده در «input_data_blob_prefix» را از سطل ورودی مشخص‌شده در input_data_bucket_name که در فضای ذخیره‌سازی ابری فناوری آگهی میزبانی می‌شود، می‌گیرد. کاراکترها: `az, AZ, 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_bucket_name با نام output_data_blob_prefix قرار می‌گیرد.
job_parameters.output_domain_bucket_name	رشته	این سطل ذخیره سازی فایل AVRO دامنه خروجی شما است. این در فضای ذخیره سازی ابری فناوری تبلیغات است.
job_parameters.attribution_report_to	رشته	به طور متقابل منحصر به Reporting_site. این نشانی وب گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است.
job_parameters.reporting_site	رشته	متقابلاً منحصر به attribution_report_to است. این نام میزبان URL گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. توجه: می‌توانید گزارش‌هایی را با چندین منبع گزارش در یک درخواست ارسال کنید تا زمانی که همه منابع گزارش‌دهی متعلق به یک سایت گزارش‌دهنده ذکر شده در این پارامتر باشند.
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 را می توان با استفاده از تماس 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	رشته	این شناسه کار / دسته منحصر به فرد است که در درخواست 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 است. این نشانی وب گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. این در درخواست createJob مشخص شده است.
job_parameters.reporting_site	رشته	متقابلاً منحصر به attribution_report_to است. این نام میزبان URL گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. توجه داشته باشید، می‌توانید گزارش‌هایی را با چندین منبع گزارش در یک درخواست ارسال کنید تا زمانی که همه منابع گزارش‌دهی متعلق به یک سایت گزارش‌دهنده ذکر شده در این پارامتر باشند. این در درخواست 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" است.)

،

پس از استقرار، سرویس Aggregation دو نقطه پایانی را برای استفاده از فناوری تبلیغات در معرض نمایش می گذارد: createJob و getJob .

می توانید اطلاعات بیشتری در مورد نقاط پایانی createJob و getJob در مستندات Aggregation Service API بخوانید.

ایجاد شغل

نقطه پایانی createJob از طریق یک درخواست HTTP POST فراخوانی می شود و به بدنه درخواست نیاز دارد. هنگامی که درخواست createJob انجام شد، یک پاسخ موفقیت آمیز HTTP 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 متقابلاً انحصاری هستند و فقط یکی مورد نیاز است.

همچنین می‌توانید با افزودن 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 با 128 کاراکتر یا کمتر باشد. این درخواست کار دسته‌ای را مشخص می‌کند و همه گزارش‌های جمع‌آوری avro مشخص‌شده در «input_data_blob_prefix» را از سطل ورودی مشخص‌شده در input_data_bucket_name که در فضای ذخیره‌سازی ابری فناوری آگهی میزبانی می‌شود، می‌گیرد. کاراکترها: `az, AZ, 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_bucket_name با نام output_data_blob_prefix قرار می‌گیرد.
job_parameters.output_domain_bucket_name	رشته	این سطل ذخیره سازی فایل AVRO دامنه خروجی شما است. این در فضای ذخیره سازی ابری فناوری تبلیغات است.
job_parameters.attribution_report_to	رشته	به طور متقابل منحصر به Reporting_site. این نشانی وب گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است.
job_parameters.reporting_site	رشته	متقابلاً منحصر به attribution_report_to است. این نام میزبان URL گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. توجه: می‌توانید گزارش‌هایی را با چندین منبع گزارش در یک درخواست ارسال کنید تا زمانی که همه منابع گزارش‌دهی متعلق به یک سایت گزارش‌دهنده ذکر شده در این پارامتر باشند.
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 را می توان با استفاده از تماس 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	رشته	این شناسه کار / دسته منحصر به فرد است که در درخواست 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 است. این نشانی وب گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. این در درخواست createJob مشخص شده است.
job_parameters.reporting_site	رشته	متقابلاً منحصر به attribution_report_to است. این نام میزبان URL گزارش یا مبدا گزارشی است که گزارش از آنجا دریافت شده است. مبدا بخشی از سایتی خواهد بود که در Aggregation Service Onboarding ثبت شده است. توجه داشته باشید، می‌توانید گزارش‌هایی را با چندین منبع گزارش در یک درخواست ارسال کنید تا زمانی که همه منابع گزارش‌دهی متعلق به یک سایت گزارش‌دهنده ذکر شده در این پارامتر باشند. این در درخواست 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" است.)