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

واجهة برمجة التطبيقات الأساسية لإعداد التقارير - الدليل المرجعي

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

المقدمة

يمكنك إجراء طلب بحث عن واجهة برمجة التطبيقات الأساسية لإعداد التقارير لبيانات "إحصاءات 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=ga:12345

مطلوبة.

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

تاريخ البدء

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

مطلوبة.

يجب أن تحدّد جميع طلبات بيانات "إحصاءات 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).

أقرب تاريخ 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=ga:sessions,ga:bounces

مطلوبة.

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

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

ترتيب

sort=ga:country,ga:browser

اختياريّ.

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

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

يتيح لك ترتيب نتائج طلب البحث طرح أسئلة مختلفة حول بياناتك. على سبيل المثال، للإجابة عن السؤال &&;ما هي أهم البلدان، والمتصفّحات التي يستخدمونها: يمكنك إجراء طلب بحث باستخدام المعلمة التالية. مرتّبة أولاً حسب 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
- وعامل التشغيل

اختياريّ.

تؤدي معلّمة سلسلة طلب البحث 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 فلترًا على مقياس مرات مشاهدة الصفحة.
عامل التشغيل: يحدّد نوع مطابقة الفلتر المطلوب استخدامه. وتكون عوامل التشغيل خاصة بأي من الأبعاد أو المقاييس.
التعبير: يشير إلى القيم التي سيتم تضمينها أو استبعادها من النتائج. تستخدم التعبيرات بنية التعبير العادي.

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

وهناك ستة عوامل تشغيل للفلترة للأبعاد و6 عوامل تشغيل للفلاتر للمقاييس. يجب أن تكون عوامل التشغيل مشفّرة بعنوان 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`	عرض النتائج عندما يكون الوقت المستغرَق في الصفحة عشر ثوانٍ أو أقل: `filters=ga:timeOnPage%3C%3D10`

**فلاتر السمات**
المُشغِّل	الوصف	نموذج مشفّر لعنوان URL	مثال
`==`	مطابقة تامة	`%3D%3D`	المقاييس المجمّعة حيث تكون مدينة إيرفين: `filters=ga:city%3D%3DIrvine`
`!=`	لا يطابق	`!%3D`	المقاييس المجمّعة التي لا تكون المدينة فيها إيرفين: `filters=ga:city!%3DIrvine`
`=@`	يحتوي على سلسلة فرعية	`%3D@`	المقاييس المجمّعة التي تتضمّن المدينة York: `filters=ga:city%3D@York`
`!@`	لا يحتوي على سلسلة فرعية	`!@`	المقاييس المجمّعة التي لا تتضمّن المدينة 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 OR 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=DEFAULT

اختياريّ.

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

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

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

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

صفوف فارغة فارغة

include-empty-rows=true

اختياريّ.

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

فهرس البدء

start-index=10

اختياريّ.

إذا لم يتم تقديمه، سيكون فهرس البداية 1. (تستند فهارس النتائج إلى نتيجة واحدة. يعني ذلك أنّ الصف الأول هو الصف 1، وليس الصف 0.) استخدِم هذه المعلّمة كآلية للتقسيم على صفحات مع معلَمة max-results للحالات التي تتجاوز فيها totalResults 10,000 وتريد استرداد الصفوف التي تمت فهرستها عند 10,001 وما بعدها.

الحد الأقصى للنتائج

max-results=100

اختياريّ.

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

تعرض واجهة برمجة التطبيقات الأساسية لإعداد التقارير في "إحصاءات Google " 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 لاختيار حقل "ب" مدمج في الحقل "أ"، واستخدِم a/b/c لاختيار حقل "ج" مدمج داخل الحقل "ب".
يمكنك استخدام أداة اختيار فرعية لطلب مجموعة من الحقول الفرعية المحددة للمصفوفات أو العناصر من خلال وضع التعبيرات بين قوسين "( )".
على سبيل المثال: تعرض fields=columnHeaders(name,dataType) الحقلين name وdataType فقط في المصفوفة columnHeaders. ويمكنك أيضًا تحديد حقل فرعي واحد، حيث يساوي fields=columnHeader(name) السمة fields=columnHeader/name.

طباعة جميلة

prettyPrint=false

اختياريّ.

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

UserUser الحصة

quotaUser=4kh4r2h4

اختياريّ.

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

وتلغي هذه السياسة userIp في حال توفير كليهما.

الإجابة

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

ملاحظة: يشير المصطلح "results;quot&; إلى المجموعة الكاملة من الصفوف التي تطابق طلب البحث، في حين أنّ "answer&answer" تشير إلى مجموعة الصفوف التي يتم عرضها في الصفحة الحالية للنتائج. ويمكن أن تختلف هذه القيم إذا كان إجمالي عدد الأرقام أكبر من حجم الصفحة للاستجابة الحالية، على النحو الموضّح في 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 تنفيذ المنطق الصحيح للتعامل مع الأخطاء. للحصول على تفاصيل عن رموز الخطأ وكيفية معالجتها، يُرجى الاطّلاع على الدليل المرجعي لاستجابات الأخطاء.

جرِّب هذه الميزة الآن.

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

للاطّلاع على التركيبات الصالحة للمقاييس والأبعاد في طلب البحث، أدخِل نماذج القيم للمَعلمات في مستكشف طلبات البحث. تظهر نتائج طلب البحث النموذجي كجدول يحتوي على قيم لجميع المقاييس والأبعاد المحددة.
لتقديم طلب بشأن البيانات المباشرة والاطّلاع على الاستجابة بتنسيق 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)