Принцип работы DataLens Partner API
Диаграмма последовательности работы с DataLens Partner API:
Примечание
Для создания сервисного аккаунта у пользователя должны быть права администратора на каталог, в котором развернут DataLens.
-
Пользователь создает подключение партнера в интерфейсе DataLens.
-
DataLens возвращает:
- идентификатор подключения
connection_id
; - идентификатор каталога
folder_id
; - идентификатор сервисного аккаунта
service_account_id
; - идентификатор ключа сервисного аккаунта
svc_acct_key_id
; - закрытый ключ сервисного аккаунта
svc_acct_private_key
.
- идентификатор подключения
-
Пользователь передает полученную информацию партнеру и делает запрос на создание клиента для отправки данных.
-
Партнер создает клиента и генерирует JWT-токен. Подробнее о JWT-токене в документации сервиса Identity and Access Management.
-
Партнер получает IAM-токен в обмен на JWT-токен.
Полученный токен используется в дальнейших запросах к DataLens Partner API. Подробнее об IAM-токене в документации сервиса Identity and Access Management.
-
Партнер создает связь клиента с подключением DataLens с помощью метода API Создание связи с клиентом.
DataLens Partner API возвращает идентификатор клиента
client_id
. -
Партнер запрашивает информацию о подключении и таблицах, в которые необходимо записывать данные, с помощью метода API Информация о подключении.
-
Партнер отправляет данные в DataLens.
В заголовке каждого запроса на отправку данных партнер отправляет уникальный идентификатор операции
Operation UUID
. -
DataLens материализует полученные данные и отображает их в интерфейсе.
-
Пользователь создает датасеты, чарты, дашборды на основе подключения партнера.
Особенности работы с 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.
Важно
Число и порядок столбцов в теле запроса должны совпадать с числом и порядком столбцов, которые указаны в схеме таблицы.