Yandex.Cloud
  • Сервисы
  • Почему Yandex.Cloud
  • Сообщество
  • Решения
  • Тарифы
  • Документация
  • Связаться с нами
Подключиться
Yandex DataLens Partners API
  • Принцип работы
  • Аутентификация в API
  • Справочник API
    • Обзор
    • Создание связи с клиентом
    • Удаление связи с клиентом
    • Информация о подключении
    • Обновление таблицы
    • Удаление таблицы
    • Запись данных
    • Удаление данных
  • Квоты и лимиты
  • Правила тарификации
  1. Принцип работы

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

  • Особенности работы с API
    • Operation UUID
    • Partitioning Key
    • Replacing Key
    • Формат данных

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

Примечание

Для создания сервисного аккаунта у пользователя должны быть права администратора на каталог, в котором развернут DataLens.

  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.

Важно

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

Language / Region
Вакансии
Политика конфиденциальности
Условия использования
Брендбук
© 2021 ООО «Яндекс.Облако»