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

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

مقدمة

تتيح لك "واجهة برمجة التطبيقات لإعداد تقارير المسارات المتعدّدة القنوات" طلب بيانات تقرير "المسارات المتعدّدة القنوات" في "إحصاءات Google". يتألف كل تقرير من إحصاءات مشتقة من البيانات التي تُعيد إرسالها إلى "إحصاءات Google" بواسطة رمز التتبّع، وهي مُنظّمة على شكل سمات ومقاييس. ومن خلال اختيار مجموعة من السمات والمقاييس، يمكنك استخدام Reporting API لإنشاء تقارير مخصّصة حسب مواصفاتك الخاصة.

تحتوي واجهة برمجة التطبيقات على طريقة واحدة تطلب بيانات التقارير وهي: report.get. باستخدام هذه الطريقة، يمكنك تقديم رقم تعريف الجدول المتوافق مع الملف الشخصي الذي تريد استرداد بياناته. بالإضافة إلى ذلك، يمكنك تحديد ما يلي:

  • يشير ذلك المصطلح إلى مجموعة من السمات والمقاييس.
  • نطاق زمني.
  • يشير هذا المصطلح إلى مجموعة من مَعلمات الخيارات التي تتحكّم في البيانات التي يتم عرضها.

توفّر واجهة برمجة التطبيقات طريقة report.get في نقطة نهاية REST: https://www.googleapis.com/analytics/v3/data/mcf. يعرض القسم التالي نموذجًا لطلب ويصف كل مَعلمة من المَعلمات.

الطلب

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

analytics.data.mcf.get()

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

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/mcf
  ?ids=ga:12345
  &metrics=mcf:totalConversions,mcf:totalConversionValue
  &start-date=2011-10-01
  &end-date=2011-10-31

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

يجب تفويض جميع الطلبات إلى واجهة برمجة التطبيقات لإعداد التقارير للمسارات المتعددة القنوات، ويفضل أن يكون ذلك من خلال OAuth 2.0.

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

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

الاسم القيمة مطلوبة ملخّص
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 نعم تمثّل هذه السمة قائمة بالمقاييس المفصولة بفواصل، مثل mcf:totalConversions,mcf:totalConversionValue. يجب أن يحدّد طلب البحث الصالح مقياسًا واحدًا على الأقل.
dimensions string لا قائمة بالسمات المفصولة بفواصل لتقرير "المسارات المتعدّدة القنوات"، مثل mcf:source,mcf:keyword.
sort string لا تمثّل هذه السمة قائمة بالسمات والمقاييس المفصولة بفواصل، ما يشير إلى ترتيب الترتيب واتجاه الترتيب للبيانات المعروضة.
filters string لا فلاتر السمة أو المقياس التي تفرض قيودًا على البيانات المعروضة لطلبك
samplingLevel string لا مستوى أخذ العينات المطلوب. القيم المسموح بها:
  • DEFAULT — تعرض استجابة مع حجم عينة يوازن بين السرعة والدقة.
  • FASTER: لعرض ردّ سريع بحجم عيّنة أصغر
  • HIGHER_PRECISION: لعرض إجابة أكثر دقة باستخدام حجم عينة كبير، ولكن قد يؤدي ذلك إلى بطء الاستجابة.
start-index integer لا الصف الأول من البيانات المطلوب استردادها، بدءًا من 1. استخدِم هذه المَعلمة كآلية تقسيم على صفحات مع المعلَمة max-results.
max-results integer لا تمثّل هذه السمة الحد الأقصى لعدد الصفوف المطلوب تضمينها في الردّ.

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

ids

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

الرجوع إلى أعلى الصفحة

تاريخ البدء

start-date=2011-10-01
مطلوبة.
يجب أن تحدّد جميع طلبات بيانات "المسارات المتعدّدة القنوات" نطاقًا زمنيًا. في حال عدم تضمين المعلمتَين 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 هو 2011-01-01. ما من قيود على الحدّ الأقصى لـ start-date.
تكون التواريخ النسبية دائمًا مرتبطة بالتاريخ الحالي في وقت طلب البحث وتستند إلى المنطقة الزمنية للملف الشخصي المحدّد في طلب البحث.

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

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

الرجوع إلى أعلى الصفحة

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

end-date=2011-10-31
مطلوبة.
يجب أن تحدّد جميع طلبات بيانات "المسارات المتعدّدة القنوات" نطاقًا زمنيًا. في حال عدم تضمين المعلمتَين 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=mcf:source,mcf:keyword
اختياريّ.

تحدِّد مَعلمة السمات مفاتيح البيانات الأساسية لتقرير "المسارات المتعدّدة القنوات"، مثل mcf:source أو mcf:medium. استخدِم السمات لتقسيم مقاييس إحالاتك الناجحة. على سبيل المثال، يمكنك طلب الحصول على إجمالي عدد الإحالات الناجحة التي تؤدي إلى موقعك الإلكتروني، إلا أنّ طلب عدد الإحالات الناجحة مقسّم حسب الوسيط هو الأكثر أهمية. في هذه الحالة، سترى عدد الإحالات الناجحة من نتائج البحث المجانية والإحالة والبريد الإلكتروني وما إلى ذلك.

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

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

القيم غير المتاحة

عندما يتعذّر تحديد قيمة السمة، تستخدم "إحصاءات Google" السلسلة الخاصة (not set).

الرجوع إلى أعلى الصفحة

metrics

metrics=mcf:totalConversions,mcf:totalConversionValue
مطلوبة.

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

عند طلب المقاييس، يُرجى مراعاة ما يلي:

  • يجب أن يوفر أي طلب مقياسًا واحدًا على الأقل، ولا يمكن أن يتكون الطلب من أبعاد فقط.
  • يمكنك توفير 10 مقاييس كحد أقصى لأي طلب بحث.

الرجوع إلى أعلى الصفحة

ترتيب

sort=mcf:source,mcf:medium
اختياريّ.

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

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

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

sort=mcf:source,mcf:medium

للإجابة عن السؤال ذي الصلة "ما هي أهم وسائط الإحالات الناجحة ومن أي مصادر؟"، يمكنك إجراء طلب بحث باستخدام المَعلمة التالية. ويتم ترتيب العمود أولاً حسب mcf:medium ثم حسب mcf:source، وذلك بترتيب تصاعدي:

sort=mcf:medium,mcf:source

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

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

الرجوع إلى أعلى الصفحة

الفلاتر

filters=mcf:medium%3D%3Dreferral
اختياريّ.

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

https://www.googleapis.com/analytics/v3/data/mcf
?ids=mcf:12134
&dimensions=mcf:source
&metrics=mcf:totalConversions
&filters=mcf:medium%3D%3Dreferral
&start-date=2011-10-01
&end-date=2011-10-31

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

الرجوع إلى أعلى الصفحة

samplingLevel

samplingLevel=DEFAULT
اختياريّ.
استخدِم هذه المَعلمة لضبط مستوى العينة (أي عدد الجلسات المستخدَمة لحساب النتيجة) لطلب بحث لإعداد التقارير. وتتوافق القيم المسموح بها مع واجهة الويب وتشمل:
  • DEFAULT — تعرض استجابة مع حجم عينة يوازن بين السرعة والدقة.
  • FASTER: لعرض ردّ سريع بحجم عيّنة أصغر
  • HIGHER_PRECISION: لعرض إجابة أكثر دقة باستخدام حجم عينة كبير، ولكن قد يؤدي ذلك إلى بطء الاستجابة.
إذا لم يتم توفير هذه السمة، سيتم استخدام مستوى العينة DEFAULT.
راجِع قسم أخذ العينات للاطّلاع على تفاصيل عن كيفية حساب النسبة المئوية للجلسات التي تم استخدامها لطلب بحث معيّن.

الرجوع إلى أعلى الصفحة

max-results

max-results=100
اختياريّ.

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

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

الرجوع إلى أعلى الصفحة

الإجابة

في حال نجاح هذا الطلب، يعرض هذا الطلب نص استجابة ببنية JSON المحدّدة أدناه.

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

تنسيق الرد

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

الرجوع إلى أعلى الصفحة

حقول الرد

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

اسم الموقع القيمة الوصف
kind string نوع المورد القيمة هي "analytics#mcfData".
id string رقم تعريف لاستجابة البيانات هذه.
query object يحتوي هذا الكائن على جميع القيم التي تم تمريرها كمعلَمات إلى طلب البحث. ويتم شرح معنى كل حقل في وصف مَعلمة طلب البحث المقابلة له.
query.start-date string تاريخ البدء.
query.end-date string تاريخ الانتهاء.
query.ids string معرّف الجدول الفريد.
query.dimensions[] list قائمة سمات الإحصاءات
query.metrics[] list قائمة بمقاييس الإحصاءات
query.sort[] list قائمة المقاييس أو السمات التي يتم ترتيب البيانات وفقًا لها.
query.filters string قائمة مفصولة بفواصل لفلاتر المقاييس أو السمات.
query.samplingLevel string Requested sampling level.
query.start-index integer فهرس البداية للصفوف. القيمة التلقائية هي 1.
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 لطلبات البحث الكبيرة.
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" أو "MCF_SEQUENCE" فقط كنوع البيانات. تتضمّن رؤوس أعمدة المقاييس أنواع بيانات لقيم المقاييس، مثل "INTEGER" و"DOUBLE" و"CURRENCY" وما إلى ذلك.
totalsForAllResults object إجمالي القيم للمقاييس المطلوبة كأزواج المفتاح/القيمة لأسماء المقاييس وقيمها. ويكون ترتيب القيم الإجمالية للمقاييس مطابقًا لترتيب المقاييس المحدد في الطلب.
rows[] list

تقرير صفوف البيانات، حيث يحتوي كل صف على قائمة Mcf.Rowsمن الكائنات. تمثّل هذه القائمة الداخلية قيم السمات متبوعة بقيم المقاييس بالترتيب نفسه المحدَّد في الطلب. يحتوي كل صف على قائمة تضمّ N حقل، حيث يشير N إلى عدد السمات + عدد المقاييس.

يشمل الكائن Mcf.Rows كائنًا آخر من النوع primitiveValue أو conversionPathValue. ويمكن أن تكون قيم السمات من أي نوع، بينما تكون جميع قيم المقاييس من النوع primitiveValue.

علامة primitiveValue هي مجرد سلسلة ملفوفة في كائن. مثال:

{
  "primitiveValue": "2183"
}

السمة conversionPathValue هي عنصر يلتف حول مصفوفة من العناصر، حيث يحتوي كل عنصر على سلسلة nodeValue وسلسلة interactionType اختيارية. مثال:

{
  "conversionPathValue": [
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    },
    {
      "interactionType" : "CLICK",
      "nodeValue" : "google"
    }
  ]
}

الرجوع إلى أعلى الصفحة

رموز الخطأ

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

الرجوع إلى أعلى الصفحة

تجربة

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

الرجوع إلى أعلى الصفحة

أخذ العينات

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

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

إذا كانت استجابة MCF Reporting API تتضمّن بيانات مستندة إلى عيّنات، سيكون حقل الاستجابة 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)