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

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