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. Compléter le fichier manifeste du projet

Créer un projet Apps Script

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

Remarque :Si vous utilisez un service tiers pour le connecteur, vous devez connaître toutes les conditions requises pour utiliser l'API, y compris générer Clés API, etc.

Écrire le code du connecteur

Un ensemble spécifique de fonctions doit être défini pour chaque connecteur. La l'application d'hébergement (par exemple, Looker Studio) exécute ces fonctions. Votre le connecteur doit gérer les requêtes entrantes et y répondre comme décrit dans la documentation de référence de l'API Community Connector. Si vous rencontrez des problèmes lors du développement 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 un service tiers. Pour en savoir plus, consultez la documentation de référence sur getAuthType(). Actuellement méthodes d'authentification 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

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 les Guide d'authentification OAuth 2.0 et ajoutez les fonctions supplémentaires requises au 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. Voir 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 la écran de configuration du connecteur. Les éléments de configuration pris en charge sont listés dans la documentation de référence sur ConfigType.

Si votre source de données nécessite un paramètre de date, appelez config.setDateRangeRequired(true). Si vous devez poser des questions conditionnelles ou dynamiques de configuration, consultez la section Configuration en escalier.

Voici un exemple de connecteur dans lequel l'utilisateur doit saisir un le code du nom du package npm. Un champ d'informations et un champ de saisie sont définis dans le 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 la création d'une communauté le connecteur. Il élimine les modèles courants et propose une saisie semi-automatique pour que les méthodes et les valeurs d'énumération n'ont pas besoin d'être mémorisées. Pour consulter la documentation de référence, consultez le 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. N'importe quelle valeur 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 le le schéma est peut-être fixe ou vous devez le fournir de manière dynamique l'heure de la requête.

Par exemple, si un connecteur récupère des données de rapport en fonction d'un ID de rapport, le les données renvoyées pour ce rapport. Par conséquent, le schéma peut ne pas être connu à l'avance. Dans ce cas, getSchema() peut nécessiter une extraction de données, et le schéma devra être calculé.

Remarque :Pour SELECT_MULTIPLE, la valeur configParams est 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 les données de la requête donnée. N'importe quelle 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 des éléments attention:

• lastRefresh
lastRefresh représente un horodatage qui marque l'heure de l'événement une demande d'actualisation des données. Vous devez pouvoir analyser la valeur 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 s'il faut envoyer une nouvelle requête d'extraction à la source de données ou diffuser les données du cache.

• dateRange
  Si dateRangeRequired est défini sur true dans getConfig(), chaque getData() contient la période sélectionnée dans la demande. Voir Utiliser des plages de dates.

L'exemple suivant récupère des données en fonction de la requête entrante et renvoie le 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é nécessaires pour déployer et utiliser votre connecteur dans Looker Studio.

Attention :Toutes les informations que vous placez dans le fichier manifeste doivent être prises en compte public, car il sera accessible à toute personne utilisant le connecteur.

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

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 les fichiers manifestes.

Étapes suivantes

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