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

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

  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 או בכל שיטת שמירה אחרת במטמון, חותמת הזמן של 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 מופיעים בחומר העזר בנושא מניפסט.

השלבים הבאים

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