Создайте соединитель сообщества

Этапы создания инструмента для взаимодействия с сообществом:

  1. Создайте новый проект Apps Script.
  2. Напишите код коннектора.
  3. Заполните проектную документацию.

Создайте новый проект Apps Script.

Перейдите в Google Apps Script , чтобы создать новый проект. Apps Script создаст для вас скрипт по умолчанию. Вы можете удалить функцию myFunction и переименовать проект. ( Узнайте больше об Apps Script )

Напишите код коннектора

Для каждого коннектора требуется определенный набор функций. Эти функции будет выполнять приложение-хостинг (например, Looker Studio). Ваш коннектор должен обрабатывать входящие запросы и отвечать в соответствии с описанием в справочнике API коннекторов сообщества . Если у вас возникнут проблемы при разработке кода, обратитесь к руководству по отладке за помощью.

Определите тип аутентификации в методе getAuthType().

Эта функция вызывается для определения метода аутентификации, используемого для стороннего сервиса. Подробности см. в справочнике по AuthType getAuthType() . В настоящее время поддерживаются следующие методы аутентификации: [список методов аутентификации].

Например, для следующего коннектора аутентификация не требуется:

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() .

На основе ответа, полученного от функции getConfig() , Looker Studio отобразит экран конфигурации коннектора. Поддерживаемые элементы конфигурации перечислены в справочнике ConfigType .

Если ваш источник данных требует указания даты в качестве параметра, вызовите метод `config.setDateRangeRequired(true)` . Если вам необходимо задать условные или динамические параметры конфигурации, см. раздел «Пошаговая конфигурация» .

Ниже приведён пример коннектора, требующего от пользователя ввода кода имени npm-пакета. В функции getConfig() определены поля info и input:

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
    Если в getConfig() dateRangeRequired установлен в true , каждый вызов 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;
}

Заполните манифест проекта.

Файл манифеста содержит информацию о вашем коннекторе сообщества, необходимую для развертывания и использования коннектора в Looker Studio.

Чтобы отредактировать файл манифеста в среде разработки Apps Script, щелкните меню «Вид» и выберите «Показать файл манифеста» . Это создаст новый файл манифеста appsscript.json .

Обновите манифест, добавив следующие данные:

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 см. в справочнике манифестов .

Следующие шаги

Следующим шагом будет развертывание вашего Community Connector .