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

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

रिपोर्ट

Analytics रिपोर्टिंग एपीआई v4, रिपोर्ट रिसॉर्स को ऐक्सेस करने के लिए batchGetमैथ देता है. इन सेक्शन में batchGet के लिए, अनुरोध के मुख्य हिस्से के स्ट्रक्चर के बारे में जानकारी दी गई है. साथ ही, batchGet के जवाब के मुख्य हिस्से के स्ट्रक्चर के बारे में भी बताया गया है.

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

डेटा का अनुरोध करने के लिए, Analytics रिपोर्टिंग एपीआई v4 का इस्तेमाल करने के लिए, आपको reportRequest ऑब्जेक्ट बनाना होगा, जिसके लिए ये ज़रूरी शर्तें पूरी करनी होंगी:

  • viewId फ़ील्ड के लिए, मान्य व्यू आईडी.
  • dateRanges फ़ील्ड में कम से कम एक मान्य एंट्री होनी चाहिए.
  • मेट्रिक फ़ील्ड में कम से कम एक मान्य एंट्री.

व्यू आईडी ढूंढने के लिए, खाते की खास जानकारी तरीके को क्वेरी करें या खाता एक्सप्लोरर का इस्तेमाल करें. अगर तारीख की सीमा नहीं दी गई है, तो तारीख की डिफ़ॉल्ट सीमा यह है: {"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 तरीके के ज़रिए ज़्यादा से ज़्यादा पांच रिपोर्ट अनुरोध ऑब्जेक्ट स्वीकार किए जाते हैं. सभी अनुरोध एक ही होने चाहिए dateRange, viewId, segments, samplingLevel, और cohortGroup.

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

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

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

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

उपलब्ध डाइमेंशन और मेट्रिक की सूची पाने के लिए, डाइमेंशन और मेट्रिक एक्सप्लोरर या मेटाडेटा एपीआई का इस्तेमाल किया जा सकता है.

फ़िल्टर करना

batchGet अनुरोध सबमिट करते समय, आप इसे सिर्फ़ ऐसे मेट्रिक दिखाने के लिए कह सकते हैं जो खास शर्तें पूरी करती हों. मेट्रिक को फ़िल्टर करने के लिए, अनुरोध के मुख्य हिस्से में एक या एक से ज़्यादा मेट्रिक फ़िल्टर क्लॉज़ तय करें. साथ ही, हर MetricFilterClause में एक या ज़्यादा मेट्रिक फ़िल्टर के बारे में बताएं. हर 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 सिर्फ़ ऐसे पेज व्यू दिखाता है जिनका मान 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 फ़ील्ड का नाम या उपनाम डालें.
  • 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 अनुरोध सबमिट करते समय, आप उसे सिर्फ़ ऐसे डाइमेंशन दिखाने के लिए कह सकते हैं जो कुछ खास शर्तों को पूरा करते हों. डाइमेंशन को फ़िल्टर करने के लिए, अनुरोध के मुख्य हिस्से में एक या एक से ज़्यादा डाइमेंशन फ़िल्टर क्लॉज़ तय करें. साथ ही, हर DimensionsFilterClause में एक या ज़्यादा डाइमेंशनफ़िल्टर के बारे में बताएं. हर 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 रिपोर्टिंग 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 रिपोर्टिंग एपीआई v4, samplesReadCounts और samplingSpaceSizes फ़ील्ड दिखाता है. अगर नतीजों का सैंपल नहीं लिया जाता है, तो इन फ़ील्ड के बारे में नहीं बताया जाएगा.

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

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

पेजों को क्रम में लगाना

Analytics रिपोर्टिंग एपीआई 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' की बेहतर सुविधाओं पर एक नज़र डालें.