يجب تقديم تفويض
إجراء طلب بحث في بيانات عدد زيارات البحث باستخدام الفلاتر والمعلمات التي تحدّدها. تُرجع الطريقة صفًا واحدًا أو أكثر يتم تجميعها حسب مفاتيح الصفوف (السمات) التي تحددها. يجب تحديد نطاق زمني لمدة يوم واحد أو أكثر.
عندما يكون التاريخ أحد الأبعاد، يتم حذف أي أيام بدون بيانات من قائمة النتائج. لمعرفة الأيام التي تحتوي على بيانات، يمكنك إصدار طلب بحث بدون فلاتر مجمّعة حسب التاريخ للنطاق الزمني المطلوب.
يتم ترتيب النتائج تنازليًا حسب عدد النقرات. إذا كان هناك صفان لهما نفس عدد النقرات، يتم ترتيبهما بطريقة عشوائية.
يمكنك الاطّلاع على نموذج بايثون لاستدعاء هذه الطريقة.
تخضع واجهة برمجة التطبيقات لقيود داخلية في Search Console ولا تضمن عرض جميع صفوف البيانات، بل تضمن عرض الصفوف العلوية.
معرفة حدود مقدار البيانات المتاحة.
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY} { "startDate": "2015-04-01", "endDate": "2015-05-01", "dimensions": ["country","device"] }
الطلب
طلب HTTP
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
المَعلمات
اسم المعلَمة | القيمة | الوصف |
---|---|---|
مَعلمات المسار | ||
siteUrl |
string |
عنوان URL للموقع الإلكتروني كما هو محدّد في Search Console. أمثلة:
http://www.example.com/ (لموقع إلكتروني يبدأ بعنوان URL) أو
sc-domain:example.com (لموقع إلكتروني على النطاق)
|
التفويض
يتطلب هذا الطلب تفويضًا باستخدام نطاق واحد على الأقل من النطاقات التالية (مزيد من المعلومات حول المصادقة والتفويض).
النطاق |
---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
نص الطلب
في نص الطلب، يمكنك توفير البيانات بالبنية التالية:
{ "startDate": string, "endDate": string, "dimensions": [ string ], "type": string, "dimensionFilterGroups": [ { "groupType": string, "filters": [ { "dimension": string, "operator": string, "expression": string } ] } ], "aggregationType": string, "rowLimit": integer, "startRow": integer }
اسم الموقع | القيمة | الوصف | Notes |
---|---|---|---|
startDate |
string |
[مطلوبة] تاريخ بدء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بتوقيت المحيط الهادئ (UTC - 7:00/8:00). يجب أن يكون أقل من تاريخ الانتهاء أو مساويًا له. هذه القيمة مُدرَجة في النطاق. | |
endDate |
string |
[مطلوبة] تاريخ انتهاء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بتوقيت المحيط الهادئ (UTC - 7:00/8:00). يجب أن يكون أكبر من تاريخ البدء أو مساويًا له. هذه القيمة مُدرَجة في النطاق. | |
dimensions[] |
list |
[اختياري] لا تتوفّر سمات أو أكثر لتجميع النتائج حسبها.يتم تجميع النتائج بالترتيب الذي تقدِّمه لهذه السمات.يمكنك استخدام أي اسم سمة في dimensionFilterGroups[].filters[].dimension بالإضافة إلى السمة "date".ويتم دمج قيم سمات التجميع لإنشاء مفتاح فريد لكل صف نتائج. إذا لم يتم تحديد أي سمات، سيتم دمج كل القيم في صف واحد. ما من حدّ أقصى لعدد السمات التي يمكنك التجميع حسبها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [البلد، الجهاز] | |
searchType |
string |
تمت إزالة هذا العمود. يمكنك استخدام type كبديل.
|
|
type |
string |
[اختياري] يمكنك فلترة النتائج حسب النوع التالي:
|
|
dimensionFilterGroups[] |
list |
[اختياري] صفر أو أكثر من مجموعات الفلاتر المطلوب تطبيقها على قيم تجميع السمات. يجب أن تتطابق جميع مجموعات الفلاتر ليتم عرض صف في الردّ. في مجموعة فلاتر واحدة، يمكنك تحديد ما إذا كانت جميع الفلاتر يجب أن تتطابق أو يجب أن تتطابق واحدة على الأقل. | |
dimensionFilterGroups[].groupType |
string |
تحدّد هذه العلامة ما إذا كان يجب أن تعرض جميع الفلاتر في هذه المجموعة قيمة صحيحة ("و")، أو أن تعرض فلترًا واحدًا أو أكثر القيمة "صحيح" (غير متاح بعد).
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filters[] |
list |
[اختياري] لا تتوفّر أي فلاتر أو أكثر لاختبارها على الصف. يتألف كل فلتر من
اسم السمة وعامل تشغيل وقيمة. الحد الأقصى للطول 4096 حرفًا. أمثلة:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
السمة التي ينطبق عليها هذا الفلتر. يمكنك الفلترة حسب أي سمة مُدرَجة هنا، حتى إذا لم تكن تستخدِم التجميع حسب هذه السمة.
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[اختياري] كيف يجب أن تتطابق (أو لا تتطابق) القيمة المحدّدة مع قيمة السمة للصف.
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filters[].expression |
string |
قيمة الفلتر المطلوب مطابقتها أو استبعادها، حسب عامل التشغيل. | |
aggregationType |
string |
[اختياري] كيفية تجميع البيانات وفي حال تجميعها حسب الموقع الإلكتروني، يتم تجميع كل البيانات الخاصة بالموقع الإلكتروني نفسه، أما إذا تم تجميعها حسب الصفحة، فسيتم تجميع كل البيانات حسب معرّف الموارد المنتظم (URI) الأساسي. في حال الفلترة أو التجميع حسب الصفحة، اختَر "تلقائي"، وإلا يمكنك تجميع البيانات حسب الموقع الإلكتروني أو حسب الصفحة، وفقًا للطريقة التي تريد بها احتساب بياناتك. يمكنك مراجعة مستندات المساعدة لمعرفة كيفية احتساب البيانات بشكل مختلف حسب الموقع الإلكتروني أو حسب الصفحة. ملاحظة: في حال التجميع أو الفلترة حسب الصفحة، لا يمكنك التجميع حسب الموقع الإلكتروني. إذا حدّدت أي قيمة أخرى غير القيمة "تلقائي"، سيتطابق نوع التجميع في النتيجة مع النوع المطلوب، أما إذا طلبت نوعًا غير صالح، فستظهر لك رسالة خطأ. لن تغيّر واجهة برمجة التطبيقات نوع التجميع إذا كان النوع المطلوب غير صالح. القيم المقبولة هي:
|
|
rowLimit |
integer |
[اختياري، النطاق الصالح هو من 1 إلى 25,000، القيمة التلقائية هي 1,000] الحد الأقصى لعدد الصفوف المطلوب عرضها. لتصفُّح النتائج، استخدِم الإزاحة startRow . |
|
startRow |
integer |
[اختياري، القيمة التلقائية هي 0] فهرس صفري للصف الأول في الاستجابة. يجب أن يكون رقمًا غير سالب. إذا تجاوز startRow عدد نتائج طلب البحث، ستكون الاستجابة ناجحة بدون صفوف. |
|
dataState |
string |
[اختياري] إذا كانت "الكل" (غير حساسة لحالة الأحرف)، ستتضمن البيانات بيانات حديثة. إذا كانت الحالة "Final" (غير حساسة لحالة الأحرف) أو إذا تم حذف هذه المَعلمة، لن تتضمّن البيانات المعروضة سوى البيانات النهائية. |
الإجابة
يتم تجميع النتائج وفقًا للأبعاد المحددة في الطلب. وسيتم تجميع كل القيم التي لها مجموعة قيم السمات نفسها في صف واحد. على سبيل المثال، إذا اخترت التجميع حسب سمة البلد، سيتم تجميع كل النتائج التي تخص "الولايات المتحدة" معًا، كما سيتم تجميع كل النتائج عن "mdv" معًا، وهكذا. إذا كنت قد جمّعت حسب البلد والجهاز، فسيتم تجميع كل النتائج عن "الولايات المتحدة، جهاز لوحي"، وسيتم تجميع كل النتائج عن "الولايات المتحدة الأمريكية، جهاز جوّال"، وهكذا. يمكنك الاطّلاع على مستندات تقرير إحصاءات البحث للتعرّف على تفاصيل حول كيفية احتساب النقرات ومرات الظهور وما إلى ذلك ومعنى كلٍّ منها.
يتم ترتيب النتائج حسب عدد النقرات، بترتيب تنازلي، ما لم تجمع النتائج حسب التاريخ، وفي هذه الحالة يتم ترتيب النتائج تصاعديًا حسب التاريخ، أي من الأقدم أو الأحدث إلى آخر مرة. إذا كان هناك ربط بين صفَّين، يكون نظام الترتيب عشوائيًا.
اطّلِع على السمة rowLimit في الطلب لمعرفة الحدّ الأقصى لعدد القيم التي يمكن عرضها.
{ "rows": [ { "keys": [ string ], "clicks": double, "impressions": double, "ctr": double, "position": double } ], "responseAggregationType": string }
اسم الموقع | القيمة | الوصف | Notes |
---|---|---|---|
rows[] |
list |
قائمة بالصفوف المجمَّعة حسب القيم الرئيسية بالترتيب المحدَّد في طلب البحث. | |
rows[].keys[] |
list |
قائمة بقيم السمات لهذا الصف، مجمّعة حسب السمات في الطلب، وبالترتيب المحدّد في الطلب. | |
rows[].clicks |
double |
عدد النقرات للصف. | |
rows[].impressions |
double |
عدد مرات الظهور للصف. | |
rows[].ctr |
double |
نسبة النقر إلى الظهور للصف تتراوح القيم من 0 إلى 1.0، شاملة. | |
rows[].position |
double |
متوسط موضع الظهور في نتائج البحث | |
responseAggregationType |
string |
كيفية تجميع النتائج.يمكنك الاطّلاع على مستندات المساعدة لمعرفة كيف يتم احتساب البيانات بشكل مختلف حسب الموقع الإلكتروني مقارنةً بالصفحة.
القيم المقبولة هي:
|
تجربة
يمكنك استخدام مستكشف واجهات برمجة التطبيقات أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الاستجابة.