रिपोर्ट बनाना

यह Analytics Reporting API v4 की डेवलपर गाइड है. एपीआई की ज़्यादा जानकारी के लिए, एपीआई का रेफ़रंस देखें.

रिपोर्ट

Analytics Reporting API v4 में, रिपोर्ट संसाधन को ऐक्सेस करने के लिए, batchGet तरीका इस्तेमाल किया जाता है. इन सेक्शन में, batchGet के लिए अनुरोध के मुख्य हिस्से और batchGet के जवाब के मुख्य हिस्से के बारे में बताया गया है.

अनुरोध का मुख्य भाग

डेटा का अनुरोध करने के लिए Analytics Reporting API v4 का इस्तेमाल करने के लिए, आपको एक 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.

जवाब का मुख्य भाग

एपीआई अनुरोध का रिस्पॉन्स का मुख्य हिस्सा, रिपोर्ट ऑब्जेक्ट का कलेक्शन है. रिपोर्ट का स्ट्रक्चर ColumnHeader ऑब्जेक्ट में तय किया जाता है. इससे रिपोर्ट में डाइमेंशन, मेट्रिक, और उनके डेटा टाइप की जानकारी मिलती है. डाइमेंशन और मेट्रिक की वैल्यू, data फ़ील्ड में मौजूद होती हैं.

यहां ऊपर दिए गए अनुरोध के सैंपल के तौर पर एक जवाब दिया गया है:

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

मेट्रिक

मेट्रिक को गिना जा सकता है. हर अनुरोध के लिए, कम से कम एक मेट्रिक ऑब्जेक्ट होना चाहिए.

यहां दिए गए उदाहरण में, batchGet तरीके को Sessions मेट्रिक दी गई है, ताकि तारीख की तय सीमा के दौरान सेशन की कुल संख्या की जानकारी मिल सके:

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

not के लिए true तय करने पर, फ़िल्टर इस तरह काम करता है:

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

इस उदाहरण में, batchGet सिर्फ़ वे पेज व्यू दिखाता है जिनकी वैल्यू दो से ज़्यादा है:

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 फ़ील्ड में जाकर, कारोबार का नाम या उपनाम डालें.
  • sortOrder फ़ील्ड में जाकर, क्रम से लगाने का क्रम (ASCENDING या DESCENDING) तय करें.

इस उदाहरण में, 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

not के लिए true तय करने पर, फ़िल्टर इस तरह काम करता है:

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 फ़ील्ड का इस्तेमाल करके उसका नाम डालें.
  • sortOrder फ़ील्ड में जाकर, क्रम तय करने का क्रम (ASCENDING या DESCENDING) तय करें.

उदाहरण के लिए, नीचे दिया गया 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 डेटा के सबसेट का अनुरोध करने के लिए, सेगमेंट का इस्तेमाल करें. उदाहरण के लिए, किसी खास देश या शहर के उपयोगकर्ताओं को एक सेगमेंट में तय किया जा सकता है और ऐसे उपयोगकर्ता जो आपकी साइट के किसी खास हिस्से पर दूसरे हिस्से पर जाते हैं. फ़िल्टर सिर्फ़ वे पंक्तियां दिखाते हैं जो किसी शर्त को पूरा करती हैं, जबकि सेगमेंट, ऐसे उपयोगकर्ताओं, सेशन या इवेंट का सबसेट दिखाते हैं जो सेगमेंट की शर्तों को पूरा करते हैं.

सेगमेंट से अनुरोध करते समय, पक्का करें कि:

  • batchGet तरीके में मौजूद हर ReportRequest में, सेगमेंट की एक जैसी परिभाषाएं होनी चाहिए.
  • डाइमेंशन की सूची में 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"
    }
  ]
}

अगर किसी रिपोर्ट में सैंपल किया गया डेटा शामिल है, तो Analytics Reporting API v4 samplesReadCounts और samplingSpaceSizes फ़ील्ड दिखाता है. अगर नतीजे सैंपल नहीं किए गए हैं, तो इन फ़ील्ड को तय नहीं किया जाएगा.

यहां जवाब का एक उदाहरण दिया गया है. इसमें, तारीख की दो सीमाओं वाले अनुरोध का सैंपल डेटा दिया गया है. नतीजों की गिनती करीब 1.5 करोड़ सेशन के सैंपलिंग स्पेस के करीब 5 लाख नमूनों से की गई थी:

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

खोज नतीजों को पेजों में बांटना

Analytics Reporting API v4, pageToken और pageSize फ़ील्ड का इस्तेमाल करके, रिस्पॉन्स के ऐसे नतीजों को पेज नंबर में डालता है जो कई पेजों में फैले होते हैं. आपको reports.batchGet अनुरोध के जवाब में, nextPageToken पैरामीटर से pageToken मिलता है:

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

अगला कदम

अब आपने रिपोर्ट बनाने से जुड़ी बुनियादी बातों के बारे में जान लिया है, तो एपीआई v4 की बेहतर सुविधाओं पर एक नज़र डालें.