بعد إعداد تطبيق العميل كما هو موضّح في تطبيقي الأول، يمكنك استخدام Search Ads 360 API لطلب التقارير وتنزيلها. يمكنك إجراء أحد النوعَين التاليَين من الطلبات:
- المتزامن
يتطلب هذا الخيار طلبًا واحدًا فقط ويعرض التقرير بتنسيق استجابة بتنسيق JSON. الطلبات المتزامنة:
- يمكن عرض تقارير المعلِن وحساب محرك البحث فقط
- حظر عميلك إلى أن يتم إنشاء التقرير من خلال "إعلانات شبكة البحث 360"
إذا كنت تطلب تقارير كبيرة من المعلِن أو حساب محرّك البحث، ننصحك باستخدام الأسلوب غير المتزامن.
- غير متزامن
يتطلب منك إرسال طلب أولي يحدِّد البيانات التي تريد تضمينها في التقرير. وبعد ذلك، تُرسِل طلبات إضافية إلى استطلاع "إعلانات شبكة البحث 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.