16. Использование Proxy API

Для взаимодействия с API инсталляций и кластеров услуги в закрытом контуре предоставляется возможность использования средств наложенной защиты Datamart Platform Studio.

Взаимодействие с API посредством Proxy API доступно по протоколам:

  • REST API

  • gRPC

Примечание

Для авторизации при обращении к Proxy API потребуется получить токен одним из способов, которые описаны в разделе rp_api:numref:rp_api Инструменты API.

Описание ролевого доступа к эндпоинтам API компонентов описано в разделе (Раздел 17.3 Настройка ролей доступа к эндпоинтам)

16.1. Взаимодействие с REST API

В бандле приложения должно быть указано имя интерфейса и разрешен к нему доступ (посредством указания параметра api: «true»):

Примечание

При необходимости выполнения запроса инсталляциям, объединенным в кластер в рамках Datamart Platform Studio, необходимо выполнить запрос к кластеру с использованием метода /api/v1/proxy-api

Пример описания интерфейса rest_uploader в бандле приложения

Рисунок 16.1 Пример описания интерфейса rest_uploader в бандле приложения

Назначение правил доступа к эндпоинтам по ролям описаны в разделе Раздел 17.3 Настройка ролей доступа к эндпоинтам.

Примечание

Если требуется в ответе от Proxy API получить прямой ответ от API инсталляции, а не «обёртку» ответа в JSON, то в заголовке запроса надо предать дополнительный параметр:

-H «X-Proxy-Mode: direct»

16.1.1. Взаимодействие с REST API инсталляций через эндпоинт /api/v1/secure/

Примечание

Данный метод позволяет взаимодействовать только с API инсталляций, для обращения к API кластера требуется подключаться к АПИ отдельной инсталляции кластера, либо использовать метод /api/v1/proxy-api/.

Шаблон curl-запроса к Proxy API /api/v1/secure/:

curl -X <method>
'http(s)://<ip-studio>:8088/api/v1/secure/<organization_ogrn>/<datamart_mnemonic>/
<installation_name>/<installation_id>/
{interface/<interface_name>}/<request_path>' \
-H "Authorization: Bearer <access_token>" \
-H "<headers>" \
-d "<data>"

где:

  • <method> — метод обращения к REST API (GET, POST, PATCH, PUT, DELETE);

  • <ip-studio> — ip-адрес Datamart Platform Studio;

  • <organization_ogrn> — ОГРН Организации, в рамках которой развёрнута Витрина;

  • <datamart_mnemonic> — мнемоника целевой Витрины;

  • <installation_name> — имя инсталляции в целевой Витрине;

  • <installation_id> — идентификатор инсталляции (присутствует в её названии);

  • interface/<interface_name> - опциональный параметр указания интерфейса, если этот параметр опущен, Proxy API выполнит запрос к первому из API интерфейсов инсталляции:

    • «interface» - ключевое слово для указания интерфейса;

    • <interface_name> - имя интерфейса в бандле приложения;

  • <request_path> — URI оригинального API инсталляции;

  • <access_token> — JWT токен, полученный от системы аутентификации;

  • <headers> — заголовки запроса;

  • <data> — данные запроса.

При обращении к энпоинту /api/v1/secure/ Proxy API выполняет следующие действия:

  1. Определяет инсталляцию по URL параметру installation_id

  2. Находит интерфейсы этой инсталляции с api: «true»

  3. Если задан URL параметр interface, то среди найденных интерфейсов определяет целевой по имени из параметра, если параметр interface не задан - берет первый из списка.

16.1.2. Взаимодействие с REST API через эндпоинт /api/v1/proxy-api/ по протоколу HTTP/2

Примечание

Данный метод позволяет взаимодействовать с API инсталляций и кластеров посредством указания типа объекта взаимодействия.

Пример curl-запроса:

curl -X <method> 'http(s)://<ip-studio>:443/api/v1/proxy-api/' \
-H "Authorization: Bearer <access_token>" \
-H "X-Id: <id>" \
-H "X-Object-Type: <object_type>" \
-H "X-Interface: <interface>" \
-H "X-Endpoint: <request_path>" \
-H "<headers>" \
-d "<data>"

где:

  • <method> — метод обращения к REST API (GET, POST, PATCH, PUT, DELETE);

  • <ip-studio> — ip-адрес Datamart Platform Studio;

  • <access_token> — JWT токен, полученный от системы аутентификации;

  • <id> — идентификатор сущности в категории (по умолчанию installation_id);

  • <object_type> - «installation» (по-умолчанию) или «cluster», если категория не указана, то произойдёт обращение к API инсталляции

  • <interface> - имя API интерфейса в бандле приложения;

  • <request_path> — URI оригинального API инсталляции;

  • <headers> — заголовки запроса;

  • <data> — данные запроса.

16.2. Примеры Proxy API v1 запросов в Prostore

Пример запроса на REST API Prostore (без Proxy API):

curl -X 'POST' \
'http://<ip-query-execution>:9090/api/v1/datamarts/query?format=json' \
-H 'Content-Type: application/json' \
-d '{"query": "check_versions()"}'

где:

  • <ip-query-execution> — ip-адрес инсталляции Простора.

Аналогичный запрос через Proxy API Datamart Platform Studio будет выглядеть так:

curl -X POST \
'http(s)://<ip-studio>:8088/api/v1/secure/<organization_ogrn>/<datamart_mnemonic>/<installation_name>/<installation_id>/api/v1/datamarts/query?format=json' \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"query": "check_versions()"}'

где:

  • <ip-studio> — ip-адрес Datamart Platform Studio;

  • <organization_ogrn> — ОГРН Организации, в рамках которой развёрнута Витрина;

  • <datamart_mnemonic> — мнемоника целевой Витрины;

  • <installation_name> — имя инсталляции в целевой Витрине;

  • <installation_id> — идентификатор инсталляции (присутствует в её названии);

  • <access_token> — токен proxy API;

Пример успешного ответа Datamart Platform Studio на запрос выше:

{
    "result": [
        {
            "component_name": "query-execution-core",
            "version": "6.4.0"
        },
        {
            "component_name": "ADP: adp instance",
            "version": "PostgreSQL 13.4 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-44), 64-bit"
        },
        {
            "component_name": "ADP: kafka-postgres connector reader",
            "version": "0.6.1"
        },
        {
            "component_name": "ADP: kafka-postgres connector writer",
            "version": "0.6.1"
        },
        {
            "component_name": "status-monitor",
            "version": "6.4.0"
        },
        {
            "component_name": "rest-api",
            "version": "1.0.2"
        }
    ],
    "metadata": [
        {
            "name": "component_name",
            "type": "VARCHAR",
            "size": null,
            "nullable": false
        },
        {
            "name": "version",
            "type": "VARCHAR",
            "size": null,
            "nullable": false
        }
    ],
    "rows": 6,
    "queryId": null,
    "statistics": {
        "elapsedTotalMs": 13,
        "elapsedDbMs": 2
    }
}

16.2.1. Пример Proxy API запроса на создание витрины в Prostore

curl -X POST \
'http(s)://<ip-studio>:8088/api/v1/secure/<organization_ogrn>/<datamart_mnemonic>/<installation_name>/<installation_id>/api/v1/datamarts/query?format=json' \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"query": "create database <dtm_name>;"}'

где:

  • <dtm_name> — название датамарта (витрины).

Пример успешного ответа Datamart Platform Studio на запрос выше:

{
    "result": [],
    "metadata": [],
    "rows": 0,
    "queryId": null,
    "statistics": {
        "elapsedTotalMs": 66,
        "elapsedDbMs": 6
    }
}

16.2.2. Пример Proxy API запроса на создание таблицы в Prostore

В примере указана тестовая таблица test_db.testapi с полным DDL:

curl -X POST \
'http(s)://<ip-studio>:8088/api/v1/secure/<organization_ogrn>/<datamart_mnemonic>/<installation_name>/<installation_id>/api/v1/datamarts/query?format=json' \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"query": "create table test_db.testapi (id BIGINT not null, message VARCHAR not null, primary key (id)) distributed by (id);"}'

Пример корректного ответа Студии на запрос выше:

{
    "result": [],
    "metadata": [],
    "rows": 0,
    "queryId": null,
    "statistics": {
        "elapsedTotalMs": 201,
        "elapsedDbMs": 99
    }
}

16.3. Выполнение запросов к Стандартному загрузчику (СЗ)

Примечание

Для выполнения запросов к Стандартному загрузчику (СЗ) приложение СЗ должно быть установлено и сконфигурировано согласно одной из схем взаимодействия, описанной в документации:

см: Стандартный загрузчик (Модуль управления данными)

16.3.1. Примеры REST-запросов на загрузку данных

Ниже приводится пример загрузки файла через REST API стандартного загрузчика для режима СЗ REST: Push. Загрузка данных производится в витрину <dtm_name>, в таблицу <table_name> через интерфейс СЗ rest_uploader.

Datamart Platform Studio установлена по адресу <base_url>

16.3.1.1. Запрос на загрузку JSON данных по протоколу HTTP/2

curl -X POST '<base_url>/api/v1/proxy-api/' \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"
-H "X-Id: <installation_id>" \
-H "X-Object-Type: installation" \
-H "X-Interface: rest_uploader" \
-H "X-Endpoint: /api/v3/datamarts/<dtm_name>/tables/<table_name>/upload" \
-H "<headers>" \
-d "[
     {
       "id": 13,
       "description": "Евгений",
       "client_id": 35
     },
     {
       "id": 14,
       "description": "Иосиф",
       "client_id": 53
     },
     {
       "id": 15,
       "description": "Дональд",
       "client_id": 72
     }
   ]"

Если данные находятся в файле, можно использовать опцию -d с указанием имени json-файла

16.3.1.2. Запрос на загрузку csv-файла по протоколу HTTP/2

curl -X POST '<base_url>/api/v1/proxy-api/' \
-H "Authorization: Bearer <access_token>" \
-H "X-Id: <installation_id>" \
-H "X-Object-Type: installation" \
-H "X-Interface: rest_uploader" \
-H "X-Endpoint: /api/v3/datamarts/<dtm_name>/tables/<table_name>/upload" \
-H "<headers>" \
-d "@<filename.csv>"

16.3.1.3. Запрос на загрузку csv-файла по протоколу HTTP 1.1

Аналогичный запрос на загрузку файла через Proxy API протоколу HTTP 1.1 при обращении к эндпоинту /api/v1/secure строится таким образом:

curl -X POST \
'<base_url>/api/v1/secure
/<organization_ogrn>/<datamart_mnemonic>
/<installation_name>/<installation_id>
/interface/rest_uploader
/v2/datamarts/<dtm_name>/tables/<table_name>/upload' \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: text/csv" \
-d "@<filename.csv>"

16.3.1.4. Ответ на запрос и проверка результата

Успешный ответ от СЗ на запрос содержит requestId и sessionId задания на загрузку данных в СЗ:

{
    "requestId": "18",
    "sessionId": "18"
}

Для проверки результата загрузки данных выполняется запрос к эндпоинту standard-loader с полученным requestId:

curl -X POST '<base_url>/api/v1/proxy-api/' \
-H "Authorization: Bearer <access_token>" \
-H "X-Id: <installation_id>" \
-H "X-Object-Type: installation" \
-H "X-Interface: standard-loader" \
-H "X-Endpoint: /api/v3/requests/<requestId>/status" \

Пример ответа СЗ об успешной загрузке:

{
    "code": 300,
    "description": "Успешно обработан",
    "errorMessage": null
}

16.4. Взаимодействие с API по gRPC

Для организации обращения к API инсталляций через Proxy API по протоколу gRPC в бандле приложения должно быть указано имя интерфейса и разрешен к нему доступ (посредством указания параметра api: «true»). Кроме этого, в настройках интерфейсов инсталляции или кластера для gRPC интерфейса требуется указать порт взаимодействия через Proxy API:

Настройка порта подключения gRPC для Proxy API

Рисунок 16.2 Настройка порта подключения gRPC для Proxy API

Примечание

Порт подключения gRPC для Proxy API должен быть уникален в рамках Datamart Platform Studio. По указанному порту выполняется маршрутизация gRPC запросов к указанному интерфейсу.

Диапазон допустимых портов указывается в .env файле настроек Datamart Platform Studio, значения по умолчанию:

  • STUDIO_GRPC_PROXY_PORT_MIN = 30000

  • STUDIO_GRPC_PROXY_PORT_MAX = 30099

16.4.1. Авторизация gRPC запросов

Для авторизации gRPC запросов через Proxy API требуется использовать JWT-токен. Получить токен можно одним из способов, которые описаны в разделе rp_api:numref:rp_api Инструменты API

16.4.2. Пример выполнения gRPC запроса к Стандартному загрузчику

Ниже приводится пример взаимодействия с компонентом СЗ loadManager. Порт gRPC в настойках интерфейса standard-loader-manager для инсталляции standard_loader (наименование приложения loadManager) выбран 30001. Выполняется запрос BeginDelta к Ядру Prostore.

Datamart Platform Studio установлена по адресу <base_url>.

Файл loader_api.proto - proto-файл gRPC, который содержит описание сервисов, методов и форматов сообщений, которыми обмениваются клиент и сервер gRPC.

ru.itone.dtm.loadManager.DeltaService.BeginDelta - имя метода BeginDelta в proto-файле.

grpcurl \
   -plaintext \
   -H 'Authorization':'Bearer <oauth-token>' \
   -emit-defaults \
   -proto '/Users/test/Downloads/loader_api.proto' \
   -import-path '/Users/test/Downloads' \
   -d '{"datamart":"test","userId":"1234"}' \
   '<base_url>:30001' \
   ru.itone.dtm.loadManager.DeltaService.BeginDelta

Пример полученного через Proxy API ответа:

{
    "deltaNum": "2"
}