Crea un connettore della community

I passaggi per creare un connettore della community sono:

  1. Crea un nuovo progetto Apps Script.
  2. Scrivi il codice del connettore.
  3. Completa il manifest del progetto.

Crea un nuovo progetto Apps Script

Visita Google Apps Script per creare un nuovo progetto. Apps Script creerà uno script predefinito per te. Puoi rimuovere la funzione myFunction e rinominare il progetto. Scopri di più su Apps Script.

Scrivere il codice del connettore

Ogni connettore deve avere un insieme specifico di funzioni definite. L'applicazione di hosting (ad es. Looker Studio) eseguirà queste funzioni. Il connettore deve gestire le richieste in entrata e rispondere come descritto nel riferimento API Community Connector. Se riscontri problemi durante lo sviluppo del codice, leggi la guida al debug per ricevere assistenza.

Definisci il tipo di autenticazione in getAuthType()

Questa funzione viene chiamata per identificare il metodo di autenticazione utilizzato per il servizio di terze parti. Per informazioni dettagliate, consulta il riferimento getAuthType(). I metodi di autenticazione attualmente supportati sono elencati nel riferimento AuthType.

Ad esempio, il seguente connettore non richiede l'autenticazione:

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

Se l'origine dati richiede l'autenticazione OAuth 2.0, consulta la Guida all'autenticazione OAuth 2.0 e aggiungi le funzioni aggiuntive richieste al connettore.

Definisci la configurazione tramite getConfig()

La funzione getConfig() viene chiamata per ottenere la configurazione del connettore, inclusi i valori forniti dall'utente richiesti dal connettore. Per i dettagli, consulta il riferimento getConfig().

In base alla risposta fornita da getConfig(), Looker Studio visualizzerà la schermata di configurazione del connettore. Gli elementi di configurazione supportati sono elencati nel riferimento ConfigType.

Se l'origine dati richiede la data come parametro, chiama config.setDateRangeRequired(true). Se devi porre domande di configurazione condizionali o dinamiche, consulta la configurazione a più passaggi.

Di seguito è riportato un esempio di connettore che richiede all'utente di inserire un codice nome pacchetto npm. Un campo informativo e un campo di input sono definiti nella funzione 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();
}

Definisci i campi con getSchema()

Questa funzione viene chiamata per ottenere lo schema per la richiesta specificata. Tutti i parametri di configurazione definiti dalla funzione getConfig() verranno forniti nell'argomento request. Per i dettagli, consulta il riferimento getSchema().

A seconda dell'origine dati del connettore e della configurazione fornita dall'utente, lo schema potrebbe essere fisso o potresti doverlo fornire dinamicamente al momento della richiesta.

Ad esempio, se un connettore recupera i dati del report in base a un ID report, i dati restituiti per quel report e quindi lo schema potrebbero non essere noti in anticipo. In questo caso, getSchema() potrebbe richiedere il recupero dei dati e lo schema dovrà essere calcolato.

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

Recuperare e restituire dati con getData()

Questa funzione viene chiamata per ottenere i dati per la richiesta specificata. Tutti i parametri di configurazione definiti dalla funzione getConfig() verranno forniti nell'argomento request. Per i dettagli, consulta il riferimento getData().

I seguenti parametri della richiesta getData() richiedono ulteriore attenzione:

  • lastRefresh
    lastRefresh rappresenta un timestamp che indica l'ora dell'ultima richiesta di aggiornamento dei dati. Dovresti essere in grado di analizzare il valore con new Date(timestampString). Se utilizzi il servizio di cache di Apps Script o qualsiasi altro metodo di memorizzazione nella cache, il timestamp lastRefresh può aiutarti a determinare se effettuare una nuova richiesta di recupero all'origine dati o pubblicare i dati dalla cache.

  • dateRange
    Se dateRangeRequired è impostato su true in getConfig(), ogni chiamata getData() conterrà l'intervallo di date selezionato nella richiesta. Per ulteriori dettagli, consulta la sezione Utilizzo degli intervalli di date.

Il seguente esempio recupera i dati in base alla richiesta in entrata e restituisce le statistiche del pacchetto:

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

Completa il manifest del progetto

Il file manifest contiene informazioni sul connettore della community necessarie per implementare e utilizzare il connettore in Looker Studio.

Per modificare il file manifest nell'ambiente di sviluppo di Apps Script, fai clic sul menu Visualizza e poi su Mostra file manifest. Verrà creato un nuovo file manifest appsscript.json.

Aggiorna il manifest in modo da includere i seguenti dati:

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

Per informazioni dettagliate sul manifest di Looker Studio, consulta il riferimento al manifest.

Passaggi successivi

Il passaggio successivo consiste nell'implementare il connettore della community.