Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

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

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

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 yaz

Her bağlayıcının belirli bir işlev grubunun tanımlanması gerekir. Barındırma uygulaması (ör. Looker Studio) bu işlevleri yürütür. Bağlayıcınızın gelen istekleri işlemesi ve Community Connector API referansında açıklandığı gibi yanıt vermesi beklenir. Kodunuzu geliştirirken sorunlarla karşılaşırsanız yardım için hata ayıklama kılavuzunu okuyun.

getAuthType() fonksiyonunda kimlik doğrulama türünü tanımlayın

Bu işlev, üçüncü taraf hizmet için kullanılan kimlik doğrulama yöntemini tanımlamak amacıyla ç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ı kimlik doğrulaması gerektirmez:

npm-downloads/src/auth.js

GitHub'da göster

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 görüntüleyin ve gerekli diğer işlevleri bağlayıcınıza ekleyin.

Yapılandırmayı `getConfig()` aracılığıyla tanımlayın

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

Looker Studio, getConfig() tarafından sağlanan yanıta göre 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 tarihi gerektiriyorsa config.setDateRangeRequired(true) yöntemini çağırın. Koşullu veya dinamik yapılandırma soruları sormanız gerekirse adımlı yapılandırma bölümüne bakın.

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

npm-downloads/src/main.js

GitHub'da göster

// 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ımlayın

Bu işlev, belirtilen 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ını inceleyin.

Bağlayıcınızın veri kaynağına ve kullanıcı tarafından sağlanan yapılandırmaya bağlı olarak şema düzeltilebilir veya istek sırasında dinamik olarak bunu sağlamanız gerekebilir.

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

npm-downloads/src/main.js

GitHub'da göster

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, belirtilen isteğin verilerini 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 getData() referansını inceleyin.

getData() isteğindeki aşağıdaki parametrelere daha fazla dikkat edilmesi gerekir:

lastRefresh
lastRefresh, verilerin yenilenmesi için en son isteğin zamanını işaret eden bir zaman damgasını temsil eder. Değeri new Date(timestampString) ile ayrıştırabilirsiniz. Apps Komut Dosyası Önbellek Hizmeti veya başka bir önbelleğe alma yöntemi kullanıyorsanız lastRefresh zaman damgası, veri kaynağına yeni bir getirme isteği göndermek mi yoksa önbellekten veri sunmak mı istediğinizi belirlemenize yardımcı olabilir.
dateRange
dateRangeRequired, getConfig() için true olarak ayarlanırsa her getData() çağrısı, istekte seçilen tarih aralığını içerir. Daha ayrıntılı bilgi için Tarih Aralıklarıyla Çalışma bölümüne bakın.

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

npm-downloads/src/main.js

GitHub'da göster

// 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 manifestini tamamlamak

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

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

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

npm-downloads/src/appsscript.json

GitHub'da göster

{
  "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 manifest dosyasıyla ilgili ayrıntılar için referans manifest referansına bakın.

Sonraki adımlar

Bir sonraki adım Topluluk Bağlayıcınızı dağıtmak olacaktır.

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

Yeni bir Apps Komut Dosyası projesi oluşturma

Bağlayıcı kodunu yaz

getAuthType() fonksiyonunda kimlik doğrulama türünü tanımlayın

Yapılandırmayı getConfig() aracılığıyla tanımlayın

Alanları getSchema() ile tanımlayın

getData() ile veri getirme ve döndürme

Proje manifestini tamamlamak

Sonraki adımlar

Yapılandırmayı `getConfig()` aracılığıyla tanımlayın