Создание настраиваемого коннектора Google Data Studio от А до Я. Часть 1

В предыдущей статье я описал идею коннекторов Google Data Studio. Теперь я хочу показать вам, как его построить. Я буду создавать коннектор для отображения статистики о треках, проигранных в Spotify, чтобы, например, пользователь мог видеть, какой исполнитель был его самым популярным за указанный период времени. Для этого я воспользуюсь общедоступным API Spotify.

В этой статье я опишу основные этапы создания коннектора и покажу вам, как настроить среду разработки.

Если вы не проявите терпения, вы можете найти полный код этой статьи на странице https://github.com/Bajena/spotify-gds-connector/tree/Tutorial1;). Вы также можете протестировать разъем по ссылке this.

Пойдем!

Шаг 1 - Настройте скрипт Google

Коннектор GDS - это, по сути, скрипт Google, который реализует интерфейс, предоставляемый Google, поэтому для работы с Google Data Studio наш коннектор должен будет реагировать на следующие методы:
- getAuthType
- getConfig
- getSchema
- getData

Чтобы создать сценарий, перейдите на https://script.google.com и создайте новый сценарий.

Первое, что я рекомендую после создания скрипта, - это установить правильные права доступа. Если вы хотите, чтобы коннектор работал и для других людей, выберите «Все, у кого есть ссылка». Не волнуйтесь, никто не увидит ваш код, если вы явно не дадите ему ссылку. Эта опция просто позволит Google Data Studio правильно получить доступ к вашему скрипту.

Шаг 2 - Среда настройки (также известная как «Развертывание»)

Во-вторых, мне потребовалось время, чтобы понять, как выпускать новые версии разъемов. Следует ли хранить отдельные файлы сценариев для производственной среды / среды разработки? Нет, Google изобрел концепцию «развертываний» и «версий».

Вы можете думать о «версиях» как о состоянии базы кода ярлыков, подобно тегам GIT. Версию можно применить к «развертыванию», которое можно сравнить с сервером, на котором вы развертываете свои веб-приложения.

По умолчанию существует только одно специальное развертывание под названием «Последняя версия» - оно особенное, потому что вы не можете применить к нему какие-либо версии. Развертывание «Последней версии» всегда будет запускать точный код, который вы можете увидеть в редакторе Google, поэтому в основном его можно рассматривать как среду «разработчика».

Мы хотели бы иметь еще одну среду под названием «Производство», которая не будет ломаться каждый раз, когда мы добавляем новый символ в наш код. Итак, сначала перейдите в Файл - ›Управление версиями и создайте новую версию под названием« Начальная версия ».

Затем перейдите в Опубликовать - ›Развернуть из манифеста…, нажмите« Создать », введите имя« Производство »и выберите версию 1 (версию, которую мы только что создали). Теперь у нас будет производственная среда, привязанная к версии 1, и если мы когда-нибудь захотим обновить производственную среду, нам просто нужно поднять ее версию.

Шаг 3 - Настройка локальной разработки

Когда я начал работать над сценарием, мне быстро стало не хватать функций моего любимого текстового редактора (Sublime Text 3). Несмотря на то, что редактор Google работает не так уж плохо и даже имеет такие функции, как завершение кода, он не может заменить расширенные редакторы / IDE.

Конечно, одна из идей заключалась в том, чтобы написать код в Sublime, а затем скопировать и вставить его в редактор Google, однако, как только мой код стал больше одного файла, он начал сильно раздражать, поэтому мне нужно было найти другой способ.

После нескольких минут поиска в Google я нашел библиотеку под названием CLASP, которая представляет собой интерфейс командной строки для операций Google Script. Несмотря на то, что он еще не очень зрелый, его достаточно использовать.
Вот как настроить проект с помощью CLASP:

Добавьте CLASP как devDependency с помощью менеджера пакетов yarn. Бегyarn add @google/clasp
Создайте подпапку src для хранения файлов сценариев Google и файлов конфигурации CLASP (.clasp.json, .claspignore). Причина в том, что скоро мы добавим tests folder для модульных тестов. Поверьте мне ;)
Запустите clasp login и войдите, используя свои учетные данные Google. Вам также может потребоваться включить API скриптов Google на этой странице: https://script.google.com/home/usersettings
Запустите clasp clone <SCRIPT>. ‹SCRIPT_ID› можно найти в URL-адресе редактора скриптов Google.
Добавьте .claspignorefile в папку src со следующими записями:

**/**
!*.js
!appsscript.json

Теперь всякий раз, когда вы вносите изменения, запускайте clasp push, чтобы обновить удаленный код. Вы также можете добавить следующий сценарий в package.json ‘s scripts: ”push”: “cd src;clasp push;cd -”

Шаг 4. Подготовьте коннектор с фиктивными данными

Хорошо, у нас уже есть наша машина и сценарий, готовые к разработке, так что теперь мы можем сосредоточиться на самом коде коннектора.

Файл манифеста

Сначала отредактируем файл манифеста (appsscript.json). Эта простая информация необходима, например, для отображения вашего коннектора в галерее настраиваемых коннекторов.

{
  "dataStudio": {
    "name": "Spotify Connector",
    "company": "None",
    "logoUrl": "https://developer.spotify.com/assets/branding-guidelines/[email protected]",
    "addonUrl": "https://github.com/Bajena/spotify-gds-connector",
    "supportUrl": "https://github.com/Bajena/spotify-gds-connector",
    "description": "This connector can be used to show stats about your last played tracks"
  }
}

getAuthType функция

Давайте добавим первую требуемую функцию в код коннекторов (обычно Code.js файл) - getAuthType. Он сообщает Google Data Studio, если для получения данных требуется дополнительная аутентификация. А пока вернемся сюда "NONE".

function getAuthType() {
  return {
    type: "NONE"
  };
}

Более подробную информацию об этой функции вы можете найти здесь.

`getConfig` функция

Следующим шагом является определение конфигурации - списка входных данных, требуемых от пользователя перед добавлением коннектора в отчет. Нам не понадобится сложная конфигурация для коннектора - только диапазон дат для получения статистики Spotify. Функция диапазона дат встроена в соединители по умолчанию, поэтому наша функция будет такой же простой, как:

function getConfig() {
  return {
    dateRangeRequired: true
  };
}

Один мой совет здесь - если вам нужно добавить поле ввода текста в конфигурацию, и вы пытаетесь проверить текст, такого способа нет ... Единственное, что вы можете сделать, это вызвать ошибку и полностью разрушить соединитель во время выполнения .

Подробнее об этой функции здесь

функция getSchema

В этой функции мы определим поля, с которыми пользователи смогут поиграть. Я просто вставлю сюда функцию - она должна быть понятной:

function getSchema() {
  return {
    schema: [
      {
        name: 'track_name',
        label: 'Track Name',
        dataType: 'STRING',
        semantics: {
          conceptType: 'DIMENSION'
        }
      },
      {
        name: 'artist',
        label: 'Artist',
        dataType: 'STRING',
        semantics: {
          conceptType: 'DIMENSION'
        }
      },
      {
        name: 'played_at_hour',
        label: 'Played at (date + hour)',
        dataType: 'STRING',
        semantics: {
          conceptType: 'DIMENSION',
          semanticGroup: 'DATETIME',
          semanticType: 'YEAR_MONTH_DAY_HOUR'
        }
      },
      {
        name: 'played_at_date',
        label: 'Played at (date)',
        dataType: 'STRING',
        semantics: {
          conceptType: 'DIMENSION',
          semanticGroup: 'DATETIME',
          semanticType: 'YEAR_MONTH_DAY'
        }
      },
      {
        name: 'plays',
        label: 'Plays',
        dataType: 'NUMBER',
        formula: 'COUNT(track_name)',
        semantics: {
          conceptType: 'METRIC',
          isReaggregatable: false
        }
      },
      {
        name: 'tracks_count',
        label: 'Played Tracks',
        dataType: 'NUMBER',
        formula: 'COUNT(track_name)',
        semantics: {
          conceptType: 'METRIC',
          isReaggregatable: false
        }
      },
      {
        name: 'popularity',
        label: 'Popularity',
        dataType: 'NUMBER',
        semantics: {
          conceptType: 'METRIC'
        }
      }
    ]
  };
}

Если вам нужна дополнительная информация о том, что означают эти ключи, ознакомьтесь с документами Google.

функция getData

Теперь мы подошли к основной части каждого коннектора - функции getData. Он отвечает за получение данных из сторонних API и преобразование их в формат, принятый Google Data Studio. А пока мы просто вернем фиктивные данные. В следующей части этой серии мы начнем использовать реальные данные Spotify API. Следующий фрагмент +/- тот же код, что и в этом руководстве:

function getData(request) {
  // Prepare the schema for the fields requested.
  var dataSchema = [];
  var fixedSchema = getSchema().schema;
  request.fields.forEach(function(field) {
    for (var i = 0; i < fixedSchema.length; i++) {
      if (fixedSchema[i].name == field.name) {
        dataSchema.push(fixedSchema[i]);
        break;
      }
    }
  });
// We'll query Spotify API here. For now let's just return two mocked records
  var mockedData = {
    items: [
      {
        track: {
          name: "Voice of the New Generation",
          popularity: 25,
          artists: [
            {
              name: "Santa Cruz"
            }
          ]
        },
        played_at: "2018-06-08T16:16:13.185Z"
      },
      {
        track: {
          name: "Shorty Wanna Be A Thug",
          popularity: 59,
          artists: [
            {
              name: "2Pac"
            }
          ]
        },
        played_at: "2018-06-08T14:11:02Z"
      }
    ]
  };
// Prepare the tabular data.
  var data = [];
  mockedData.items.forEach(function(play) {
    var values = [];
    var playTime = new Date(play.played_at);
    // Google expects YYMMDD format
    var playedAtDate = playTime.toISOString().slice(0, 10).replace(/-/g, "");
    // Provide values in the order defined by the schema.
    dataSchema.forEach(function(field) {
      switch (field.name) {
      case 'track_name':
        values.push(play.track.name);
        break;
      case 'artist':
        values.push(play.track.artists[0].name);
        break;
      case 'played_at_hour':
        values.push(
          playedAtDate +
          (playTime.getHours() < 10 ? '0' : '') + playTime.getHours()
        );
        break;
      case 'played_at_date':
        values.push(playedAtDate);
        break;
      case 'popularity':
        values.push(play.track.popularity);
        break;
      default:
        values.push('');
      }
    });
    data.push({
      values: values
    });
  });
return {
    schema: dataSchema,
    rows: data
  };
}

isAdminUser функция

Это не обязательно, но полезно при разработке коннектора. Если значение этой функции равно true, то при сбое коннектора по какой-либо причине пользователю будет отображаться полное сообщение об ошибке.

function isAdminUser() {
  return true;
}

Шаг 5 - Проверьте разъем

Отлично, мы создали супер-базовый соединитель! А теперь посмотрим, как его можно употреблять. Перейдите в Опубликовать - ›Развернуть из манифеста… и откройте ссылку на развертывание Head (сначала вам может потребоваться изменить ее на запуск в контексте правильного пользователя - проверьте GIF ниже).

Посмотрите, как работает коннектор:

Вы также можете проверить это сами здесь: https://datastudio.google.com/datasources/create?connectorId=AKfycbwSGHSMwF2IMeP97bzn9rO2IGaQo0d-qZD5YPNpW9ok_eMyjdQ-yL9eDorakhIABBavGg

Шаг 6 - отладьте свой коннектор

Не всегда наш код работает сразу, особенно когда мы изучаем новые технологии, поэтому рано или поздно вам понадобится способ отладки кода коннектора.

Самый простой способ - добавить в код console.log("message", additionalObjectInfo) операторов. Позже, когда ваш скрипт будет выполнен, вы сможете просматривать журналы на панели скриптов Google (Сведения о проекте - ›Журналы Stackdriver).

Еще одна важная вещь об отладке - вам не нужно создавать новый отчет GDS каждый раз, когда вы обновляете код скрипта. В большинстве случаев достаточно просто нажать кнопку «Обновить данные» в Google Data Studio.

Далее…

Оно живое! В следующем уроке я покажу вам, как аутентифицироваться в API Spotify и запрашивать его, чтобы получить данные. Вы также узнаете, как кэшировать запросы API, чтобы ускорить работу коннектора.

Создание настраиваемого коннектора Google Data Studio от А до Я. Часть 1 - Базовая настройка.