Принцип работы DataLens Partner API

Диаграмма последовательности работы с DataLens Partner API:

1. Пользователь создает подключение партнера в интерфейсе DataLens.

2. DataLens возвращает:

   • идентификатор подключения connection_id;
   • идентификатор каталога folder_id;
   • идентификатор сервисного аккаунта service_account_id;
   • идентификатор ключа сервисного аккаунта svc_acct_key_id;
   • закрытый ключ сервисного аккаунта svc_acct_private_key.

3. Пользователь передает полученную информацию партнеру и делает запрос на создание клиента для отправки данных.

4. Партнер создает клиента и генерирует JWT-токен. Подробнее о JWT-токене в документации сервиса Identity and Access Management.

5. Партнер получает IAM-токен в обмен на JWT-токен.

   Полученный токен используется в дальнейших запросах к DataLens Partner API. Подробнее об IAM-токене в документации сервиса Identity and Access Management.

6. Партнер создает связь клиента с подключением DataLens с помощью метода API Создание связи с клиентом.

   DataLens Partner API возвращает идентификатор клиента client_id.

7. Партнер запрашивает информацию о подключении и таблицах, в которые необходимо записывать данные, с помощью метода API Информация о подключении.

8. Партнер отправляет данные в DataLens.

   В заголовке каждого запроса на отправку данных партнер отправляет уникальный идентификатор операции Operation UUID.

9. DataLens материализует полученные данные и отображает их в интерфейсе.

10. Пользователь создает датасеты, чарты, дашборды на основе подключения партнера.

Особенности работы с API

Необходимо учитывать следующие особенности при работе с DataLens Partner API.

Operation UUID

При каждом запросе на запись партнер передает в заголовке уникальный идентификатор операции Operation UUID.
Идентификатор генерируется на стороне клиента.

Если во время передачи данных запрос будет прерван (например, из-за неполадок сети), клиенту необходимо повторить запрос с идентичными значениями.
Сервер DataLens Partner API проверит статус предыдущего запроса с таким же значением Operation UUID и сделает следующее:

• Если сервер DataLens успешно записал данные, то он отправит ответ 200 OK.
• Если сервер DataLens находится в процессе записи, то он отправит ответ 423 Locked.
• Если сервер DataLens не записал данные, то он начнет запись в БД.

Подробнее о генерации UUID.

Partitioning Key

Для записи данных в таблицу можно указывать ключ партиционирования.

Ключ партиционирования — это произвольное выражение из столбцов таблицы, которые указаны в схеме. Например, ["FieldName1","FieldName2","FieldName3"].

С помощью ключа клиент может удалять данные частями (партициями).
Например, партиция может быть по месяцу, по дню или по типу события.

Replacing Key

Для замены существующих данных в таблице можно указать ключ замены данных.

Ключ замены данных — это произвольное выражение из столбцов таблицы, которые указаны в схеме. Например, ["FieldName1","FieldName2"].

С помощью ключа клиент может заменить данные, которые были загружены ранее.

Пример использования

Для таблицы из трех полей: Country, City, Goods quantity, в качестве ключа замены данных указан replacing_key: ["Country", "City"].

При первой загрузке переданы следующие данные:

["Russia", "Moscow", 1]
["Russia", "Kazan", 2.1]
["Russia", "Kazan", 2.2]

Так как данных в таблице не было, все данные были успешно загружены.

При следующей загрузке переданы данные:

["Russia", "Kazan", 10]

В результате удалятся все данные, которые соответствуют ключу ["Russia", "Kazan", ...].
В таблице останутся следующие данные:

["Russia", "Moscow", 1]
["Russia", "Kazan", 10]

Формат данных

Данные в DataLens Partner API записываются в формате NDJSON.
При каждом запросе на запись необходимо указать заголовки, которые определяют формат данных:

X-DL-Data-Format: array
Content-Type: application/x-ndjson

В теле запроса каждая строка данных передается в виде JSON-массива:

["fieldValue11", "fieldValue21"]
["fieldValue12", "fieldValue22"]
["fieldValue13", "fieldValue23"]

Дата и время должны быть переданы в формате ISO 8601.
Если в дате и времени есть сведения о часовом поясе (time zone), DataLens автоматически приведет его к стандарту UTC.