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

تُعد GoogleAdsService خدمة موحَّدة لاسترداد العناصر وإعداد التقارير من Google Ads API. تتضمن الخدمة طُرقًا:

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

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

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

اطّلِع على مزيد من المعلومات حول نقل الصفحات مقابل البث.

تقديم طلب

تتطلّب طريقة البحث عنصر SearchGoogleAdsRequest الذي يتكوّن من السمات التالية:

• customer_id
• لغة طلب البحث في "إعلانات Google" query التي تشير إلى المورد المطلوب طلب البحث منه، والسمات والشرائح والمقاييس المطلوب استردادها، والشروط المطلوب استخدامها لتحديد العناصر التي يتم عرضها
• (GoogleAdsService.Search فقط) A page_size للإشارة إلى عدد العناصر التي يتم عرضها في استجابة واحدة عند استخدام نقل الصفحات.
• (GoogleAdsService.Search فقط) page_token اختيارية لاسترداد الدفعة التالية من النتائج عند استخدام نقل الصفحات.

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

معالجة الرد

تعرض GoogleAdsService قائمة بكائنات GoogleAdsRow.

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

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

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

أنواع التعداد غير المعروفة

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

ملاحظات مهمة:

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

التصنيف إلى قطاعات أو شرائح

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

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

على سبيل المثال، الرد على طلب بحث يختار 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.