建立社群連接器

建立社群連結器的步驟如下：

建立新的 Apps Script 專案。
編寫連接器程式碼。
完成專案資訊清單。

建立新的 Apps Script 專案

前往 Google Apps Script 建立新專案。Apps Script 會為您建立預設指令碼。您可以移除 myFunction 函式，並重新命名專案。(進一步瞭解 Apps Script)

編寫連接器程式碼

每個連接器都必須定義一組特定函式。主機應用程式 (例如數據分析) 會執行這些函式。連接器應處理傳入要求，並按照社群連接器 API 參考資料所述方式回應。如果在開發程式碼時遇到問題，請參閱偵錯指南。

在 getAuthType() 中定義驗證類型

這個函式會呼叫，以識別第三方服務使用的驗證方法。詳情請參閱 getAuthType() 參考資料。目前支援的驗證方法列於AuthType參考資料。

舉例來說，下列連接器不需要驗證：

npm-downloads/src/auth.js

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

如果資料來源需要 OAuth 2.0 驗證，請參閱 OAuth 2.0 驗證指南，並在連接器中新增其他必要函式。

透過 `getConfig()` 定義設定

系統會呼叫 getConfig() 函式，取得連接器的設定，包括連接器所需的使用者提供值。詳情請參閱 getConfig() 參考資料。

根據 getConfig() 提供的回應，數據分析會顯示連結器設定畫面。如要查看支援的設定元素，請參閱 ConfigType 參考資料。

如果資料來源需要日期做為參數，請呼叫 config.setDateRangeRequired(true)。如需詢問條件式或動態設定問題，請參閱分階段設定。

以下是連接器的範例，使用者必須輸入 npm 套件名稱代碼。資訊和輸入欄位定義於 getConfig() 函式中：

npm-downloads/src/main.js

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

使用 getSchema() 定義欄位

系統會呼叫此函式，以取得指定要求的結構定義。getConfig() 函式定義的任何設定參數都會在 request 引數中提供。詳情請參閱getSchema()參考資料。

視連接器的資料來源和使用者提供的設定而定，結構定義可能是固定的，也可能必須在要求時動態提供。

舉例來說，如果連接器是根據報表 ID 擷取報表資料，則該報表傳回的資料和結構定義可能事先未知。在這種情況下，getSchema() 可能需要擷取資料，且必須計算結構定義。

npm-downloads/src/main.js

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

使用 getData() 擷取及傳回資料

系統會呼叫這個函式，以取得指定要求的資料。getConfig() 函式定義的任何設定參數都會在 request 引數中提供。詳情請參閱getData()參考資料。

getData() 要求中的下列參數需要特別注意：

lastRefresh
lastRefresh 代表時間戳記，標示最近一次要求重新整理資料的時間。您應該可以透過 new Date(timestampString) 剖析值。如果您使用 Apps Script 快取服務或其他快取方法，lastRefresh 時間戳記可協助您判斷是否要向資料來源發出新的擷取要求，或是從快取提供資料。
dateRange
如果 dateRangeRequired 在 getConfig() 中設為 true，則每個 getData() 呼叫都會在要求中包含所選日期範圍。詳情請參閱「使用日期範圍」。

以下範例會根據連入要求擷取資料，並傳回套件統計資料：

npm-downloads/src/main.js

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

填寫專案資訊清單

資訊清單檔案包含社群連接器的相關資訊，這些資訊是在數據分析中部署及使用連接器時的必要條件。

如要在 Apps Script 開發環境中編輯資訊清單檔案，請按一下「檢視」選單，然後按一下「顯示資訊清單檔案」。系統會建立新的appsscript.json資訊清單檔案。

更新資訊清單，加入下列資料：

npm-downloads/src/appsscript.json

前往 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"
  ]
}

如要瞭解 Data Studio 資訊清單的詳細資料，請參閱資訊清單參考資料。

後續步驟

下一步是部署社群連結器。

建立社群連接器 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立新的 Apps Script 專案

編寫連接器程式碼

在 getAuthType() 中定義驗證類型

透過 getConfig() 定義設定

使用 getSchema() 定義欄位

使用 getData() 擷取及傳回資料

填寫專案資訊清單

後續步驟

建立社群連接器

透過 `getConfig()` 定義設定