Вы читаете development версию документации. Для просмотра актуальной версии перейдите в ветку: master.

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

Примечание

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

Datamart Platform Studio предоставляет возможность авторизовать и перенаправлять запросы к API эндпоинтам инсталляций и кластеров в закрытом контуре. При помощи этого возможно, например, взаимодействовать с ядром Prostore, загружать csv-файлы через standard-loader и т.д, не имея прямого доступа к серверам Витрины (см. Рисунок 16.1).

При выполнении запросов в модулях Proxy API фиксируется лог выполненных запросов.

Схема функционирования средств наложенной защиты Datamart Studio

Рисунок 16.1 Схема функционирования средств наложенной защиты Datamart Studio

Чтобы функционал Proxy API стал доступен для использования, Datamart Platform Studio должна быть связана с IAM сервисом аутентификации - Keycloak. В нём определяются пользователи и их роли в Datamart Platform Studio.

Для взаимодействия с API компонентов услуги посредством Proxy API требуется получить токен IAM сервиса аутентификации Keycloak.

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

  • REST API

  • gRPC

Примечание

Для авторизации при обращении к Proxy API потребуется получить токен одним из способов, которые описаны в разделе rp_api (Раздел 15 API Datamart Platform Studio).

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

Примечание

Описание конфигурации модуля Proxy API , в том числе настройки правил ролевого доступа к эндпоинтам API компонентов описано в документе «Руководство Администратора» Раздел 9.3 Настройка правил ролевого доступа к эндпоинтам.

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

Примечание

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

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

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

Примечание

Если в ответе на запрос требуется получить прямой ответ от 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.3 Настройка порта подключения 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 Datamart Platform Studio

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"
}