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

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

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

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

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

مزيد من المعلومات عن الفهرسة مقابل البث

تقديم طلب

تتطلّب طريقة البحث استخدام SearchGoogleAdsRequest، الذي يتألّف من السمات التالية:

• customer_id
• لغة طلب البحث في "إعلانات Google" query التي تشير إلى المرجع المطلوب البحث عنه والسمات والشرائح والمقاييس التي يجب استرجاعها والشروط التي يجب استخدامها لتقييد العناصر التي يتم عرضها
• (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

إنّ الموارد التي يتم عرضها بنوع 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.