Créer un connecteur de communauté

Pour créer un connecteur de communauté, procédez comme suit:

  1. Créez un projet Apps Script.
  2. Écrivez le code du connecteur.
  3. Remplissez le fichier manifeste du projet.

Créer un projet Apps Script

Accédez à Google Apps Script pour créer un projet. Apps Script crée un script par défaut pour vous. N'hésitez pas à supprimer la fonction myFunction et à renommer le projet. En savoir plus sur Apps Script

Écrire le code du connecteur

Un ensemble spécifique de fonctions doit être défini pour chaque connecteur. L'application d'hébergement (par exemple, Looker Studio) exécute ces fonctions. Votre connecteur doit gérer les requêtes entrantes et répondre comme indiqué dans la documentation de référence de l'API du connecteur de communauté. Si vous rencontrez des problèmes lors du développement de votre code, consultez le guide de débogage pour obtenir de l'aide.

Définir le type d'authentification dans getAuthType()

Cette fonction est appelée pour identifier la méthode d'authentification utilisée pour le service tiers. Pour en savoir plus, consultez la documentation de référence sur getAuthType(). Les méthodes d'authentification actuellement compatibles sont listées dans la documentation de référence sur AuthType.

Par exemple, le connecteur suivant ne nécessite pas d'authentification:

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

Si votre source de données nécessite une authentification OAuth 2.0, consultez le guide sur l'authentification OAuth 2.0 et ajoutez les fonctions supplémentaires requises à votre connecteur.

Définir la configuration via getConfig()

La fonction getConfig() est appelée pour obtenir la configuration du connecteur, y compris les valeurs fournies par l'utilisateur requises par le connecteur. Pour en savoir plus, consultez la documentation de référence sur getConfig().

En fonction de la réponse fournie par getConfig(), Looker Studio affiche l'écran de configuration du connecteur. Les éléments de configuration acceptés sont répertoriés dans la documentation de référence sur ConfigType.

Si votre source de données nécessite la date comme paramètre, appelez config.setDateRangeRequired(true). Si vous devez poser des questions de configuration conditionnelle ou dynamique, consultez la section Configuration par étapes.

Voici un exemple de connecteur dans lequel l'utilisateur doit saisir un code de nom de package npm. Des informations et un champ de saisie sont définis dans la fonction getConfig():

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

Définir les champs avec getSchema()

Cette fonction est appelée pour obtenir le schéma de la requête donnée. Tous les paramètres de configuration définis par la fonction getConfig() seront fournis dans l'argument request. Pour en savoir plus, consultez la documentation de référence sur getSchema().

En fonction de la source de données de votre connecteur et de la configuration fournie par l'utilisateur, le schéma peut être fixe ou vous devrez peut-être le fournir de manière dynamique au moment de la requête.

Par exemple, si un connecteur récupère les données d'un rapport en fonction d'un ID de rapport, les données renvoyées pour ce rapport peuvent ne pas être connues au préalable. Dans ce cas, getSchema() peut nécessiter une extraction de données, et le schéma devra être calculé.

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

Extraire et renvoyer des données avec getData()

Cette fonction est appelée pour obtenir les données de la requête donnée. Tous les paramètres de configuration définis par la fonction getConfig() seront fournis dans l'argument request. Pour en savoir plus, consultez la documentation de référence sur getData().

Les paramètres suivants de la requête getData() nécessitent une attention supplémentaire:

  • lastRefresh
    lastRefresh représente un horodatage qui marque l'heure de la requête la plus récente d'actualisation des données. Vous devriez pouvoir analyser la valeur avec new Date(timestampString). Si vous utilisez le service de cache Apps Script ou toute autre méthode de mise en cache, l'horodatage lastRefresh peut vous aider à déterminer s'il faut envoyer une nouvelle requête d'extraction à la source de données ou diffuser des données à partir du cache.

  • dateRange
    Si dateRangeRequired est défini sur true dans getConfig(), chaque appel getData() contiendra la plage de dates sélectionnée dans la requête. Pour en savoir plus, consultez la section Utiliser des plages de dates.

L'exemple suivant extrait des données en fonction de la requête entrante et renvoie les statistiques de package:

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

Remplir le fichier manifeste du projet

Le fichier manifeste contient des informations sur votre connecteur de communauté, lesquelles sont nécessaires pour le déployer et l'utiliser dans Looker Studio.

Pour modifier le fichier manifeste dans l'environnement de développement Apps Script, cliquez sur le menu View (Affichage), puis sur Show manifest file (Afficher le fichier manifeste). Cette opération entraîne la création d'un fichier manifeste appsscript.json.

Mettez à jour le fichier manifeste pour inclure les données suivantes:

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

Pour en savoir plus sur le fichier manifeste Looker Studio, consultez la documentation de référence.

Étapes suivantes

L'étape suivante consiste à déployer votre connecteur de communauté.