Metadata API – מדריך למפתחים

מסמך זה מסביר מושגים חשובים לגבי השימוש ב-Metadata API כדי לגשת לרשימות ולמאפיינים של עמודות ב-Google Analytics.

מבוא

Metadata API מחזיר את רשימת העמודות (כלומר מאפיינים ומדדים) שנחשפו בממשקי ה-API לדיווח של Google Analytics ואת המאפיינים שלהן. אם אתם משתמשים חדשים ב-API, קראו את הסקירה הכללית על מטא-נתונים של API כדי לקבל מבוא ל-Metadata API.

לפני שתתחיל

הגישה לכל ממשקי ה-API של Google Analytics מתבצעת באופן דומה. לפני שמתחילים עם Metadata API, צריך:

• בדף ספריות לקוח אפשר למצוא רשימה מלאה של ספריות לקוח ספציפיות לשפת תכנות שעובדות עם ה-API.
• ב מדריך העזר מפורט מידע נוסף על ממשק ה-API ועל הגישה לנתונים בלי ספריית לקוח.

כל ספריית לקוח מספקת אובייקט שירות יחיד של ניתוח נתונים כדי לגשת לכל הנתונים של Metadata API. בדרך כלל, כדי ליצור את אובייקט השירות לשימוש עם Metadata API, צריך לבצע את השלבים הבאים:

1. רשום את האפליקציה שלך ב מסוף Google API.
2. יוצרים אובייקט שירות של Analytics ומגדירים את מפתח ה-API.

מפתח רישום ומפתח API

האפליקציה שלכם צריכה לזהות את עצמה בכל פעם שהיא שולחת בקשה ל-API של Analytics, על ידי הוספה של מפתח API לכל בקשה.

קבלת מפתח API ושימוש בו

כך מקבלים מפתח API:

1. פותחים את הדף Credentials ב-API Console.
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 במסוף על ידי לחיצה על Create credentials > מפתח API. כדי להגביל את המפתח לפני שמשתמשים בו בסביבת הייצור, לוחצים על Restrict key ובוחרים אחת מהאפשרויות של Restrict.

כדי לשמור על האבטחה של מפתחות ה-API, מומלץ לפעול לפי השיטות המומלצות לשימוש מאובטח במפתחות API.

אחרי שיצרתם מפתח API, האפליקציה יכולה לצרף את פרמטר השאילתה key=yourAPIKey לכל כתובות ה-URL של הבקשות.

מפתח ה-API בטוח להטמעה בכתובות URL; אין צורך בקידוד.

הערה: אם האפליקציה שלכם כבר אימתה משתמש והסמיכה אותו (למשל, באמצעות OAuth 2.0), כל בקשה שתשלחו ל-Metadata API באמצעות אובייקט שירות מורשה של Analytics תזהה באופן אוטומטי את האפליקציה שלכם. במקרה כזה אין צורך להגדיר את מפתח ה-API.

קטעי הקוד הבאים ממחישים כיצד להגדיר את מפתח ה-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. לפרטים על הסרת מאפיינים, אפשר לעיין במדיניות ההוצאה משימוש של נתונים.

תרחישים לדוגמה

אפשר להשתמש ב-Metadata API כדי לפתור את התרחישים הבאים:

• עמודות שהוצאו משימוש
• שמות העמודות
• עמודות עם תבניות
• עמודות מחושבים
• עמודות ופלחים
• גרסאות API
• Etags

עמודות שהוצאו משימוש

אם עמודה (כלומר מאפיין או מדד) הוצאה משימוש, המאפיין status יוגדר כ-DEPRECATED.

הערה: האפליקציה צריכה לבדוק אם יש עמודות DEPRECATED בשאילתות של Reporting API ולהפסיק להשתמש בהן. אם יש עמודה חלופית זמינה, צריך להשתמש בה במקום זאת. עמודות DEPRECATED יוסרו מממשקי ה-API של Reporting ו-Metadata אחרי ש תקופת ההוצאה משימוש תסתיים, ושאילתות לגבי העמודות האלה יחזירו שגיאה.

קטע הקוד הבא מראה איך להשתמש במאפיין 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;
}

נוסף בגרסת API

אפשר להשתמש במאפיין 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.

בדיקת תגובה שנשמרה במטמון

אם משווים בין ערך ה-ETag שהוחזר מתגובה של Metadata API ושווה ערך ל-ETag של משאב שנשמר במטמון, הגרסה ששמורה במטמון היא הנוכחית. אם תגי ה-ETags לא זהים, מעדכנים את האפליקציה ומרעננים את המטמון עם התגובה העדכנית.

אם רוצים לאחזר רק את ערך ה-ETag מ-Metadata API, צריך להגדיר את פרמטר השאילתה fields ל-etag בזמן שליחת הבקשה. להצגת דוגמה

שימוש ב-ETag עם בקשת API

אם יש לכם גרסה שנשמרה במטמון של אוסף עמודות, תוכלו לכלול את ערך ה-ETag שלה בבקשת Metadata API על ידי הגדרת שדה הכותרת If-None-Match של ה-HTTP. Metadata API יבדוק את ערך ה-ETag ויגיב עם גרסה מעודכנת של המשאב וסטטוס HTTP של 200 OK או תגובה ריקה עם סטטוס 304 Not Modified אם הגרסה ששמורה במטמון עדכנית.

הערה: יכול להיות שספריית הלקוח שבה משתמשים כדי לשלוח בקשות ל-Metadata API מזהה ETag ומשתמשת בו, או מספקת תמיכה לכך. כדאי לעיין במסמכי התיעוד של הספרייה כדי לוודא שיש תמיכה ב-ETag.