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

Aby utworzyć społecznościowe oprogramowanie sprzęgające, należy:

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

Tworzenie nowego projektu Apps Script

Aby utworzyć nowy projekt, otwórz stronę Google Apps Script. Apps Script utworzy za Ciebie domyślny skrypt. Możesz usunąć funkcję myFunction i zmienić nazwę projektu. (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. Funkcje te będą wykonywane przez aplikację hostującą (np. Looker Studio). Oprogramowanie sprzęgające powinno obsługiwać przychodzące żądania i odpowiadać w sposób opisany w dokumentacji interfejsu Community Connector API. Jeśli podczas tworzenia kodu wystąpią problemy, przeczytaj przewodnik dotyczący debugowania, aby uzyskać pomoc.

Zdefiniuj typ uwierzytelniania w getAuthType()

Funkcja ta jest wywoływana w celu identyfikacji metody uwierzytelniania używanej w usłudze innej firmy. Więcej informacji znajdziesz w dokumentacji getAuthType(). Obecnie obsługiwane metody uwierzytelniania znajdziesz w dokumentacji AuthType.

Na przykład poniższe 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, zapoznaj się z przewodnikiem po uwierzytelnianiu OAuth 2.0 i dodaj do oprogramowania sprzęgającego dodatkowe wymagane funkcje.

Zdefiniuj konfigurację za pomocą opcji getConfig()

Funkcja getConfig() jest wywoływana w celu pobrania konfiguracji oprogramowania sprzęgającego z uwzględnieniem wartości podanych przez użytkownika, które są wymagane przez oprogramowanie sprzęgające. Więcej informacji znajdziesz w dokumentacji getConfig().

Na podstawie odpowiedzi przesłanej przez getConfig() Looker Studio wyrenderuje ekran konfiguracji oprogramowania sprzęgającego. Obsługiwane elementy konfiguracji znajdziesz w dokumentacji ConfigType.

Jeśli Twoje źródło danych wymaga parametru date, wywołaj config.setDateRangeRequired(true). Jeśli musisz zadać pytania dotyczące konfiguracji warunkowej lub dynamicznej, zapoznaj się z sekcją dotyczącą konfiguracji krokowej.

Poniżej znajdziesz przykład oprogramowania sprzęgającego, które wymaga od użytkownika wpisania kodu nazwy pakietu npm. Pole informacji i pole do wprowadzania danych są zdefiniowane w funkcji 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ą metody getSchema()

Ta funkcja jest wywoływana w celu pobrania schematu dla danego żądania. Wszystkie parametry konfiguracji zdefiniowane przez funkcję getConfig() będą podane 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 udostępnionej przez użytkownika schemat może być stały lub wymagać dynamicznego dostarczania w momencie żądania.

Jeśli na przykład oprogramowanie sprzęgające pobiera dane raportu na podstawie identyfikatora raportu, dane zwrócone z tego raportu, więc schemat może być wcześniej nieznane. W tym przypadku getSchema() może wymagać pobrania danych i konieczne jest obliczenie schematu.

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ą metody getData()

Funkcja ta jest wywoływana w celu uzyskania danych dla danego żądania. Wszystkie parametry konfiguracji zdefiniowane przez funkcję getConfig() będą podane w argumencie request. Więcej informacji znajdziesz w dokumentacji getData().

Te parametry żądania getData() wymagają dodatkowej uwagi:

  • lastRefresh
    lastRefresh oznacza sygnaturę czasową, która wskazuje czas ostatniego żądania odświeżenia danych. Możesz przeanalizować wartość za pomocą funkcji new Date(timestampString). Jeśli korzystasz z usługi Apps Script Cache lub innej metody buforowania, sygnatura czasowa lastRefresh może pomóc Ci w określeniu, czy wysłać nowe żądanie pobierania do źródła danych, czy udostępniać dane z pamięci podręcznej.

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

Poniższy przykład pobiera dane na podstawie przychodzącego żądania i zwraca statystyki pakietu:

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

Wypełnij plik manifestu projektu

Plik manifestu zawiera informacje o społecznościowym oprogramowaniu sprzęgającym, które są wymagane do wdrożenia oprogramowania sprzęgającego i korzystania z niego w Looker Studio.

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

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.