בניית מחבר קהילה

השלבים ליצירת מחבר קהילה הם:

  1. יוצרים פרויקט חדש ב-Apps Script.
  2. כותבים את קוד המחבר.
  3. משלימים את קובץ המניפסט של הפרויקט.

יצירת פרויקט חדש ב-Apps Script

כדי ליצור פרויקט חדש, נכנסים אל Google Apps Script. ‫Apps Script ייצור בשבילכם סקריפט ברירת מחדל. אפשר להסיר את הפונקציה myFunction ולשנות את שם הפרויקט. (מידע נוסף על Apps Script)

כתיבת קוד המחבר

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

הגדרת סוג האימות בפונקציה getAuthType()

הפונקציה הזו נקראת כדי לזהות את שיטת האימות שמשמשת את שירות הצד השלישי. פרטים נוספים מפורטים במאמר בנושא getAuthType(). שיטות האימות שנתמכות כרגע מפורטות במאמר AuthType reference.

לדוגמה, המחבר הבא לא דורש אימות:

npm-downloads/src/auth.js
var cc = DataStudioApp.createCommunityConnector();

// https://developers.google.com/datastudio/connector/reference#getauthtype
function getAuthType() {
  var AuthTypes = cc.AuthType;
  return cc
    .newAuthTypeResponse()
    .setAuthType(AuthTypes.NONE)
    .build();
}

אם מקור הנתונים דורש אימות OAuth 2.0, צריך לעיין במדריך לאימות OAuth 2.0 ולהוסיף את הפונקציות הנדרשות הנוספות למחבר.

הגדרת התצורה באמצעות getConfig()

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

על סמך התשובה שסופקה על ידי getConfig(), יוצג ב-Looker Studio מסך ההגדרות של המחבר. רשימת רכיבי ההגדרה הנתמכים מופיעה במאמר בנושא ConfigType.

אם מקור הנתונים דורש תאריך כפרמטר, צריך להפעיל את הפונקציה config.setDateRangeRequired(true). אם אתם צריכים לשאול שאלות לגבי הגדרה מותנית או דינמית, כדאי לעיין במאמר בנושא הגדרה בשלבים.

הדוגמה הבאה היא של מחבר שמחייב את המשתמש להזין קוד של שם חבילת npm. פונקציית getConfig() מגדירה שדה מידע ושדה קלט:

npm-downloads/src/main.js
// https://developers.google.com/datastudio/connector/reference#getconfig
function getConfig() {
  var config = cc.getConfig();

  config
    .newInfo()
    .setId('instructions')
    .setText(
      'Enter npm package names to fetch their download count. An invalid or blank entry will revert to the default value.'
    );

  config
    .newTextInput()
    .setId('package')
    .setName(
      'Enter a single package name or multiple names separated by commas (no spaces!)'
    )
    .setHelpText('e.g. "googleapis" or "package,somepackage,anotherpackage"')
    .setPlaceholder(DEFAULT_PACKAGE)
    .setAllowOverride(true);

  config.setDateRangeRequired(true);

  return config.build();
}

הגדרת השדות באמצעות getSchema()‎

הפונקציה הזו נקראת כדי לקבל את הסכימה של הבקשה הנתונה. כל פרמטר הגדרה שמוגדר על ידי הפונקציה getConfig() יסופק בארגומנט request. פרטים נוספים מופיעים במאמר בנושא getSchema().

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

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

npm-downloads/src/main.js
function getFields() {
  var fields = cc.getFields();
  var types = cc.FieldType;
  var aggregations = cc.AggregationType;

  fields
    .newDimension()
    .setId('packageName')
    .setName('Package')
    .setType(types.TEXT);

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

  fields
    .newMetric()
    .setId('downloads')
    .setName('Downloads')
    .setType(types.NUMBER)
    .setAggregation(aggregations.SUM);

  return fields;
}

// https://developers.google.com/datastudio/connector/reference#getschema
function getSchema(request) {
  return {schema: getFields().build()};
}

אחזור והחזרה של נתונים באמצעות getData()

הפונקציה הזו נקראת כדי לקבל נתונים עבור הבקשה הנתונה. כל פרמטר הגדרה שמוגדר על ידי הפונקציה getConfig() יסופק בארגומנט request. פרטים נוספים מופיעים במאמר בנושא getData().

הפרמטרים הבאים מהבקשה getData() דורשים תשומת לב נוספת:

  • ‫lastRefresh
    lastRefresh מייצג חותמת זמן שמציינת את השעה של הבקשה האחרונה לרענון הנתונים. אפשר לנתח את הערך באמצעות new Date(timestampString). אם אתם משתמשים ב-Apps Script Cache Service או בשיטת שמירה במטמון אחרת, חותמת הזמן lastRefresh יכולה לעזור לכם להחליט אם לשלוח בקשת אחזור חדשה למקור הנתונים או להציג נתונים מהמטמון.

  • ‫dateRange
    אם הערך של dateRangeRequired מוגדר ל-true ב-getConfig(), כל קריאה של getData() תכיל את טווח התאריכים שנבחר בבקשה. פרטים נוספים זמינים במאמר עבודה עם טווחי תאריכים.

בדוגמה הבאה, הנתונים מאוחזרים על סמך הבקשה הנכנסת, והנתונים הסטטיסטיים של החבילה מוחזרים:

npm-downloads/src/main.js
// https://developers.google.com/datastudio/connector/reference#getdata
function getData(request) {
  request.configParams = validateConfig(request.configParams);

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

  try {
    var apiResponse = fetchDataFromApi(request);
    var normalizedResponse = normalizeResponse(request, apiResponse);
    var data = getFormattedData(normalizedResponse, requestedFields);
  } catch (e) {
    cc.newUserError()
      .setDebugText('Error fetching data from API. Exception details: ' + e)
      .setText(
        'The connector has encountered an unrecoverable error. Please try again later, or file an issue if this error persists.'
      )
      .throwException();
  }

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

/**
 * Gets response for UrlFetchApp.
 *
 * @param {Object} request Data request parameters.
 * @returns {string} Response text for UrlFetchApp.
 */
function fetchDataFromApi(request) {
  var url = [
    'https://api.npmjs.org/downloads/range/',
    request.dateRange.startDate,
    ':',
    request.dateRange.endDate,
    '/',
    request.configParams.package
  ].join('');
  var response = UrlFetchApp.fetch(url);
  return response;
}

/**
 * Parses response string into an object. Also standardizes the object structure
 * for single vs multiple packages.
 *
 * @param {Object} request Data request parameters.
 * @param {string} responseString Response from the API.
 * @return {Object} Contains package names as keys and associated download count
 *     information(object) as values.
 */
function normalizeResponse(request, responseString) {
  var response = JSON.parse(responseString);
  var package_list = request.configParams.package.split(',');
  var mapped_response = {};

  if (package_list.length == 1) {
    mapped_response[package_list[0]] = response;
  } else {
    mapped_response = response;
  }

  return mapped_response;
}

/**
 * Formats the parsed response from external data source into correct tabular
 * format and returns only the requestedFields
 *
 * @param {Object} parsedResponse The response string from external data source
 *     parsed into an object in a standard format.
 * @param {Array} requestedFields The fields requested in the getData request.
 * @returns {Array} Array containing rows of data in key-value pairs for each
 *     field.
 */
function getFormattedData(response, requestedFields) {
  var data = [];
  Object.keys(response).map(function(packageName) {
    var package = response[packageName];
    var downloadData = package.downloads;
    var formattedData = downloadData.map(function(dailyDownload) {
      return formatData(requestedFields, packageName, dailyDownload);
    });
    data = data.concat(formattedData);
  });
  return data;
}

השלמת קובץ המניפסט של הפרויקט

קובץ המניפסט מכיל מידע על מחבר הקהילה שנדרש לפריסה ולשימוש במחבר ב-Looker Studio.

כדי לערוך את קובץ המניפסט בסביבת הפיתוח של Apps Script, לוחצים על התפריט תצוגה ואז על הצגת קובץ המניפסט. ייווצר קובץ מניפסט חדש appsscript.json.

מעדכנים את המניפסט ומוסיפים לו את הנתונים הבאים:

npm-downloads/src/appsscript.json
{
  "dependencies": {
    "libraries": []
  },
  "dataStudio": {
    "name": "npm Downloads",
    "logoUrl": "https://raw.githubusercontent.com/npm/logos/master/npm%20square/n-64.png",
    "company": "Google Data Studio Developer Relations",
    "companyUrl": "https://developers.google.com/datastudio/",
    "addonUrl": "https://github.com/googledatastudio/community-connectors/tree/master/npm-downloads#readme",
    "supportUrl": "https://github.com/googledatastudio/community-connectors/issues",
    "description": "Get npm package download counts.",
    "sources": ["npm"],
    "templates": {
      "default": "1twu0sHjqR5dELAPyGJcw4GS3-D0_NTrQ"
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

פרטים על מניפסט של Looker Studio מופיעים במאמר בנושא מניפסט.

השלבים הבאים

השלב הבא הוא פריסת מחבר הקהילה.