إنشاء تقرير

هذا دليل المطوِّر إلى الإصدار 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"],
      }
    }
  ]
}

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

يستخدم الإصدار 4 من Analytics 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 من واجهة برمجة التطبيقات.