Crea un connettore della community

Ecco i passaggi per creare un connettore della community:

1. Creare 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.

Nota: se utilizzi un servizio di terze parti per il tuo connettore, devi conoscere i requisiti necessari per l'utilizzo dell'API, inclusa la generazione di chiavi API e così via.

Scrivi il codice del connettore

Per ogni connettore deve essere definito un insieme specifico di funzioni. L'applicazione di hosting (ad es. Looker Studio) eseguirà queste funzioni. Il connettore dovrebbe gestire le richieste in entrata e rispondere come descritto nel riferimento per l'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. Consulta il riferimento getAuthType() per i dettagli. I metodi di autenticazione attualmente supportati sono elencati nella documentazione di riferimento AuthType.

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

npm-downloads/src/auth.js

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

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

Definisci la configurazione tramite getConfig()

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

In base alla risposta fornita da getConfig(), Looker Studio mostrerà 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 sulla configurazione condizionale o dinamica, consulta la sezione relativa alla configurazione con passaggi.

Di seguito è riportato un esempio di connettore che richiede all'utente di inserire un codice del nome del pacchetto npm. Un campo informazioni e un campo di immissione sono definiti nella funzione getConfig():

npm-downloads/src/main.js

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

Nota: il servizio Apps Script di DataStudio semplifica la scrittura di un connettore della community. Estrae i pattern comuni e offre il completamento automatico in modo che metodi ed enum non debbano essere memorizzati. Per visualizzare la documentazione di riferimento, consulta il servizio Looker Studio

Definisci i campi con getSchema()

Questa funzione viene chiamata per ottenere lo schema per la richiesta specificata. Eventuali parametri di configurazione definiti dalla funzione getConfig() verranno forniti nell'argomento request. Per informazioni dettagliate, vedi il riferimento getSchema().

A seconda dell'origine dati del connettore e della configurazione fornita dall'utente, lo schema potrebbe essere corretto o potrebbe essere necessario fornirlo 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 il report e, di conseguenza, lo schema potrebbero non essere noti in anticipo. In questo caso, getSchema() potrebbe richiedere un recupero dei dati e dovrà essere calcolato lo schema.

Nota: per SELECT_MULTIPLE, il valore configParams è una stringa delimitata da virgole. Per CHECKBOX, il valore di configParam è truthy.

npm-downloads/src/main.js

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

Recupera e restituisce dati con getData()

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

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

• lastRefresh
lastRefresh rappresenta un timestamp che contrassegna l'ora della richiesta di aggiornamento dei dati più recente. Dovresti poter 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 fornire 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 Utilizzo degli intervalli di date.

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

npm-downloads/src/main.js

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

Completa il manifest del progetto

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

Attenzione: tutte le informazioni inserite nel file manifest devono essere considerate pubbliche, in quanto saranno accessibili a chiunque utilizzi il connettore.

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

Aggiorna il file manifest in modo da includere i seguenti dati:

npm-downloads/src/appsscript.json

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

Per maggiori dettagli sul file manifest di Looker Studio, consulta l'articolo di riferimento sul file manifest.

Passaggi successivi

Il prossimo passaggio sarà implementare il connettore della community.