إنشاء تقرير

هذا دليل للمطوِّرين حول الإصدار 4 من Analytics Reporting API. للحصول على مرجع تفصيلي حول واجهة برمجة التطبيقات، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات.

التقارير

يوفّر الإصدار 4 من Analytics Reporting API طريقة batchGet للوصول إلى مورد التقارير. تصف الأقسام التالية بنية نص الطلب لـ batchGet وبنية نص الاستجابة من batchGet.

نص الطلب

لاستخدام الإصدار 4 من Analytics Reporting API من أجل طلب البيانات، يجب إنشاء عنصر ReportRequest والذي يلبّي الحد الأدنى من المتطلبات التالية:

  • رقم تعريف ملف شخصي صالح للحقل viewId.
  • إدخال واحد صالح على الأقل في الحقل dateRanges
  • إدخال واحد صالح على الأقل في حقل metrics

للعثور على رقم تعريف الملف الشخصي، يمكنك الاستعلام عن طريقة ملخّصات الحسابات أو استخدام مستكشف الحسابات. وفي حال عدم توفير نطاق زمني، سيكون النطاق الزمني التلقائي هو: {"startDate": "7daysAgo", "endDate": "yesterday"}.

إليك نموذج طلب يتضمّن الحد الأدنى من الحقول المطلوبة:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:users"}]
    }
  ]
}

تقبل الطريقة batchGet خمسة عناصر من ReportRequest كحد أقصى. يجب أن تحتوي جميع الطلبات على البيانات التالية: dateRange وviewId وsegments samplingLevel وcohortGroup.

نص الاستجابة

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

إليك نموذج رد لنموذج الطلب أعلاه:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

المقاييس

المقاييس عبارة عن قياسات كمية، ويتطلب كل طلب عنصر مقياس واحد على الأقل.

في المثال التالي، يتم توفير المقياس Sessions لطريقة batchGet للحصول على إجمالي عدد الجلسات في النطاق الزمني المحدّد:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
      "metrics": [{"expression": "ga:sessions"}]
    }
  ]
}

يمكنك استخدام مستكشف السمات والمقاييس أو Metadata API للحصول على قائمة السمات والمقاييس المتاحة.

الفلترة

عند إرسال طلب batchGet، يمكنك أن تطلب منه عرض المقاييس التي تستوفي معايير محدّدة فقط. لفلترة المقاييس، حدِّد واحدًا أو أكثر من MetricFilterClauses في نص الطلب، وفي كل MetricFilterClause، حدِّد واحدًا أو أكثر من MetricFilters. في كل MetricFilter، حدِّد القيم لما يلي:

  • metricName
  • not
  • operator
  • comparisonValue

دع {metricName} يمثّل المقياس، و{operator} operator و{comparisonValue} comparisonValue. بعد ذلك يعمل الفلتر على النحو التالي:

if {metricName} {operator} {comparisonValue}
   return the metric

إذا حدّدت true للسمة not، يعمل الفلتر على النحو التالي:

if {metricName} {operator} {comparisonValue}
   do not return the metric

في المثال التالي، لا تعرض الدالة batchGet سوى مشاهدات الصفحة التي تكون قيمتها أكبر من 2:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

التعبيرات

تعبير المقياس هو تعبير رياضي تحدّده أنت على المقاييس الحالية، ويعمل مثل المقاييس المحسوبة الديناميكية. يمكنك تحديد اسم مستعار لتمثيل تعبير المقياس، على سبيل المثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

الترتيب

لترتيب النتائج حسب قيمة مقياس، اتّبِع الخطوات التالية:

  • أدخِل الاسم أو الاسم المستعار من خلال الحقل fieldName.
  • حدِّد نظام الترتيب (ASCENDING أو DESCENDING) من خلال الحقل sortOrder.

في المثال التالي، تعرض batchGet المقاييس التي تم ترتيبها أولاً حسب الجلسات، ثم حسب مشاهدات الصفحة على الويب بترتيب تنازلي:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

الأبعاد

تصف الأبعاد السمات المميزة للمستخدمين وجلساتهم والإجراءات التي يتخذونها. على سبيل المثال، يصف بُعد المدينة سمة من سمات الجلسات، كما يشير إلى المدينة ("القاهرة" أو "دبي") التي نشأت منها كل جلسة. في طلب batchGet، يمكنك تحديد صفر أو أكثر من كائنات السمة، على سبيل المثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics":
      [
        {"expression": "ga:users"}
      ],
      "dimensions":
      [
        {"name": "ga:city"}
      ]
    }
  ]
}

الفلترة

عند إرسال طلب batchGet، يمكنك أن تطلب منه عرض السمات التي تستوفي معايير محدّدة فقط. لفلترة السمات، في نص الطلب، حدِّد واحدًا أو أكثر من DimensionsFilterClauses، وفي كل DimensionsFilterClause، حدِّد واحدًا أو أكثر من DimensionsFilters. في كل DimensionsFilters، حدِّد القيم لما يلي:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

لنفترض أنّ {dimensionName} تمثّل السمة و{operator} وoperator و{expressions} expressions. بعد ذلك يعمل الفلتر على النحو التالي:

if {dimensionName} {operator} {expressions}
    return the dimension

إذا حدّدت true للسمة not، يعمل الفلتر على النحو التالي:

if {dimensionName} {operator} {expressions}
    do not return the dimension

في المثال التالي، يعرض batchGet عدد مرات مشاهدة الصفحات والجلسات في متصفّح Chrome:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

الترتيب

لترتيب النتائج حسب قيمة السمة:

  • أدخِل اسمه من خلال الحقل fieldName.
  • حدِّد نظام الترتيب (ASCENDING أو DESCENDING) من خلال الحقل sortOrder.

على سبيل المثال، تعرض السمة batchGet التالية السمات مرتبة حسب البلد ثم حسب المتصفّح:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

حِزم المدرجات التكرارية

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

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

نطاقات زمنية متعددة

يتيح لك الإصدار 4 من Google Analytics Reporting API إمكانية الحصول على البيانات في نطاقات زمنية متعدّدة ضمن طلب واحد. سواء كان طلبك يحدد نطاقًا زمنيًا واحدًا أو نطاقين، يتم عرض البيانات في كائن dateRangeValue، على سبيل المثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

ترتيب دلتا

عند طلب قيم المقياس في نطاقين زمنيين، يمكنك ترتيب النتائج حسب الفرق بين قيم المقياس في النطاقات الزمنية، على سبيل المثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

سلوك بُعد التاريخ

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

على سبيل المثال، جرِّب طلبًا للسمة ga:date والمقياس ga:sessions في نطاقَين زمنيَين: كانون الثاني (يناير) وفبراير. وفقًا للبيانات المطلوبة في شهر كانون الثاني (يناير)، ستكون القيم لشهر شباط (فبراير) 0، وفي ردّ البيانات المطلوبة في شباط (فبراير)، ستكون القيم في كانون الثاني (يناير) 0.

تقرير كانون الثاني (يناير)

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

تقرير شهر شباط (فبراير)

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

الشرائح

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

عند تقديم طلب باستخدام شرائح، تأكّد مما يلي:

  • يجب أن يحتوي كل ReportRequest ضمن طريقة batchGet على تعريفات شرائح متطابقة.
  • أنت تضيف ga:segment إلى قائمة السمات.

مثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

راجِع النماذج للاطّلاع على مزيد من الأمثلة على الطلبات التي تتضمّن شرائح.

رقم تعريف الشريحة

استخدِم الحقل segmentId لطلب الشرائح. لا يمكنك استخدام كل من segmentId وdynamicSegment لطلب الشرائح.

مثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

أخذ العينات

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

  • اضبُط القيمة على SMALL للحصول على استجابة سريعة بحجم عينة أصغر.
  • يمكنك ضبط القيمة على LARGE للحصول على استجابة أكثر دقة ولكن أبطأ.
  • اضبط القيمة على DEFAULT للحصول على استجابة توازن بين السرعة والدقة.

مثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

إذا تضمّن تقرير بيانات مستندة إلى عيّنات، يعرض الإصدار 4 من Analytics Reporting API حقلَي samplesReadCounts وsamplingSpaceSizes. وإذا لم تكن النتائج مستندة إلى عينات، لن يتم تحديد هذه الحقول.

في ما يلي مثال على استجابة تحتوي على عيّنة بيانات من طلب بنطاقَين زمنيَين. تم احتساب النتائج من حوالي 500 ألف عيّنة لمساحة عيّنة تبلغ حوالي 15 مليون جلسة:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

تقسيم النتائج على عدّة صفحات

يستخدم الإصدار الرابع من "إحصاءات Google Reporting API" الحقلين pageToken وpageSize للتقسيم على صفحات ضمن نتائج الاستجابة التي تشمل صفحات متعددة. ستحصل على pageToken من المَعلمة nextPageToken في الردّ على الطلب reports.batchGet:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

الخطوة التالية

الآن بعد أن اطّلعت على أساسيات إنشاء تقرير، يمكنك إلقاء نظرة على الميزات المتقدمة في الإصدار 4 من واجهة برمجة التطبيقات.