মেটাডেটা API - বিকাশকারী গাইড

এই নথিটি Google Analytics কলামগুলির তালিকা এবং বৈশিষ্ট্যগুলি অ্যাক্সেস করতে মেটাডেটা API ব্যবহার করার বিষয়ে গুরুত্বপূর্ণ ধারণাগুলি ব্যাখ্যা করে৷

ভূমিকা

মেটাডেটা API Google Analytics রিপোর্টিং API এবং তাদের বৈশিষ্ট্যগুলিতে উন্মোচিত কলামগুলির তালিকা (যেমন, মাত্রা এবং মেট্রিক্স) প্রদান করে। আপনি যদি এপিআই-এ নতুন হয়ে থাকেন, মেটাডেটা API-এর পরিচিতির জন্য মেটাডেটা API ওভারভিউ পড়ুন।

তুমি শুরু করার আগে

সমস্ত Google Analytics API একই পদ্ধতিতে অ্যাক্সেস করা হয়। আপনি মেটাডেটা API দিয়ে শুরু করার আগে আপনার উচিত:

  • API এর সাথে কাজ করে এমন প্রোগ্রামিং ভাষা নির্দিষ্ট ক্লায়েন্ট লাইব্রেরির একটি সম্পূর্ণ তালিকার জন্য ক্লায়েন্ট লাইব্রেরি পৃষ্ঠাটি পড়ুন।
  • API ইন্টারফেস এবং ক্লায়েন্ট লাইব্রেরি ছাড়াই ডেটা অ্যাক্সেস করার বিষয়ে জানতে রেফারেন্স গাইড পড়ুন।

প্রতিটি ক্লায়েন্ট লাইব্রেরি সমস্ত মেটাডেটা API ডেটা অ্যাক্সেস করার জন্য একটি একক বিশ্লেষণ পরিষেবা অবজেক্ট প্রদান করে। মেটাডেটা API এর সাথে ব্যবহারের জন্য পরিষেবা অবজেক্ট তৈরি করতে আপনাকে সাধারণত নিম্নলিখিত পদক্ষেপগুলি অতিক্রম করতে হবে:

  1. Google API কনসোলে আপনার অ্যাপ্লিকেশন নিবন্ধন করুন৷
  2. একটি বিশ্লেষণ পরিষেবা বস্তু তৈরি করুন এবং API কী সেট করুন।

নিবন্ধন এবং API কী

প্রতিটি অনুরোধের সাথে একটি এপিআই কী অন্তর্ভুক্ত করে আপনার অ্যাপ্লিকেশানটি যখনই অ্যানালিটিক্স এপিআই-তে একটি অনুরোধ পাঠায় তখনই এটিকে নিজেকে সনাক্ত করতে হবে।

একটি API কী অর্জন এবং ব্যবহার করা

একটি API কী অর্জন করতে:

  1. API কনসোলে শংসাপত্র পৃষ্ঠা খুলুন।
  2. এই API দুই ধরনের শংসাপত্র সমর্থন করে। আপনার প্রকল্পের জন্য উপযুক্ত যে কোনো শংসাপত্র তৈরি করুন:

    • OAuth 2.0: যখনই আপনার অ্যাপ্লিকেশন ব্যক্তিগত ব্যবহারকারীর ডেটার অনুরোধ করে, তখন অনুরোধের সাথে একটি OAuth 2.0 টোকেন পাঠাতে হবে। আপনার আবেদন প্রথমে একটি ক্লায়েন্ট আইডি পাঠায় এবং সম্ভবত, একটি টোকেন পাওয়ার জন্য একটি ক্লায়েন্ট গোপনীয়তা পাঠায়। আপনি ওয়েব অ্যাপ্লিকেশন, পরিষেবা অ্যাকাউন্ট বা ইনস্টল করা অ্যাপ্লিকেশনগুলির জন্য OAuth 2.0 শংসাপত্র তৈরি করতে পারেন৷

      দ্রষ্টব্য: যেহেতু এই API-তে OAuth 2.0 অনুমোদনের প্রয়োজন এমন কোনও পদ্ধতি নেই, তাই আপনাকে শুধুমাত্র API কীগুলি পেতে হবে, যা নীচে বর্ণিত হয়েছে৷ যাইহোক, যদি আপনার অ্যাপ্লিকেশনটি অন্য API কল করে যার জন্য ব্যবহারকারীর অনুমোদনের প্রয়োজন হয়, তাহলে আপনার এখনও OAuth 2.0 শংসাপত্রের প্রয়োজন।

      আরও তথ্যের জন্য, OAuth 2.0 ডকুমেন্টেশন দেখুন।

    • API কী: একটি অনুরোধ যা একটি OAuth 2.0 টোকেন প্রদান করে না একটি API কী পাঠাতে হবে। কী আপনার প্রকল্পকে শনাক্ত করে এবং API অ্যাক্সেস, কোটা এবং রিপোর্ট প্রদান করে।

      API API কীগুলিতে বিভিন্ন ধরণের সীমাবদ্ধতা সমর্থন করে। যদি আপনার প্রয়োজনীয় API কীটি ইতিমধ্যেই বিদ্যমান না থাকে, তাহলে Create Credentials > API কী ক্লিক করে কনসোলে একটি API কী তৈরি করুন। আপনি কীটিকে উৎপাদনে ব্যবহার করার আগে Restrict key-এ ক্লিক করে সীমাবদ্ধতাগুলির একটি নির্বাচন করে সীমাবদ্ধ করতে পারেন।

আপনার API কীগুলি সুরক্ষিত রাখতে, নিরাপদে API কীগুলি ব্যবহার করার জন্য সর্বোত্তম অনুশীলনগুলি অনুসরণ করুন৷

আপনার একটি API কী থাকার পরে, আপনার অ্যাপ্লিকেশনটি সমস্ত অনুরোধের URL-এ ক্যোয়ারী প্যারামিটার key= yourAPIKey যোগ করতে পারে।

API কী ইউআরএল-এ এম্বেড করার জন্য নিরাপদ; এটা কোন এনকোডিং প্রয়োজন নেই.

নিম্নলিখিত কোড স্নিপেটগুলি ব্যাখ্যা করে যে কীভাবে বিভিন্ন ক্লায়েন্ট লাইব্রেরির জন্য API কী সেট করতে হয়:

জাভা

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.
  }
}

পাইথন

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.

পিএইচপি

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.

জাভাস্ক্রিপ্ট

<!--
  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 বৈশিষ্ট্য রয়েছে যা কলামের জন্য প্রযোজ্য বৈশিষ্ট্যগুলির একটি উপসেট অন্তর্ভুক্ত করে।

নিম্নলিখিত টেবিলটি বৈধ বৈশিষ্ট্যগুলির সম্পূর্ণ তালিকা:

ব্যবহারের ক্ষেত্রে

মেটাডেটা API নিম্নলিখিত ব্যবহারের ক্ষেত্রে সমাধান করতে ব্যবহার করা যেতে পারে:

অপ্রচলিত কলাম

যদি একটি কলাম (অর্থাৎ একটি মাত্রা বা মেট্রিক) অবমূল্যায়ন করা হয় তাহলে তার 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 ইউজার ইন্টারফেসে (যেমন ওয়েব ইন্টারফেস) ব্যবহার করা হয়।

নিম্নলিখিত স্নিপেট দেখায় কিভাবে একটি কলামের UI নাম পুনরুদ্ধার করতে হয়:

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;
}

API সংস্করণে যোগ করা হয়েছে

একটি নির্দিষ্ট সংস্করণের একটি রিপোর্টিং API এ একটি কলাম ব্যবহার করা যেতে পারে কিনা তা পরীক্ষা করতে addedInApiVersion বৈশিষ্ট্যটি ব্যবহার করুন৷ উদাহরণস্বরূপ, কলামটি কোর রিপোর্টিং API V3- তে ব্যবহার করা যেতে পারে তা যাচাই করতে নিম্নলিখিত ফাংশনটিতে কল করুন:

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

ETag

প্রতিটি মেটাডেটা API প্রতিক্রিয়াতে একটি ETag অন্তর্ভুক্ত করা হয়। ETag হল একটি শনাক্তকারী যা মেটাডেটা API প্রতিক্রিয়া ক্যাশে এবং আপডেট করতে ব্যবহার করা যেতে পারে। এটি গুরুত্বপূর্ণ কারণ কলাম (যেমন মাত্রা এবং মেট্রিক্স) ডেটা দীর্ঘ সময়ের জন্য অপরিবর্তিত থাকতে পারে এবং ক্যাশে ডেটা ব্যবহার করা হলে অপ্রয়োজনীয় অনুরোধ এবং আপডেট করা অদক্ষ।

আপনি যদি একটি কলাম সংগ্রহের ETag সংরক্ষণ করেন তবে এটি প্রাথমিকভাবে 2 উপায়ে ব্যবহার করা যেতে পারে: একটি ক্যাশে করা মেটাডেটা API প্রতিক্রিয়া আপ-টু-ডেট কিনা তা পরীক্ষা করতে এবং এটিকে একটি মেটাডেটা API অনুরোধের অংশ হিসাবে অন্তর্ভুক্ত করতে।

একটি ক্যাশড প্রতিক্রিয়া পরীক্ষা করা হচ্ছে

আপনি যদি একটি মেটাডেটা API প্রতিক্রিয়া থেকে প্রত্যাবর্তিত ETag মান তুলনা করেন এবং এটি একটি ক্যাশ করা সংস্থানের জন্য ETag এর সমতুল্য হয় তবে ক্যাশে করা সংস্করণটি বর্তমান। যদি ETags সমতুল্য না হয় তাহলে আপনার অ্যাপ্লিকেশন আপডেট করুন এবং সর্বশেষ প্রতিক্রিয়া সহ ক্যাশে রিফ্রেশ করুন।

আপনি যদি মেটাডেটা API থেকে শুধুমাত্র ETag মান পুনরুদ্ধার করতে চান, তাহলে অনুরোধ করার সময় ক্ষেত্র ক্যোয়ারী প্যারামিটারটিকে etag এ সেট করুন। একটি উদাহরণ দেখুন ।

একটি API অনুরোধের সাথে একটি ETag ব্যবহার করা

যদি আপনার কাছে একটি কলাম সংগ্রহের একটি ক্যাশে সংস্করণ থাকে তবে আপনি If-None-Match HTTP হেডার ফিল্ড সেট করে একটি মেটাডেটা API অনুরোধে এর ETag মান অন্তর্ভুক্ত করতে পারেন। মেটাডেটা এপিআই ETag মান পরীক্ষা করবে এবং হয় রিসোর্সের একটি আপডেটেড ভার্সন এবং 200 OK HTTP স্ট্যাটাস দিয়ে সাড়া দেবে অথবা 304 Not Modified স্ট্যাটাস সহ একটি খালি রেসপন্স যদি আপনার ক্যাশে করা ভার্সন বর্তমান থাকে।