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

بعد نشر "خدمة التجميع" بنجاح، يمكنك استخدام نقطتَي النهاية 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 القابلة للتجميع والمحدّدة في `input_data_blob_prefix` من حزمة الإدخال المحدّدة في `input_data_bucket_name` والمستضافة على مساحة التخزين السحابية الخاصة بتكنولوجيا الإعلان. الأحرف: `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 باستخدام طلب GET عبر HTTPS مع المَعلمة 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".)

نشر الطلبات وإدارتها باستخدام "خدمة التجميع" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إنشاء وظيفة

حقول الطلب

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

حقول الردود

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