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. 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 skrypt domyślny. 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 oprogramowanie sprzęgające musi mieć zdefiniowany określony zestaw funkcji. Aplikacja hostująca (np. Studio danych) wykona te funkcje. Oczekuje się, że Twoje oprogramowanie sprzęgające będzie obsługiwać żądania przychodzące i odpowiadać na nie w sposób opisany w dokumentacji interfejsu Community Connector API. Jeśli podczas tworzenia kodu napotkasz problemy, zapoznaj się z przewodnikiem po debugowaniu.

Określanie typu 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 AuthType.

Na przykład ten łącznik 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 oprogramowania sprzęgającego dodatkowe wymagane funkcje.

Określanie konfiguracji za pomocą getConfig()

Funkcja getConfig() jest wywoływana w celu uzyskania konfiguracji oprogramowania sprzęgającego, w tym wartości podanych przez użytkownika, których wymaga oprogramowanie sprzęgające. Szczegółowe informacje znajdziesz w getConfig().

Na podstawie odpowiedzi podanej przez getConfig() Studio danych wyświetli ekran konfiguracji oprogramowania sprzęgającego. Obsługiwane elementy konfiguracji są wymienione w ConfigTypeodniesieniu.

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 kodu nazwy pakietu npm. Pole informacyjne i pole do wprowadzania danych 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ściowego. Upraszcza typowe wzorce i oferuje autouzupełnianie, dzięki czemu nie musisz pamiętać metod ani wartości wyliczeniowych. Aby wyświetlić dokumentację, zapoznaj się z [usługą Studio danych]

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 oprogramowania sprzęgającego i konfiguracji podanej przez użytkownika schemat może być stały lub może być konieczne dynamiczne podawanie go 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 góry. 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ść configParam 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.

Następujące 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 sekcji 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 Studio danych.

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

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, 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 Studia danych znajdziesz w dokumentacji referencyjnej.

Dalsze kroki

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