طلب التقارير

أصبحت Search Ads 360 Reporting API الجديدة متاحة الآن. توفّر واجهة برمجة التطبيقات الجديدة مرونة محسّنة لإنشاء تقارير مخصّصة ودمج البيانات في تطبيقات وعمليات إعداد التقارير. اطّلِع على المزيد من المعلومات عن نقل البيانات إلى واجهة Search Ads 360 Reporting API الجديدة واستخدامها.

بعد إعداد تطبيق العميل كما هو موضّح في تطبيقي الأول، يمكنك استخدام Search Ads 360 API لطلب التقارير وتنزيلها. يمكنك إجراء أحد النوعَين التاليَين من الطلبات:

المتزامن

يتطلب هذا الخيار طلبًا واحدًا فقط ويعرض التقرير بتنسيق استجابة بتنسيق JSON. الطلبات المتزامنة:

إذا كنت تطلب تقارير كبيرة من المعلِن أو حساب محرّك البحث، ننصحك باستخدام الأسلوب غير المتزامن.

غير متزامن

يتطلب منك إرسال طلب أولي يحدِّد البيانات التي تريد تضمينها في التقرير. وبعد ذلك، تُرسِل طلبات إضافية إلى استطلاع "إعلانات شبكة البحث 360". عند انتهاء "إعلانات شبكة البحث 360" من إنشاء التقرير، يتم إرسال طلبات لتنزيل التقرير كملف واحد أو أكثر. الطلبات غير المتزامنة:

  • يمكن عرض أي نوع تقرير
  • تقسيم التقارير الكبيرة جدًا إلى ملفات متعددة
  • تنسيق التقارير بتنسيق CSV أو TSV

نموذج البيانات: الصفوف والأعمدة

تنظِّم "إعلانات شبكة البحث 360" البيانات في تقرير على شكل صفوف وأعمدة. يحدّد نوع التقرير الذي تطلبه الصفوف التي تم عرضها. على سبيل المثال، إذا طلبت تقرير الكلمات الرئيسية، سيحتوي كل صف على بيانات عن كلمة رئيسية واحدة. يمكنك الاطّلاع على مرجع أنواع التقارير للحصول على قائمة بجميع أنواع التقارير. يمكنك تحديد الأعمدة التي تريدها في التقرير من خلال تسمية كل عمود في طلب التقرير. اطّلِع على مرجع أنواع التقارير للاطّلاع على قائمة الأعمدة التي يمكن عرضها لكل نوع من أنواع التقارير.

سلوك العمود

يعتمد سلوك العمود على نوع البيانات التي يتضمّنها العمود (يعرض المرجع أنواع التقارير سلوك كل عمود):

  • أعمدة السمات: يحتوي عمود السمات على بيانات تهيئ كيانًا ما أو تحدّده في إحدى الحملات، مثل اسم الحملة أو عرض سعر الكلمة الرئيسية. تعرض Search Ads 360 API دائمًا القيمة الحالية لعمود السمة، بغض النظر عن أي تاريخ أو نطاق زمني محدّد في الطلب. على سبيل المثال، إذا غيّرت عرض سعر كلمة رئيسية من 2.00 إلى 1.50 أمس، ثم طلبت تقريرًا عن بيانات الشهر الماضي، سيعرض التقرير القيمة 1.50 لعرض سعر الكلمة الرئيسية.

  • أعمدة المقاييس. يحتوي عمود المقياس على بيانات عن أداء حملتك، مثل عدد النقرات على إعلان معيّن أو عدد الزيارات وفقًا لما تسجّله علامة Floodlight أو الأرباح. في حال عدم تحديد نطاق زمني ليوم واحد، تعرض واجهة برمجة التطبيقات قيمة مجمّعة لأعمدة المقاييس. على سبيل المثال، إذا طلبت تقريرًا عن بيانات الشهر الماضي، ستعرض واجهة برمجة التطبيقات إجمالي عدد النقرات للشهر الماضي.

  • أعمدة الشرائح: يقسم عمود التقسيم البيانات إلى صفوف منفصلة. على سبيل المثال، date هو عمود شريحة يمكنك تحديده للعديد من أنواع التقارير. إذا حدّدت العمود date في تقرير الكلمات الرئيسية بنطاق زمني من 2013-01-01 إلى 2013-01-07، ستعرض واجهة برمجة التطبيقات سبعة صفوف لكل كلمة رئيسية، تتطابق كل منها مع يوم واحد وتعرض مقاييس ذلك اليوم. اطّلِع على التقارير المقسّمة.

العملات

يجب إدخال طلب التقرير لتحديد عملة البيانات المالية (كلّ من السمتَين dailyBudget والمقاييس مثل cost). يمكنك تحديد أحد الخيارَين التاليَين:

  • عملة الوكالة، إذا كان التقرير على مستوى وكالة أو معلن أو حساب محرّك بحث.
  • عملة المعلِن، إذا كان التقرير متاحًا في نطاق حساب المعلِن أو حساب محرّك البحث
  • عملة حساب محرّك البحث، إذا كان التقرير مرتبطًا بحساب محرّك البحث
  • USD

استخدِم سمة الطلب Reports.request.statisticsCurrency لتحديد عملة.

سيشير التقرير نفسه إلى العملة في السمة Reports.statisticsCurrencyCode.

المنطقة الزمنية

يتم تخزين مقاييس "إعلانات شبكة البحث 360" في تواريخ بدون مناطق زمنية. تتوافق هذه التواريخ مع المنطقة الزمنية لحساب محرّك البحث لمقاييس محرّكات البحث (مثل النقرات ومرات الظهور والزيارات)، والمنطقة الزمنية لشبكة "مدير الحملة" لمقاييس الإحالات الناجحة (مثل الإجراءات والمعاملات والأرباح). عندما يأتي كل مقياس في التقرير من المنطقة الزمنية نفسها، سيتم عرض هذه المنطقة الزمنية في الطلب. وإلّا، لن يتم عرض أي منطقة زمنية. ويمكن لطلباتك ضبط Reports.request.verifySingleTimeZone: true لتعذّر الوصول إلى التقارير التي تعرض مقياسًا من أكثر من منطقة زمنية واحدة.

إذا كانت جميع المقاييس الواردة في التقرير تندرج ضمن منطقة زمنية واحدة، يتم عرض هذه المنطقة الزمنية بالتنسيق Reports.statisticsTimeZoneReports.