Utwórz społecznościowe oprogramowanie sprzęgające

Aby utworzyć społecznościowe oprogramowanie sprzęgające:

  1. Utwórz nowy projekt Apps Script.
  2. Wpisz kod oprogramowania sprzęgającego.
  3. Uzupełnij plik manifestu projektu.

Tworzenie nowego projektu Apps Script

Otwórz Google Apps Script, aby utworzyć nowy projekt. Apps Script utworzy skrypt domyślny. Możesz usunąć funkcję myFunction i zmienić nazwę nad projektem. (więcej informacji o Apps Script)

Pisanie kodu oprogramowania sprzęgającego

Każde oprogramowanie sprzęgające musi mieć zdefiniowany określony zestaw funkcji. aplikację hostującą (np. Looker Studio) wykona te funkcje. Twoje oprogramowanie sprzęgające ma obsługiwać żądania przychodzące i odpowiadać zgodnie z opisem w zapoznaj się z dokumentacją dotyczącą interfejsu Community Connector API. W przypadku problemów podczas przeczytaj przewodnik debugowania, aby uzyskać pomoc.

Zdefiniuj typ uwierzytelniania w getAuthType()

Ta funkcja jest wywoływana w celu zidentyfikowania metody uwierzytelniania używanej w przypadku Usługa zewnętrzna. Więcej informacji znajdziesz w dokumentacji funkcji getAuthType(). Obecnie listę obsługiwanych metod uwierzytelniania znajdziesz w dokumentacji AuthType.

Na przykład to oprogramowanie sprzęgające nie wymaga uwierzytelniania:

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

Jeśli Twoje źródło danych wymaga uwierzytelniania OAuth 2.0, wyświetl Przewodnik po uwierzytelnianiu przez OAuth 2.0 i dodawanie kolejnych wymaganych funkcji do za pomocą łącznika.

Zdefiniuj konfigurację za pomocą: getConfig()

Funkcja getConfig() jest wywoływana w celu pobrania konfiguracji dla łącznie z wartościami podanymi przez użytkownika, których wymaga oprogramowanie sprzęgające. Zobacz getConfig().

Na podstawie odpowiedzi otrzymanej od getConfig() Looker Studio wyrenderuje ekranu konfiguracji oprogramowania sprzęgającego. Zobaczysz listę obsługiwanych elementów konfiguracji. w dokumentacji ConfigType.

Jeśli źródło danych wymaga podania daty jako parametru, wywołaj config.setDateRangeRequired(true). Jeśli chcesz zapytać o tryb warunkowy lub dynamiczny na pytania dotyczące konfiguracji znajdziesz w artykule o konfiguracji krokowej.

Poniżej znajduje się przykład oprogramowania sprzęgającego, które wymaga od użytkownika wpisania kod nazwy pakietu npm. Pole informacji i pole do wprowadzania danych są zdefiniowane w sekcji Funkcja 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();
}
.

Zdefiniuj pola za pomocą getSchema()

Ta funkcja jest wywoływana w celu pobrania schematu dla danego żądania. Dowolne zostaną podane parametry konfiguracji zdefiniowane przez funkcję getConfig() w argumencie request. Więcej informacji znajdziesz w dokumentacji getSchema().

W zależności od źródła danych oprogramowania sprzęgającego i konfiguracji dostarczonej przez użytkownika, schemat może zostać poprawiony lub trzeba go będzie dynamicznie udostępniać w czasu żądania.

Jeśli na przykład oprogramowanie sprzęgające pobiera dane raportu na podstawie identyfikatora raportu, komponent danych zwracanych dla tego raportu, więc schemat może nie być wcześniej znany. W tym przypadku getSchema() może wymagać pobrania danych, a schemat musi .

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

Pobieranie i zwracanie danych za pomocą getData()

Ta funkcja jest wywoływana w celu pobrania danych dla danego żądania. Dowolna konfiguracja parametry zdefiniowane przez funkcję getConfig() zostaną udostępnione w parametrze request. Więcej informacji znajdziesz w dokumentacji getData().

Te parametry z żądania getData() wymagają dodatkowych uwaga:

  • lastRefresh
    lastRefresh wskazuje sygnaturę czasową, która wskazuje czas ostatniej poprosić o odświeżenie danych. Wartość powinna być analizowana za pomocą argumentu new Date(timestampString) Jeśli używasz Apps Script Cache Service lub innej metody buforowania, sygnatura czasowa lastRefresh pomoże Ci określić, czy wysłać do źródła danych nowe żądanie pobierania czy wyświetlać treści z pamięci podręcznej.

  • dateRange
    Jeśli dateRangeRequired ma wartość true w konfiguracji getConfig(), każdy element getData() będzie zawierać wybrany zakres dat w żądaniu. Zobacz Więcej informacji znajdziesz w artykule Praca z zakresami dat.

Ten przykład pobiera dane na podstawie przychodzącego żądania i zwraca statystyki przesyłki:

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

Ukończ plik manifestu projektu

Plik manifestu zawiera informacje o społecznym oprogramowaniu sprzęgającym, które są wymagane do wdrożenia i używania oprogramowania sprzęgającego w Looker Studio.

Aby edytować plik manifestu w środowisku programistycznym Apps Script, kliknij otwórz menu Widok i kliknij Pokaż plik manifestu. Spowoduje to utworzenie nowego appsscript.json plik manifestu.

Zaktualizuj plik manifestu, aby zawierał te dane:

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

Szczegółowe informacje o pliku manifestu Looker Studio znajdziesz w dokumentacji pliku manifestu.

Dalsze kroki

Następnym krokiem będzie wdrożenie społecznościowego oprogramowania sprzęgającego.