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

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

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

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

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

مزيد من المعلومات عن الترقيم مقابل البث.

تقديم طلب

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

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