שמירה במטמון באמצעות Firebase

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

ב-Looker Studio יש מערכת מטמון משלה לדוחות. במהלך היצירה של מחבר, אפשר ליישם מטמון מותאם אישית כדי לאפשר דוחות מהירים יותר להימנע מהגבלות קצב של ריבית שנתית.

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

דרישות

• מסד נתונים בזמן אמת ב-Firebase. אם אין לכם גישה לאחד מהם, אתם צריכים ליצור את הפרויקט ב-Google Cloud Platform (GCP) ופועלים לפי מדריך לתחילת העבודה ליצירת Firebase משלכם מופע של מסד נתונים בזמן אמת.
• חשבון שירות ב-GCP לקריאה ולכתיבה של נתונים בזמן אמת ב-Firebase מסד נתונים.
• מחבר קהילה שמאחזר נתונים ממקור.

מגבלות

• אי אפשר להשתמש בפתרון הזה עם Looker Studio Advanced Services. מתי אתם משתמשים ב-Looker Studio Advanced Services, קוד המחבר שלכם באפליקציות לסקריפט אין גישה לנתונים. לכן אי אפשר לשמור את הנתונים במטמון באמצעות Apps Script.
• בעלי הרשאת עריכה וצופים לא יכולים לאפס את המטמון הספציפי הזה.

פתרון

הטמעת חשבון שירות

1. יצירה של חשבון שירות בפרויקט ב-Google Cloud.
2. צריך לוודא שלחשבון השירות הזה יש גישה ל-BigQuery בפרויקט בענן.
   • תפקידי ניהול הזהויות והרשאות הגישה (IAM): Firebase Admin
3. מורידים את קובץ ה-JSON כדי לקבל את המפתחות של חשבונות השירות. אחסון תוכן במאפייני הסקריפט של פרויקט המחבר שלכם. אחרי ההוספה של צריכים להיראות בערך כך בממשק המשתמש של Apps Script:
   
4. הכללה של ספריית OAuth2 ל-Apps Script בפרויקט Apps Script.
5. מטמיעים את קוד OAuth2 הנדרש לחשבון השירות:

firestore-cache/src/firebase.js

הצגת הקוד ב-GitHub

var SERVICE_ACCOUNT_CREDS = 'SERVICE_ACCOUNT_CREDS';
var SERVICE_ACCOUNT_KEY = 'private_key';
var SERVICE_ACCOUNT_EMAIL = 'client_email';
var BILLING_PROJECT_ID = 'project_id';

var scriptProperties = PropertiesService.getScriptProperties();

/**
 * Copy the entire credentials JSON file from creating a service account in GCP.
 * Service account should have `Firebase Admin` IAM role.
 */
function getServiceAccountCreds() {
  return JSON.parse(scriptProperties.getProperty(SERVICE_ACCOUNT_CREDS));
}

function getOauthService() {
  var serviceAccountCreds = getServiceAccountCreds();
  var serviceAccountKey = serviceAccountCreds[SERVICE_ACCOUNT_KEY];
  var serviceAccountEmail = serviceAccountCreds[SERVICE_ACCOUNT_EMAIL];

  return OAuth2.createService('FirebaseCache')
    .setAuthorizationBaseUrl('https://accounts.google.com/o/oauth2/auth')
    .setTokenUrl('https://accounts.google.com/o/oauth2/token')
    .setPrivateKey(serviceAccountKey)
    .setIssuer(serviceAccountEmail)
    .setPropertyStore(scriptProperties)
    .setCache(CacheService.getScriptCache())
    .setScope([
      'https://www.googleapis.com/auth/userinfo.email',
      'https://www.googleapis.com/auth/firebase.database'
    ]);
}

מטמיעים קוד לקריאה ולכתיבה מ-Firebase

שימוש ב-Firebase Database REST API כדי לקרוא ולכתוב ב-Firebase מסד נתונים בזמן אמת. הקוד הבא מיישם את השיטות הנדרשות כדי באמצעות הגישה ל-API הזה.

הטמעת getData()

המבנה של קוד getData() הקיים שלא נשמר במטמון אמור להיראות כך:

firestore-cache/src/without-caching.js

הצגת הקוד ב-GitHub

/*
 * This file is only to demonstrate how the `getData()` fucntion would look
 * like without the Firebase Realtime Database caching. It is not a part of
 * the connector code and should not be included in Apps Script / Clasp.
 */

function getData(request) {
  var requestedFields = getFields().forIds(
    request.fields.map(function(field) {
      return field.name;
    })
  );

  var fetchedData = fetchAndParseData(request);
  var data = getFormattedData(fetchedData, requestedFields);

  return {
    schema: requestedFields.build(),
    rows: data
  };
}

כדי להשתמש בשמירה במטמון בקוד getData(), צריך לבצע את השלבים הבאים:

1. מצאו את ה'מקטע' או 'unit' של נתונים שצריך לשמור במטמון.

2. יוצרים מפתח ייחודי כדי לאחסן את יחידת הנתונים המינימלית במטמון.
   בהטמעה לדוגמה, נעשה שימוש ב-zipcode מ-configparams בתור המפתח.
   אופציונלי: במטמון לכל משתמש, צריך ליצור מפתח מורכב עם המפתח הבסיסי וגם זהות המשתמש. הטמעה לדוגמה:
   js var baseKey = getBaseKey(request); var userEmail = Session.getEffectiveUser().getEmail(); var hasheduserEmail = getHashedValue(userEmail); var compositeKey = baseKey + hasheduserEmail;

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

   var cacheForZipcode = {
     data: <data being cached>,
     ymd: <current date in YYYYMMDD format>
   }
   

4. אם לא קיימים נתונים שנשמרו במטמון או שהנתונים שנשמרו במטמון לא עדכניים, צריך לאחזר נתונים מהמקור ושומרים אותו במטמון.

בדוגמה הבאה, main.js כולל קוד getData() עם שמירה במטמון .

קוד לדוגמה

הנה דוגמה מלאה למחבר שמשתמש ב-FireBase לשמירה במטמון:

main.js

firestore-cache/src/main.js

הצגת הקוד ב-GitHub

// [start common_connector_code]
var cc = DataStudioApp.createCommunityConnector();

function getAuthType() {
  return cc
    .newAuthTypeResponse()
    .setAuthType(cc.AuthType.NONE)
    .build();
}

function getConfig(request) {
  var config = cc.getConfig();

  config
    .newTextInput()
    .setId('zipcode')
    .setName('Enter Zip Code')
    .setPlaceholder('eg. 95054');

  return config.build();
}

function getFields() {
  var fields = cc.getFields();
  var types = cc.FieldType;
  var aggregations = cc.AggregationType;

  fields
    .newDimension()
    .setId('zipcode')
    .setName('Zip code')
    .setType(types.TEXT);

  fields
    .newDimension()
    .setId('date')
    .setName('Date')
    .setType(types.YEAR_MONTH_DAY);

  fields
    .newMetric()
    .setId('temperature')
    .setName('Temperature (F)')
    .setType(types.NUMBER)
    .setIsReaggregatable(false);

  return fields;
}

function getSchema(request) {
  return {
    schema: getFields().build()
  };
}
// [end common_connector_code]

// [start caching_implementation]
function getData(request) {
  var requestedFields = getFields().forIds(
    request.fields.map(function(field) {
      return field.name;
    })
  );

  var cacheUpdateNeeded = true;
  var url = buildFirebaseUrl(request.configParams.zipcode);
  var cache = firebaseCache('get', url);

  if (cache) {
    var currentYmd = getCurrentYmd();
    cacheUpdateNeeded = currentYmd > cache.ymd;
  }

  if (cacheUpdateNeeded) {
    var fetchedData = fetchAndParseData(request);
    cache = {};
    cache.data = fetchedData;
    cache.ymd = currentYmd;
    firebaseCache('delete', url);
    firebaseCache('post', url, cache);
  }

  var data = getFormattedData(cache.data, requestedFields);

  var requestedFields = getFields().forIds(
    request.fields.map(function(field) {
      return field.name;
    })
  );

  var cache = getCachedData(request);
  var data = getFormattedData(cache, requestedFields);

  return {
    schema: requestedFields.build(),
    rows: data
  };
}

function getCachedData(request) {
  var cacheUpdateNeeded = true;
  var url = buildFirebaseUrl(request.configParams.zipcode);
  var cachedData = getFromCache(url);
  var currentYmd = getCurrentYmd();

  if (cachedData) {
    cacheUpdateNeeded = currentYmd > cachedData.ymd;
  }

  if (cacheUpdateNeeded) {
    var fetchedData = fetchAndParseData(request);
    freshData = {};
    freshData.data = fetchedData;
    freshData.ymd = currentYmd;
    deleteFromCache(url);
    putInCache(url, freshData);
    cachedData = freshData;
  }

  return cachedData.data;
}

function getCurrentYmd() {
  var currentDate = new Date();
  var year = currentDate.getFullYear();
  var month = ('0' + (currentDate.getMonth() + 1)).slice(-2);
  var date = ('0' + currentDate.getDate()).slice(-2);
  var currentYmd = year + month + date;
  return currentYmd;
}

// [end caching_implementation]

// [start common_getdata_implementation]
function fetchAndParseData(request) {
  // TODO: Connect to your own API endpoint and parse the fetched data.
  // To keep this example simple, we are returning dummy data instead of
  // connecting to an enpoint. This does not affect the caching.
  var parsedData = sampleData;
  return parsedData;
}

function getFormattedData(fetchedData, requestedFields) {
  var data = fetchedData.map(function(rowData) {
    return formatData(rowData, requestedFields);
  });
  return data;
}

function formatData(rowData, requestedFields) {
  var row = requestedFields.asArray().map(function(requestedField) {
    switch (requestedField.getId()) {
      case 'date':
        return rowData.date;
      case 'zipcode':
        return rowData.zipcode;
      case 'temperature':
        return rowData.temperature;
      default:
        return '';
    }
  });
  return {values: row};
}
// [end common_getdata_implementation]

var sampleData = [
  {
    date: '20190601',
    zipcode: '95054',
    temperature: 80
  },
  {
    date: '20190602',
    zipcode: '95054',
    temperature: 82
  },
  {
    date: '20190603',
    zipcode: '95054',
    temperature: 82
  },
  {
    date: '20190604',
    zipcode: '95054',
    temperature: 85
  },
  {
    date: '20190605',
    zipcode: '95054',
    temperature: 84
  },
  {
    date: '20190606',
    zipcode: '95054',
    temperature: 83
  },
  {
    date: '20190607',
    zipcode: '95054',
    temperature: 81
  }
];

firebase.js

firestore-cache/src/firebase.js

הצגת הקוד ב-GitHub

// [start firebase_access_implementation]

var FIREBASE_REALTIME_DB_BASE_URL = '.firebaseio.com';
var FIREBASE_REALTIME_DB_COLLECTION = '/cache';

/**
 * Returns the URL for a file in a firebase database.
 *
 * @param {string} fileName The filename in the database
 * @returns {string} The url for the file in the database
 */
function buildFirebaseUrl(fileName) {
  var serviceAccountCreds = getServiceAccountCreds();
  var projectId = serviceAccountCreds[BILLING_PROJECT_ID];

  if (fileName) {
    fileName = '/' + fileName;
  }
  var urlElements = [
    'https://',
    projectId,
    FIREBASE_REALTIME_DB_BASE_URL,
    FIREBASE_REALTIME_DB_COLLECTION,
    fileName,
    '.json'
  ];
  var url = urlElements.join('');
  return url;
}

/**
 * Generic method for handling the Firebase Realtime Database REST API.
 * For `get`: returns the data at the given url.
 * For `post`: posts the data in in firestore db at the given url and returns `undefined`.
 * For `delete`: deletes the data at the given url and returns `undefined`.
 *
 * @param {string} method Method for the REST API: `get`, `post`, or `delete`
 * @param {string} url REST endpoint
 * @param {string} [data] Data to be stored for `post` method
 * @returns {undefined|object} Returns data from the REST endpoint for `get`
 *          method. For other methods, returns `undefined`.
 */
function firebaseCache(method, url, data) {
  var oAuthToken = getOauthService().getAccessToken();

  var responseOptions = {
    headers: {
      Authorization: 'Bearer ' + oAuthToken
    },
    method: method,
    contentType: 'application/json'
  };

  // Add payload for post method
  if (method === 'post') {
    responseOptions['payload'] = JSON.stringify(data);
  }

  var response = UrlFetchApp.fetch(url, responseOptions);

  // Return value only for `get`.
  if (method === 'get') {
    var responseObject = JSON.parse(response);
    if (responseObject === null) {
      return null;
    } else {
      var autoKey = Object.keys(responseObject)[0];
      var returnValue = responseObject[autoKey];
    }
    return returnValue;
  }
}

function getFromCache(url) {
  return firebaseCache('get', url);
}

function deleteFromCache(url) {
  return firebaseCache('delete', url);
}

function putInCache(url, data) {
  return firebaseCache('put', url, data);
}

// [end firebase_access_implementation]

var SERVICE_ACCOUNT_CREDS = 'SERVICE_ACCOUNT_CREDS';
var SERVICE_ACCOUNT_KEY = 'private_key';
var SERVICE_ACCOUNT_EMAIL = 'client_email';
var BILLING_PROJECT_ID = 'project_id';

var scriptProperties = PropertiesService.getScriptProperties();

/**
 * Copy the entire credentials JSON file from creating a service account in GCP.
 * Service account should have `Firebase Admin` IAM role.
 */
function getServiceAccountCreds() {
  return JSON.parse(scriptProperties.getProperty(SERVICE_ACCOUNT_CREDS));
}

function getOauthService() {
  var serviceAccountCreds = getServiceAccountCreds();
  var serviceAccountKey = serviceAccountCreds[SERVICE_ACCOUNT_KEY];
  var serviceAccountEmail = serviceAccountCreds[SERVICE_ACCOUNT_EMAIL];

  return OAuth2.createService('FirebaseCache')
    .setAuthorizationBaseUrl('https://accounts.google.com/o/oauth2/auth')
    .setTokenUrl('https://accounts.google.com/o/oauth2/token')
    .setPrivateKey(serviceAccountKey)
    .setIssuer(serviceAccountEmail)
    .setPropertyStore(scriptProperties)
    .setCache(CacheService.getScriptCache())
    .setScope([
      'https://www.googleapis.com/auth/userinfo.email',
      'https://www.googleapis.com/auth/firebase.database'
    ]);
}

מקורות מידע נוספים

מחבר Chrome UX מאפשר מרכז בקרה המבוסס על נפח של כ-20GB ב-BigQuery לאלפי משתמשים. המחבר הזה משתמש במסד נתונים בזמן אמת ב-Firebase יחד עם שירות המטמון של הסקריפט של Apps לגישה של שמירה במטמון בשתי שכבות. צפייה code לקבלת פרטי ההטמעה.