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

طرق البحث

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

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

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