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

Aby utworzyć społecznościowe oprogramowanie sprzęgające, wykonaj te czynności:

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 dla Ciebie domyślny skrypt. Możesz usunąć funkcję myFunction i zmienić nazwę projektu. (Więcej informacji o Apps Script)

Uwaga: jeśli używasz usługi innej firmy do obsługi złącza, musisz zapoznać się z jej wymaganiami dotyczącymi korzystania z interfejsu API, w tym z generowaniem kluczy interfejsu API itp.

Pisanie kodu oprogramowania sprzęgającego

Każde złącze musi mieć zdefiniowany określony zestaw funkcji. Aplikacja hostująca (np. Looker Studio) będzie wykonywać te funkcje. Oczekuje się, że Twój konektor będzie obsługiwać żądania przychodzące i odpowiadać na nie zgodnie z opisem w dokumentacji interfejsu Community Connector API. Jeśli podczas tworzenia kodu napotkasz problemy, zapoznaj się z przewodnikiem po debugowaniu.

Określ typ uwierzytelniania w funkcji getAuthType()

Ta funkcja jest wywoływana w celu określenia metody uwierzytelniania używanej w usłudze innej firmy. Szczegółowe informacje znajdziesz w materiałach referencyjnych dotyczących funkcji getAuthType(). Obecnie obsługiwane metody uwierzytelniania są wymienione w AuthTypedokumentacji.

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

npm-downloads/src/auth.js

Wyświetl w GitHubie

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 źródło danych wymaga uwierzytelniania OAuth 2.0, zapoznaj się z przewodnikiem po uwierzytelnianiu OAuth 2.0 i dodaj do konektora dodatkowe wymagane funkcje.

Określanie konfiguracji za pomocą getConfig()

Funkcja getConfig() jest wywoływana w celu uzyskania konfiguracji łącznika, w tym wartości podanych przez użytkownika, których wymaga łącznik. Szczegółowe informacje znajdziesz w getConfig().

Na podstawie odpowiedzi udzielonej przez getConfig() Looker Studio wyświetli ekran konfiguracji łącznika. Obsługiwane elementy konfiguracji są wymienione w ConfigTypetym dokumencie.

Jeśli źródło danych wymaga daty jako parametru, wywołaj funkcję config.setDateRangeRequired(true). Jeśli chcesz zadać pytania dotyczące konfiguracji warunkowej lub dynamicznej, zapoznaj się z informacjami o konfiguracji krokowej.

Poniżej znajdziesz przykład oprogramowania sprzęgającego, które wymaga od użytkownika wpisania nazwy pakietu npm. Pole informacyjne i pole wejściowe są zdefiniowane w funkcji getConfig():

npm-downloads/src/main.js

Wyświetl w GitHubie

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

Uwaga: usługa DataStudio Apps Script ułatwia pisanie złącza społeczności. Upraszcza typowe wzorce i oferuje autouzupełnianie, dzięki czemu nie musisz pamiętać metod ani wartości wyliczeniowych. Dokumentację znajdziesz w usłudze Looker Studio

.

Definiowanie pól za pomocą funkcji getSchema()

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

W zależności od źródła danych konektora i konfiguracji podanej przez użytkownika schemat może być stały lub trzeba go dynamicznie podawać w momencie wysyłania żądania.

Jeśli na przykład łącznik pobiera dane raportu na podstawie identyfikatora raportu, dane zwrócone dla tego raportu, a tym samym schemat, mogą nie być znane z wyprzedzeniem. W takim przypadku getSchema() może wymagać pobrania danych, a schemat będzie musiał zostać obliczony.

Uwaga: w przypadku parametru SELECT_MULTIPLE wartość configParams jest ciągiem znaków rozdzielonym przecinkami. W przypadku CHECKBOX wartość configParams to truthy.

npm-downloads/src/main.js

Wyświetl w GitHubie

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

Ta funkcja jest wywoływana w celu pobrania danych dla danego żądania. Wszystkie parametry konfiguracji zdefiniowane przez funkcję getConfig() zostaną podane w argumencie request. Więcej informacji znajdziesz w getData()materiałach referencyjnych.

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

• lastRefresh
lastRefresh to sygnatura czasowa, która oznacza czas ostatniej prośby o odświeżenie danych. Wartość powinna być możliwa do przeanalizowania za pomocą funkcji new Date(timestampString). Jeśli używasz usługi pamięci podręcznej Apps Script lub innej metody buforowania, sygnatura czasowa lastRefresh może pomóc Ci określić, czy wysłać nowe żądanie pobrania do źródła danych, czy udostępnić dane z pamięci podręcznej.

• dateRange
  Jeśli w getConfig() parametr dateRangeRequired ma 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.

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

npm-downloads/src/main.js

Wyświetl w GitHubie

// 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 łączniku społecznościowym, które są wymagane do wdrożenia i używania łącznika w Looker Studio.

Ostrzeżenie: wszelkie informacje umieszczone w pliku manifestu należy traktować jako publiczne, ponieważ będą one dostępne dla każdego, kto korzysta z Twojego łącznika.

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

Zaktualizuj plik manifestu, dodając te dane:

npm-downloads/src/appsscript.json

Wyświetl w GitHubie

{
  "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 manifeście Looker Studio znajdziesz w dokumentacji manifestu.

Dalsze kroki

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