Créer un connecteur de communauté

Voici les étapes à suivre pour créer un connecteur de communauté :

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

Créer un projet Apps Script

Accédez à Google Apps Script pour créer un projet. Apps Script créera 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)

Remarque : Si vous utilisez un service tiers pour votre connecteur, vous devez connaître les exigences qu'il impose pour utiliser l'API, y compris la génération de clés API, etc.

Écrire le code du connecteur

Chaque connecteur doit avoir un ensemble spécifique de fonctions définies. L'application hôte (par exemple, Looker Studio) exécutera ces fonctions. Votre connecteur est censé gérer les requêtes entrantes et y répondre comme décrit dans la documentation de référence de l'API Community Connectors. 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 référence AuthType.

Par exemple, le connecteur suivant ne nécessite aucune authentification :

npm-downloads/src/auth.js

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

Si votre source de données nécessite une authentification OAuth 2.0, consultez le guide d'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 dont votre connecteur a besoin. Pour en savoir plus, consultez la documentation de référence sur getConfig().

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

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

Voici un exemple de connecteur qui exige que l'utilisateur saisisse un nom de package npm. Un champ d'informations et un champ de saisie sont définis dans la fonction getConfig() :

npm-downloads/src/main.js

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

Remarque : Le service Apps Script DataStudio facilite l'écriture d'un connecteur de communauté. Il extrait les modèles courants et propose l'autocomplétion pour que vous n'ayez pas à mémoriser les méthodes et les valeurs d'énumération. Pour consulter la documentation de référence, consultez Service Looker Studio.

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

Selon la source de données de votre connecteur et 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 des données de rapport en fonction d'un ID de rapport, les données renvoyées pour ce rapport et, par conséquent, le schéma peuvent ne pas être connus à l'avance. Dans ce cas, getSchema() peut nécessiter une récupération de données et le schéma devra être calculé.

Remarque : Pour SELECT_MULTIPLE, la valeur configParams est une chaîne délimitée par des virgules. Pour CHECKBOX, la valeur de configParam est truthy.

npm-downloads/src/main.js

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

Récupérer et renvoyer des données avec getData()

Cette fonction est appelée pour obtenir des données pour 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 particulière :

• lastRefresh
lastRefresh représente un code temporel qui marque l'heure de la demande d'actualisation des données la plus récente. 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, le code temporel lastRefresh peut vous aider à déterminer si vous devez envoyer une nouvelle requête d'extraction à la source de données ou diffuser les 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 Utiliser des plages de dates.

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

npm-downloads/src/main.js

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

Compléter le fichier manifeste du projet

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

Attention : Toute information que vous saisissez dans le fichier manifeste doit être considérée comme publique, car elle sera accessible à toute personne utilisant votre connecteur.

Pour modifier le fichier manifeste dans l'environnement de développement Apps Script, cliquez sur le menu Afficher, puis sur Afficher le fichier manifeste. Un fichier manifeste appsscript.json est alors créé.

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

npm-downloads/src/appsscript.json

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

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

Étapes suivantes

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