Crea un connettore della community

I passaggi per creare un connettore della scheda Community sono:

1. Crea un nuovo progetto Apps Script.
2. Scrivi il codice del connettore.
3. Completa il file 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 connettore, devi conoscere i requisiti per l'utilizzo dell'API, inclusa la generazione di chiavi API e così via.

Scrivi il codice del connettore

Ogni connettore deve avere un insieme specifico di funzioni definite. L'applicazione di hosting (ad es. Data Studio) eseguirà queste funzioni. Il connettore deve gestire le richieste in entrata e rispondere come descritto in riferimento all'API del connettore della scheda Community. Se riscontri problemi durante lo sviluppo del codice, consulta 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 maggiori dettagli, consulta il riferimento a 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

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 richieste a l 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 maggiori dettagli, consulta il riferimento a getConfig().

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

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

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

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 Apps5/} Script semplifica la scrittura di un connettore della scheda Community connector.DataStudio Estrae pattern comuni e offre il completamento automatico, in modo che non sia necessario memorizzare metodi e valori enum. Per visualizzare la documentazione di riferimento, consulta la sezione [Servizio Data Studio]

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 maggiori dettagli, consulta il riferimento a getSchema().

A seconda dell'origine dati del connettore e della configurazione fornita dall'utente, lo schema potrebbe essere fisso oppure dovrai fornirlo dinamicamente al momento della richiesta.

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

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 restituisci i 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 maggiori dettagli, consulta il riferimento a 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 getData() chiamata conterrà l'intervallo di date selezionato nella richiesta. Per maggiori dettagli, consulta la sezione Utilizzare gli 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

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 file manifest del progetto

Il file manifest contiene informazioni sul connettore della scheda Community necessarie per eseguire il deployment e utilizzare il connettore in Data 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 e poi 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 Data Studio, consulta il riferimento al file manifest.

Passaggi successivi

Il passaggio successivo consiste nell'eseguire il deployment del connettore della scheda Community.