Community-Connector erstellen

So erstellen Sie einen Community-Connector:

  1. Erstellen Sie ein neues Apps Script-Projekt.
  2. Schreiben Sie den Connector-Code.
  3. Vervollständigen Sie das Projektmanifest.

Neues Apps Script-Projekt erstellen

Rufen Sie Google Apps Script auf, um ein neues Projekt zu erstellen. Apps Script erstellt ein für Sie ein. Sie können die Funktion myFunction entfernen und umbenennen für das Projekt. Weitere Informationen zu Apps Script

Connector-Code schreiben

Für jeden Connector muss ein bestimmter Satz von Funktionen definiert sein. Die Hostinganwendung (z.B. Looker Studio) diese Funktionen ausführen. Ihr wird erwartet, dass der Connector eingehende Anfragen verarbeitet und wie in folgendem Artikel beschrieben antwortet: Community Connector API-Referenz Wenn Sie bei der Entwicklung Ihren Code erhalten, finden Sie im Leitfaden zur Fehlerbehebung.

Authentifizierungstyp in getAuthType() definieren

Diese Funktion wird aufgerufen, um die für die Drittanbieterdienst. Weitere Informationen finden Sie in der Referenz zu getAuthType(). Aktuell Die unterstützten Authentifizierungsmethoden sind in der Referenz zu AuthType aufgeführt.

Für den folgenden Connector ist beispielsweise keine Authentifizierung erforderlich:

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

Wenn für Ihre Datenquelle eine OAuth 2.0-Authentifizierung erforderlich ist, öffnen Sie die Leitfaden zur OAuth 2.0-Authentifizierung und fügen Sie die zusätzlichen erforderlichen Funktionen an Ihren Connector.

Konfiguration über getConfig() definieren

Die Funktion getConfig() wird aufgerufen, um die Konfiguration für die Connector-Typ, einschließlich der vom Nutzer bereitgestellten Werte, die der Connector benötigt. Weitere Informationen finden Sie unter getConfig().

Anhand der von getConfig() erhaltenen Antwort wird in Looker Studio Folgendes gerendert: Konfigurationsbildschirm des Connectors. Die unterstützten Konfigurationselemente sind aufgeführt in der Referenz zu ConfigType.

Wenn für Ihre Datenquelle ein Datum als Parameter erforderlich ist, rufen Sie config.setDateRangeRequired(true). Wenn Sie bedingte oder dynamische Informationen zur Konfiguration finden Sie unter Schrittweise Konfiguration.

Im folgenden Beispiel für einen Connector muss der Nutzer eine npm-Paketnamencode. Ein Info- und ein Eingabefeld werden im getConfig()-Funktion:

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

Felder mit getSchema() definieren

Diese Funktion wird aufgerufen, um das Schema für die angegebene Anfrage abzurufen. Beliebig Von der Funktion getConfig() definierte Konfigurationsparameter werden bereitgestellt im Argument request. Weitere Informationen finden Sie in der Referenz zu getSchema().

Abhängig von der Datenquelle des Connectors und der Konfiguration des kann das Schema festgelegt sein oder Sie müssen dies dynamisch Zeitpunkt der Anfrage.

Wenn ein Connector beispielsweise Berichtsdaten auf Basis einer Berichts-ID abruft, für diesen Bericht zurückgegebene Daten. Daher ist das Schema möglicherweise nicht im Voraus bekannt. In diesem Fall erfordert getSchema() möglicherweise einen Datenabruf und das Schema muss berechnet werden.

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

Daten mit getData() abrufen und zurückgeben

Diese Funktion wird aufgerufen, um Daten für die angegebene Anfrage abzurufen. Beliebige Konfiguration Von der Funktion getConfig() definierte Parameter werden im request-Argument Weitere Informationen finden Sie in der Referenz zu getData().

Die folgenden Parameter der getData()-Anfrage erfordern zusätzliche Aufmerksamkeit:

  • lastRefresh
    lastRefresh steht für einen Zeitstempel, der den Zeitpunkt der Anforderung einer Aktualisierung der Daten. Sie sollten in der Lage sein, den Wert mit new Date(timestampString) Wenn Sie den Apps Script Cache Service oder jede andere Caching-Methode, kann Ihnen der Zeitstempel lastRefresh dabei helfen, ermitteln, ob eine neue Abrufanfrage an die Datenquelle gestellt oder eine Daten aus dem Cache.

  • dateRange
    Wenn dateRangeRequired in getConfig() auf true gesetzt ist, wird jeder getData() -Aufruf enthält den ausgewählten Zeitraum in der Anfrage. Weitere Informationen finden Sie unter Weitere Informationen

Im folgenden Beispiel werden Daten basierend auf der eingehenden Anfrage abgerufen und der Paketstatistiken:

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

Projektmanifest ausfüllen

Die Manifestdatei enthält Informationen zu Ihrem Community-Connector. erforderlich, um den Connector in Looker Studio bereitzustellen und zu verwenden.

Um die Manifestdatei in der Apps Script-Entwicklungsumgebung zu bearbeiten, klicken Sie auf das Menü Ansicht und klicken Sie auf Manifestdatei anzeigen. Dadurch wird ein neues Manifestdatei von appsscript.json.

Aktualisieren Sie das Manifest, sodass es die folgenden Daten enthält:

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

Weitere Informationen zum Looker Studio-Manifest finden Sie in der Referenz zu Manifesten.

Nächste Schritte

Im nächsten Schritt stellen Sie den Community-Connector bereit.