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

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

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

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

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

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

تقديم طلب

تتطلّب طريقة البحث 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.

السابق
تغيير العناصر
التالي
البيانات الوصفية للمرجع