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

اطّلِع على الأقسام التالية للتعرّف على كيفية إنشاء تقارير البحث في "الإعلانات على شبكة البحث". 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 صف. لا توجد بيانات مهمة اختلاف الأداء بين طرق التقارير الأصغر (<10000 صف).

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

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

يعرض نموذج طلب البحث هذا بيانات الأداء لحساب آخر 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 من واجهة pyplot.

يتألف الطلب من بروتوكول HTTP من نوع POST يؤدي إلى واجهة برمجة التطبيقات لإعداد التقارير في "إعلانات شبكة البحث 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 مضمَّن في طلب 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 في عبارة 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 value لكل حقل 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".