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

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

מבוא

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

לפני שתתחיל

הגישה לכל ממשקי ה-API של Google Analytics דומה. לפני שמתחילים עם Metadata API, מומלץ:

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

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

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

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

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

רכישה של מפתח API ושימוש בו

כדי לקבל מפתח API:

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

כדי לשמור על אבטחת מפתחות ה-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
• תגים

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

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

הערה: האפליקציה שלך צריכה לחפש ולהפסיק להשתמש ב-DEPRECATED עמודות בשאילתות API. אם יש עמודה חלופית זמינה, צריך להשתמש בה. DEPRECATED עמודות יוסרו מ-Reporting 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;
}

נוסף בגרסת ה-API

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

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

ETag

ETag כלול בכל תגובה של Metadata API. ה-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. ממשק ה-API של המטא-נתונים יבדוק את ערך ה-ETag ויגיב עם גרסה מעודכנת של המשאב ועם סטטוס HTTP של 200 OK, או תגובה ריקה עם הסטטוס 304 Not Modified, אם גרסת המטמון הנוכחית היא שלך.

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