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

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

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

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

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

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

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

הגדרת סוג אימות ב-getAuthType()

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

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

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

השלבים הבאים

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