إنشاء تقارير البحث في 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

يرسِل طلبًا واحدًا ويبدأ اتصالاً دائمًا بواجهة برمجة التطبيقات لإعداد التقارير في "إعلانات شبكة البحث 360" بغض النظر عن حجم التقرير.

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

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

ملاحظة: تقدّم لغة طلبات البحث في "إعلانات شبكة البحث 360" معلومات تفصيلية حول كيفية استخدام كل عبارة من عبارات طلب البحث.

تقديم طلب

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

ملاحظة: تعرض الأمثلة أدناه طلب HTTP/JSON الأساسي. ويتم استخدامها لتوضيح المفاهيم. ننصحك باستخدام مكتبات العملاء المستندة إلى gRPC لإرسال الطلبات في تطبيقك.

يتألف الطلب من POST HTTP إلى خادم Reporting API في "إعلانات شبكة البحث 360"، على أحد عناوين URL التالية:

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

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

في ما يلي مثال كامل على تعريف التقرير searchStream مضمّن في طلب POST عبر HTTP:

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، استخدِم القائمة المنسدلة نعم/لا لاستبعاد المقاييس غير المتاحة.

ملاحظة: عند الحصول على مقاييس ذات صلة بالعملة (مثل cost_micros) لتاريخ معيّن أو نطاق زمني، احرص على تضمين segments.date في عبارة SELECT.

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

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

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

يمكن اختياره باستخدام

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

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

ملاحظة: يمكنك الاطّلاع على لغة طلبات البحث في "إعلانات شبكة البحث 360" للتعرّف على كيفية استخدام كل عبارة في طلب البحث.

التقسيم

يمكنك تقسيم نتائج البحث عن طريق إضافة حقل 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 للاطّلاع على قائمة بحقول شرائح الجمهور المتاحة التي يمكنك استخدامها.

شرائح متعدّدة

تنبيه: يمكن أن يزداد عدد الصفوف بشكل كبير لكل حقل 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 لهذا المورد

ملاحظة: يتم دائمًا عرض الحقل resource_name الخاص بالمرجع في العبارة FROM، حتى إذا لم يتم تحديده في العبارة SELECT. اطّلِع على حقل 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'

ملاحظة: إذا حدّدت تاريخًا لا يمثّل اليوم الأول من الفترة، ستتلقّى الخطأ MISALIGNED_DATE_FOR_FILTER.

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

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

تواريخ محدّدة مُسبقًا
TODAY	اليوم فقط
YESTERDAY	أمس فقط
LAST_7_DAYS	آخر 7 أيام باستثناء اليوم
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

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

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

• قد يتوفّر لاحقًا مورد من النوع UNKNOWN، ولكن قد يظل UNKNOWN إلى أجل غير مسمى.

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

• قد تتضمّن موارد UNKNOWN مقاييس تفصيلية يمكنك الاستعلام عنها.

• تكون موارد UNKNOWN مرئية بالكامل عادةً في واجهة مستخدِم "إعلانات شبكة البحث 360".