Community-Connector erstellen

So erstellen Sie einen Community Connector:

1. Erstellen Sie ein neues Apps Script-Projekt.
2. Schreiben Sie den Connector-Code.
3. Füllen Sie das Projektmanifest aus.

Neues Apps Script-Projekt erstellen

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

Hinweis :Wenn Sie einen Drittanbieterdienst für Ihren Connector verwenden, müssen Sie sich mit den Anforderungen vertraut machen, die für die Verwendung der API gelten, z. B. das Generieren von API-Schlüsseln.

Connector-Code schreiben

Für jeden Connector muss ein bestimmter Satz von Funktionen definiert sein. Die Hostinganwendung (z.B. Looker Studio) führt diese Funktionen aus. Ihr Connector muss eingehende Anfragen verarbeiten und wie in der Community Connector API-Referenz beschrieben antworten. Wenn beim Entwickeln des Codes Probleme auftreten, finden Sie in der Anleitung zur Fehlerbehebung Hilfe.

Authentifizierungstyp in getAuthType() definieren

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

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

npm-downloads/src/auth.js

Auf GitHub ansehen

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 die OAuth 2.0-Authentifizierung erforderlich ist, lesen Sie den Leitfaden zur OAuth 2.0-Authentifizierung und fügen Sie Ihrem Connector die zusätzlich erforderlichen Funktionen hinzu.

Konfiguration über getConfig() definieren

Die Funktion getConfig() wird aufgerufen, um die Konfiguration für den Connector abzurufen, einschließlich der vom Nutzer angegebenen Werte, die für Ihren Connector erforderlich sind. Weitere Informationen finden Sie in der Referenz zu getConfig().

Anhand der von getConfig() bereitgestellten Antwort wird in Looker Studio der Bildschirm für die Connector-Konfiguration gerendert. Die unterstützten Konfigurationselemente sind in der Referenz zu ConfigType aufgeführt.

Wenn für Ihre Datenquelle ein Datum als Parameter erforderlich ist, rufen Sie config.setDateRangeRequired(true) auf. Wenn Sie Fragen zur bedingten oder dynamischen Konfiguration stellen müssen, lesen Sie den Abschnitt Konfiguration in Schritten.

Im Folgenden sehen Sie ein Beispiel für einen Connector, bei dem der Nutzer einen npm-Paketnamen-Code eingeben muss. In der Funktion getConfig() werden ein Infofeld und ein Eingabefeld definiert:

npm-downloads/src/main.js

Auf GitHub ansehen

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

Hinweis :Der Apps Script-Dienst DataStudio erleichtert das Schreiben eines Community-Connectors. Es abstrahiert gängige Muster und bietet die automatische Vervollständigung, sodass Methoden und Enumerationswerte nicht auswendig gelernt werden müssen. Die Referenzdokumentation finden Sie unter Looker Studio-Dienst.

Felder mit getSchema() definieren

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

Je nach Datenquelle des Connectors und der vom Nutzer bereitgestellten Konfiguration kann das Schema fest sein oder Sie müssen es dynamisch zur Anfragezeit bereitstellen.

Wenn ein Connector beispielsweise Berichtsdaten anhand einer Berichts-ID abruft, sind die für diesen Bericht zurückgegebenen Daten und damit das Schema möglicherweise nicht im Voraus bekannt. In diesem Fall muss getSchema() möglicherweise Daten abrufen und das Schema muss berechnet werden.

Hinweis: Für SELECT_MULTIPLE ist der Wert configParams ein durch Kommas getrennter String. Für CHECKBOX ist der Wert von configParam wahr.

npm-downloads/src/main.js

Auf GitHub ansehen

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. Alle von der getConfig()-Funktion definierten Konfigurationsparameter werden im request-Argument bereitgestellt. Weitere Informationen finden Sie in der Referenz zu getData().

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

• lastRefresh
lastRefresh steht für einen Zeitstempel, der den Zeitpunkt der letzten Anfrage zum Aktualisieren von Daten angibt. Sie sollten den Wert mit new Date(timestampString) parsen können. Wenn Sie den Apps Script Cache Service oder eine andere Caching-Methode verwenden, können Sie anhand des lastRefresh-Zeitstempels feststellen, ob Sie eine neue Abrufanfrage an die Datenquelle senden oder Daten aus dem Cache bereitstellen sollen.

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

Im folgenden Beispiel werden Daten basierend auf der eingehenden Anfrage abgerufen und die Paketstatistiken zurückgegeben:

npm-downloads/src/main.js

Auf GitHub ansehen

// 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 fertigstellen

Die Manifestdatei enthält Informationen zu Ihrem Community Connector, die für die Bereitstellung und Verwendung des Connectors in Looker Studio erforderlich sind.

Achtung :Alle Informationen, die Sie in die Manifestdatei einfügen, sollten als öffentlich betrachtet werden, da sie für alle Nutzer Ihres Connectors zugänglich sind.

Wenn Sie die Manifestdatei in der Apps Script-Entwicklungsumgebung bearbeiten möchten, klicken Sie auf das Menü Ansicht und dann auf Manifestdatei anzeigen. Dadurch wird eine neue appsscript.json-Manifestdatei erstellt.

Aktualisieren Sie das Manifest mit den folgenden Daten:

npm-downloads/src/appsscript.json

Auf GitHub ansehen

{
  "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 Manifest-Referenz.

Nächste Schritte

Als Nächstes müssen Sie Ihren Community Connector bereitstellen.