Metadata API - راهنمای برنامه‌نویس

این سند مفاهیم مهم استفاده از API فراداده برای دسترسی به لیست و ویژگی های ستون های Google Analytics را توضیح می دهد.

معرفی

API فراداده فهرستی از ستون‌ها (یعنی ابعاد و معیارها) را که در APIهای گزارش‌دهی Google Analytics و ویژگی‌های آن‌ها در معرض دید قرار گرفته‌اند، برمی‌گرداند. اگر تازه وارد API هستید، برای آشنایی با API فراداده، نمای کلی API فراداده را بخوانید.

قبل از اینکه شروع کنی

همه APIهای Google Analytics به روشی مشابه قابل دسترسی هستند. قبل از شروع با API فراداده باید:

  • صفحه کتابخانه های سرویس گیرنده را برای لیست کاملی از کتابخانه های مشتری خاص زبان برنامه نویسی که با API کار می کنند، بخوانید.
  • راهنمای مرجع را بخوانید تا در مورد رابط API و دسترسی به داده‌ها بدون کتابخانه مشتری اطلاعات کسب کنید.

هر کتابخانه سرویس گیرنده یک شی سرویس تجزیه و تحلیل واحد را برای دسترسی به تمام داده های API فراداده فراهم می کند. برای ایجاد شیء سرویس برای استفاده با Metadata API، معمولاً باید مراحل زیر را طی کنید:

  1. برنامه خود را در Google API Console ثبت کنید.
  2. یک شیء سرویس Analytics ایجاد کنید و کلید API را تنظیم کنید.

ثبت نام و کلید API

برنامه شما باید هر بار که درخواستی را به API Analytics ارسال می کند، خود را با قرار دادن یک کلید API با هر درخواست شناسایی کند.

به دست آوردن و استفاده از یک کلید API

برای به دست آوردن یک کلید API:

  1. صفحه Credentials را در کنسول 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 مورد نیاز شما از قبل وجود ندارد، با کلیک روی ایجاد اعتبار > کلید API، یک کلید API در کنسول ایجاد کنید. می‌توانید کلید را قبل از استفاده از آن در تولید با کلیک کردن روی Restrict key و انتخاب یکی از محدودیت‌ها محدود کنید.

برای ایمن نگه داشتن کلیدهای API خود، بهترین روش ها را برای استفاده ایمن از کلیدهای API دنبال کنید.

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

قطعه کد زیر نحوه تنظیم API Key برای کتابخانه های مختلف کلاینت را نشان می دهد:

جاوا

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.

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.

جاوا اسکریپت

<!--
  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 است که شامل زیرمجموعه ای از ویژگی ها است که برای ستون قابل اعمال است.

جدول زیر لیست کامل ویژگی های معتبر است:

موارد استفاده

Metadata API را می توان برای حل موارد استفاده زیر استفاده کرد:

ستون های منسوخ شده

اگر یک ستون (یعنی یک بعد یا متریک) منسوخ شود، ویژگی status آن روی DEPRECATED تنظیم می شود.

قطعه زیر نحوه استفاده از ویژگی status را برای بررسی اینکه آیا یک ستون منسوخ شده است نشان می دهد:

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

اگر ستونی تغییر نام/حذف شود، ویژگی status آن بر روی DEPRECATED تنظیم می‌شود و ممکن است یک ویژگی replacedBy شده Id ستون جایگزین تنظیم شود.

قطعه زیر نحوه استفاده از ویژگی 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;
}

در نسخه API اضافه شده است

از ویژگی addedInApiVersion برای بررسی اینکه آیا یک ستون را می توان در API گزارش یک نسخه مشخص شده استفاده کرد یا خیر استفاده کنید. به عنوان مثال، تابع زیر را فراخوانی کنید تا بررسی کنید که ستون می تواند در Core Reporting API V3 استفاده شود:

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

ETag

یک ETag در هر پاسخ API فراداده گنجانده شده است. ETag شناسه‌ای است که می‌تواند برای ذخیره و به‌روزرسانی پاسخ‌های API فراداده استفاده شود. این مهم است زیرا داده‌های ستون‌ها (به عنوان مثال ابعاد و معیارها) می‌توانند برای مدت طولانی بدون تغییر باقی بمانند و درخواست‌ها و به‌روزرسانی‌های غیرضروری در صورت استفاده از داده‌های ذخیره‌سازی شده ناکارآمد است.

اگر ETag یک مجموعه ستونی را ذخیره می‌کنید، می‌توان آن را عمدتاً به دو روش استفاده کرد: بررسی به‌روز بودن پاسخ متادیتای ذخیره‌شده در حافظه پنهان، و گنجاندن آن به عنوان بخشی از درخواست API فراداده.

بررسی پاسخ ذخیره شده در حافظه پنهان

اگر مقدار ETag برگردانده شده از یک پاسخ API فراداده را مقایسه کنید و معادل ETag برای یک منبع ذخیره شده در حافظه پنهان است، نسخه ذخیره شده فعلی است. اگر تگ های ET معادل نیستند، برنامه خود را به روز کنید و کش را با آخرین پاسخ تازه سازی کنید.

اگر می‌خواهید فقط مقدار ETag را از API فراداده بازیابی کنید، هنگام درخواست، پارامتر query فیلدها را روی etag تنظیم کنید. یک نمونه ببینید .

استفاده از ETag با درخواست API

اگر نسخه ذخیره شده یک مجموعه ستونی دارید، می توانید مقدار ETag آن را با تنظیم فیلد هدر HTTP If-None-Match در یک درخواست API فراداده قرار دهید. API فراداده مقدار ETag را بررسی می‌کند و اگر نسخه ذخیره‌شده شما فعلی باشد، با نسخه به‌روز شده منبع و وضعیت HTTP 200 OK پاسخ می‌دهد یا با یک پاسخ خالی با وضعیت 304 Not Modified پاسخ می‌دهد.