ایجاد گزارش

این یک راهنمای توسعه دهنده برای Analytics Reporting API v4 است. برای مرجع دقیق API، به مرجع API مراجعه کنید.

گزارش ها

Analytics Reporting API v4 متد batchGet را برای دسترسی به منبع Reports فراهم می کند. بخش‌های زیر ساختار بدنه درخواست برای batchGet و ساختار بدنه پاسخ از batchGet را توضیح می‌دهند.

درخواست بدن

برای استفاده از Analytics Reporting API v4 برای درخواست داده، باید یک شی ReportRequest بسازید که حداقل شرایط زیر را دارد:

  • شناسه نمای معتبر برای قسمت viewId .
  • حداقل یک ورودی معتبر در قسمت dateRanges .
  • حداقل یک ورودی معتبر در قسمت معیارها .

برای یافتن شناسه نمایش ، روش خلاصه حساب را جستجو کنید یا از Account Explorer استفاده کنید. اگر محدوده تاریخ ارائه نشده باشد، محدوده تاریخ پیش‌فرض این است: {"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 یکسان داشته باشند .

بدنه پاسخگویی

بدنه پاسخ درخواست API آرایه ای از اشیاء گزارش است. ساختار گزارش در شی 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"}]
    }
  ]
}

می‌توانید از کاوشگر ابعاد و معیارها یا API فراداده برای دریافت فهرست ابعاد و معیارهای موجود استفاده کنید.

فیلتر کردن

هنگام ارسال درخواست batchGet ، می‌توانید از آن بخواهید که تنها معیارهایی را که دارای معیارهای خاص هستند، برگرداند. برای فیلتر کردن معیارها، در متن درخواست، یک یا چند MetricFilterClause و در هر MetricFilterClause ، یک یا چند MetricFilter را مشخص کنید. در هر 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 ، می‌توانید از آن بخواهید که فقط ابعادی را که دارای معیارهای خاص هستند، بازگرداند. برای فیلتر کردن ابعاد، در بدنه درخواست، یک یا چند DimensionsFilterClause و در هر DimensionsFilterClause ، یک یا چند DimensionsFilter را مشخص کنید. در هر 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 بازدید از صفحات و جلسات را در مرورگر کروم برمی‌گرداند:

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"
        }
      ]
    }
  ]
}

محدوده تاریخ چندگانه

Google Analytics Reporting API v4 به شما این امکان را می‌دهد که داده‌ها را در بازه‌های تاریخ متعدد در یک درخواست دریافت کنید. چه درخواست شما یک یا دو محدوده تاریخ را مشخص کند، داده ها در شی 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"
            ]
        }
    ]
},
...

بخش ها

برای درخواست زیرمجموعه ای از داده های Analytics خود، از بخش ها استفاده کنید. به عنوان مثال، می‌توانید کاربرانی را از یک کشور یا شهر خاص در یک بخش و کاربرانی که از بخش خاصی از سایت شما بازدید می‌کنند، در بخش دیگر تعریف کنید. فیلترها فقط ردیف‌هایی را برمی‌گردانند که یک شرط را برآورده می‌کنند، در حالی که بخش‌ها زیرمجموعه‌ای از کاربران، جلسات یا رویدادهایی را برمی‌گردانند که شرایط حاوی بخش‌ها را برآورده می‌کنند.

هنگام درخواست با بخش ها، اطمینان حاصل کنید که:

  • هر 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"}]
    }
  ]
}

نمونه برداری

نمونه‌گیری می‌تواند بر نتایج داده‌های شما تأثیر بگذارد و دلیل رایجی است که چرا مقادیر بازگشتی از API با رابط وب مطابقت ندارند. از فیلد 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"
    }
  ]
}

اگر گزارشی حاوی داده های نمونه برداری شده باشد، Analytics Reporting API v4 فیلدهای samplesReadCounts و samplingSpaceSizes را برمی گرداند. اگر از نتایج نمونه برداری نشود، این فیلدها تعریف نمی شوند.

در زیر یک نمونه پاسخ است که حاوی داده های نمونه برداری شده از یک درخواست با دو محدوده تاریخ است. نتایج از تقریباً 500 هزار نمونه از فضای نمونه برداری تقریباً 15 میلیون جلسه محاسبه شد:

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

صفحه بندی

Analytics Reporting API v4 از فیلدهای 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",
  }]
}

گام بعدی

اکنون که اصول ایجاد گزارش را پوشش داده اید، به ویژگی های پیشرفته API v4 نگاهی بیندازید.