توقّفت مواقع Universal Analytics العادية (UA) عن معالجة البيانات في 1 تموز (يوليو) 2023. ستتوقّف مواقع Universal Analytics 360 عن معالجة البيانات في 1 تموز (يوليو) 2024، وسيتم إيقاف بعض ميزات Universal Analytics 360 نهائيًا قبل ذلك، وذلك بسبب نقلنا البيانات إلى "إحصاءات Google 4". استخدِم Data API للوصول إلى ميزات إعداد التقارير لمواقع "إحصاءات Google 4".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Core Reporting API - الدليل المرجعي

يوفر هذا المستند المرجع الكامل لكل من طلب البحث والردّ المتعلق بالإصدار 3.0 من Core Reporting API.

مقدمة

يمكنك إنشاء طلب بحث في واجهة برمجة التطبيقات الأساسية لإعداد التقارير الخاصة ببيانات تقارير "إحصاءات Google". ويتطلب كل طلب بحث رقم تعريف ملف شخصي، وتاريخَي بدء وانتهاء، ومقياس واحد على الأقل. يمكنك أيضًا توفير مَعلمات طلب بحث إضافية، مثل السمات والفلاتر والشرائح لتحسين طلب البحث. يمكنك الاطّلاع على دليل نظرة عامة للتعرّف على آلية عمل كل هذه المفاهيم معًا.

الطلب

توفّر واجهة برمجة التطبيقات طريقة واحدة لطلب البيانات، وهي:

analytics.data.ga.get()

تظهر هذه الطريقة في مكتبات العملاء المختلفة، وتحتوي على واجهات خاصة بلغة معيّنة لضبط معلَمات طلب البحث.

يمكن أيضًا الاستعلام عن واجهة برمجة التطبيقات كنقطة نهاية REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

تحدّد كل مَعلمة طلب بحث لعنوان URL مَعلمة طلب بحث في واجهة برمجة التطبيقات يجب ترميزها باستخدام عنوان URL.

ملخّص مَعلمات طلب البحث

يلخّص الجدول التالي جميع مَعلمات طلبات البحث التي تقبلها واجهة برمجة التطبيقات الأساسية لإعداد التقارير. انقر على اسم كل مَعلمة للحصول على وصف تفصيلي.

الاسم	القيمة	مطلوبة	ملخّص
`ids`	`string`	نعم	رقم تعريف الجدول الفريد بالصيغة ga:XXXX، حيث يشير XXXX إلى رقم تعريف الملف الشخصي (الملف الشخصي) في "إحصاءات Google" الذي سيسترد طلب البحث البيانات من أجله.
`start-date`	`string`	نعم	تاريخ بدء استرجاع بيانات "إحصاءات Google". يمكن أن تحدّد الطلبات تاريخ بدء بتنسيق `YYYY-MM-DD` أو كتاريخ نسبي (على سبيل المثال، `today` أو `yesterday` أو `NdaysAgo` حيث يكون `N` عددًا صحيحًا موجبًا).
`end-date`	`string`	نعم	تاريخ الانتهاء لاسترجاع بيانات "إحصاءات Google". يمكن أن يحدد الطلب تاريخ انتهاء بتنسيق `YYYY-MM-DD`، أو كتاريخ نسبي (على سبيل المثال، `today` أو `yesterday` أو `NdaysAgo` حيث يكون `N` عددًا صحيحًا موجبًا).
`metrics`	`string`	نعم	تمثّل هذه السمة قائمة بالمقاييس المفصولة بفواصل، مثل `ga:sessions,ga:bounces`.
`dimensions`	`string`	لا	قائمة بالسمات المفصولة بفواصل لبيانات "إحصاءات Google"، مثل `ga:browser,ga:city`.
`sort`	`string`	لا	تمثّل هذه السمة قائمة بالسمات والمقاييس المفصولة بفواصل، ما يشير إلى ترتيب الترتيب واتجاه الترتيب للبيانات المعروضة.
`filters`	`string`	لا	فلاتر السمة أو المقياس التي تفرض قيودًا على البيانات المعروضة لطلبك
`segment`	`string`	لا	يُقسِّم البيانات المعروضة لطلبك.
`samplingLevel`	`string`	لا	مستوى أخذ العينات المطلوب. القيم المسموح بها: `DEFAULT` — تعرض استجابة مع حجم عينة يوازن بين السرعة والدقة. `FASTER`: لعرض ردّ سريع بحجم عيّنة أصغر `HIGHER_PRECISION`: لعرض إجابة أكثر دقة باستخدام حجم عينة كبير، ولكن قد يؤدي ذلك إلى بطء الاستجابة.
`include-empty-rows`	`boolean`	لا	يتم ضبط القيمة تلقائيًا على "صحيح"، وفي حال ضبطها على "خطأ"، سيتم حذف الصفوف التي تكون فيها جميع قيم المقاييس صفرًا من الاستجابة.
`start-index`	`integer`	لا	الصف الأول من البيانات المطلوب استردادها، بدءًا من 1. استخدِم هذه المَعلمة كآلية تقسيم على صفحات إلى جانب المَعلمة `max-results`.
`max-results`	`integer`	لا	تمثّل هذه السمة الحد الأقصى لعدد الصفوف المطلوب تضمينها في الردّ.
`output`	`string`	لا	نوع الإخراج المطلوب لبيانات "إحصاءات Google" التي يتم عرضها في الردّ. القيمتان المقبولتان هما `json` و`dataTable`. الإعدادات التلقائية: `json`.
`fields`	`string`	لا	أداة تحدد مجموعة فرعية من الحقول لتضمينها في الرد.
`prettyPrint`	`string`	لا	لعرض استجابة تتضمن مسافات بادئة وفواصل أسطر. الإعداد التلقائي هو `false`.
`userIp`	`string`	لا	تحدِّد عنوان IP للمستخدم النهائي الذي يتم إجراء طلب البيانات من واجهة برمجة التطبيقات له. تُستخدَم لتحديد الاستخدام لكل عنوان IP.
`quotaUser`	`string`	لا	بديل لـ userIp في الحالات التي يكون فيها عنوان IP للمستخدم غير معروف.
`access_token`	`string`	لا	ومن الطرق الممكنة لتوفير رمز OAuth 2.0 المميز.
`callback`	`string`	لا	اسم دالة معاودة الاتصال في JavaScript التي تعالج الاستجابة. تُستخدَم في طلبات JavaScript JSON-P.
`key`	`string`	لا	يتم استخدامه لتفويض OAuth 1.0a لتحديد تطبيقك للحصول على الحصة. مثلاً: `key=AldefliuhSFADSfasdfasdfASdf`.

تفاصيل مَعلمة طلب البحث

ids

ids=ga:12345

مطلوبة.

المعرّف الفريد المُستخدَم لاسترداد بيانات "إحصاءات Google". يمثّل هذا المعرّف تسلسلاً لمساحة الاسم ga: مع رقم تعريف الملف الشخصي (الملف الشخصي) في "إحصاءات Google". يمكنك استرداد رقم تعريف الملف الشخصي باستخدام طريقة analytics.management.profiles.list التي توفّر id في مورد الملف الشخصي (الملف الشخصي) في Google Analytics Management API.

تاريخ البدء

start-date=2009-04-20

مطلوبة.

يجب أن تحدّد جميع طلبات البيانات من "إحصاءات Google" نطاقًا زمنيًا. في حال عدم تضمين المعلمتَين start-date وend-date في الطلب، سيعرض الخادم رسالة خطأ. يمكن أن تكون قيم التاريخ مرتبطة بتاريخ محدّد باستخدام النمط YYYY-MM-DD أو نسبة مئوية من خلال استخدام today أو yesterday أو النمط NdaysAgo. ويجب أن تتطابق القيم مع [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).

أول تاريخ صالح للسمة start-date هو 2005-01-01. ما من قيود قصوى لتاريخ البدء.

تكون التواريخ النسبية دائمًا مرتبطة بالتاريخ الحالي في وقت طلب البحث وتستند إلى المنطقة الزمنية للملف الشخصي المحدّد في طلب البحث.

مثال على النطاق الزمني لآخر 7 أيام (بدءًا من أمس) باستخدام تواريخ نسبية:

  &start-date=7daysAgo
  &end-date=yesterday

تاريخ الانتهاء

end-date=2009-05-20

مطلوبة.

أول تاريخ صالح للسمة end-date هو 2005-01-01. ما من قيود قصوى على end-date.

مثال على نطاق زمني لآخر 10 أيام (بدءًا من اليوم) باستخدام تواريخ نسبية:

  &start-date=9daysAgo
  &end-date=today

الأبعاد

dimensions=ga:browser,ga:city

اختياريّ.

تقسّم المَعلمة dimensions المقاييس حسب معايير شائعة، على سبيل المثال، حسب ga:browser أو ga:city. يمكنك طلب معرفة إجمالي عدد مشاهدات الصفحة على الويب في موقعك الإلكتروني، ولكن قد يكون من الأفضل طلب عدد مشاهدات الصفحة المقسّمة حسب المتصفح. في هذه الحالة، سترى عدد مشاهدات الصفحة من Firefox وInternet Explorer وChrome وما إلى ذلك.

عند استخدام dimensions في طلب بيانات، يجب الانتباه إلى القيود التالية:

يمكنك توفير 7 أبعاد كحد أقصى في أي طلب بحث.
لا يمكنك إرسال طلب بحث يتألف من سمات فقط، بل يجب دمج أي سمات مطلوبة مع مقياس واحد على الأقل.
يمكن الاستعلام عن سمات معيّنة فقط في طلب البحث نفسه. استخدِم أداة الدمج الصالحة في مرجع المقاييس والسمات للاطّلاع على السمات التي يمكن استخدامها معًا.

metrics

metrics=ga:sessions,ga:bounces

مطلوبة.

الإحصاءات المجمَّعة لنشاط المستخدم في موقعك الإلكتروني، مثل النقرات وعدد مشاهدات الصفحة على الويب إذا كان طلب البحث لا يحتوي على مَعلمة dimensions، ستوفّر المقاييس المعروضة قيمًا مجمّعة للنطاق الزمني المطلوب، مثل إجمالي عدد مرات مشاهدة الصفحة على الويب أو إجمالي عدد مرات الارتداد. ومع ذلك، عند طلب السمات، يتم تقسيم القيم حسب قيمة السمة. على سبيل المثال، يعرض الحقل ga:pageviews المطلوب باستخدام ga:country إجمالي عدد مشاهدات الصفحة على الويب لكل بلد. عند طلب المقاييس، يُرجى أخذ ما يلي في الاعتبار:

يجب أن يوفر أي طلب مقياسًا واحدًا على الأقل، ولا يمكن أن يتكون الطلب من أبعاد فقط.
يمكنك توفير 10 مقاييس كحد أقصى لأي طلب بحث.
يمكن استخدام معظم مجموعات المقاييس من فئات متعددة معًا، بشرط عدم تحديد أي سمات.
ويمكن استخدام أحد المقاييس مع سمات أو مقاييس أخرى، ولكن عندما تنطبق فقط مجموعات صالحة على ذلك المقياس. اطّلِع على مرجِع المقاييس والسمات لمعرفة التفاصيل.

ترتيب

sort=ga:country,ga:browser

اختياريّ.

تمثّل هذه السمة قائمة بالمقاييس والسمات التي تشير إلى ترتيب الترتيب واتجاه الترتيب للبيانات المعروضة.

يتم تحديد الترتيب بالترتيب من اليسار إلى اليمين للمقاييس والسمات المدرَجة.
يتم ترتيب direction تلقائيًا بترتيب تصاعدي ويمكن تغييره إلى تنازلي باستخدام بادئة علامة الطرح (-) في الحقل المطلوب.

يتيح لك ترتيب نتائج طلب البحث طرح أسئلة مختلفة حول بياناتك. على سبيل المثال، للإجابة عن السؤال "ما هي أهم البلدان، وما هي المتصفحات الأكثر استخدامًا؟" يمكنك إجراء استعلام باستخدام المعلمة التالية. ويتم ترتيب العمود أولاً حسب ga:country ثم حسب ga:browser، كليهما بترتيب تصاعدي:

sort=ga:country,ga:browser

للإجابة عن السؤال المتعلق "ما هي أهم المتصفّحات التي أستخدمها والبلدان التي تستخدمها أكثر من غيرها؟"، يمكنك إجراء طلب بحث باستخدام المَعلمة التالية. يتم ترتيب العمود أولاً حسب ga:browser ثم حسب ga:country، وذلك بترتيب تصاعدي:

sort=ga:browser,ga:country

عند استخدام المعلَمة sort، يجب الانتباه إلى ما يلي:

لا يتم ترتيب سوى السمات أو قيم المقاييس التي استخدمتها في المَعلمتَين dimensions أو metrics. إذا كان طلبك مرتَّبًا في حقل لم تتم الإشارة إليه في مَعلمة السمات أو المقاييس، ستظهر لك رسالة خطأ.
يتم ترتيب السلاسل تصاعديًا حسب اللغة en-US تلقائيًا.
يتم فرز الأرقام بترتيب رقمي تصاعديًا افتراضيًا.
يتم ترتيب التواريخ تصاعديًا حسب التاريخ تلقائيًا.

الفلاتر

filters=ga:medium%3D%3Dreferral

بنية الفلتر
عوامل تشغيل الفلتر
فلترة التعبيرات
دمج الفلاتر
- عامل التشغيل OR
- عامل التشغيل AND

اختياريّ.

تعمل معلَمة سلسلة طلب البحث filters على تقييد البيانات التي يتم عرضها من طلبك. لاستخدام المَعلمة filters، أدخِل سمة أو مقياسًا تريد الفلترة عليه، ثم أضِف تعبير الفلتر. على سبيل المثال، يطلب طلب البحث التالي إدراج ga:pageviews وga:browser للملف الشخصي 12134 حيث تبدأ السمة ga:browser بالسلسلة Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

تقيد طلبات البحث التي تمت تصفيتها الصفوف التي يتم تضمينها في النتيجة (أو لا يتم تضمينها). ويتم اختبار كل صف في النتيجة مقابل الفلتر: إذا كان الفلتر مطابقًا، يتم الاحتفاظ بالصف وإذا لم يكن مطابقًا، يتم حذفه.

ترميز عناوين URL: تعمل مكتبات برامج Google API على ترميز عوامل تشغيل الفلاتر تلقائيًا.
فلترة السمات: تحدث الفلترة قبل تجميع أيّ سمات، بحيث تمثّل المقاييس المعروضة إجمالي السمات ذات الصلة فقط. في المثال أعلاه، سيكون عدد مشاهدات الصفحة هو فقط مشاهدات الصفحة التي يكون فيها Firefox هو المتصفح.
فلترة المقاييس: تحدث الفلترة حسب المقاييس بعد تجميع المقاييس.
التركيبات الصالحة: يمكنك الفلترة للوصول إلى سمة أو مقياس ليس جزءًا من طلب البحث، شرط أن تكون جميع السمات أو المقاييس الواردة في الطلب والفلتر مجموعات صالحة. على سبيل المثال، يمكنك إجراء طلب بحث عن قائمة قديمة لعدد مشاهدات الصفحات على الويب، مع الفلترة حسب متصفّح معيّن. اطّلِع على مرجع السمات والمقاييس للحصول على مزيد من المعلومات.

بنية الفلتر

يستخدم عامل تصفية واحد النموذج:

ga:name operator expression

في بناء الجملة هذا:

name - اسم السمة أو المقياس المطلوب الفلترة وفقًا له. على سبيل المثال: فلاتر ga:pageviews على مقياس مشاهدات الصفحة على الويب
عامل التشغيل - يحدّد نوع مطابقة الفلتر المطلوب استخدامه. ترتبط عوامل التشغيل بسمات أو مقاييس.
expression - يوضح القيم المراد تضمينها في النتائج أو استبعادها منها. تستخدم التعبيرات بناء جملة تعبير عادي.

عوامل تشغيل الفلتر

هناك ستة عوامل تشغيل للفلاتر للأبعاد وستة عوامل تشغيل للفلاتر للمقاييس. يجب ترميز عوامل التشغيل بعنوان URL ليتم تضمينها في سلاسل طلبات البحث الخاصة بعناوين URL.

ملاحظة: استخدِم مستكشف طلبات بحث خلاصة البيانات لتصميم الفلاتر التي تحتاج إلى ترميز عناوين URL، لأنّ "مستكشف طلبات البحث" يعمل تلقائيًا على ترميز عناوين URL التي تحتوي على سلاسل ومسافات.

**فلاتر المقاييس**
مُشغِّل	الوصف	نموذج ترميز عنوان URL	أمثلة
`==`	علامة يساوي	`%3D%3D`	عرض نتائج تتضمّن الوقت المستغرَق في الصفحة عشر ثوانٍ بالضبط: `filters=ga:timeOnPage%3D%3D10`
`!=`	لا يساوي	`!%3D`	عرض نتائج عندما يكون الوقت في الصفحة ليس عشر ثوانٍ: `filters=ga:timeOnPage!%3D10`
`>`	أكبر من	`%3E`	عرض نتائج يكون فيها الوقت المستغرَق في الصفحة أكبر من عشر ثوانٍ تمامًا: `filters=ga:timeOnPage%3E10`
`<`	أقل من	`%3C`	عرض نتائج إذا كان الوقت المستغرَق في الصفحة أقل من عشر ثوانٍ تمامًا: `filters=ga:timeOnPage%3C10`
`>=`	أكبر من أو يساوي	`%3E%3D`	عرض نتائج تتضمّن الوقت المستغرَق في الصفحة عشر ثوانٍ أو أكثر: `filters=ga:timeOnPage%3E%3D10`
`<=`	أقل من أو يساوي	`%3C%3D`	عرض نتائج إذا كان الوقت المستغرَق في الصفحة في الصفحة يبلغ 10 ثوانٍ أو أقل: `filters=ga:timeOnPage%3C%3D10`

**فلاتر السمات**
مُشغِّل	الوصف	نموذج ترميز عنوان URL	مثال
`==`	المطابقة التامة	`%3D%3D`	المقاييس المجمّعة التي تكون فيها المدينة إرفاين: `filters=ga:city%3D%3DIrvine`
`!=`	لا يطابق	`!%3D`	المقاييس المجمّعة التي تكون فيها المدينة ليست إرفاين: `filters=ga:city!%3DIrvine`
`=@`	تحتوي على سلسلة فرعية	`%3D@`	المقاييس المجمّعة التي تحتوي فيها المدينة على يورك: `filters=ga:city%3D@York`
`!@`	لا يحتوي على السلسلة الفرعية	`!@`	المقاييس المجمّعة التي لا تتضمّن المدينة فيها يورك: `filters=ga:city!@York`
`=~`	يحتوي على تطابق للتعبير العادي	`%3D~`	المقاييس المجمّعة التي تبدأ فيها المدينة بـ جديد: `filters=ga:city%3D~%5ENew.*` (%5E هو عنوان URL المشفر من الحرف ^ الذي يربط نمطًا في بداية السلسلة).
`!~`	لا يُطابق التعبير العادي	`!~`	المقاييس المجمّعة التي لا تبدأ فيها المدينة بالعبارة جديد: `filters=ga:city!~%5ENew.*`

فلترة التعبيرات

هناك قاعدتان مهمتان لتعبيرات التصفية:

الأحرف المحجوزة في عنوان URL: يجب أن يتم ترميز الأحرف مثل & بعنوان URL بالطريقة المعتادة.
الأحرف المحجوزة: يجب استبدال الفاصلة المنقوطة والفاصلة بشرطة مائلة للخلف عند ظهورها في تعبير:
- فاصلة منقوطة \;
- فاصلة \,
التعبيرات العادية: يمكنك أيضًا استخدام التعبيرات العادية في تعبيرات الفلاتر باستخدام عاملَي التشغيل =~ و!~. وتكون تركيبتها مماثلة لتعبيرات Perl العادية وتتضمّن هذه القواعد الإضافية:
- الحد الأقصى للطول هو 128 حرفًا: تؤدي التعبيرات العادية التي تزيد عن 128 حرفًا إلى عرض رمز حالة 400 Bad Request من الخادم.
- حساسية حالة الأحرف - تكون مطابقة التعبير العادي غير حساسة لحالة الأحرف.

دمج الفلاتر

يمكن دمج الفلاتر باستخدام المنطق المنطقي OR وAND. ويتيح لك ذلك توسيع الحدّ الأقصى المسموح به لتعبير الفلتر، وهو 128 حرفًا.

أو

يتم تحديد عامل التشغيل OR باستخدام فاصلة (,). وله الأولوية على عامل التشغيل AND ولا يجوز استخدامه للجمع بين السمات والمقاييس في التعبير نفسه.

أمثلة: (يجب ترميز كل عنوان URL)

البلد هو إما (الولايات المتحدة أو كندا):
ga:country==United%20States,ga:country==Canada

مستخدمو Firefox على أنظمة تشغيل (Windows أو Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

و

يتم تحديد عامل التشغيل AND باستخدام فاصلة منقوطة (;). يسبقه عامل التشغيل OR ويمكن استخدامه للجمع بين الأبعاد والمقاييس في التعبير نفسه.

أمثلة: (يجب ترميز كل عنوان URL)

البلد هو الولايات المتحدة والمتصفّح هو Firefox:
ga:country==United%20States;ga:browser==Firefox

البلد هو الولايات المتحدة ولا تبدأ اللغة بـ "en":
ga:country==United%20States;ga:language!~^en.*

نظام التشغيل هو (Windows أو Macintosh) والمتصفح (Firefox أو Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

البلد هو الولايات المتحدة والجلسات أكبر من 5:
ga:country==United%20States;ga:sessions>5

قسم

segment=gaid::-10

    segment=sessions::condition::ga:medium%3D%3Dreferral

    segment=users::condition::ga:browser%3D%3DChrome

اختياريّ.

لمعرفة التفاصيل الكاملة حول كيفية طلب شريحة في واجهة برمجة التطبيقات الأساسية لإعداد التقارير، يُرجى الاطّلاع على دليل مطوّر البرامج.

للحصول على نظرة عامة حول الشرائح، راجِع مرجع ميزات الشرائح و الشرائح في مركز المساعدة.

السمات والمقاييس مسموح بها في الشرائح.
لا يمكن استخدام بعض السمات والمقاييس في الشرائح. لمراجعة السمات والمقاييس المسموح بها في الشرائح، انتقِل إلى مستكشف السمات والمقاييس.

ملاحظة: تم إيقاف البادئة dynamic:: نهائيًا اعتبارًا من 27 آذار (مارس) 2014. ننصحك بنقل البيانات إلى البنية الجديدة في أقرب وقت ممكن.

samplingLevel

samplingLevel=DEFAULT

اختياريّ.

استخدِم هذه المَعلمة لضبط مستوى العينة (أي عدد الجلسات المستخدَمة لحساب النتيجة) لطلب بحث لإعداد التقارير. وتتوافق القيم المسموح بها مع واجهة الويب وتشمل:

DEFAULT — تعرض استجابة مع حجم عينة يوازن بين السرعة والدقة.
FASTER: لعرض ردّ سريع بحجم عيّنة أصغر
HIGHER_PRECISION: لعرض إجابة أكثر دقة باستخدام حجم عينة كبير، ولكن قد يؤدي ذلك إلى بطء الاستجابة.

إذا لم يتم توفير هذه السمة، سيتم استخدام مستوى العينة DEFAULT.

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

تضمين-صفوف فارغة

include-empty-rows=true

اختياريّ.

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

start-index

start-index=10

اختياريّ.

إذا لم يتم توفير هذه السمة، سيكون فهرس البدء هو 1. (تستند فهارس النتائج إلى الرقم 1. وهذا يعني أنّ الصف الأول هو الصف 1 وليس الصف 0).max-resultstotalResults

max-results

max-results=100

اختياريّ.

الحد الأقصى لعدد الصفوف المطلوب تضمينها في هذه الاستجابة. يمكنك استخدام هذه السمة مع start-index لاسترداد مجموعة فرعية من العناصر أو استخدامها بمفردها للحد من عدد العناصر التي تم إرجاعها، بدءًا من العنصر الأول. إذا لم يتم توفير max-results، يعرض طلب البحث الحد الأقصى التلقائي وهو 1000 صف.

تعرض واجهة Analytics Core Reporting API من 10,000 صف كحدٍّ أقصى لكل طلب، بغض النظر عن العدد المطلوب. ويمكن أن يعرض أيضًا صفوفًا أقل من المطلوب، إذا لم يكن هناك العدد الذي تتوقّعه من شرائح السمات. على سبيل المثال، هناك أقل من 300 قيمة محتملة للسمة ga:country، لذلك عند التقسيم حسب البلد فقط، لا يمكنك الحصول على أكثر من 300 صف، حتى في حال ضبط السمة max-results على قيمة أعلى.

الإنتاج

output=dataTable

اختياريّ.

استخدِم هذه المَعلمة لضبط نوع ناتج بيانات "إحصاءات Google" التي يتم عرضها في الاستجابة. القيم المسموح بها هي:

json: يؤدي هذا الخيار إلى إخراج سمة rows التلقائية في الاستجابة التي تحتوي على عنصر JSON.
dataTable: يؤدي هذا الخيار إلى إخراج سمة dataTable في الاستجابة تحتوي على عنصر في جدول البيانات. يمكن استخدام الكائن Data Table هذا مباشرةً مع العروض المرئية في "قوائم الأغاني الرائجة على Google".

إذا لم يتم توفير هذه المعلومات، سيتم استخدام استجابة JSON التلقائية.

fields

fields=rows,columnHeaders(name,dataType)

اختياريّ.

يتم تحديد الحقول التي سيتم عرضها في استجابة جزئية. إذا كنت تستخدم مجموعة فرعية فقط من الحقول في استجابة واجهة برمجة التطبيقات، يمكنك استخدام المعلَمة fields لتحديد الحقول التي تريد تضمينها.

يعتمد تنسيق قيمة مَعلمة طلب الحقول بشكل غير دقيق على بنية XPath. يتم تلخيص البنية المتوافقة أدناه.

استخدِم قائمة مفصولة بفواصل لاختيار عدة حقول.
استخدِم a/b لاختيار الحقل b المتداخل في الحقل a، واستخدِم a/b/c لاختيار الحقل c المتداخل داخل الحقل b.
استخدِم أداة اختيار فرعي لطلب مجموعة من الحقول الفرعية المحدّدة للمصفوفات أو الكائنات من خلال وضع التعبيرات بين قوسَين "( )".
على سبيل المثال: تعرض السمة fields=columnHeaders(name,dataType) الحقلين name وdataType فقط في المصفوفة columnHeaders. يمكنك أيضًا تحديد حقل فرعي واحد، حيث يكون fields=columnHeader(name) مساويًا لـ fields=columnHeader/name.

prettyPrint

prettyPrint=false

اختياريّ.

تعرض الردّ بتنسيق يمكن لشخص عادي قراءته إذا كانت true. القيمة التلقائية: false.

quotaUser

quotaUser=4kh4r2h4

اختياريّ.

تتيح لك هذه الميزة فرض حصص لكل مستخدم من تطبيق من جهة الخادم حتى في الحالات التي يكون فيها عنوان IP للمستخدم غير معروف. وقد يحدث ذلك مثلاً في التطبيقات التي تنفّذ مهام cron على App Engine نيابةً عن المستخدم. يمكنك اختيار أي سلسلة عشوائية تعرّف عن المستخدم بشكل فريد، ولكن لا يمكن أن يتجاوز طولها 40 حرفًا.

يؤدي هذا الإجراء إلى إلغاء userIp في حال توفير كليهما.

الإجابة

في حال نجاح هذا الطلب، يعرض هذا الطلب نص استجابة ببنية JSON المحدّدة أدناه. في حال ضبط معلَمة output على dataTable، سيعرض الطلب نص استجابة ببنية JSON (جدول البيانات) المحددة أدناه.

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

JSON

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

حقول الرد

يتم تعريف خصائص بنية نص الاستجابة على النحو التالي:

اسم الموقع	القيمة	الوصف
`kind`	`string`	نوع المورد القيمة هي "analytics#gaData".
`id`	`string`	رقم تعريف لاستجابة البيانات هذه.
`query`	`object`	يحتوي هذا الكائن على جميع القيم التي تم تمريرها كمعلَمات إلى طلب البحث. ويتم شرح معنى كل حقل في وصف مَعلمة طلب البحث المقابلة له.
`query.start-date`	`string`	تاريخ البدء.
`query.end-date`	`string`	تاريخ الانتهاء.
`query.ids`	`string`	معرّف الجدول الفريد.
`query.dimensions[]`	`list`	قائمة سمات الإحصاءات
`query.metrics[]`	`list`	قائمة بمقاييس الإحصاءات
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	يتم ضبط القيمة تلقائيًا على "صحيح"، وفي حال ضبطها على "خطأ"، سيتم حذف الصفوف التي تكون فيها جميع قيم المقاييس صفرًا من الاستجابة.
`query.sort[]`	`list`	قائمة المقاييس أو السمات التي يتم ترتيب البيانات وفقًا لها.
`query.filters`	`string`	قائمة مفصولة بفواصل لفلاتر المقاييس أو السمات.
`query.segment`	`string`	شريحة في "إحصاءات Google"
`query.start-index`	`integer`	بدء الفهرس.
`query.max-results`	`integer`	الحد الأقصى لعدد النتائج في كل صفحة
`startIndex`	`integer`	هو فهرس البداية للصفوف التي حدّدتها معلمة طلب البحث `start-index`. والقيمة التلقائية هي 1.
`itemsPerPage`	`integer`	الحد الأقصى لعدد الصفوف التي يمكن أن تتضمّنها الاستجابة، بغض النظر عن العدد الفعلي للصفوف التي يتم عرضها. إذا تم تحديد معلَمة طلب البحث `max-results`، ستكون قيمة `itemsPerPage` هي الأصغر، أي `max-results` أو 10,000. القيمة التلقائية للسمة `itemsPerPage` هي 1,000.
`totalResults`	`integer`	إجمالي عدد الصفوف في نتيجة طلب البحث، بغض النظر عن عدد الصفوف التي تم عرضها في الرد. وبالنسبة إلى طلبات البحث التي تؤدي إلى عدد كبير من الصفوف، يمكن أن يكون `totalResults` أكبر من `itemsPerPage`. يمكنك الاطّلاع على التنقّل بين الصفحات لمزيد من التوضيح حول `totalResults` و`itemsPerPage` لطلبات البحث الكبيرة.
`startDate`	`string`	تاريخ بدء طلب البيانات، على النحو المحدّد في المعلَمة `start-date`.
`endDate`	`string`	تاريخ انتهاء طلب البيانات، على النحو المحدّد في المعلَمة `end-date`.
`selfLink`	`string`	رابط إلى هذه الصفحة من النتائج لطلب البحث عن البيانات هذا.
`previousLink`	`string`	رابط إلى الصفحة السابقة من النتائج لطلب البحث عن البيانات هذا.
`nextLink`	`string`	رابط إلى الصفحة التالية من النتائج لطلب البحث عن البيانات هذا.
`profileInfo`	`object`	معلومات عن الملف الشخصي (الملف الشخصي) الذي تم طلب بياناته. تتوفر بيانات الملف الشخصي من خلال Google Analytics Management API.
`profileInfo.profileId`	`string`	رقم تعريف الملف الشخصي، مثل `1174`.
`profileInfo.accountId`	`string`	رقم تعريف الحساب الذي ينتمي إليه هذا الملف الشخصي، مثل `30481`.
`profileInfo.webPropertyId`	`string`	معرّف الموقع الإلكتروني الذي ينتمي إليه هذا الملف الشخصي، مثل `UA-30481-1`.
`profileInfo.internalWebPropertyId`	`string`	رقم التعريف الداخلي للموقع الإلكتروني الذي ينتمي إليه هذا الملف الشخصي (الملف الشخصي)، مثل `UA-30481-1`.
`profileInfo.profileName`	`string`	اسم الملف الشخصي (الملف الشخصي).
`profileInfo.tableId`	`string`	رقم تعريف الجدول للملف الشخصي (الملف الشخصي)، يتكون من "ga:" متبوعًا برقم تعريف الملف الشخصي.
`containsSampledData`	`boolean`	صحيح إذا كانت الاستجابة تحتوي على بيانات مستندة إلى عيّنات.
`sampleSize`	`string`	عدد العيّنات المستخدَمة لاحتساب البيانات المستندة إلى عيّنات.
`sampleSpace`	`string`	إجمالي حجم مساحة أخذ العينات. يشير ذلك إلى إجمالي حجم مساحة العيّنة المتاحة التي تم اختيار العيّنات منها.
`columnHeaders[]`	`list`	رؤوس الأعمدة التي تسرد أسماء السمات متبوعة بأسماء المقاييس. يكون ترتيب السمات والمقاييس مطابقًا للترتيب الذي تم تحديده في الطلب من خلال المَعلمتَين `metrics` و`dimensions`. عدد العناوين هو عدد السمات + عدد المقاييس.
`columnHeaders[].name`	`string`	اسم السمة أو المقياس
`columnHeaders[].columnType`	`string`	نوع العمود. إما "السمة" أو "المقياس".
`columnHeaders[].dataType`	`string`	نوع البيانات. تحتوي عناوين أعمدة السمات على `STRING` فقط كنوع البيانات. تتضمّن رؤوس أعمدة المقاييس أنواع بيانات لقيم المقاييس، مثل `INTEGER` و`PERCENT` و`TIME` و`CURRENCY` و`FLOAT` وما إلى ذلك. ويمكنك الاطّلاع على استجابة واجهة برمجة التطبيقات للبيانات الوصفية للتعرّف على كل أنواع البيانات الممكنة.
`totalsForAllResults`	`object`	إجمالي القيم للمقاييس المطلوبة كأزواج المفتاح/القيمة لأسماء المقاييس وقيمها. ويكون ترتيب القيم الإجمالية للمقاييس مطابقًا لترتيب المقاييس المحدد في الطلب.
`rows[]`	`list`	صفوف بيانات "إحصاءات Google"، حيث يحتوي كل صف على قائمة بقيم السمات متبوعة بقيم المقاييس. ترتيب السمات والمقاييس متطابق مع الترتيب المحدّد في الطلب. يحتوي كل صف على قائمة تضمّ N حقل، حيث يشير N إلى عدد السمات + عدد المقاييس.

JSON (جدول البيانات)

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

حقول الرد

يتم تعريف خصائص بنية نص الاستجابة على النحو التالي:

اسم الموقع	القيمة	الوصف
`kind`	`string`	نوع المورد القيمة هي "analytics#gaData".
`id`	`string`	رقم تعريف لاستجابة البيانات هذه.
`query`	`object`	يحتوي هذا الكائن على جميع القيم التي تم تمريرها كمعلَمات إلى طلب البحث. ويتم شرح معنى كل حقل في وصف مَعلمة طلب البحث المقابلة له.
`query.start-date`	`string`	تاريخ البدء.
`query.end-date`	`string`	تاريخ الانتهاء.
`query.ids`	`string`	معرّف الجدول الفريد.
`query.dimensions[]`	`list`	قائمة سمات الإحصاءات
`query.metrics[]`	`list`	قائمة بمقاييس الإحصاءات
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	يتم ضبط القيمة تلقائيًا على "صحيح"، وفي حال ضبطها على "خطأ"، سيتم حذف الصفوف التي تكون فيها جميع قيم المقاييس صفرًا من الاستجابة.
`query.sort[]`	`list`	قائمة المقاييس أو السمات التي يتم ترتيب البيانات وفقًا لها.
`query.filters`	`string`	قائمة مفصولة بفواصل لفلاتر المقاييس أو السمات.
`query.segment`	`string`	شريحة في "إحصاءات Google"
`query.start-index`	`integer`	بدء الفهرس.
`query.max-results`	`integer`	الحد الأقصى لعدد النتائج في كل صفحة
`startIndex`	`integer`	هو فهرس البداية للصفوف التي حدّدتها معلمة طلب البحث `start-index`. والقيمة التلقائية هي 1.
`itemsPerPage`	`integer`	الحد الأقصى لعدد الصفوف التي يمكن أن تتضمّنها الاستجابة، بغض النظر عن العدد الفعلي للصفوف التي يتم عرضها. إذا تم تحديد معلَمة طلب البحث `max-results`، ستكون قيمة `itemsPerPage` هي الأصغر، أي `max-results` أو 10,000. القيمة التلقائية للسمة `itemsPerPage` هي 1,000.
`totalResults`	`integer`	إجمالي عدد الصفوف في نتيجة طلب البحث، بغض النظر عن عدد الصفوف التي تم عرضها في الرد. وبالنسبة إلى طلبات البحث التي تؤدي إلى عدد كبير من الصفوف، يمكن أن يكون `totalResults` أكبر من `itemsPerPage`. يمكنك الاطّلاع على التنقّل بين الصفحات لمزيد من التوضيح حول `totalResults` و`itemsPerPage` لطلبات البحث الكبيرة.
`startDate`	`string`	تاريخ بدء طلب البيانات، على النحو المحدّد في المعلَمة `start-date`.
`endDate`	`string`	تاريخ انتهاء طلب البيانات، على النحو المحدّد في المعلَمة `end-date`.
`selfLink`	`string`	رابط إلى هذه الصفحة من النتائج لطلب البحث عن البيانات هذا.
`previousLink`	`string`	رابط إلى الصفحة السابقة من النتائج لطلب البحث عن البيانات هذا.
`nextLink`	`string`	رابط إلى الصفحة التالية من النتائج لطلب البحث عن البيانات هذا.
`profileInfo`	`object`	معلومات عن الملف الشخصي (الملف الشخصي) الذي تم طلب بياناته. تتوفر بيانات الملف الشخصي من خلال Google Analytics Management API.
`profileInfo.profileId`	`string`	رقم تعريف الملف الشخصي، مثل `1174`.
`profileInfo.accountId`	`string`	رقم تعريف الحساب الذي ينتمي إليه هذا الملف الشخصي، مثل `30481`.
`profileInfo.webPropertyId`	`string`	معرّف الموقع الإلكتروني الذي ينتمي إليه هذا الملف الشخصي، مثل `UA-30481-1`.
`profileInfo.internalWebPropertyId`	`string`	رقم التعريف الداخلي للموقع الإلكتروني الذي ينتمي إليه هذا الملف الشخصي (الملف الشخصي)، مثل `UA-30481-1`.
`profileInfo.profileName`	`string`	اسم الملف الشخصي (الملف الشخصي).
`profileInfo.tableId`	`string`	رقم تعريف الجدول للملف الشخصي (الملف الشخصي)، يتكون من "ga:" متبوعًا برقم تعريف الملف الشخصي.
`containsSampledData`	`boolean`	صحيح إذا كانت الاستجابة تحتوي على بيانات مستندة إلى عيّنات.
`sampleSize`	`string`	عدد العيّنات المستخدَمة لاحتساب البيانات المستندة إلى عيّنات.
`sampleSpace`	`string`	إجمالي حجم مساحة أخذ العينات. يشير ذلك إلى إجمالي حجم مساحة العيّنة المتاحة التي تم اختيار العيّنات منها.
`columnHeaders[]`	`list`	رؤوس الأعمدة التي تسرد أسماء السمات متبوعة بأسماء المقاييس. يكون ترتيب السمات والمقاييس مطابقًا للترتيب الذي تم تحديده في الطلب من خلال المَعلمتَين `metrics` و`dimensions`. عدد العناوين هو عدد السمات + عدد المقاييس.
`columnHeaders[].name`	`string`	اسم السمة أو المقياس
`columnHeaders[].columnType`	`string`	نوع العمود. إما "السمة" أو "المقياس".
`columnHeaders[].dataType`	`string`	نوع البيانات. تحتوي عناوين أعمدة السمات على `STRING` فقط كنوع البيانات. تتضمّن رؤوس أعمدة المقاييس أنواع بيانات لقيم المقاييس، مثل `INTEGER` و`PERCENT` و`TIME` و`CURRENCY` و`FLOAT` وما إلى ذلك. ويمكنك الاطّلاع على استجابة واجهة برمجة التطبيقات للبيانات الوصفية للتعرّف على كل أنواع البيانات الممكنة.
`totalsForAllResults`	`object`	إجمالي القيم للمقاييس المطلوبة كأزواج المفتاح/القيمة لأسماء المقاييس وقيمها. ويكون ترتيب القيم الإجمالية للمقاييس مطابقًا لترتيب المقاييس المحدد في الطلب.
`dataTable`	`object`	تمثّل هذه السمة عنصر جدول البيانات الذي يمكن استخدامه مع الرسوم البيانية من Google.
`dataTable.cols[]`	`list`	قائمة بواصفات الأعمدة للسمات متبوعة بالمقاييس. يكون ترتيب السمات والمقاييس مطابقًا للترتيبات المحدَّدة في الطلب من خلال المَعلمتَين `metrics` و`dimensions`. عدد الأعمدة هو عدد السمات + عدد المقاييس.
`dataTable.cols[].id`	`string`	رقم تعريف يمكن استخدامه للإشارة إلى عمود معيّن (كبديل لاستخدام فهارس الأعمدة). يتم استخدام رقم تعريف السمة أو المقياس لضبط هذه القيمة.
`dataTable.cols[].label`	`string`	تسمية للعمود (والتي قد يتم عرضها من خلال تصور). يتمّ استخدام رقم تعريف السمة أو المقياس لضبط هذه القيمة.
`dataTable.cols[].type`	`string`	نوع البيانات لهذا العمود
`dataTable.rows[]`	`list`	صفوف بيانات "إحصاءات Google" بتنسيق جدول البيانات، حيث يكون كل صف عنصرًا يحتوي على قائمة بقيم الخلايا للسمات متبوعة بمقاييس. ترتيب السمات والمقاييس متطابق مع الترتيب المحدّد في الطلب. تحتوي كل خلية على قائمة من الحقول N، حيث يشير N إلى عدد السمات + عدد المقاييس.

رموز الخطأ

تعرض واجهة برمجة التطبيقات الأساسية لإعداد التقارير رمز حالة HTTP 200 في حال تم قبول الطلب. في حال حدوث خطأ أثناء معالجة طلب بحث، تعرض واجهة برمجة التطبيقات رمز خطأ ووصفًا. يحتاج كل تطبيق يستخدم analytics API إلى تنفيذ منطق مناسب للتعامل مع الأخطاء. للحصول على تفاصيل حول رموز الأخطاء وكيفية التعامل معها، يمكنك قراءة الدليل المرجعي للردود على الأخطاء.

تجربة

يمكنك تجربة طلبات البحث في Core Reporting API.

للاطّلاع على مجموعات صالحة من المقاييس والسمات في طلب بحث، أدخِل قيم نماذج للمعلَمات في مستكشف طلبات البحث. ويتم عرض نتائج نموذج طلب البحث كجدول يحتوي على قيم لجميع المقاييس والسمات المحدّدة.
لتقديم طلب بشأن البيانات المباشرة والاطّلاع على الردّ بتنسيق JSON، جرِّب طريقة analytics.data.ga.get في مستكشف واجهات برمجة تطبيقات البيانات من Google.

أخذ العينات

تحتسب "إحصاءات Google" مجموعات معيّنة من السمات والمقاييس بشكل سريع. لعرض البيانات في وقت معقول، قد تعالج خدمة "إحصاءات Google" عيّنة من البيانات فقط.

يمكنك تحديد مستوى تحليل العيّنات المطلوب استخدامه لطلب معيّن من خلال ضبط المَعلمة samplingLevel.

إذا كانت استجابة واجهة برمجة التطبيقات الأساسية لإعداد التقارير تتضمّن عيّنات بيانات، سيتم عرض حقل الردّ containsSampledData على النحو التالي: true. بالإضافة إلى ذلك، سيوفّر موقعان معلومات عن مستوى تحليل العيّنات لطلب البحث: sampleSize وsampleSpace. باستخدام هاتَين القيمتَين، يمكنك حساب النسبة المئوية للجلسات التي تم استخدامها لطلب البحث. على سبيل المثال، إذا كان sampleSize هو 201,000 وsampleSpace هو 220,000، يستند التقرير إلى (201,000 / 220,000) * 100 = 91.36% من الجلسات.

اطّلِع على أخذ العينات للحصول على وصف عام لأخذ العينات وطريقة استخدامه في "إحصاءات Google".

معالجة نتائج البيانات الكبيرة

إذا كنت تتوقّع أن يعرض طلب البحث مجموعة نتائج كبيرة، اتّبِع الإرشادات الواردة أدناه لمساعدتك في تحسين طلب بحث واجهة برمجة التطبيقات وتجنُّب الأخطاء وتقليل تجاوز الحصص. تجدر الإشارة إلى أنّنا نحدّد أساسًا للأداء من خلال السماح بـ 7 سمات و10 مقاييس كحدّ أقصى في أيّ طلب من واجهة برمجة التطبيقات. مع أنّ بعض طلبات البحث التي تحدّد أعدادًا كبيرة من المقاييس والسمات قد تستغرق وقتًا أطول من غيرها في المعالجة، قد لا يكون الحدّ من عدد المقاييس المطلوبة كافيًا لتحسين أداء طلبات البحث. بدلاً من ذلك، يمكنك استخدام الأساليب التالية للحصول على أفضل نتائج الأداء.

تقليل السمات لكل طلب بحث

تسمح واجهة برمجة التطبيقات بتحديد ما يصل إلى 7 أبعاد في أي طلب واحد. وفي كثير من الأحيان، يجب أن تحسب "إحصاءات Google" نتائج طلبات البحث المعقدة هذه بسرعة. وقد يستغرق ذلك وقتًا طويلاً بشكل خاص إذا كان عدد الصفوف الناتجة مرتفعًا. على سبيل المثال، قد يتطابق طلب البحث عن الكلمات الرئيسية حسب المدينة حسب الساعة مع ملايين الصفوف من البيانات. يمكنك تحسين الأداء عن طريق تقليل عدد الصفوف التي تحتاج "إحصاءات Google" إلى معالجتها من خلال الحدّ من عدد السمات في طلب البحث.

تقسيم الاستعلام حسب النطاق الزمني

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

ترقيم الصفحات

قد يكون تتبّع النتائج طريقة مفيدة لتقسيم مجموعات النتائج الكبيرة إلى أجزاء يمكن إدارتها. يوضّح الحقل totalResults عدد الصفوف المطابقة، في حين يقدّم الحقل itemsPerPage الحد الأقصى لعدد الصفوف التي يمكن عرضها في النتيجة. إذا كانت النسبة مرتفعة من totalResults إلى itemsPerPage، قد تستغرق طلبات البحث الفردية وقتًا أطول من اللازم. إذا كنت تحتاج فقط إلى عدد محدود من الصفوف، لأغراض العرض مثلاً، قد يكون من السهل لك ضبط حد صريح لحجم الردّ من خلال المعلَمة max-results. في المقابل، إذا كان تطبيقك يحتاج إلى معالجة مجموعة كبيرة من النتائج بالكامل، قد يكون طلب الحد الأقصى المسموح به من الصفوف أكثر فعالية.

استخدام برنامج gzip

هناك طريقة سهلة وملائمة لتقليل معدل نقل البيانات المطلوب لكل طلب، وهي تفعيل ضغط gzip. وعلمًا أنّ ذلك يتطلّب وقتًا إضافيًا لوحدة المعالجة المركزية (CPU) لفك ضغط النتائج، فإنّ المفاضلة مع تكاليف الشبكة عادةً ما تكون مهمة جدًا. للحصول على استجابة بترميز gzip، عليك تنفيذ أمرَين: ضبط عنوان Accept-Encoding، وتعديل وكيل المستخدم الخاص بك ليتضمن السلسلة gzip. في ما يلي مثال على عناوين HTTP تم تنسيقها بشكل صحيح لتفعيل ضغط gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)