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

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

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

สร้างโปรเจ็กต์ Apps Script ใหม่

ไปที่ Google Apps Script เพื่อสร้างโปรเจ็กต์ใหม่ Apps Script จะสร้างสคริปต์เริ่มต้นให้คุณ คุณสามารถนำฟังก์ชัน myFunction ออกและเปลี่ยนชื่อโปรเจ็กต์ได้ (ดูข้อมูลเพิ่มเติมเกี่ยวกับ Apps Script)

เขียนรหัสเครื่องมือเชื่อมต่อ

เครื่องมือเชื่อมต่อทั้งหมดจำเป็นต้องมีชุดฟังก์ชันเฉพาะที่กำหนดไว้ แอปพลิเคชันที่โฮสต์ (เช่น Looker Studio) จะเรียกใช้ฟังก์ชันเหล่านี้ เครื่องมือเชื่อมต่อของคุณควรจัดการคำขอที่เข้ามาใหม่และตอบกลับตามที่อธิบายไว้ในเอกสารอ้างอิง 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 หรือวิธีการแคชอื่นๆ การประทับเวลา 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 มีข้อมูลเกี่ยวกับปลั๊กอินจากชุมชนสำหรับใช้ลิงก์ข้อมูล ซึ่งจำเป็นสำหรับการทำให้เครื่องมือเชื่อมต่อใช้งานได้และใช้เครื่องมือเชื่อมต่อใน Looker Studio

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

อัปเดตไฟล์ 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

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

ขั้นตอนต่อไปคือการทำให้ปลั๊กอินจากชุมชนสำหรับใช้ลิงก์ข้อมูลใช้งานได้