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

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

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

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

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

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

تقديم طلب

تتوقّع السمة GoogleAdsService.SearchStream قيمة SearchGoogleAdsStreamRequest، وتتوقّع السمة GoogleAdsService.Search قيمة SearchGoogleAdsRequest. يتضمن كلا نوعي الطلبات ما يلي:

  • customer_id
  • تمثّل هذه السمة طلب بحث query بلغة طلب البحث في "إعلانات Google" يحدّد المورد المطلوب البحث عنه، والسمات والشرائح والمقاييس المطلوب استردادها، والشروط المطلوب استخدامها لتقييد العناصر التي يتم عرضها.

استنادًا إلى الطريقة، يتيح الطلب أيضًا الحقول الخاصة بالطريقة:

  • SearchGoogleAdsStreamRequest (SearchStream فقط):
    • سمة summary_row_setting اختيارية لطلب صف ملخّص يحتوي على مقاييس مجمّعة
  • SearchGoogleAdsRequest (Search فقط):
    • ‫page_token اختياري لاسترداد الدفعة التالية من النتائج عند استخدام التنقّل بين الصفحات (تم تثبيت page_size عند 10,000 صف، ويؤدي ضبط page_size في الطلب إلى ظهور خطأ RequestError.PAGE_SIZE_NOT_SUPPORTED)
    • رسالة search_settings اختيارية لضبط return_summary_row وreturn_total_results_count وomit_results
    • قيمة منطقية اختيارية للسمة validate_only للتحقّق من صحة طلب البحث بدون تنفيذه

لمزيد من المعلومات عن لغة طلب البحث في "إعلانات Google"، اطّلِع على دليل لغة طلب البحث في "إعلانات Google".

معالجة ردّ

تعرض السمة GoogleAdsService قائمة بعناصر GoogleAdsRow (إما داخل دفعات SearchGoogleAdsStreamResponse يتم بثها أو في SearchGoogleAdsResponse مقسَّمة على صفحات).

يمثّل كل GoogleAdsRow كائنًا يعرضه طلب بحث، ويتألف من مجموعة من السمات التي تتم تعبئتها استنادًا إلى الحقول المطلوبة في عبارة SELECT. لا تتم تعبئة السمات غير المضمّنة في عبارة SELECT في عناصر GoogleAdsRow في الردّ.

على سبيل المثال، على الرغم من أنّ ad_group_criterion يحتوي على سمة status، لا تتم تعبئة حقل status لسمة ad_group_criterion الخاصة بالصف في ردّ على طلب بحث لا تتضمّن فيه عبارة SELECT السمة ad_group_criterion.status. وبالمثل، لا تتم تعبئة السمة campaign للصف إذا لم يتضمّن البند SELECT أي حقول من المورد campaign.

يمكن أن يحتوي كل GoogleAdsRow على سمات ومقاييس مختلفة عن صف آخر في مجموعة النتائج نفسها، لذا يجب عرض الصفوف كعناصر بدلاً من صفوف ثابتة في جدول.

أنواع التعداد UNKNOWN وUNSPECIFIED

إنّ الموارد التي يتم عرضها بقيمة تعداد UNKNOWN لا تكون متوافقة بالكامل مع إصدار واجهة برمجة التطبيقات هذا، في حين تشير القيمة UNSPECIFIED إلى أنّه لم يتم ضبط حقل تعداد أو لم يتم طلبه في عبارة SELECT. يمكن إنشاء الموارد التي تتضمّن قيمة تعداد UNKNOWN من خلال واجهات أخرى، مثل واجهة مستخدم "إعلانات Google". يمكنك اختيار المقاييس عندما يكون للمورد نوع UNKNOWN، ولكن لا يمكنك تغيير المورد من خلال واجهة برمجة التطبيقات. على سبيل المثال، قد يكون هناك نوع حملة أو نوع إعلان متاح في واجهة المستخدم ولكنه غير متاح في إصدار واجهة برمجة التطبيقات الذي تستعلم عنه.

في ما يلي بعض الاعتبارات التي يجب وضعها في الاعتبار:

  • يمكن أن يتوفّر مورد من النوع UNKNOWN في إصدار لاحق من واجهة برمجة التطبيقات أو يظل UNKNOWN إلى أجل غير مسمى.
  • يمكن أن تظهر عناصر جديدة من النوع UNKNOWN في أي وقت. هذه العناصر متوافقة مع الأنظمة القديمة لأنّ قيمة التعداد UNKNOWN متوفّرة في كل تعداد في واجهة برمجة التطبيقات. يتم عرض الموارد مع UNKNOWN لكي تتمكّن من الاطّلاع على مقاييس الأداء الإجمالية لحسابك بدقة.
  • يمكن أن تحتوي موارد UNKNOWN على مقاييس تفصيلية مرفقة بها يمكن الاستعلام عنها.
  • تكون موارد UNKNOWN عادةً مرئية بالكامل في واجهة مستخدم "إعلانات Google".
  • لا يمكن عادةً تغيير موارد UNKNOWN من خلال واجهة برمجة التطبيقات.

التقسيم

يحتوي الردّ على GoogleAdsRow واحد لكل مجموعة مما يلي:

  • مثيل للمورد الرئيسي المحدّد في عبارة FROM
  • قيمة كل حقل segments محدّد

على سبيل المثال، يحتوي الردّ على طلب بحث يختار 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.

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