Metadata API - डेवलपर गाइड

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

शुरुआती जानकारी

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

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

सभी Google Analytics एपीआई को एक ही तरह से ऐक्सेस किया जाता है. Metadata 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 दस्तावेज़ देखें.

   • एपीआई पासकोड: OAuth 2.0 टोकन न देने वाले अनुरोध के लिए, एपीआई कुंजी भेजना ज़रूरी है. कुंजी आपके प्रोजेक्ट की पहचान करती है. साथ ही, एपीआई ऐक्सेस, कोटा, और रिपोर्ट उपलब्ध कराती है.

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

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

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

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

ध्यान दें: अगर आपके ऐप्लिकेशन ने पहले ही पुष्टि कर ली है और किसी उपयोगकर्ता (उदाहरण के लिए, OAuth 2.0 का इस्तेमाल करने) को अनुमति दी है, तो किसी आधिकारिक Analytics सेवा ऑब्जेक्ट का इस्तेमाल करके Metadata API का किया गया कोई भी अनुरोध, आपके ऐप्लिकेशन की पहचान अपने-आप कर लेगा. इस मामले में, आपको एपीआई पासकोड सेट करने की ज़रूरत नहीं है.

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

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>

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

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

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

** appUiName एट्रिब्यूट अब काम नहीं करता. आपको appUiName एट्रिब्यूट का इस्तेमाल करने वाले सभी कोड हटा देने चाहिए और सिर्फ़ uiName एट्रिब्यूट का इस्तेमाल करना चाहिए. एट्रिब्यूट हटाने के बारे में जानने के लिए, डेटा रोकने की नीति देखें.

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

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

• अब काम नहीं करने वाले कॉलम
• कॉलम के नाम
• टेंप्लेट किए गए कॉलम
• आपके दिए गए फ़ॉर्मूला के आधार पर तैयार किए गए कॉलम
• कॉलम और सेगमेंट
• एपीआई के वर्शन
• इटैग

बहिष्कृत कॉलम

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

ध्यान दें: आपके ऐप्लिकेशन को रिपोर्टिंग एपीआई क्वेरी में DEPRECATED कॉलम की जांच करनी चाहिए और उसका इस्तेमाल बंद कर देना चाहिए. अगर रीप्लेसमेंट कॉलम उपलब्ध है, तो इसका इस्तेमाल किया जाना चाहिए. रोके जाने की अवधि खत्म होने पर, DEPRECATED कॉलम को Reporting और Metadata API से हटा दिया जाएगा. इसके बाद, उन कॉलम की क्वेरी में गड़बड़ी दिखेगी.

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

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

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

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

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

कॉलम के नाम

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

appUiName एट्रिब्यूट अब काम नहीं करता. आपको appUiName एट्रिब्यूट का इस्तेमाल करने वाले सभी कोड हटा देने चाहिए और सिर्फ़ uiName एट्रिब्यूट का इस्तेमाल करना चाहिए. एट्रिब्यूट हटाने के बारे में जानने के लिए, डेटा रोकने की नीति देखें.

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

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 एट्रिब्यूट का इस्तेमाल करके देखें कि किसी खास वर्शन के Reporting API में, कॉलम का इस्तेमाल किया जा सकता है या नहीं. उदाहरण के लिए, नीचे दिए गए फ़ंक्शन को कॉल करके पुष्टि करें कि कॉलम का इस्तेमाल Core Reporting API V3 में किया जा सकता है:

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

ETag

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

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

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

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

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

एपीआई अनुरोध के साथ ETag का इस्तेमाल करना

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

ध्यान दें: Metadata API के अनुरोध करने के लिए, जिस क्लाइंट लाइब्रेरी का इस्तेमाल किया जा रहा है वह ETag की पहचान कर सकती है और उसका इस्तेमाल कर सकती है. इसके अलावा, ऐसा करने में मदद भी कर सकती है. ETag की सुविधा उपलब्ध है या नहीं, इसकी पुष्टि करने के लिए लाइब्रेरी के दस्तावेज़ पढ़ें.