Crea un conector de comunidad

Los pasos para crear un Conector de la comunidad son los siguientes:

1. Crea un nuevo proyecto de Apps Script.
2. Escribe el código del conector.
3. Completa el manifiesto del proyecto.

Crea un nuevo proyecto de Apps Script

Visita Google Apps Script para crear un proyecto nuevo. Apps Script creará un secuencia de comandos predeterminada para ti. Puedes quitar la función myFunction y cambiarle el nombre el proyecto. (Más información sobre Apps Script)

Nota: Si usas un servicio de terceros para tu conector, debes familiarizarse con los requisitos que tienen para usar la API, incluida la generación de Claves de API, etcétera.

Escribe el código del conector

Cada conector debe tener definido un conjunto específico de funciones. El de hosting (p.ej., Looker Studio) ejecutará estas funciones. Tu que el conector gestione las solicitudes entrantes y responda como se describe en la referencia de la API de Community Connector. Si tienes problemas durante el desarrollo tu código, lee la guía de depuración si necesitas ayuda.

Define el tipo de autenticación en getAuthType()

Esta función se llama para identificar el método de autenticación que se usa para la Servicio de terceros. Consulta la referencia de getAuthType() para obtener más información. Actualmente los métodos de autenticación compatibles se enumeran en la referencia de AuthType.

Por ejemplo, el siguiente conector no requiere autenticación:

npm-downloads/src/auth.js

Ver en 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 tu fuente de datos requiere autenticación OAuth 2.0, consulta el Guía de autenticación de OAuth 2.0 y agrega las funciones adicionales necesarias para del conector.

Define la configuración a través de getConfig()

Se llama a la función getConfig() para obtener la configuración de la conector, incluidos los valores proporcionados por el usuario que requiere el conector. Consulta Consulta la referencia de getConfig() para obtener más detalles.

Según la respuesta de getConfig(), Looker Studio renderizará el de la configuración del conector. Se enumeran los elementos de configuración admitidos en la referencia de ConfigType.

Si tu fuente de datos requiere la fecha como parámetro, llama config.setDateRangeRequired(true). Si necesitas pedirle al público configuración, consulta configuración escalonada.

El siguiente es un ejemplo de un conector que requiere que el usuario ingrese un npm. Una información y un campo de entrada se definen en el Función getConfig():

npm-downloads/src/main.js

Ver en 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: El servicio de Apps Script DataStudio facilita la escritura de una comunidad o del conector. Abstrae patrones comunes y ofrece autocompletado para que los métodos y los valores de enumeración no tienen que memorizarse. Para ver la documentación de referencia, consultar el servicio de Looker Studio

Define los campos con getSchema()

Se llama a esta función para obtener el esquema de la solicitud determinada. Cualquiera Se proporcionarán los parámetros de configuración definidos por la función getConfig() en el argumento request. Consulta la referencia de getSchema() para obtener más detalles.

Según la fuente de datos del conector y la configuración proporcionada por el usuario, es posible que se corrija el esquema o que debas proporcionarlo de forma dinámica en la hora de la solicitud.

Por ejemplo, si un conector recupera datos de informes en función de un ID de informe, el los datos devueltos para ese informe y, por lo tanto, es posible que el esquema no se conozca de antemano. En este caso, es posible que getSchema() requiera una recuperación de datos, y el esquema deberá calcular.

Nota: Para SELECT_MULTIPLE, el valor configParams está delimitado por comas una cadena vacía. Para CHECKBOX, el valor de configParam es verdad.

npm-downloads/src/main.js

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

Cómo recuperar y mostrar datos con getData()

Se llama a esta función para obtener datos de la solicitud dada. Cualquier configuración Los parámetros definidos por la función getConfig() se proporcionarán en el request. Consulta la referencia de getData() para obtener más detalles.

Los siguientes parámetros de la solicitud getData() requieren atención:

• lastRefresh
lastRefresh representa una marca de tiempo que indica la hora de la última solicitar una actualización de datos. Deberías poder analizar el valor con new Date(timestampString) Si usas el servicio de caché de Apps Script o Con cualquier otro método de almacenamiento en caché, la marca de tiempo lastRefresh puede ayudarte a determinar si se debe realizar una nueva solicitud de recuperación a la fuente de datos o entregarla los datos de la caché.

• dateRange
  Si dateRangeRequired se establece en true en getConfig(), cada getData() llamada contendrá el período seleccionado en la solicitud. Consulta Consulta Cómo trabajar con períodos para obtener más detalles.

En el siguiente ejemplo, se recuperan datos según la solicitud entrante y se muestra el estadísticas del paquete:

npm-downloads/src/main.js

Ver en 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 el manifiesto del proyecto

El archivo de manifiesto contiene información sobre tu Community Connector que se necesario para implementar y usar tu conector en Looker Studio.

Precaución: Cualquier información que incluyas en el archivo de manifiesto debe considerarse público, ya que será accesible para cualquier persona que use tu conector.

Para editar el archivo de manifiesto en el entorno de desarrollo de Apps Script, haz clic en el menú Ver y haz clic en Mostrar archivo de manifiesto. Esto creará un nuevo Archivo de manifiesto appsscript.json.

Actualiza el manifiesto para que incluya los siguientes datos:

npm-downloads/src/appsscript.json

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

Para obtener detalles sobre el manifiesto de Looker Studio, consulta la referencia del manifiesto de referencia.

Próximos pasos

El siguiente paso será implementar Community Connector.