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

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

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

المقدمة

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

مطلوبة.

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

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

تاريخ البدء

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

مطلوبة.

أقرب تاريخ 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" السلسلة الخاصة (غير محدّدة).

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

المقاييس

metrics=mcf:totalConversions,mcf:totalConversionValue

مطلوبة.

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

عند طلب المقاييس، يُرجى وضع ما يلي في الاعتبار:

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

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

ترتيب

sort=mcf:source,mcf:medium

اختياريّ.

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

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

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

sort=mcf:source,mcf:medium

للإجابة عن السؤال ذي الصلة &quot،ما هي أهم وسائط الإحالة الناجحة، ومن أي مصادر・quot. يمكنك إجراء طلب بحث باستخدام المعلَمة التالية. يتم الترتيب أولاً حسب 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=DEFAULT

اختياريّ.

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

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

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

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

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

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

max-results=100

اختياريّ.

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

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

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

الإجابة

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

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

إذا كانت استجابة واجهة برمجة التطبيقات لإعداد التقارير في المسارات المتعددة القنوات تحتوي على عينات من البيانات، سيكون حقل الاستجابة 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)