اقرأ الأقسام التالية للتعرّف على كيفية إنشاء تقارير البحث في 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".