جارٍ استرداد العناصر

GoogleAdsService هي خدمة موحّدة لاسترداد البيانات وعرض التقارير في Google Ads API. تتضمّن الخدمة طرقًا تؤدي إلى ما يلي:

• استرداد سمات محدّدة للعناصر
• استرداد مقاييس الأداء للعناصر استنادًا إلى نطاق زمني
• ترتيب العناصر استنادًا إلى سماتها
• استخدِم الشروط لتحديد العناصر التي تريد عرضها في الرد.
• تحديد عدد العناصر التي يتم عرضها

يمكن أن تعرض GoogleAdsService النتائج بطريقتَين:

• تعرض GoogleAdsService.SearchStream جميع الصفوف في ردّ واحد متسلسل، ما يجعله أكثر فعالية مع مجموعات النتائج الكبيرة (التي تتضمّن أكثر من 10,000 صف). ننصحك باستخدام هذا الخيار إذا كان تطبيقك ينزّل مجموعات نتائج كاملة أو يعالج الصفوف كتدفق.
• GoogleAdsService.Search تقسم الردود الكبيرة إلى صفحات نتائج يسهل التعامل معها. يكون هذا الإجراء مفيدًا إذا كان تطبيقك التفاعلي يعرض صفحة واحدة من النتائج في كل مرة.

مزيد من المعلومات عن التقسيم إلى صفحات مقابل البث

تقديم طلب

تتوقّع السمة GoogleAdsService.SearchStream القيمة SearchGoogleAdsStreamRequest، وتتوقّع السمة GoogleAdsService.Search القيمة SearchGoogleAdsRequest. يشمل كلا نوعَي الطلبات ما يلي:

• customer_id
• لغة طلب البحث في "إعلانات Google" query التي تحدّد المورد المطلوب البحث عنه والسمات والشرائح والمقاييس المطلوب استردادها والشروط التي يجب استخدامها لتقييد العناصر التي يتم عرضها

استنادًا إلى الطريقة، يتيح الطلب أيضًا حقولاً خاصة بالطريقة:

• SearchGoogleAdsStreamRequest (SearchStream فقط):
  • summary_row_setting اختيارية لطلب صف ملخّص يحتوي على مقاييس مجمّعة
• SearchGoogleAdsRequest (Search فقط):
  • page_token اختياري لاسترداد الدفعة التالية من النتائج عند استخدام التقسيم إلى صفحات (يتم ضبط page_size على 10,000 صف، ويؤدي ضبط page_size في الطلب إلى ظهور الخطأ RequestError.PAGE_SIZE_NOT_SUPPORTED)
  • رسالة search_settings اختيارية لتحديد إعدادات return_summary_row وreturn_total_results_count وomit_results
  • قيمة منطقية validate_only اختيارية للتحقّق من صحة طلب البحث بدون تنفيذه

لمزيد من المعلومات عن "لغة طلبات البحث في إعلانات Google"، اطّلِع على دليل لغة طلبات البحث في إعلانات Google.

معالجة ردّ

تعرض الدالة GoogleAdsService قائمة بكائنات GoogleAdsRow (إما داخل دفعات SearchGoogleAdsStreamResponse يتم بثها أو في SearchGoogleAdsResponse مقسّمة إلى صفحات).

يمثّل كل GoogleAdsRow كائنًا تعرضه نتيجة طلب بحث، ويتألف من مجموعة من السمات التي يتم ملؤها استنادًا إلى الحقول المطلوبة في عبارة SELECT. لا تتم تعبئة السمات غير المضمّنة في عبارة SELECT في عناصر GoogleAdsRow في الرد.

على سبيل المثال، على الرغم من أنّ ad_group_criterion يتضمّن السمة status، لا يتم ملء الحقل status الخاص بالسمة ad_group_criterion في الصف في ردّ على طلب بحث لا تتضمّن عبارة SELECT فيه ad_group_criterion.status. وبالمثل، لا تتم تعبئة السمة campaign الخاصة بالصف إذا لم تتضمّن العبارة SELECT أي حقول من المرجع campaign.

يمكن أن يحتوي كل GoogleAdsRow على سمات ومقاييس مختلفة عن صف آخر في مجموعة النتائج نفسها، لذا يجب عرض الصفوف كعناصر بدلاً من صفوف ثابتة في جدول.

أنواع التعداد UNKNOWN وUNSPECIFIED

إنّ الموارد التي يتم عرضها مع قيمة تعداد UNKNOWN لا تكون متوافقة بشكل كامل مع إصدار واجهة برمجة التطبيقات هذا، بينما يشير UNSPECIFIED إلى أنّه لم يتم ضبط حقل التعداد أو لم يتم طلبه في عبارة SELECT. من المحتمل أنّ المراجع التي تتضمّن قيمة تعداد UNKNOWN قد تم إنشاؤها من خلال واجهات أخرى، مثل واجهة مستخدم "إعلانات Google". يمكنك اختيار مقاييس عندما يكون نوع المرجع UNKNOWN، ولكن لا يمكنك تعديل المرجع من خلال واجهة برمجة التطبيقات. مثال على ذلك هو نوع حملة أو نوع إعلان متاح في واجهة المستخدم وغير متاح في إصدار واجهة برمجة التطبيقات الذي تستخدمه.

في ما يلي بعض الاعتبارات التي يجب وضعها في الاعتبار:

• يمكن أن يتوفّر مرجع بنوع UNKNOWN في إصدار لاحق من واجهة برمجة التطبيقات أو يظل UNKNOWN إلى أجل غير مسمى.
• يمكن أن تظهر عناصر جديدة من النوع UNKNOWN في أي وقت. تكون هذه العناصر متوافقة مع الإصدارات السابقة لأنّ قيمة التعداد UNKNOWN متوفّرة في كل تعداد في واجهة برمجة التطبيقات. يتم عرض الموارد مع UNKNOWN حتى تتمكّن من الاطّلاع على مقاييس الأداء الإجمالية لحسابك بدقة.
• يمكن أن تتضمّن موارد UNKNOWN مقاييس تفصيلية يمكن البحث عنها.
• تكون مراجع UNKNOWN مرئية بالكامل عادةً في واجهة مستخدم "إعلانات Google".
• لا يمكن عادةً تعديل موارد UNKNOWN من خلال واجهة برمجة التطبيقات.

التقسيم

يحتوي الردّ على GoogleAdsRow واحد لكل مجموعة من ما يلي:

• مثيل للمورد الرئيسي المحدّد في عبارة FROM
• قيمة كل حقل segments محدّد

على سبيل المثال، يحتوي الردّ على طلب بحث يختار FROM campaign ويتضمّن segments.ad_network_type وsegments.date في بند برمجي SELECT على صف واحد لكل مجموعة من ما يلي:

• campaign
• segments.ad_network_type
• segments.date

يتم تقسيم النتائج ضمنيًا حسب كل مثيل للمرجع الرئيسي، وليس حسب قيم الحقول الفردية المحدّدة. على سبيل المثال:

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

يؤدي إلى ظهور صف واحد لكل حملة، وليس صف واحد لكل قيمة مميزة للحقل campaign.status.