إنشاء تقارير البحث في Search Ads 360 Reporting API

اقرأ الأقسام التالية للتعرّف على كيفية إنشاء تقارير البحث في Search Ads 360 Reporting API.

خدمة البحث

تقدّم Search Ads 360 Reporting API خدمة خاصة للبحث وإعداد التقارير.

SearchAds360Service هي خدمة موحَّدة لاسترداد العناصر وإعداد التقارير عنها، وتوفّر طريقتَين للبحث: SearchStream وSearch. يتم تمرير عمليات البحث في سلسلة طلب بحث مكتوبة بلغة طلب البحث في "إعلانات شبكة البحث 360". يمكنك تحديد طلبات البحث لإجراء ما يلي:

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

تعرض كلتا طريقتي البحث جميع الصفوف التي تطابق طلب بحثك. على سبيل المثال، عند استرداد campaign.id وcampaign.name وmetrics.clicks، تعرض واجهة برمجة التطبيقات SearchAds360Row تحتوي على عنصر حملة مع مجموعة حقلَي id وname وكائن metrics مع مجموعة الحقول clicks الخاصة بها.

طرق البحث

SearchStream

تُرسِل طلبًا واحدًا وتبدأ اتصالاً دائمًا بـ Search Ads 360 Reporting API بغض النظر عن حجم التقرير.

  • تبدأ حزم البيانات في التنزيل على الفور مع تخزين النتيجة الكاملة مؤقتًا في المخزن المؤقت للبيانات.
  • يمكن أن تبدأ التعليمة البرمجية في قراءة البيانات المخزنة مؤقتًا دون الحاجة إلى انتظار انتهاء البث بالكامل.
Search

يتم إرسال طلبات متعدّدة مقسّمة على صفحات لتنزيل التقرير بالكامل.

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

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

مثال على طلب البحث

يعرض نموذج طلب البحث هذا بيانات الأداء لأحد الحسابات خلال آخر 30 يومًا حسب الحملة، مقسّمةً حسب الجهاز:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

تقديم طلب

لتقديم طلب، يجب تمرير سلسلة customer_id وquery إلى الواجهة SearchAds360Service.SearchStream أو SearchAds360Service.Search.

يتألف الطلب من POST HTTP يؤدي إلى خادم Search Ads 360 Reporting API على أي من عنوانَي URL التاليَين:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

في ما يلي مثال كامل لتعريف التقرير الخاص بـ searchStream الذي تم تضمينه في طلب HTTP POST:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

معالجة الرد

تعرض SearchAds360Service قائمة بكائنات SearchAds360Row.

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

على سبيل المثال، يملأ الاستعلام أدناه كل عنصر SearchAds360Row باستخدام campaign.id وcampaign.name وcampaign.status فقط. ويتم حذف السمات الأخرى، مثل campaign.engine_id أو campaign.bidding_strategy_type.

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

المستندات المرجعية

يتضمّن قسم المراجع جميع المعلومات التي تحتاجها لاستخدام كل أداة بشكل صحيح. وتتوفر صفحة واحدة لكل مورد، على سبيل المثال ad_group وcampaign. تسرد صفحتَا segments وmetrics جميع حقول الشرائح والمقاييس المتاحة.

بعض الموارد والشرائح والمقاييس غير متوافقة ولا يمكن استخدامها معًا، في حين أن البعض الآخر متوافق تمامًا ويتكامل مع بعضها البعض. تتضمن كل صفحة من صفحات الموارد المعلومات التالية (إن كانت متاحة ومناسبة) والمزيد:

الموارد المنسوبة

بالنسبة إلى بعض الموارد، قد يتوفّر لك خيار ضم الموارد ذات الصلة ضمنيًا من خلال اختيار حقولها مع حقول المورد في عبارة FROM. على سبيل المثال، المورد campaign هو مورد مرتبط بمورد ad_group. هذا يعني أنه يمكنك تضمين حقول مثل campaign.id وcampaign.bidding_strategy_type في طلب البحث عند استخدام ad_group في عبارة FROM.

يسرد قسم الموارد المحدَّدة الموارد المنسوبة المتاحة. لم تنسب بعض الموارد موارد.

عمود حقول الموارد

يتم تضمين جميع حقول المورد في عمود حقول الموارد. يرتبط كل حقل موارد بمزيد من التفاصيل حول الحقل، بما في ذلك الوصف والفئة ونوع البيانات ونوع عنوان URL والإعداد القابل للتصفية والتحديد والفرز والمكرر.

عمود الشرائح

لا يمكن اختيار كل حقول الشرائح باستخدام مورد معيّن.

يسرد عمود الشرائح حقول segments التي يمكنك استخدامها في نفس عبارة SELECT مثل حقول المورد. يرتبط كل حقل بالتفاصيل الكاملة حول الحقل، بما في ذلك الوصف والفئة ونوع البيانات ونوع عنوان URL والإعداد القابل للتصفية والتحديد والترتيب والمكرر. إذا كنت تستخدم المورد في عبارة FROM، يمكنك استخدام القائمة المنسدلة نعم/لا لفلترة المقاطع غير المتاحة.

عمود المقاييس

لا يمكن اختيار بعض حقول المقاييس باستخدام مورد معيّن.

يسرد عمود المقاييس حقول metrics التي يمكنك استخدامها في عبارة SELECT نفسها مثل حقول المورد. يرتبط كل حقل بالتفاصيل الكاملة حول الحقل، بما في ذلك الوصف والفئة ونوع البيانات ونوع عنوان URL والإعداد القابل للتصفية والتحديد والترتيب والمكرر. إذا كنت تستخدم المورد في عبارة FROM، استخدِم القائمة المنسدلة نعم/لا لفلترة المقاييس غير المتاحة.

تقسيم الموارد

تحتوي بعض الموارد على حقول تقسيم للموارد يمكنك اختيارها عندما يكون المورد ضمن عبارة FROM. على سبيل المثال، إذا اخترت حقل مورد campaign، مثل campaign.name، عند استخدام campaign_budget في عبارة FROM، سيتم عرض campaign.resource_name campaign.resource_name تلقائيًا وتقسيمه إلى شرائح، لأن campaign هو مورد تقسيم لـ campaign_budget.

يسرد قسم تقسيم الموارد موارد التقسيم المتاحة. لا تحتوي بعض الموارد على موارد تقسيم.

يمكن الاختيار مع

تكون بعض حقول segments غير متوافقة مع الموارد والشرائح والمقاييس الأخرى.

تحتوي صفحة segments على عنصر قابل للاختيار مع لكل حقل segments يسرد جميع حقول الموارد المتوافقة وحقول metrics وحقول segments الأخرى التي يمكنك تضمينها في عبارة SELECT الخاصة بك.

التصنيف إلى قطاعات أو شرائح

يمكنك تقسيم نتائج البحث من خلال إضافة الحقل segments.FIELD_NAME إلى عبارة SELECT في طلب البحث.

على سبيل المثال، ينتج عن segments.device في طلب البحث أدناه تقرير يحتوي على صف للحقل impressions لكل جهاز للمورد المحدد في عبارة FROM.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

تبدو النتائج التي تم عرضها من خلال SearchAds360Service.SearchStream على شكل سلسلة JSON هذه:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

راجِع segments للحصول على قائمة بحقول الشرائح المتاحة التي يمكنك استخدامها.

شرائح متعددة

يمكنك تحديد مقاطع متعددة في عبارة SELECT من طلب البحث. وتحتوي الاستجابة على كائن SearchAds360Row واحد لكل مجموعة من مثيل المورد الرئيسي المحدد في عبارة FROM والقيمة لكل حقل segment محدّد.

على سبيل المثال، سيعرض الاستعلام التالي صفًا واحدًا لكل مجموعة من campaign وsegments.ad_network_type وsegments.date.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

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

ينتج عن المثال التالي لطلب البحث صف واحد لكل حملة، وليس صفًا واحدًا لكل قيمة مختلفة في الحقل campaign.status.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

التصنيف الضمني

يتم تقسيم كل تقرير بشكل مبدئي حسب المورد المحدّد في العبارة FROM. يتمّ تقسيم المقاييس حسب الحقل resource_name في هذا المورد.

يعرض نموذج طلب البحث هذا تلقائيًا دالة ad_group.resource_name ويستخدمها ضمنيًا لتقسيم المقاييس على مستوى ad_group.

SELECT metrics.impressions
FROM ad_group

تبدو سلسلة JSON المعروضة مشابهة لما يلي:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

شرائح التاريخ الأساسية

يمكنك استخدام شرائح التاريخ الأساسية في الفقرة WHERE لتحديد تاريخ أو فترة زمنية.

تُعرَف حقول الشرائح التالية باسم شرائح التاريخ الأساسي: segments.date وsegments.week وsegments.month وsegments.quarter وsegments.year.

يعرض نموذج طلب البحث هذا مقاييس clicks للحملة لآخر 30 يومًا.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

تمثّل حقول شرائح التاريخ الأساسية استثناء للقاعدة العامة التي لا يمكنك استخدام حقل الشرائح فيها في عبارة WHERE، ما لم تُدرج أيضًا الحقل في عبارة SELECT. راجع التصفية المحظورة لمزيد من المعلومات.

قواعد شرائح التاريخ الأساسية:

  • يمكنك استخدام حقل تاريخ أساسي في بند WHERE بدون تضمينه في بند SELECT. يمكنك أيضًا تضمين الحقل في كلتا العبارتين إذا أردت ذلك.

    يعرض نموذج طلب البحث هذا مقاييس clicks حسب اسم الحملة خلال النطاق الزمني. يُرجى العلم أنّ السمة segments.date غير مضمّنة في البند SELECT.

    SELECT
    campaign.name,
    metrics.clicks
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

  • إذا ضمّنت حقل تاريخ أساسي في بند SELECT، عليك تحديد تاريخ أو نطاق زمني محدود في بند WHERE. ليس بالضرورة أن تتطابق الحقول المحدّدة في الفقرتين SELECT وWHERE.

    يعرض نموذج طلب البحث هذا مقاييس clicks حسب اسم الحملة، مقسَّمة حسب الشهر لجميع الأيام في النطاق الزمني.

    SELECT
  campaign.name,
  metrics.clicks,
  segments.month
FROM campaign
WHERE segments.date > '2022-02-01'
  AND segments.date < '2022-03-01'

تواريخ ISO 8601

يمكنك استخدام تنسيق YYYY-MM-DD (ISO 8601) لتحديد التواريخ والنطاقات الزمنية، على سبيل المثال:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

بالنسبة إلى شرائح التاريخ الأساسية التي تتطلّب فترة زمنية (segments.week، segments.month، segments.quarter)، يمكنك استخدام عامل التشغيل = مع اليوم الأول من الفترة الزمنية، على سبيل المثال:

WHERE segments.month = '2022-06-01'

التواريخ المحدَّدة مسبقًا

يمكنك أيضًا استخدام التواريخ والنطاقات الزمنية المحدّدة مسبقًا التالية:

التواريخ المحدَّدة مسبقًا
TODAY اليوم فقط.
YESTERDAY أمس فقط.
LAST_7_DAYS الأيام السبعة السابقة ولا تشمل اليوم
LAST_BUSINESS_WEEK أسبوع العمل السابق لمدة 5 أيام (من الاثنين إلى الجمعة)
THIS_MONTH جميع الأيام في الشهر الحالي
LAST_MONTH جميع الأيام في الشهر السابق
LAST_14_DAYS الأيام الـ 14 السابقة باستثناء اليوم
LAST_30_DAYS آخر 30 يومًا باستثناء اليوم
THIS_WEEK_SUN_TODAY الفترة بين يوم الأحد السابق واليوم الحالي.
THIS_WEEK_MON_TODAY الفترة بين يوم الاثنين السابق واليوم الحالي.
LAST_WEEK_SUN_SAT فترة 7 أيام بدءًا من يوم الأحد السابق.
LAST_WEEK_MON_SUN فترة تبلغ 7 أيام بدءًا من يوم الاثنين السابق

مثال:

WHERE segments.date DURING LAST_30_DAYS

صفر مقاييس

عند تنفيذ طلب بحث، قد تصادف بعض المقاييس ذات القيمة صفر لبعض الكيانات. تعرَّف على كيفية التعامل مع صفر مقاييس في طلبات البحث.

أنواع تعداد غير معروفة

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

لا يزال بإمكانك اختيار المقاييس عندما يكون نوع المورد UNKNOWN، ولكن يجب وضع ما يلي في الاعتبار:

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