Расширьте возможности своих проектов Domo с помощью настраиваемых коннекторов

Расширьте свои проекты Domo с помощью настраиваемых коннекторов (включает 20-минутное учебное пособие)

В этом уроке я сделаю именно то, что написано на банке: покажу вам, как создать собственный коннектор между Spotify и Domo.

Отказ от ответственности: меня зовут Джей Уилсон. Я старший технический консультант и менеджер по техническому успеху в Domo, но, кроме того, мне нравится думать о себе как о ремесленнике. Мне нравится использовать данные и технологии для решения бизнес-задач и разработки цифровых продуктов. Мои тексты являются моими собственными и не обязательно отражают взгляды Домо.

Я написал это руководство, потому что концептуально я знал, что создание пользовательских коннекторов для загрузки сторонних данных в Domo должно быть простым делом, но, честно говоря, я откладывал это на шесть месяцев; потому что я был слишком напуган, чтобы начать. Итак, однажды вечером я собрал друзей, собрал коллекцию крафтового пива, стиснул зубы и приклеился к стулу, пока не написал свой первый коннектор.

Это было так легко! Я едва выпил две бутылки пива, прежде чем закончил свой первый коннектор!

… Хорошо, я немного соврал. У меня был разработчик из нашей команды в Штатах, который провел меня через настройки аутентификации, И, поскольку я не разработчик JavaScript, мне пришлось использовать, черт возьми, переполнение стека… так что это заняло час вместо 20 минут.

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

• Мой взгляд на Domo без бреда и на то, как его используют мои клиенты.
• Возможности, которые создают пользовательские соединители в цифровых проектах.
• Как стек больших данных Domo обеспечивает ценность данных с первого дня.

Я знаю, что инфраструктура озера данных может быть деликатной темой для архитекторов и инженеров, но было бы упущением не добавить свои два цента в игру Domo в космосе.

Нет БС. Что такое Домо?

Многие клиенты используют и хвалят Domo за ее сложные инструменты визуализации данных и совместной работы, сравнимые с PowerBI, Tableau и Qlik. Но это лишь малая часть платформы Domo.

Более опытные пользователи узнают Domo как интегрированный стек больших данных, который включает в себя защищенное от сбоев хранение и преобразование данных, а также надежные средства управления данными и безопасности, доступные через веб-браузер, API и интерфейсы командной строки.

Некоторые из самых продвинутых клиентов Domo используют платформу для размещения услуг и цифровых продуктов, ориентированных на клиентов, через структуру пользовательских приложений.

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

Делайте больше с двусторонней платформой подключения Domo

Растущая библиотека Domo, состоящая из более чем 1000 стандартных (без кода) соединителей, позволяет пользователям собирать данные практически из любого онлайн-источника, включая Adobe Analytics, Google Analytics, Instagram, Wrike, Salesforce, Marketo, LinkedIn и MS Dynamics, что упрощает подключение. -и играйте в многочисленных бизнес-кейсах с первого дня.

Тем не менее, я никогда не забуду реакцию моего старого седого наставника, когда я поделился с ним своей информационной панелью Salesforce. "Ну и что?" он рявкнул на меня: «Ни один интересный бизнес-вопрос не может быть полностью решен на основе данных, сгенерированных внутри компании». Истинное понимание исходит из сочетания нескольких внутренних и внешних источников данных. Введите пользовательские коннекторы.

Почему вам следует обратить внимание на настраиваемые коннекторы.

Коннекторы Domo построены на JavaScript и поэтому открывают доступ к ранее недоступным наборам данных и сервисам. Действительно, когда дело доходит до взаимодействия с данными, ваше воображение (и техническое мастерство) являются единственными ограничениями.

Вишенка на торте: обратная запись представляет собой двунаправленный поток данных. Вы можете отправлять данные из Domo в исходные системы, взаимодействовать со сторонними службами или передавать выбранный инструмент анализа! Примеры включают:

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

На рынке, где многие инструменты SAAS предназначены только для загрузки, двунаправленная структура Domo открывает новые возможности для взаимодействия с данными, автоматизации бизнеса, а также для быстрой разработки и предоставления новых цифровых продуктов и услуг.

Великая дискуссия о структурированных и неструктурированных данных

Инженеры по обработке данных и технологи озера данных признают создание коннекторов необходимым шагом для преобразования неструктурированного текста в полезные данные.

В этом руководстве мы создадим коннектор, который извлекает отчет Me из API Spotify, а затем использует JavaScript для преобразования ответа в одну строку данных, которую можно сохранить в Domo.

А теперь о полемике.

Некоторые пуристы отличают озера данных от других моделей хранения тем, хранят ли они данные в неструктурированной форме (необработанный текст прямо из API). Они утверждают, что преобразование текстовых ответов API в табличный формат ДО хранения лишает Domo статуса озера данных. Я рассматриваю решение Domo хранить и предоставлять бизнес-пользователям структурированные данные как различие между ценными и непригодными для использования данными.

Примечание. Для клиентов, которым требуется модель схемы при чтении, Domo предлагает базу данных AppDb для хранения неструктурированных данных.

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

- Учебник начинается здесь -

Первый отчет, который мы получим, — это отчет Me — набор данных из одной строки, описывающий пользователя, прошедшего аутентификацию в Spotify. Мы будем использовать этот простой отчет для создания основ сценариев JavaScript и дизайна коннектора, прежде чем украсить коннектор операторами switch, функциями и вложенными циклами, чтобы позволить нам переключаться между отчетами «Я», «Лучшие треки» и «Лучшие исполнители».

Вспоминая слова моего наставника, набор данных Spotify сам по себе вряд ли интересен. Какие интересные идеи вы могли бы обнаружить, если бы взяли отчеты Top Tracks, извлекли текст из другого API, а затем отправили этот текст в службу обработки естественного языка для распознавания сущностей? Что, если бы вы вмешались в тренировки Fitbit, дни года или схемы покупок? Мы не можем охватить все это в этом коротком руководстве, но это JavaScript — вы можете делать все, что хотите!

Этот первый коннектор — просто ворота к более интересным проектам!

Мой ускоренный курс по JSON для неразработчиков

Данные, полученные из API, закодированы в виде строк JSON (нотация объекта JavaScript), которые должны быть преобразованы в табличный формат, прежде чем мы сможем их сохранить.

Каждый элемент в JSON определяется парами ключ-значение.

Ключ определяет атрибут («имя», «изображения», «подписчики») и должен быть уникальным для каждого объекта. Это аналог столбца в таблице.

Значения имеют разные типы данных (строка, целое число, логическое значение, массив или другие пары "ключ-значение"). Значения аналогичны значению поля в записи данных; однако JSON заметно отличается от традиционного SQL, поскольку в JSON значение может быть многозначным (массив) или содержать вложенную пару ключ-значение.

• за ключом «последователи» следует { }, указывающий, что он принимает вложенные пары ключ-значение. содержащие «href» и «total».
• За «genres» следует [ ], что означает, что он принимает массив (или список) элементов — в данном случае строк.
• «images» также является массивом; однако он отличается от genres, поскольку каждый элемент images должен быть парой ключ-значение.
• Элементы в списке должны иметь один и тот же тип данных.

ПРИМЕЧАНИЕ.Строка и объекты — НЕ одно и то же. API передают строки символов. Механизм JavaScript переводит правильно отформатированную строку в объект JSON.

Настройка учетной записи разработчика Spotify

Ускоренный курс окончен. Начнем строить!

Чтобы создать коннектор между Domo и Spotify, нам нужно начать с регистрации приложения в Spotify.

Создайте учетную запись разработчика, а затем зарегистрируйте некоммерческое приложение на сайте разработчиков Spotify: https://developer.spotify.com/dashboard/

При определении приложения установите URL-адрес обратного вызова https://api.domo.com/builder/oauth.html. Когда вы публикуете коннектор Domo, вам будет предложено добавить дополнительный URL-адрес обратного вызова, специфичный для вашего коннектора.

• Многие сторонние API потребуют от вас регистрации, чтобы они могли отслеживать количество совершаемых вами вызовов (квота) и, при необходимости, замедлять или ограничивать ваши вызовы (дросселирование).
• Каждое приложение будет иметь связанный идентификатор клиента и секрет клиента. Эти учетные данные будут направлять запрос API из Domo в нужное приложение в Spotify, сообщая ему, чью квоту этот запрос нарушает, и определяя набор допустимых действий, которые может выполнить ваш запрос (область). В нашем случае нам нужен доступ к отчету Я, но нам не нужна возможность обновлять плейлисты.

Создайте свой коннектор

В конечном счете, вы развернете первый черновой вариант своего коннектора на your_instance.domo.com, но сначала мы разработаем коннектор в Domo’s Connector IDE: api.domo.com/builder/index.html#!/

Шаг 1. Создайте новый коннектор

Дайте вашим соединителям хорошие имена, вы не сможете изменить их позже!

Шаг 2. Загрузите значки коннекторов

Я использовал https://resizeimage.net/ для изменения размера изображений, но подойдет любой инструмент.

Шаг 3. Настройте аутентификацию для стороннего API

Каждый API работает по-своему. К счастью, существует несколько стандартизированных сред аутентификации. Spotify поддерживает 3 разных метода аутентификации, но мы будем использовать OAuth2.0, так как это общий стандарт.

• Документация для аутентификации Домо
• Документация по аутентификации Spotify

• Ключ клиента и секрет выдаются сторонним API (из https://developer.spotify.com/dashboard)
• URL-адрес авторизации, параметры, URL-адрес токена доступа, метод запроса, тип предоставления — все это часть стандартной структуры рукопожатия OAuth2.0, но они уникальны для каждого стороннего приложения.
• Напомним, Scope контролирует, что ваше приложение может делать с Spotify. Различные приложения могут иметь разные области действия. (Области авторизации Spotify).

Этот фрагмент кода JavaScript позволяет убедиться, что Domo успешно получил токен доступа от Spotify, и требуется, прежде чем коннектор сможет перейти к следующему шагу.

• DOMO – это уникальная библиотека функций JavaScript для Domo. Он включает DOMO.log() для замены console.log() для вывода сообщений на консоль.
• Параметры аутентификации передаются в JavaScript через объект metadata с атрибутами, по которым можно перемещаться с помощью записи через точку.

Где вы уже видели OAuth2.0?

Если вы когда-либо нажимали «Войти с помощью Facebook» или «Войти с помощью Google» во всплывающем окне, вы взаимодействовали с OAuth2.0.

Шаг 4. Настройте доступные для выбора отчеты

С помощью одного соединителя вы можете определить несколько отчетов, которые обращаются к разным API или применяют разные правила обработки данных (схемы). Мы собираемся создать два отчета: «Я» и «Мои популярные треки».

Примечание. Кроме того, код «Мои лучшие исполнители» включен в конец руководства.

Шаг 5а. Добавление заголовков к моему первому HTTP-запросу

На этих этапах мы будем запрашивать API Spotify, а затем анализировать текстовый ответ в сетке данных, которую можно отправить и сохранить в Domo.

Аутентификация запросов с помощью заголовков

В наших предыдущих попытках мы настроили приложение в Spotify для обработки запросов API от Domo. Токен доступа, согласованный в рукопожатии OAuth2.0, направит наш запрос API в правильное приложение Spotify, когда мы включим токен доступа в заголовки HTTP-запроса.

Примечание: если вы обмениваетесь данными, API также необходимо знать, какой контент ожидать/отправлять (Content-type и Accept).

Пересмотренный анализ строк API

Критический момент обучения здесь — помнить, что API отправляют строки текста. Прежде чем JavaScript сможет сделать что-нибудь полезное с данными, мы должны преобразовать их в объект JSON. Следующий блок кода намеренно НЕ РАБОТАЕТ должным образом.

ПРОФЕССИОНАЛЬНЫЙ СОВЕТ по работе с длинными строками JSON

Длинные строки могут быть трудночитаемыми, если в них нет пробелов и форматирования. Используйте Visual Studio Code для применения форматирования.

• Примечание: обязательно установите тип документа JSON.
• Если у вас нет хорошего текстового редактора, есть онлайн-инструменты для красивой печати JSON.

Отправьте отчет в Domo

Мы на финишной прямой. Помните, что Domo хранит данные в реляционном формате (строки и столбцы), поэтому каждая пара ключ-значение должна содержать только одно значение (без массивов). В ответе, который мы изначально получаем из отчета Me, ключ images содержит массив, а followers имеет вложенную пару ключ-значение. Мы исправим это при определении объекта final.

• Примечание. Технически вы можете отправлять объекты JSON с массивами и вложенными парами ключ-значение прямо в magicParseJSON(). Это приведет к набору данных, схема которого меняется в зависимости от ответа от API. Это плохо, потому что ваш анализ (ETL и визуализация) предполагает использование фиксированной схемы. Вот почему модель Domo, ориентированная на создание схемы при записи, важнее соблюдения строгих правил для озера данных!
• Дополнительная документация по datagrid() здесь: обработка данных в domo.

Это был простой пример, поскольку отчет Me возвращает только одну строку, но в ситуациях, когда мы получаем несколько записей из API, мы будем использовать более сложные сценарии обработки данных для определения final объект.

Шаг 5b. Добавить отчет "Мои популярные треки"

Смотрите молодцы! Мы создали отчет Я, а теперь расширим возможности использования этого коннектора, добавив возможность захвата вашего отчета «Лучшие треки».

Знакомство с оператором Switch

Оператор switch аналогичен оператору CASE в SQL и используется для выполнения блоков кода, если выполняются условия.

• Убедитесь, что ваши обращения соответствуют названиям отчетов, которые вы настроили ранее.
• команда break закрывает текущий блок кода.
• по умолчанию будет выполняться, если отчет не соответствует ни одному из условий случая.

Перетащите существующий код следующим образом:

Надеюсь, вы узнаете исполнителей из своих хитрых плейлистов!

Обратите внимание, что первый символ в консоли — это [ . Это указывает на то, что tracks_obj — это массив, в котором каждый элемент представляет одну дорожку.

Определение схемы дорожек, часть 1

Мы могли бы отправить это в datagrid() как есть, но каждая дорожка содержит вложенные пары ключ-значение и массивы, и мы согласились, что НЕ хотим этого!

• Во-первых, мы объявим пустой массив final = []
• Затем мы будем использовать цикл forEach для перебора каждой дорожки в tracks_obj.
• Для каждой дорожки в track_obj мы определим my_track как подмножество track.
• Наконец, мы переместим .push() my_track в final.

Вложенные циклы forEach для улучшения схем

Если вы еще этого не сделали, попробуйте отправить tracks_obj.items в datagrid(), технически это работает. Я получаю одну строку на трек, но это выглядит ужасно! Прокрутите и проверьте заголовки столбцов. Вы когда-нибудь видели такие схемы?

Какова наилучшая схема для хранения данных? Надень шляпу бизнес-консультанта!

Это тривиальный пример, но последствия реальны! Данные Spotify или ERP можно получить в любое время, но если бы это был пример использования потоковых данных, эти данные не будут жить вечно, поэтому решения схемы, которые я принимаю сейчас, влияют на удобство использования навсегда.

• Не беспокойтесь, если это звучит пугающе — если вы предпочитаете отложить принятие решений по определению схемы, у Domo есть инструменты для поддержки хранения необработанных данных с помощью предложения базы данных AppDb.

В этом примере использования Spotify мы будем использовать вложенные циклы forEach для явной структуризации наших данных. Не пугайтесь, здесь все становится интереснее. Наша цель в конце всего этого: один ряд для каждого исполнителя, который пел на треке.

Ранее мы использовали цикл .forEach() для создания одного my_track для каждой дорожки. Теперь мы будем использовать вложенный цикл .forEach( ) для создания одного my_track для каждого трека и исполнителя.

Перерабатывать код с помощью функций — главный элемент защиты

Честно говоря, вы могли бы отправить это в Domo, и это было бы вполне адекватно, но, учитывая, что это чей-то отчет Top Tracks, было бы неплохо включить некоторые пользовательские метаданные. Немного перетасовав, мы можем использовать функции для повторного использования и интеграции кода, используемого для создания отчета Я.

• Удалите весь свой контент из блока переключения me и создайте функцию me_report().
• присвоить final результат me_report();

Это оно! Все сделано!

Хотя мы не проверяли его, я добавил отчет Top_Albums, чтобы вы могли его переварить позже.

Ты сделал это! Спасибо, что были со мной до самого горького конца.

Помните, что после публикации отчета вы должны добавить URL-адрес обратного вызова в свое приложение Spotify.

Путешествие в тысячу байтов начинается!

Надеюсь, это первый из многих маленьких шагов в захватывающем путешествии в любопытство к данным с Domo! Это может показаться тривиальным, но я не хочу недооценивать ценность этих знаний для вас и вашей команды.

Запросы API всегда имеют свою стоимость. В дополнение к времени вычислений, усилиям разработчиков или нагрузке на сервер часто возникают денежные затраты, связанные с использованием сторонних API-сервисов. Не задавайте один и тот же вопрос дважды, если в этом нет необходимости! Domo имеет встроенную функцию аварийного восстановления (и аварийного восстановления PEBCACS). Кроме того, новые наборы данных с конфиденциальной информацией можно защитить с помощью предопределенных политик разрешений на доступ к данным, основанных на атрибутах SSO, одним щелчком переключателя.

В этом примере несколько тысяч строк могут показаться каплей в море, но по мере того, как проекты, рабочие процессы или приложения приближаются к миллионам строк запросов API или взаимодействий с пользователем, мы хотим убедиться, что мы используем отраслевые инструменты для резервного копирования. инвестиции — в идеале, не задумываясь об этом.

Если вы еще не написали ни строчки кода, надеюсь, вы сделаете то же, что и я. Выпейте пива или вина, соберите друзей-единомышленников, перестаньте беспокоиться о скучных вещах и просто начните работу с Domo.

- Конец -

Меня зовут Джей Уилсон. Хотя моя официальная должность — старший технический консультант и менеджер по техническому успеху в Domo, мне нравится думать о себе как о ремесленнике. Мне нравится использовать данные и технологии для решения бизнес-задач и разработки цифровых продуктов. Хотя я являюсь сотрудником Domo, я пишу свои собственные тексты и не обязательно отражаю точку зрения организации.