สร้างปลั๊กอินจากชุมชนสำหรับใช้ลิงก์ข้อมูล

ขั้นตอนในการสร้างปลั๊กอินจากชุมชนมีดังนี้

  1. สร้างโปรเจ็กต์ Apps Script ใหม่
  2. เขียนโค้ดตัวเชื่อมต่อ
  3. กรอกข้อมูลในไฟล์ Manifest ของโปรเจ็กต์

สร้างโปรเจ็กต์ 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()

Looker Studio จะแสดงหน้าจอการกำหนดค่าเครื่องมือเชื่อมต่อตามคำตอบที่ getConfig() ให้ไว้ องค์ประกอบการกำหนดค่าที่รองรับจะแสดงใน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;
}

กรอกข้อมูลในไฟล์ Manifest ของโปรเจ็กต์

ไฟล์ Manifest มีข้อมูลเกี่ยวกับ Community Connector ที่จำเป็นต่อการติดตั้งใช้งานและใช้ตัวเชื่อมต่อใน Looker Studio

หากต้องการแก้ไขไฟล์ Manifest ในสภาพแวดล้อมการพัฒนา Apps Script ให้คลิกเมนูดู แล้วคลิกแสดงไฟล์ Manifest การดำเนินการนี้จะสร้าง appsscript.jsonไฟล์ Manifest ใหม่

อัปเดตไฟล์ Manifest เพื่อรวมข้อมูลต่อไปนี้

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"
  ]
}

ดูรายละเอียดเกี่ยวกับไฟล์ Manifest ของ Looker Studio ได้ที่ข้อมูลอ้างอิงของไฟล์ Manifest

ขั้นตอนถัดไป

ขั้นตอนถัดไปคือการติดตั้งใช้งานปลั๊กอินจากชุมชน