Membangun Konektor Komunitas

Langkah-langkah untuk membuat Konektor Komunitas adalah:

1. Buat project Apps Script baru.
2. Tulis kode konektor.
3. Lengkapi manifes project.

Membuat project Apps Script baru

Kunjungi Google Apps Script untuk membuat project baru. Apps Script akan membuat default untuk Anda. Jangan ragu untuk menghapus fungsi myFunction dan mengganti nama menyelesaikan proyek tersebut. (Pelajari lebih lanjut Apps Script)

Catatan: Jika menggunakan layanan pihak ketiga untuk konektor, Anda harus memahami persyaratan apa pun yang mereka miliki untuk menggunakan API, termasuk membuat Kunci API, dll.

Menulis kode konektor

Setiap konektor harus memiliki sekumpulan fungsi tertentu yang ditentukan. Tujuan aplikasi hosting Anda (misalnya Looker Studio) akan menjalankan fungsi ini. Nama konektor diharapkan menangani permintaan yang masuk dan merespons seperti yang dijelaskan dalam referensi Community Connector API. Jika Anda menghadapi masalah saat mengembangkan kode Anda, baca panduan proses debug untuk mendapatkan bantuan.

Menentukan jenis autentikasi di getAuthType()

Fungsi ini dipanggil untuk mengidentifikasi metode otentikasi yang digunakan untuk Layanan pihak ketiga. Lihat referensi getAuthType() untuk mengetahui detailnya. Saat ini metode autentikasi yang didukung tercantum dalam referensi AuthType.

Misalnya, konektor berikut tidak memerlukan autentikasi:

npm-downloads/src/auth.js

Lihat di GitHub

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();
}

Jika sumber data Anda memerlukan autentikasi OAuth 2.0, lihat Panduan autentikasi OAuth 2.0 dan tambahkan fungsi tambahan yang diperlukan ke konektor Anda.

Menentukan konfigurasi melalui getConfig()

Fungsi getConfig() dipanggil untuk mendapatkan konfigurasi bagi konektor, termasuk nilai yang diberikan pengguna yang diperlukan konektor Anda. Lihat Referensi getConfig() untuk mengetahui detailnya.

Berdasarkan respons yang diberikan oleh getConfig(), Looker Studio akan merender layar konfigurasi konektor. Elemen konfigurasi yang didukung tercantum dalam referensi ConfigType.

Jika sumber data Anda memerlukan tanggal sebagai parameter, panggil config.setDateRangeRequired(true). Jika Anda perlu mengajukan pertanyaan bersyarat atau dinamis pertanyaan konfigurasi, lihat konfigurasi bertahap.

Berikut adalah contoh konektor yang mengharuskan pengguna memasukkan kode nama paket npm. Info dan isian {i>input <i}ditentukan dalam Fungsi getConfig():

npm-downloads/src/main.js

Lihat di GitHub

// 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();
}

Catatan: Layanan Apps Script DataStudio memudahkan penulisan komunitas konektor 20%. API ini memisahkan pola umum dan menawarkan pelengkapan otomatis sehingga metode dan nilai enum tidak perlu dihafal. Untuk melihat dokumentasi referensi, lihat layanan Looker Studio

Menentukan kolom dengan getSchema()

Fungsi ini dipanggil untuk mendapatkan skema bagi permintaan yang diberikan. Apa saja parameter konfigurasi yang ditentukan oleh fungsi getConfig() akan diberikan dalam argumen request. Lihat referensi getSchema() untuk mengetahui detailnya.

Bergantung pada sumber data konektor Anda dan konfigurasi yang disediakan oleh skema mungkin telah diperbaiki atau Anda mungkin harus menyediakannya secara dinamis di waktu permintaan.

Misalnya, jika konektor mengambil data laporan berdasarkan ID Laporan, data yang ditampilkan untuk laporan tersebut sehingga skemanya mungkin tidak diketahui sebelumnya. Dalam hal ini, getSchema() mungkin memerlukan pengambilan data dan skema harus dihitung.

Catatan: Untuk SELECT_MULTIPLE, nilai configParams harus dipisahkan koma {i>string<i}. Untuk CHECKBOX, nilai configParam adalah truthy.

npm-downloads/src/main.js

Lihat di GitHub

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()};
}

Mengambil dan menampilkan data dengan getData()

Fungsi ini dipanggil untuk mendapatkan data permintaan tertentu. Konfigurasi apa pun parameter yang ditentukan oleh fungsi getConfig() akan disediakan di Argumen request. Lihat referensi getData() untuk mengetahui detailnya.

Parameter berikut dari permintaan getData() memerlukan tambahan {i>attention<i} (perhatian):

• lastRefresh
lastRefresh mewakili stempel waktu yang menandai waktu terbaru meminta pembaruan data. Anda harus dapat mengurai nilai ini dengan new Date(timestampString). Jika Anda menggunakan Layanan Cache Apps Script atau metode penyimpanan dalam cache lainnya, stempel waktu lastRefresh akan membantu Anda menentukan apakah akan membuat permintaan pengambilan baru ke sumber data atau menyajikan data dari cache.

• dateRange
  Jika dateRangeRequired disetel ke true dalam getConfig(), setiap getData() akan berisi rentang tanggal yang dipilih dalam permintaan. Lihat Menggunakan Rentang Tanggal untuk mengetahui detail selengkapnya.

Contoh berikut mengambil data berdasarkan permintaan masuk dan menampilkan statistik paket:

npm-downloads/src/main.js

Lihat di GitHub

// 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;
}

Menyelesaikan manifes project

File manifes berisi informasi tentang Konektor Komunitas Anda yang yang diperlukan untuk men-deploy dan menggunakan konektor Anda di Looker Studio.

Perhatian: Setiap informasi yang Anda masukkan ke dalam file manifes harus dipertimbangkan bersifat publik karena akan dapat diakses oleh siapa saja yang menggunakan konektor Anda.

Untuk mengedit file manifes di lingkungan pengembangan Apps Script, klik menu View dan klik Show manifest file. Ini akan membuat File manifes appsscript.json.

Perbarui manifes untuk menyertakan data berikut:

npm-downloads/src/appsscript.json

Lihat di GitHub

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

Untuk mengetahui detail tentang manifes Looker Studio, lihat referensi referensi manifes.

Langkah berikutnya

Langkah selanjutnya adalah men-deploy Konektor Komunitas.