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

Buka Google Apps Script untuk membuat project baru. Apps Script akan membuat skrip default untuk Anda. Anda dapat menghapus fungsi myFunction dan mengganti nama project. (Pelajari Apps Script lebih lanjut)

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

Menulis kode konektor

Setiap konektor harus memiliki serangkaian fungsi tertentu yang ditentukan. Aplikasi hosting (misalnya, Data Studio) akan menjalankan fungsi ini. Konektor Anda diharapkan dapat menangani permintaan masuk dan merespons seperti yang dijelaskan dalam referensi Community Connector API. Jika Anda mengalami masalah saat mengembangkan kode, baca panduan proses debug untuk mendapatkan bantuan.

Menentukan jenis autentikasi di getAuthType()

Fungsi ini dipanggil untuk mengidentifikasi metode autentikasi yang digunakan untuk layanan pihak ketiga. Lihat referensi getAuthType() untuk mengetahui detailnya. Metode autentikasi yang saat ini didukung tercantum dalam AuthType referensi.

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 untuk konektor, termasuk nilai yang diberikan pengguna yang diperlukan oleh konektor Anda. Lihat getConfig() referensi untuk mengetahui detailnya.

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

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

Berikut adalah contoh konektor yang mengharuskan pengguna memasukkan kode nama paket npm. Kolom info dan input 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 konektor komunitas Layanan ini mengabstraksi pola umum dan menawarkan fitur pelengkapan otomatis sehingga metode dan nilai enum tidak perlu dihafal. Untuk melihat dokumentasi referensi, lihat [layanan Data Studio]

Menentukan kolom dengan getSchema()

Fungsi ini dipanggil untuk mendapatkan skema untuk permintaan yang diberikan. Parameter konfigurasi apa pun yang ditentukan oleh fungsi getConfig() akan diberikan dalam argumen request. Lihat getSchema() referensi untuk mengetahui detailnya.

Bergantung pada sumber data konektor dan konfigurasi yang diberikan oleh pengguna, skema mungkin tetap atau Anda mungkin harus menyediakannya secara dinamis pada waktu permintaan.

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

Catatan: Untuk SELECT_MULTIPLE nilai configParams adalah string yang dipisahkan koma. 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 untuk permintaan yang diberikan. Parameter konfigurasi apa pun yang ditentukan oleh fungsi getConfig() akan diberikan dalam argumen request. Lihat getData() referensi untuk mengetahui detailnya.

Parameter berikut dari permintaan getData() memerlukan perhatian tambahan:

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

• dateRange
  Jika dateRangeRequired ditetapkan ke true di getConfig(), setiap panggilan getData() akan berisi rentang tanggal yang dipilih dalam permintaan. Lihat Bekerja dengan 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;
}

Melengkapi manifes project

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

Perhatian: Informasi apa pun yang Anda masukkan ke dalam file manifes harus dianggap publik karena akan dapat diakses oleh siapa saja yang menggunakan konektor Anda.

Untuk mengedit file manifes di lingkungan pengembangan Apps Script, klik menu View , lalu klik Show manifest file. Tindakan ini akan membuat file manifes appsscript.json baru.

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 Data Studio, lihat referensi referensi manifes.

Langkah berikutnya

Langkah berikutnya adalah men-deploy Konektor Komunitas.