تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

فهم واجهة برمجة التطبيقات Aggregation Service API

بعد النشر، ستعرض "خدمة التجميع" نقطتَي نهاية لاستخدام تكنولوجيا الإعلان: createJob وgetJob.

مخطط AgS

يمكنك الاطّلاع على مزيد من المعلومات عن نقطتَي النهاية createJob وgetJob في مستندات Aggregation Service API.

createJob

يتم طلب نقطة النهاية 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" من حزمة الإدخال المحدّدة في enter_data_bucket_name التي تتم استضافتها على مساحة التخزين في السحابة الإلكترونية الخاصة بتقنية الإعلان. الأحرف: `a-z, A-Z, 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. سيكون هذا هو عنوان 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"` وعمليات تصحيح الأخطاء تستهلك الميزانية.

getJob

عندما تريد تكنولوجيا الإعلان معرفة حالة مجموعة مُجمّعة مُطلوبة، يمكن لتكنولوجيا الإعلان الاتصال بنقطة نهاية 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://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".)