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

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

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

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

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

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

לכל מחבר צריך להיות מוגדר סט ספציפי של פונקציות. אפליקציית האירוח (למשל, Data 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(), ‏ Data 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;
}

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

קובץ המניפסט מכיל מידע על מחבר הקהילה שנדרש כדי לפרוס את המחבר ולהשתמש בו ב-Data 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"
  ]
}

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

השלבים הבאים

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