إنشاء تقرير

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

التقارير

يوفّر الإصدار 4 من واجهة برمجة التطبيقات لإعداد التقارير في "إحصاءات Google" طريقة batchGet للوصول إلى مورد التقارير. توضّح الأقسام التالية بنية طلب الطلب لـ batchGet وبنية نص الاستجابة من batchGet.

نص الطلب

لاستخدام الإصدار 4 من واجهة برمجة التطبيقات لإعداد التقارير في "إحصاءات Google" لطلب البيانات، يجب إنشاء عنصر ReportRequest، الذي يستوفي الحد الأدنى من المتطلبات التالية:

  • معرّف ملف شخصي صالح للحقل viewId.
  • إدخال واحد صالح على الأقل في الحقل dateRange
  • إدخال واحد صالح على الأقل في حقل المقاييس.

للعثور على رقم تعريف الملف الشخصي، ابحث عن طريقة ملخصات الحساب أو استخدم مستكشف الحساب. في حال عدم توفير نطاق زمني، يكون النطاق الزمني التلقائي هو: {"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.

نص الاستجابة

نص الاستجابة لطلب واجهة برمجة التطبيقات هو مصفوفة من عناصر الإبلاغ. يتم تعريف بنية التقرير في كائن 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"}]
    }
  ]
}

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

الفلترة

عند إرسال طلب 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، يمكنك أن تطلب منه عرض الأبعاد التي تستوفي معايير معيّنة فقط. لفلترة المكوّنات، في نص الطلب، حدِّد واحدًا أو أكثر dimensionFilterClauses وفي كل DimensionsFilterClause، حدِّد واحدًا أو أكثر. أبعاد الفلاتر حدِّد القيم التالية لكل 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" الحصول على بيانات في نطاقات زمنية متعددة في طلب واحد. سواء حدّد طلبك نطاقًا زمنيًا واحدًا أو نطاقين، يتم عرض البيانات في الكائن 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 من واجهة برمجة التطبيقات لإعداد التقارير في "إحصاءات Google" الحقلين samplesReadCounts والحقول samplingSpaceSizes. إذا لم تكن النتائج مستندة إلى عينات، لن يتم تحديد هذه الحقول.

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

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

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

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