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

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

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

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

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

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

تقديم طلب

تتطلب طريقة البحث SearchGoogleAdsRequest، والذي يتألف السمات التالية:

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