Crea un connettore della community

Ecco i passaggi per creare un connettore della community:

  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à un'istanza script predefinito. Puoi rimuovere la funzione myFunction e rinominarla del progetto. (Scopri di più su Apps Script)

Scrivi il codice del connettore

Per ogni connettore è necessario definire un insieme specifico di funzioni. La un'applicazione di hosting (ad es. Looker Studio) eseguirà queste funzioni. Il tuo deve gestire le richieste in entrata e rispondere come descritto in consulta il riferimento dell'API Community Connector. 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 servizio di terze parti. Per informazioni dettagliate, consulta il riferimento getAuthType(). Attuale I metodi di autenticazione supportati sono elencati nel riferimento di 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, visualizza la sezione guida all'autenticazione OAuth 2.0 e aggiungi le altre funzioni richieste alle del connettore.

Definisci la configurazione tramite getConfig()

La funzione getConfig() viene chiamata per ottenere la configurazione per inclusi i valori forniti dall'utente richiesti dal connettore stesso. Consulta getConfig() Riferimento per i dettagli.

In base alla risposta fornita da getConfig(), Looker Studio eseguirà il rendering di configurazione del connettore di rete. Gli elementi di configurazione supportati sono elencati nel riferimento ConfigType.

Se l'origine dati richiede la data come parametro, richiama config.setDateRangeRequired(true). Per domande condizionali o dinamiche, di configurazione, consulta la configurazione dei passaggi.

Di seguito è riportato un esempio di connettore che richiede all'utente di inserire un Codice del nome del pacchetto npm. Un'informazione e un campo di immissione sono definiti nel 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. Qualsiasi verranno forniti i parametri di configurazione definiti dalla funzione getConfig() nell'argomento request. Per informazioni dettagliate, consulta la documentazione di riferimento di getSchema().

A seconda dell'origine dati del connettore e della configurazione fornita lo schema può essere fisso oppure potresti doverlo fornire in modo dinamico l'ora della richiesta.

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

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 relativi alla richiesta specifica. Qualsiasi configurazione parametri definiti dalla funzione getConfig() verranno forniti nel request argomento. Per informazioni dettagliate, consulta la documentazione di riferimento di getData().

I seguenti parametri della richiesta getData() richiedono :

  • lastRefresh
    lastRefresh rappresenta un timestamp che segna l'ora dell'evento più recente una 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 di memorizzazione nella cache, il timestamp lastRefresh può aiutarti a determinare se inviare una nuova richiesta di recupero all'origine dati o pubblicare direttamente dalla cache.

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

L'esempio seguente recupera i dati in base alla richiesta in entrata e restituisce l'oggetto statistiche 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 tuo connettore della community, necessaria per eseguire il deployment del connettore in Looker Studio e utilizzarlo.

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

Aggiorna il file manifest in modo che includa 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 maggiori dettagli sul manifest di Looker Studio, consulta il riferimento del file manifest di riferimento.

Passaggi successivi

Il passaggio successivo sarà implementare il tuo connettore della community.