मेटाडेटा एपीआई - डेवलपर गाइड

इस दस्तावेज़ में बताया गया है कि Google Analytics कॉलम की सूची और एट्रिब्यूट को ऐक्सेस करने के लिए, मेटाडेटा एपीआई का इस्तेमाल कैसे किया जाता है.

सुविधा के बारे में जानकारी

मेटाडेटा एपीआई, Google Analytics रिपोर्टिंग एपीआई में दिखाए गए कॉलम (यानी, डाइमेंशन और मेट्रिक) की सूची दिखाता है. अगर एपीआई आपके लिए नया है, तो मेटाडेटा एपीआई के बारे में जानने के लिए मेटाडेटा एपीआई की खास जानकारी पढ़ें.

शुरू करने से पहले

सभी Google Analytics API एक ही तरीके से ऐक्सेस किए जाते हैं. मेटाडेटा एपीआई का इस्तेमाल शुरू करने से पहले:

  • एपीआई के साथ काम करने वाली प्रोग्रामिंग लैंग्वेज की खास क्लाइंट लाइब्रेरी की पूरी सूची देखने के लिए, क्लाइंट लाइब्रेरी पेज पढ़ें.
  • एपीआई इंटरफ़ेस के बारे में जानने और क्लाइंट लाइब्रेरी के बिना डेटा को ऐक्सेस करने के बारे में जानने के लिए, रेफ़रंस गाइड पढ़ें.

हर क्लाइंट लाइब्रेरी, सभी मेटाडेटा एपीआई डेटा को ऐक्सेस करने के लिए, एक Analytics सेवा ऑब्जेक्ट देती है. मेटाडेटा एपीआई के साथ इस्तेमाल करने के लिए, सेवा ऑब्जेक्ट बनाने के लिए आपको आम तौर पर नीचे दिए गए तरीके अपनाने होंगे:

  1. अपने ऐप्लिकेशन को Google API (एपीआई) कंसोल में रजिस्टर करें.
  2. Analytics सेवा ऑब्जेक्ट बनाएं और एपीआई कुंजी सेट करें.

रजिस्ट्रेशन और एपीआई कुंजी

जब भी आपका ऐप्लिकेशन Analytics API को कोई अनुरोध भेजता है, तब हर बार उसे अपने आप को पहचानने की ज़रूरत होती है. इसके लिए, हर अनुरोध के लिए एपीआई कुंजी शामिल करनी होगी.

एपीआई कुंजी को हासिल करना और उसका इस्तेमाल करना

एपीआई कुंजी पाने के लिए:

  1. एपीआई कंसोल में क्रेडेंशियल पेज खोलें.
  2. यह एपीआई दो तरह के क्रेडेंशियल के साथ काम करता है. अपने प्रोजेक्ट के लिए सही क्रेडेंशियल बनाएं:

    • OAuth 2.0: जब भी आपका ऐप्लिकेशन निजी उपयोगकर्ता के डेटा का अनुरोध करता है, तब उसे अनुरोध के साथ OAuth 2.0 टोकन भेजना चाहिए. आपका ऐप्लिकेशन सबसे पहले क्लाइंट आईडी भेजता है और क्लाइंट-साइड टोकन बनाता है. वेब ऐप्लिकेशन, सेवा खातों या इंस्टॉल किए गए ऐप्लिकेशन के लिए, OAuth 2.0 क्रेडेंशियल जनरेट किया जा सकता है.

      ध्यान दें: इस एपीआई में ऐसा कोई भी तरीका नहीं डाला गया है जिसके लिए OAuth 2.0 की अनुमति ज़रूरी हो. इसलिए, आपको सिर्फ़ एपीआई कुंजियां खरीदनी होंगी. इनके बारे में यहां बताया गया है. हालांकि, अगर आपका ऐप्लिकेशन ऐसे अन्य एपीआई को कॉल करता है जिनके लिए उपयोगकर्ता की अनुमति ज़रूरी है, तब भी आपको OAuth 2.0 क्रेडेंशियल की ज़रूरत होगी.

      ज़्यादा जानकारी के लिए, OAuth 2.0 दस्तावेज़ देखें.

    • एपीआई कुंजियां: ऐसे अनुरोध में जो एपीआई 2.0 का टोकन नहीं देते हैं, उन्हें एपीआई कुंजी भेजनी होगी. कुंजी आपके प्रोजेक्ट की पहचान करती है और एपीआई का ऐक्सेस, कोटा, और रिपोर्ट देती है.

      एपीआई कुंजियों पर कई तरह की पाबंदियां काम करती हैं. अगर आपको ऐसी एपीआई कुंजी की ज़रूरत नहीं है जिसकी ज़रूरत पहले से है, तो Console में क्रेडेंशियल बनाएं > एपीआई कुंजी पर क्लिक करके, एपीआई कुंजी बनाएं. कुंजी का इस्तेमाल करने से पहले, आप उसे प्रतिबंधित कर सकते हैं. ऐसा करने के लिए, आपको कुंजी मैनेज करें पर क्लिक करना होगा और पाबंदियां में से कोई एक चुनना होगा.

अपनी एपीआई कुंजियां सुरक्षित रखने के लिए, एपीआई कुंजियों का सुरक्षित तरीके से इस्तेमाल करने के सबसे सही तरीके अपनाएं.

एपीआई कुंजी मिलने के बाद, आपका ऐप्लिकेशन सभी अनुरोध यूआरएल के लिए, क्वेरी पैरामीटर key=yourAPIKey को जोड़ सकता है.

एपीआई कुंजी को यूआरएल में एम्बेड करना सुरक्षित है; इसे कोड में बदलने की ज़रूरत नहीं होती.

नीचे दिए गए कोड स्निपेट, अलग-अलग क्लाइंट लाइब्रेरी के लिए एपीआई कुंजी सेट करने का तरीका बताते हैं:

Java

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

कॉलम के एट्रिब्यूट

मेटाडेटा एपीआई रिस्पॉन्स में एक attributeNames प्रॉपर्टी होती है, जिसमें कॉलम के सभी मान्य एट्रिब्यूट शामिल होते हैं. हर कॉलम में एक attributes प्रॉपर्टी होती है, जिसमें उन एट्रिब्यूट का एक सबसेट शामिल होता है जो कॉलम पर लागू होते हैं.

मान्य टेबल की पूरी सूची नीचे दी गई है:

इस्तेमाल के उदाहरण

मेटाडेटा एपीआई का इस्तेमाल, नीचे दिए गए इस्तेमाल के मामलों को हल करने के लिए किया जा सकता है:

रोके गए कॉलम

अगर किसी कॉलम (यानी कि डाइमेंशन या मेट्रिक) को बंद कर दिया जाता है, तो इसका status एट्रिब्यूट, DEPRECATED पर सेट हो जाएगा.

नीचे दिया गया स्निपेट status एट्रिब्यूट का इस्तेमाल करके, यह पता लगाने का तरीका बताता है कि कॉलम को बंद किया गया है या नहीं:

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

अगर किसी कॉलम का नाम बदला गया है या उसे हटाया गया है, तो status एट्रिब्यूट को DEPRECATED पर सेट किया जाएगा. साथ ही, बदले गए कॉलम में Id एट्रिब्यूट को replacedBy पर सेट किया जा सकता है.

नीचे दिए गए स्निपेट में, replacedBy एट्रिब्यूट का इस्तेमाल करके, रीप्लेसमेंट कॉलम का आईडी देखने का तरीका बताया गया है:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

कॉलम के नाम

uiName एट्रिब्यूट, डाइमेंशन या मेट्रिक का नाम है. इनका इस्तेमाल, Google Analytics के यूज़र इंटरफ़ेस में किया जाता है, जैसे कि वेब इंटरफ़ेस.

नीचे दिए गए स्निपेट में किसी कॉलम के यूज़र इंटरफ़ेस (यूआई) का नाम पाने का तरीका बताया गया है:

function getColumnName(column) {
  return column.attributes.uiName;
}

अस्थायी कॉलम

अस्थायी कॉलम में, डाइमेंशन और मेट्रिक शामिल होते हैं, जिसमें अंकों वाला इंडेक्स होता है. उदाहरण के लिए, ga:goalXXStarts, ga:dimensionXX, ga:metricXX वगैरह. एक अस्थायी कॉलम में, minTemplateIndex और maxTemplateIndex एट्रिब्यूट होंगे, जो इंडेक्स की रेंज के बारे में बताते हैं.

नीचे दिए गए स्निपेट में यह देखने का तरीका बताया गया है कि किसी कॉलम का लेआउट है या नहीं:

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

नीचे दिए गए स्निपेट में, पब्लिशर को मान्य आईडी की सूची पाने का तरीका बताया गया है:

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

कैलकुलेट किए गए कॉलम

दूसरे कॉलम का हिसाब लगाने के बाद मिलने वाले कॉलम में calculation एट्रिब्यूट होगा. उदाहरण के लिए, ga:percentNewSessions का हिसाब ga:newSessions / ga:sessions है.

इस उदाहरण में यह बताया गया है कि कॉलम की गिनती कैसे की जाती है और कॉलम को कैसे कैलकुलेट किया जाता है:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

कॉलम और सेगमेंट

allowedInSegments एट्रिब्यूट से यह पता लगाया जा सकता है कि सेगमेंट क्वेरी पैरामीटर में किसी कॉलम का इस्तेमाल किया जा सकता है या नहीं.

इस उदाहरण में बताया गया है कि सेगमेंट में कॉलम का इस्तेमाल किया जा सकता है या नहीं:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

एपीआई वर्शन में जोड़ा गया

addedInApiVersion एट्रिब्यूट का इस्तेमाल करके यह जानें कि किसी खास वर्शन के रिपोर्टिंग एपीआई में, कॉलम का इस्तेमाल किया जा सकता है या नहीं. उदाहरण के लिए, यहां दिए गए फ़ंक्शन को कॉल करके पुष्टि करें कि कॉलम का इस्तेमाल Core Reporting API V3 में किया जा सकता है: 

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

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

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

कैश मेमोरी में सेव किए गए रिस्पॉन्स को देखा जा रहा है

अगर मेटाडेटा मेटाडेटा के रिस्पॉन्स से मिले ETag वैल्यू की तुलना की जाती है और यह कैश मेमोरी में सेव किए गए रिसॉर्स के लिए, ETag वैल्यू के बराबर है, तो इसका मतलब है कि कैश मेमोरी में सेव किया गया वर्शन मौजूदा है. अगर ई-टैग एक जैसे नहीं हैं, तो अपने ऐप्लिकेशन को अपडेट करें और नए रिस्पॉन्स के साथ कैश मेमोरी को रीफ़्रेश करें.

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

API अनुरोध के साथ ETag का इस्तेमाल करना

अगर आपके पास कॉलम कलेक्शन का कैश मेमोरी में सेव किया गया वर्शन है, तो आप If-None-Match एचटीटीपी हेडर फ़ील्ड सेट करके, मेटाडेटा एपीआई अनुरोध में इसकी ETag वैल्यू शामिल करें. मेटाडेटा API, ETag वैल्यू की जांच करेगा. साथ ही, रिसॉर्स के अपडेट किए गए वर्शन और 200 OK एचटीटीपी स्टेटस या 304 Not Modified रिस्पॉन्स के साथ खाली जवाब के साथ, कैश मेमोरी में सेव किया गया वर्शन अपडेट करेगा.