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

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

البحث في الخدمة

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

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

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

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

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

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

يعرض مثال طلب البحث هذا بيانات الأداء لحساب خلال آخر 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، استخدِم القائمة المنسدلة نعم/لا لfiltrare out المقاييس غير المتاحة.

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

تحتوي بعض المراجع على حقول مرجعية لتقسيم البيانات يمكنك اختيارها عندما يكون المرجع في عبارة FROM. على سبيل المثال، إذا اخترت حقل موارد campaign، مثل campaign.name، عند استخدام campaign_budget في عبارة FROMcampaign.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'

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

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

مثال:

WHERE segments.date DURING LAST_30_DAYS

بدون مقاييس

عند تنفيذ طلب بحث، قد تظهر لك مقاييس ذات قيمة صفر لبعض الكيانات. مزيد من المعلومات عن كيفية التعامل مع المقاييس الصفرية في طلبات البحث

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

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

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

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