نشر الطلبات وإدارتها باستخدام "خدمة التجميع"

بعد نشر "خدمة التجميع" بنجاح، يمكنك استخدام نقطتَي النهاية createJob وgetJob للتفاعل مع الخدمة. يقدّم الرسم البياني التالي تمثيلًا مرئيًا لبنية النشر لهذه النقطتَين النهائيتَين:

الشكل 1: نظرة عامة على Aggregation Service API

يمكنك الاطّلاع على مزيد من المعلومات عن نقطتَي النهاية createJob وgetJob في مستندات Aggregation Service 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 التي لا يتجاوز عددها 128 حرفًا. يحدِّد ذلك طلب المهمة المجمّعة ويأخذ جميع تقارير AVRO القابلة للتجميع المحدّدة في "بادئة_مجموعة_بيانات_الإدخال" من حزمة الإدخال المحدّدة في "اسم_حزمة_بيانات_الإدخال" التي يتم استضافتها على مساحة التخزين السحابي لتكنولوجيا الإعلان. الأحرف: `a-z, A-Z, 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_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 للإبلاغ أو مصدر الإبلاغ الذي تم استلام التقرير منه. يتم تسجيل مصدر الموقع الإلكتروني في عملية إعداد خدمة التجميع. ملاحظة: يمكنك إرسال تقارير متعددة بمصادر مختلفة ضمن طلب واحد، شرط أن تنتمي جميع المصادر إلى موقع إعداد التقارير نفسه المحدّد في هذه المَعلمة.
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". اعتبارًا من الإصدار 2.10.0، لا تستهلك عمليات تصحيح الأخطاء ميزانية الخصوصية.

الحصول على وظيفة

عندما تريد تقنية عرض الإعلانات معرفة حالة مجموعة بيانات مُجمّعة مُطلوبة، يمكنها الاتصال بنقطة نهاية 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 هذا هو عنوان URL الذي تم الإبلاغ عنه أو مصدر تلقّي التقرير. المصدر هو جزء من الموقع الإلكتروني المسجَّل في عملية إعداد خدمة التجميع. يتم تحديد ذلك في طلب createJob.
job_parameters.reporting_site	سلسلة	متعارض مع attribution_report_to هذا هو اسم مضيف عنوان URL الذي تم الإبلاغ عنه أو مصدر تلقّي التقرير. المصدر هو جزء من الموقع الإلكتروني المسجَّل في عملية إعداد خدمة التجميع. يُرجى العلم أنّه يمكنك إرسال تقارير تتضمّن مصادر إعداد تقارير متعددة في الطلب نفسه طالما أنّ جميع مصادر إعداد التقارير تنتمي إلى الموقع الإلكتروني نفسه المذكور في هذه المَعلمة. يتم تحديد ذلك في طلب 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".)