Topluluk Bağlayıcısı oluşturma

Topluluk bağlayıcısı oluşturma adımları şunlardır:

  1. Yeni bir Apps Komut Dosyası projesi oluşturun.
  2. Bağlayıcı kodunu yazın.
  3. Proje manifestini tamamlayın.

Yeni bir Apps Komut Dosyası projesi oluşturma

Yeni bir proje oluşturmak için Google Apps Komut Dosyası'nı ziyaret edin. Apps Komut Dosyası sizin için varsayılan bir komut dosyası oluşturur. myFunction işlevini kaldırabilir ve projeyi yeniden adlandırabilirsiniz. (Apps Komut Dosyası hakkında daha fazla bilgi edinin.)

Bağlayıcı kodunu yazma

Her bağlayıcının belirli bir işlev kümesi tanımlaması gerekir. Bu işlevler, barındırma uygulaması (ör. Looker Studio) tarafından yürütülür. Bağlayıcınızın, gelen istekleri işlemesi ve Topluluk Bağlayıcısı API referansında açıklandığı şekilde yanıt vermesi beklenir. Kodunuzu geliştirirken sorun yaşarsanız yardım için hata ayıklama kılavuzunu okuyun.

getAuthType() içinde kimlik doğrulama türünü tanımlayın

Bu işlev, üçüncü taraf hizmeti için kullanılan kimlik doğrulama yöntemini tanımlamak üzere çağrılır. Ayrıntılar için getAuthType() referansına bakın. Şu anda desteklenen kimlik doğrulama yöntemleri AuthType referansında listelenmiştir.

Örneğin, aşağıdaki bağlayıcı için kimlik doğrulama gerekmez:

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

Veri kaynağınız OAuth 2.0 kimlik doğrulaması gerektiriyorsa OAuth 2.0 kimlik doğrulama kılavuzunu inceleyin ve bağlayıcınıza gerekli ek işlevleri ekleyin.

Yapılandırmayı getConfig() üzerinden tanımlama

getConfig() işlevi, bağlayıcının yapılandırmasını almak için çağrılır. Bu yapılandırma, bağlayıcınızın gerektirdiği kullanıcı tarafından sağlanan değerleri içerir. Ayrıntılar için getConfig() referansına bakın.

getConfig() tarafından verilen yanıta göre Looker Studio, bağlayıcı yapılandırma ekranını oluşturur. Desteklenen yapılandırma öğeleri ConfigType referansında listelenmiştir.

Veri kaynağınız parametre olarak tarih gerektiriyorsa config.setDateRangeRequired(true) işlevini çağırın. Koşullu veya dinamik yapılandırma soruları sormanız gerekiyorsa Adımlı yapılandırma başlıklı makaleyi inceleyin.

Aşağıda, kullanıcının bir npm paket adı kodu girmesini gerektiren bir bağlayıcı örneği verilmiştir. getConfig() işlevinde bir bilgi ve bir giriş alanı tanımlanır:

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

Alanları getSchema() ile tanımlama

Bu işlev, verilen isteğin şemasını almak için çağrılır. getConfig() işlevi tarafından tanımlanan tüm yapılandırma parametreleri request bağımsız değişkeninde sağlanır. Ayrıntılar için getSchema() referansına bakın.

Bağlayıcınızın veri kaynağına ve kullanıcının sağladığı yapılandırmaya bağlı olarak şema sabit olabilir veya istek sırasında dinamik olarak sağlamanız gerekebilir.

Örneğin, bir bağlayıcı Rapor Kimliği'ne göre rapor verileri getiriyorsa bu rapor için döndürülen veriler ve dolayısıyla şema önceden bilinmeyebilir. Bu durumda getSchema() için veri getirme işlemi gerekebilir ve şemanın hesaplanması gerekir.

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() ile veri getirme ve döndürme

Bu işlev, verilen istek için verileri almak üzere çağrılır. getConfig() işlevi tarafından tanımlanan tüm yapılandırma parametreleri request bağımsız değişkeninde sağlanır. Ayrıntılar için getData() referansına bakın.

getData() isteğindeki aşağıdaki parametreler için ek dikkat gerekir:

  • lastRefresh
    lastRefresh, verilerin yenilenmesi için yapılan en son isteğin zamanını belirten bir zaman damgasını ifade eder. Değeri new Date(timestampString) ile ayrıştırabilmeniz gerekir. Apps Script Cache Service veya başka bir önbelleğe alma yöntemi kullanıyorsanız lastRefresh zaman damgası, veri kaynağına yeni bir getirme isteği gönderip göndermeyeceğinizi veya önbellekten veri sunup sunmayacağınızı belirlemenize yardımcı olabilir.

  • dateRange
    getConfig() içinde dateRangeRequired, true olarak ayarlanırsa her getData() çağrısı, istekte seçilen tarih aralığını içerir. Daha fazla bilgi için Tarih Aralıklarıyla Çalışma başlıklı makaleyi inceleyin.

Aşağıdaki örnek, gelen isteğe göre verileri getirir ve paket istatistiklerini döndürür:

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

Proje manifest dosyasını tamamlama

Manifest dosyası, bağlayıcınızı Looker Studio'da dağıtmak ve kullanmak için gerekli olan Topluluk Bağlayıcınızla ilgili bilgileri içerir.

Manifest dosyasını Apps Komut Dosyası geliştirme ortamında düzenlemek için Görünüm menüsünü ve Manifest dosyasını göster'i tıklayın. Bu işlem, yeni bir appsscript.json manifest dosyası oluşturur.

Manifest dosyasını aşağıdaki verileri içerecek şekilde güncelleyin:

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 manifestiyle ilgili ayrıntılar için manifest referansı başlıklı makaleyi inceleyin.

Sonraki adımlar

Sonraki adım, topluluk bağlayıcınızı dağıtmaktır.