Спецификация программных интерфейсов ЦБГД для работы с Фондом данных ДЗЗ
Содержание
- Спецификация программных интерфейсов ЦБГД для работы с Фондом данных ДЗЗ
- History
- Состав данных Фонда доступных по программному интерфейсу
- Обзорная схема использования API
- Аутентификация потребителей
- Авторизация внешнего web-сервиса для работы с web-сервисами ЦБГД
- Авторизация в виде authorization code
- Запрос кода у сервиса авторизации
- Подтверждение потребителя действовать от его имени
- Обмен кода на метку доступа (access token)
- Обновление метки доступа
- Получение информации о потребителе
- Поиск по каталогу ЦБГД (ФФД ДЗЗ)
- Пример поискового запроса
- Параметры поискового запроса
- Результаты поиска по каталогу
- Пример ответа на поисковый запрос
- Пример поиска по каталогу ББП (Банк базовых продуктов)
- Заказ создания Информационного продукта
- Заказ создания информационного продукта с помощью Order API
- Заказ одного маршрута ETRIS.id с разными параметрами обработки в одном заказе
- Отправка запроса на создание информационного продукта:
- Ответ сервиса создания информационного продукта
- Получение списка заказов
- Запрос информации о заказе
- Получение информационного продукта
- Порядок спектральных каналов в информационном продукте
- Просмотр снимков через виртуальный TMS-сервис
- Просмотр бесшовных мозаичных покрытий по TMS-протоколу
- Работа с данными Фонда через протокол S3
- Получение временной сессии работы с S3 хранилищем
- Установка окружения временной сессии работы с S3
- Работа c aws-cli
- Работа GDAL
- Интерактивная работа с S3 в QGIS
- Интерактивная работа с S3 с помощью WinSCP
- Endpoint сервисов ЦБГД
- Поддержка
- Термины и определения
- Принятые сокращения
History
Состав данных Фонда доступных по программному интерфейсу
С помощью описанного программного интерфейса можно получить данные с Космических систем «Ресурс-П» и «Канопус-В» двух уровней обработки:
- Уровень «1» – Геопривязанные и радиометрически скорректированные изображения маршрута или его фрагмента в путевой системе координат.
- Уровень «2» – Геокодированное или ортотрансформированное изображение маршрута или его фрагмента, представленное в картографической проекции (радиометрически скорректированное).
Формат файлов продуктов: GeoTIFF, Cloud-Optimized GeoTIFF.
Разрядность: 8 или 16 бит на пиксель.
Картографическая проекция: WGS84 (EPSG:4326), UTM, ГСК-2011.
Обзорная схема использования API
На рисунке 1 показана обзорная схема использования API.
Аутентификация потребителей
Под потребителями понимаются организации и частные лица — конечные потребители данных ДЗЗ, в чьих интересах производится доступ к данным ФФД ДЗЗ и их обработка. По состоянию на 2020 год всего в ЦБГД зарегистрировано 17000 учётных записей. Среди них более 1000 учётных записей федеральных и региональных органов власти. Эта информация на ежедневной основе актуализируется сотрудниками НЦ ОМЗ. Разумно использовать эту информацию о потребителях для авторизации внешних (по отношению к ЕТРИС ДЗЗ) web-сервисов. Личный кабинет потребителя — https://auth.gptl.ru/auth/realms/etris/account
Авторизация внешнего web-сервиса для работы с web-сервисами ЦБГД
Под внешним web-сервисом понимается web-сервис не входящий в ЕТРИС ДЗЗ. Внешними web-сервисами являются: Банк базовых продуктов, КОИС (Цифровая Земля), ГИС ОПД «Потребитель», другие информационные системы (ИС). Для каждого внешнего web-сервиса (с собственным URL) должен быть зарегистрирован client OAuth 2.0 Roles. Необходимо прислать по электронной почте название латинскими буквами подключаемой информационной системы для присвоения client_id, а также список разрешённых redirect_url на подключаемую информационную систему. Пока эта процедура производится в ручном режиме запросом к разработчикам ЦБГД. Поддерживается два вида авторизации:
- authorization code , когда подключаемый web-сервис имеет как серверную составляющую, так и web-интерфейс, с помощью которого производится аутентификация пользователей
- Resource Owner Password Credentials Grant , когда подключается web-сервис с единственным пользователем, действующий на собственном сервере и не публикующим данные в Интернет для других потребителей.
Авторизация в виде authorization code
Рассмотрим на примере взаимодействия внешнего web-сервиса с client id “KOIS”, который помимо стандартных полномочий желает получить доступ к S3-хранилищу (scope «s3policy»). Для удобства примера в качестве redirect url будет использоваться https://oidcdebugger.com/debug (позволяет проверить работоспособность обмена кодом).
Запрос кода у сервиса авторизации
Веб-сервис KOIS должен отправить пользователя по такому url:
https://auth.gptl.ru/auth/realms/etris/protocol/openid-connect/auth?client_id=KOIS&redirect_uri=https%3A%2F%2Foidcdebugger.com%2Fdebug&scope=s3policy+profile+openid+&response_type=code&response_mode=query&nonce=w8jk4eu57p
Client (внешний web-сервис) — KOIS
Scope (запрашиваемые полномочия) — s3policy, profile openid. Если запросить Scope offline_access, то метка доступа будет действительна даже когда пользователь разлогиниться (logout).
Подтверждение потребителя действовать от его имени
Эта ссылка должна быть открыта из кода web-интерфейса, а не из сервера (back-end’а), потому что ссылка откроет страницу личного кабинета ЕТРИС. После аутентификации потребителя под своей учётной записью будет показан диалог (consent), запрашивающий у потребителя разрешение на получения прав доступа от его имени к Фонду данных ДЗЗ для приложения с client id “KOIS”.
Когда пользователь подтвердит полномочия web-сервиса KOIS действовать от его (потребителя) имени, то будет перенаправлен на URL, указанный ранее в redirect_url (https://oidcdebugger.com/debug) вместе к кодом (code).
Обмен кода на метку доступа (access token)
Метка доступа (access token) уполномочивает web-сервисы на проведение запросов от имени посетителя Геопортала. Последующие действия должны производиться на back-end (не в браузере). Дальнейшие примеры приведены для bash. Обменяем полученный код на метку доступа (access token). Для конфиденциальности (чтобы другие web-сервисы не могли повторить такой обмен) в запросе указывается client_secret, получаемый во время регистрации client.
access_token=$(curl -Ss -X POST \
"https://auth.gptl.ru/auth/realms/etris/protocol/openid-connect/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'client_id=KOIS' \
-d 'client_secret=secret' \
-d 'redirect_uri=https%3A%2F%2Foidcdebugger.com%2Fdebug' \
-d 'code=полученныйкод' \
| jq . - | tee access_token.json | jq -r '.access_token' )
Ответ сервиса авторизации сохранён в файле access_token.json. Из этого файла в переменную окружения access_token извлечена метка доступа. В ответе сервиса авторизации (файл access_token.json) помимо метки доступа содержатся:
- refresh_token (метка обмена — см. [Обновление метки доступа](#Обновление метки доступа))
- id_token (метка потребителя — см. [Получение информации о потребителе](#Получение информации о потребителе)).
Обновление метки доступа
Время жизни метки доступа очень короткое для того, чтобы сократить временное окно, в течение которого злоумышленник сможет украсть метку и воспользоваться ей. Требуется регулярное обновление метки доступа с помощью refresh token (метка обмена). Обмен истекшей метки доступа запускается на back-end.
refresh_token=$( jq -r '.refresh_token' access_token.json)
access_token=$(curl -Ss -X POST \
"https://auth.gptl.ru/auth/realms/etris/protocol/openid-connect/token" \
--header 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token' \
-d 'client_id=KOIS' \
-d 'client_secret=secret' \
-d "refresh_token=${refresh_token}" \
| jq . - | tee access_token.json | jq -r '.access_token' )
Ответ сервиса авторизации сохранён в файле access_token.json.
Для присвоения переменной окружения access_token обновленной метки доступа вышеуказанная bash команда должна быть запущена как source refresh_token.sh.
Получение информации о потребителе
В случае успешного получения метки доступа в ответе сервиса авторизации возвращается метка потребителя (id_token). И access_token и id_token являются JWT (JSON Web Token). Просмотреть их содержание можно с помощью сервиса https://jwt.io или с помощью простых bash команд:
id_token=$(jq -r '.id_token' access_token.json)
read -ra token_fragments <<< "${id_token//./$' '}"
echo -n ${token_fragments[1]} | base64 -d | jq . -
(могут быть сообщения об ошибках от base64 из-за невыравнивания закодированной base64 строки кратно 4 символам)
Пример вывода метки потребителя:
{
"exp": 1591383896,
"iat": 1591373096,
"auth_time": 1591352807,
"jti": "dad55e75-8fd7-49e1-8848-016fff68c680",
"iss": "https://auth.gptl.ru/auth/realms/etris",
"aud": [
"cart-request",
"search-catalog-api",
"serv-task",
"account"
],
"sub": "e3c689f9-734a-4624-a9fa-a5564dd70cce",
"typ": "ID",
"azp": "KOIS",
"nonce": "w8jk4eu57p",
"session_state": "31b3535d-3ae4-4127-9ed8-2918059b5e5f",
"acr": "0",
"email_verified": false,
"name": "KOIS fake user",
"groups": [
"offline_access",
"/geoportal-customers",
"/geoportal-users",
"/Организации/ОАО НИИ ТП",
"/Группы/Потребители"
],
"preferred_username": "test@gptl.test",
"given_name": "Alex",
"family_name": "Rez",
"email": "test@gptl.test",
"s3policy": "publisher-policy"
}
В зависимости от запрашиваемых scope (запрашиваемые полномочия - см. [Запрос кода у сервиса авторизации](#Запрос кода у сервиса авторизации)) будет меняться наполнение метки потребителя. Возможно создание (по запросу) отдельных полей (т. н. Custom claims), которые будут включены в метку. С помощью сочетания scope и custom claims реализуется авторизация потребителей в приложениях. Например, можно добавить специальный scope=KOIS-policy, возвращающий в custom claim группы вида:
"KOIS-groups-membership": [
"contruction-operator",
"construction-manager"
],
Поиск по каталогу ЦБГД (ФФД ДЗЗ)
(Единый) Каталог ЦБГД хранит все записи о сеансах съёмки, содержащихся в (частных) каталогах НКПОР Космических Систем. Сеанс съёмки — это данные минимального уровня обработки (L0 или L1). Помимо сеансов съёмки в Каталоге ЦБГД сохранены снимки для публикации в Геопортале Роскосмоса. Снимки изготовлены из сеансов съёмки, удовлетворяющим параметрам качества, например таким как облачность.
Пример поискового запроса
curl -SsL -G "https://api.gptl.ru/catalog/v2/search" \
-d "platform_type_identifier=RP" \
-d "instrument_identifiers=GTNL1" \
-d "acquisition_date_after=2014-01-01T10:00:00Z" \
-d "acquisition_date_before=2020-01-17T10:00:00Z" \
-d "cloudiness_max=30" \
-d "limit=10" \
--data-urlencode "geometry=POLYGON((31.9388 57.1652, 31.4229 56.198, 30.9238 56.2769, 31.4274 57.2462, 31.9388 57.1652))" \
-H "Authorization: Bearer ${access_token}" \
-d "coverage_exists=true" \
| jq '.' -
Параметры поискового запроса
Параметры поискового запроса перечислены в Таблице 1.
Таблица 1. Описание параметров поискового запроса в Каталоге ЦБГД
| Параметр | Описание | Пример значения параметра |
|---|---|---|
| acquisition_date_after | дата съёмки, левая граница (дата-время в iso8601, зона +00) | |
| acquisition_date_before | дата съёмки, правая граница (дата-время в iso8601, зона +00) | |
| identifier | идентификатор метаданных | ETRIS.RP1.GTNL1.1108.7.0.2019-01-05.L0 |
| platform_identifiers | список идентификаторов КА | RP1,RP2,RP3 KV1,KVIK,KV3,KV4,KV5,KV6 |
| platform_type_identifier | идентификатор типа КА | RP,KV |
| instrument_identifiers | MSS (для KV) GTNL1 (для RP) | |
| processing_level_code | уровень обработки | 0 |
| geometry | геометрия в формате WKT (координаты в градусах) | POLYGON((23.9393 38.1621, 23.8199 37.7264, 23.4766 37.7848, 23.5939 38.2207, 23.9393 38.1621)) |
| cloudiness_max | Процент облачности | 10 |
| coverage_exists | флаг необходимости получения записей Каталога, обязательно содержащих обработанные снимки Геопортала | доступные значения: <не задано> (по умолчанию), true (вернуться только те записи каталога, для которых есть в наличии подготовленные для Геопортала снимки) |
| fields | список возвращаемых полей | доступные поля: fields=id,identifier,platform_identifier |
| format | формат ответа | доступные значения: json (по умолчанию), geojson |
| limit | лимит выборки | по умолчанию 100 |
| offset | сдвиг выборки | по умолчанию 0 |
| ordering | сортировка по заданному полю/полям (указывать через запятую; для обратного порядка указывать "-" перед названием поля) | возможные значения: "id", "identifier","date_time_stamp","last_modified", "platform_identifier","platform_type_identifier", "instrument_identifier", "cloudiness", "resolution", "acquisition_date_begin" Для обратного порядка сортировки добавить знак ‘-` перед полем. |
Результаты поиска по каталогу
В ответе сервиса содержатся все найденные записи каталога , удовлетворяющим запрашиваемым критериям. Каждая запись содержит как идентификатор ETRIS.id, так и метаданные. В разделе previews указаны ссылки на отдельные изображения пред-просмотра (или превью, или квиклуки). Геометрию этих отдельных файлов превью записана в виде multipolygon. Деление превью на отдельные файлы никак не связано с тем, как хранится и как обрабатывается сеанс съёмки.
Полезные команды фильтрации ответа:
| Фильтр | Команда |
|---|---|
| только ETRIS.id (используется при заказе продукта) | jq -r '.results[].identifier' - |
| Ссылки на квиклуки | jq -r '.results[].previews[].url' - |
| Геометрия в формате WKT | jq -r '.results[].previews[].geometry' - |
| Ссылка S3 на подготовленные снимки L2 (при наличии) | jq -r '.results[].coverage[].resource_urls.s3' - |
Пример ответа на поисковый запрос
{
"count": 64,
"results": [
{
"date_time_stamp": "2020-01-15T12:38:10.000Z",
"illumination_azimuth_angle": 305.6519775390625,
"nadir_tilt_angle": -7.360000133514404,
"resolution": 2.5,
"aggregate_information": null,
"scan_number": 1,
"receiving_station_name": "ЦП Калининград",
"cache_id": null,
"platform_name": "Канопус-В1",
"instrument_identifier": "PSS",
"receiving_station_identifier": "FKL_KLG",
"id": 3420596,
"last_modified": "2020-05-25T12:06:11.000Z",
"circuit_number": 41514,
"azimuth_scan_angle": null,
"acquisition_date_instant": null,
"identifier": "ETRIS.KV1.PSS.41514.1.0.2020-01-15.L0.FKL_KLG.NTSOMZ_MSK",
"illumination_elevation_angle": 85.71087646484375,
"processing_level_code": "0",
"acquisition_date_begin": "2020-01-15T11:22:53.000Z",
"pole_area_intersection": null,
"abstract": "Космический cнимок со СУ ПСС КА Канопус-В1 уровня обработки 0",
"cloudiness": 0,
"platform_type_identifier": "KV",
"acquisition_date_end": "2020-01-15T11:23:05.000Z",
"platform_type_name": "КанопусВ",
"platform_identifier": "KV1",
"resp_party_data_storage": [
{
"organization_name": "Научный центр оперативного мониторинга Земли ОАО \"Российские космические системы\"",
"url": "http://www.ntsomz.ru"
}
],
"sensors": [
{
"number": 1,
"instrument_identifier": "PSS",
"id": 2,
"bands": [
{
"min": 0.54,
"max": 0.86,
"description": "Панхром",
"id": 30
}
],
"is_panchromatic": true
}
],
"instrument_name": "ПСС",
"dataset_uri": null,
"previews": [
{
"geometry": "MULTIPOLYGON(((15.02199962445 -23.7402994064925,15.3048996173775 -23.7402994064925,15.3048996173775 -23.99359940016,15.02199962445 -23.99359940016,15.02199962445 -23.7402994064925)))",
"url": "http://www.gptl.ru/previews/Kanopus-V1/2020/05/3420596_4.png"
},
{
"geometry": "MULTIPOLYGON(((14.974999625625 -23.5324994116875,15.257399618565 -23.5324994116875,15.257399618565 -23.785399405365,14.974999625625 -23.785399405365,14.974999625625 -23.5324994116875)))",
"url": "http://www.gptl.ru/previews/Kanopus-V1/2020/05/3420596_3.png"
},
{
"geometry": "MULTIPOLYGON(((14.9280996267975 -23.3246994168825,15.2100996197475 -23.3246994168825,15.2100996197475 -23.5774994105625,14.9280996267975 -23.5774994105625,14.9280996267975 -23.3246994168825)))",
"url": "http://www.gptl.ru/previews/Kanopus-V1/2020/05/3420596_2.png"
},
{
"geometry": "MULTIPOLYGON(((14.91799962705 -23.2792994180175,15.16279962093 -23.2792994180175,15.16279962093 -23.3696994157575,14.91799962705 -23.3696994157575,14.91799962705 -23.2792994180175)))",
"url": "http://www.gptl.ru/previews/Kanopus-V1/2020/05/3420596_1.png"
}
],
"geometry": "MULTIPOLYGON(((14.91799962705 -23.3240994168975,15.1520996211975 -23.279399418015,15.1622996209425 -23.32439941689,14.9280996267975 -23.3690994157725,14.91799962705 -23.3240994168975)),((14.9280996267975 -23.3694994157625,15.16239962094 -23.32479941688,15.2094996197625 -23.532199411695,14.9748996256275 -23.5770994105725,14.9280996267975 -23.3694994157625)),((14.974999625625 -23.5774994105625,15.2094996197625 -23.532599411685,15.25679961858 -23.7399994065,15.0218996244525 -23.7850994053725,14.974999625625 -23.5774994105625)),((15.02199962445 -23.7854994053625,15.2568996185775 -23.74039940649,15.3044996173875 -23.947799401305,15.06919962327 -23.992999400175,15.02199962445 -23.7854994053625)))",
"hierarchy_level": null,
"_id": "3420596",
"coverage": [
{
"processing_level_code": "2B1",
"created": "2019-10-21T11:58:21.000Z",
"service_name": null,
"resolution": 12,
"acquisition_date": "2016-10-06T21:00:00.000Z",
"platform_identifier": "KV1",
"path": "KV1/MSS/2016/ETRIS.KV1.MSS.23372.1.0.2016-10-07.L2B1.ISS_KRS.NTSOMZ_MSK.2019-10-21T115727Z.tiff",
"polygon": "POLYGON1",
"metadata_identifier": "ETRIS.KV1.MSS.23372.1.0.2016-10-07.L0.ISS_KRS.NTSOMZ_MSK",
"name": "2016-10-06_f606062ef9_geotiff",
"instrument_identifier": "MSS",
"id": 83100718,
"last_modified": "2020-02-13T10:46:19.000Z",
"repository_name": "restored_geotiffs_1",
"format_name": "GeoTiff",
"_id": "83100718",
"resource_urls": {
"s3": "s3://restored-geotiffs/KV1/MSS/2016/ETRIS.KV1.MSS.23372.1.0.2016-10-07.L2B1.ISS_KRS.NTSOMZ_MSK.2019-10-21T115727Z.tiff",
"tms": "https://vtms.gptl.ru/preview?url=s3://restored-geotiffs/KV1/MSS/2016/ETRIS.KV1.MSS.23372.1.0.2016-10-07.L2B1.ISS_KRS.NTSOMZ_MSK.2019-10-21T115727Z.tiff"
}
}
]
}
]
}
Пример поиска по каталогу ББП (Банк базовых продуктов)
cat <<EOF | curl -SsL -X POST "https://api.gptl.ru/catalog/v2/bbp/scenes" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/json" --data @- | jq . -
{
"instrument_identifiers": "MSUTM101,MSUTM102",
"acquisition_date_after": "2023-05-27T00:00:00",
"acquisition_date_before": "2023-06-27T23:59:59",
"cloudiness_max": 50,
"geometry": "POLYGON((19.078661114454835 49.53112571289168,19.078661114454835 59.65387760196617,56.4284140015994 59.65387760196617,56.4284140015994 49.53112571289168,19.078661114454835 49.53112571289168))"
}
EOF
Заказать продукты ББП можно через processing_order, указав в заказе идентификаторы ББП в таком виде: BBP.MM22_MSUTM102_20230617T124702_13700400 (в начало идентификатора добавлен BBP.).
Нельзя в заказе через processing_order комбинировать идентификаторы ETRIS. и BBP.
Заказ создания Информационного продукта
Информационный продукт создаётся из данных сеанса съёмки (уровень обработки L0 или L1). За основу для обработки берётся идентификатор ETRIS.id, полученный из результатов поиска. Сейчас доступно два варианта заказа создания информационного продукта (ИП):
deprecated через API заявок (не путать с заказом) request/request (см. ранее подготовленные api-docs). Эти заявки обрабатываются в автоматизированном режиме (с участием операторов) и выполняются на средствах НКПОР космических систем.
с помощью API заказа Order API (разрабатывается для реализации ФФД ДЗЗ). Эти заказы обрабатываются автоматически (без участия операторов) и выполняются на средствах ЕТРИС ДЗЗ.
Заказ создания информационного продукта с помощью Order API
Создает заказ и запускает задание на обработку снимков. Если тело запроса не пустое, то параметры заказа берутся из запроса.
Параметры заказа:
| Наименование параметра | Описание | Возможные значения |
|---|---|---|
| srs_name | Система координат | UTM EPSG:4326 (WGS84) EPSG:7683 (ГСК-2011) |
| product_code | Уровень обработки | L1 L2 |
| bytes_per_pixel | Разрядность данных в пикселе изображения | 1 2 |
| certification | Флаг сертификации продукта на соответствие требованиям ТУ | true false |
| license | Лицензия использования в соответствии с Постановлением правительства № 840 | individually, limited_group, unlimited_group, individually_extra_processing, limited_group_extra_processing, unlimited_group_extra_processing, network_placement |
| usage_time | Срок использования данных в соответствии с Постановлением правительства № 840 | five, ten, unlimited |
| elevation | Применять ЦМР при обработке | true false |
| images/metadata_identifier | Идентификатор сеанса съёмки | ETRIS. RP1.GTNL1.2764.2.0.2021-02-02.L0.MCHS_MUR.NTSOMZ_MSK |
| images/cropping_polygon | Район обрезки сеанса съёмки. Геометрия фрагмента в формате WKT в виде POLYGON (MULTIPOLYGON не допускается), система координат - EPSG 4326 Если не указан, то будет выдан весь сеанс съёмки (т. н. маршрут) | POLYGON ((37.47213604366503 55.82198978151371, 37.54014683383076 55.82198978151371, 37.54014683383076 55.86798360492168, 37.47213604366503 55.86798360492168, 37.47213604366503 55.82198978151371)) |
| images/band_combination | Выбор информационного продукта в соответствии с комбинацией спектральных каналов | pan ms bundle pansharp |
Сформируем параметры запроса:
cat << EOF > processing_order_params.json
{
"srs_name": "EPSG:7683",
"images": [
{
"metadata_identifier": "ETRIS.RP1.GTNL1.2764.2.0.2021-02-02.L0.MCHS_MUR.NTSOMZ_MSK",
"cropping_polygon": "POLYGON ((37.47213604366503 55.82198978151371, 37.54014683383076 55.82198978151371, 37.54014683383076 55.86798360492168, 37.47213604366503 55.86798360492168, 37.47213604366503 55.82198978151371))",
"band_combination": "pansharp"
},
{
"metadata_identifier": "ETRIS.RP1.GTNL1.419.3.0.2020-09-02.L0.NTSOMZ_MSK.NTSOMZ_MSK",
"cropping_polygon": "POLYGON ((37.40643598460176 55.8609968024443, 37.45725509808062 55.8609968024443, 37.45725509808062 55.88836236687038, 37.40643598460176 55.88836236687038, 37.40643598460176 55.8609968024443))",
"band_combination": "pansharp"
}
],
"product_code": "L2",
"bytes_per_pixel": 1,
"certification": false,
"license": "unlimited_group_extra_processing",
"usage_time": "five",
"elevation": true
}
EOF
Заказ одного маршрута ETRIS.id с разными параметрами обработки в одном заказе
Бывает необходимость дважды (и более раз) указать в теле заказа один и тот же идентификатор ETRIS.id. Примеры таких случаев:
- Заказ двух фрагментов из одного маршрута съёмки,
- Заказ маршрута в двух вариантах комбинации спектральных каналов (
pan-sharpenдля визуального просмотра иmsдля анализа измерительных свойств, выраженных в физических величинах).
В этом случае второе и последующие упоминания одинакового ETRIS.id должны использовать суффиксы :1,:2 и т.д., чтобы избежать коллизиции идентификаторов при выдаче готового продукта.
Пример использования:
{
"srs_name": "UTM",
"images": [
{
"metadata_identifier": "ETRIS.RP1.GTNL1.2764.2.0.2021-02-02.L0.MCHS_MUR.NTSOMZ_MSK",
"band_combination": "pansharp"
},
{
"metadata_identifier": "ETRIS.RP1.GTNL1.2764.2.0.2021-02-02.L0.MCHS_MUR.NTSOMZ_MSK:1",
"band_combination": "ms"
}
],
"product_code": "L2",
"bytes_per_pixel": 2,
"certification": false,
"license": "unlimited_group_extra_processing",
"usage_time": "five",
"elevation": true
}
Отправка запроса на создание информационного продукта:
curl -Ss -X POST -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/json" "https://api.gptl.ru/processing-order/v0/my/orders" --data @processing_order_params.json
Ответ сервиса создания информационного продукта
Сервис создания информационного продукта возвращает ответ.
В теле ответа в секции payment_params указано, является ли информационный продукт платным для конкретного потребителя. В случае, когда продукт платный, в ответе содержится ссылка на платёжный шлюз Сбербанка с указанием суммы и деталей платежа. Если информационный продукт бесплатный, то в секции содержится "is_free": "true".
Пример ответа:
{
"id": 608,
"statuses": [{
"status": "processing",
"comment": "Выполняется обработка снимков",
"created_at": "2021-03-18T08:23:11.687652Z"
}
{
"status": "created",
"comment": null,
"created_at": "2021-03-18T08:23:09.967548Z"
}
],
"srs_name": "EPSG:7683",
"total_price": 48799.14,
"images": [
{
"metadata_identifier": "ETRIS.RP1.GTNL1.2764.2.0.2021-02-02.L0.MCHS_MUR.NTSOMZ_MSK",
"cropping_polygon": "POLYGON ((37.47213604366503 55.82198978151371, 37.54014683383076 55.82198978151371, 37.54014683383076 55.86798360492168, 37.47213604366503 55.86798360492168, 37.47213604366503 55.82198978151371))",
"band_combination": "pansharp",
"elevation": true,
"area": 21.763,
"price": 33788.8
},
{
"metadata_identifier": "ETRIS.RP1.GTNL1.419.3.0.2020-09-02.L0.NTSOMZ_MSK.NTSOMZ_MSK",
"cropping_polygon": "POLYGON ((37.40643598460176 55.8609968024443, 37.45725509808062 55.8609968024443, 37.45725509808062 55.88836236687038, 37.40643598460176 55.88836236687038, 37.40643598460176 55.8609968024443))",
"band_combination": "pansharp",
"elevation": true,
"area": 9.668,
"price": 15010.34
}
],
"products": [],
"product_code": "L2",
"bytes_per_pixel": 2,
"certification": false,
"license": "unlimited_group_extra_processing",
"usage_time": "five",
"elevation": true,
"email": "customer_niitp@dep45.niitp",
"number": "20210215-8",
"payment_params": {
"form_url": null,
"is_free": "true"
},
"bbp_order": null,
"created_at": "2021-02-15T15:36:19.494875"
}
Получение списка заказов
Получить номер и историю изменения статусов последних 5 заказов
curl "https://api.gptl.ru/processing-order/v0/my/orders?fields=number,statuses&limit=5" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq .
Запрос информации о заказе
Узнать информацию о заказе создания информационного продукта можно с помощью запроса:
curl -Ss "https://api.gptl.ru/processing-order/v0/my/orders/${number}" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}"
Возможные состояния статусов: created, paid, processing, suspended, partial_completed, completed, canceled, failed.
Пример ответа:
{
"id": 598,
"statuses": [
{
"status": "completed",
"comment": "Заказ выполнен, данные готовы для скачивания"
},
{
"status": "processing",
"comment": "Выполняется обработка снимков",
"created_at": "2021-03-18T08:23:11.687652Z"
},
{
"status": "created",
"comment": null,
"created_at": "2021-03-18T08:23:09.967548Z"
}
],
"srs_name": "UTM",
"total_price": 1135695.38,
"images": [
{
"metadata_identifier": "ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK",
"cropping_polygon": null,
"band_combination": "pansharp",
"elevation": false,
"area": 8345.792,
"price": 1135695.38
}
],
"products": [
{
"id": 360,
"files": [
{
"name": "KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS.L2.tif",
"size": 205186922,
"bucket": "cache-delivery",
"key": "customer_niitp@dep45.niitp/20210212-2/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS_d4032a9f24e31ec032c643d460af7f11f3fe0cdf/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS.L2.tif",
"url": "https://api.gptl.ru/orders/20210212-2/products/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/link?file=KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS.L2.tif&download=true"
},
{
"name": "KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN02.PMS.L2.tif",
"size": 214650630,
"bucket": "cache-delivery",
"key": "customer_niitp@dep45.niitp/20210212-2/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN02.PMS_19993cae04d74be683da7aba8ed0349022039d0b/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN02.PMS.L2.tif",
"url": "https://api.gptl.ru/orders/20210212-2/products/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/link?file=KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN02.PMS.L2.tif&download=true"
},
<вырезан длинный список сцен продукта>
],
"identifier": "ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK",
"preview_urls": [
"https://next.gptl.ru/totiler/v1/tiles/{z}/{x}/{y}.png?url=/vsis3/cache-delivery/customer_niitp@dep45.niitp/20210212-2/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/delivery/preview_pansharp.vrt"
],
"remove_date": "2021-03-18T00:37:40.208056+03:00",
"created_at": "2021-02-16T00:52:06.207338+03:00"
}
],
"product_code": "L2",
"bytes_per_pixel": 1,
"certification": false,
"license": "individually",
"usage_time": "five",
"elevation": false,
"email": "customer_niitp@dep45.niitp",
"number": "20210212-2",
"payment_params": {
"form_url": null,
"is_free": "true"
},
"bbp_order": null,
"created_at": "2021-02-12T16:39:12.543459+03:00"
}
Получение информационного продукта
Получение информационного продукта
curl -Ss "https://api.gptl.ru/processing-order/v0/my/orders/${number}?fields=products" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq . -
Ответ содержит:
{
"products": [
{
"id": 360,
"files": [
{
"name": "KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS.L2.tif",
"size": 205186922,
"bucket": "cache-delivery",
"key": "customer_niitp@dep45.niitp/20210212-2/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS_d4032a9f24e31ec032c643d460af7f11f3fe0cdf/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS.L2.tif",
"url": "https://api.gptl.ru/orders/20210212-2/products/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/link?file=KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN01.PMS.L2.tif&download=true"
},
<вырезан длинный список сцен продукта>
],
"identifier": "ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK",
"preview_urls": [
"https://next.gptl.ru/totiler/v1/tiles/{z}/{x}/{y}.png?url=/vsis3/cache-delivery/customer_niitp@dep45.niitp/20210212-2/ETRIS.KV4.MSS.10068.1.0.2019-11-26.L0.NTSOMZ_MSK.NTSOMZ_MSK/delivery/preview_pansharp.vrt"
],
"remove_date": "2021-03-18T00:37:40.208056+03:00",
"created_at": "2021-02-16T00:52:06.207338+03:00"
}
]
}
Готовые продукты доступны по трём протоколам:
S3 – в виде URI объекта (s3://bucket/key). Доступ с имеющимися учётными записями S3 или через временную сессию (STS [Получение временной сессии работы с S3 хранилищем](#Получение временной сессии работы с S3 хранилищем)).
HTTPS – в виде криптографически подписанного pre-signed URL.
TMS – в виде динамически генерируемых тайлов в проекции Псевдо-Меркатора для отображения в браузере (секция preview_urls) всего маршрута (все сцены одного маршрута совмещены в единый слой).
Для генерации криптографически подписанного pre-signed URL необходимо получить список файлов:
curl -Ss "https://api.gptl.ru/processing-order/v0/my/orders/${number}?fields=products" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq -r '.products[].files[].url' -
затем вызвать формирование Presigned-URL
curl -Ss "https://api.gptl.ru/processing-order/v0/orders/${number}/products/${identifier}/link?file=${file_name}&download=false" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq -r '.url' -
В ответе при значении параметра download=false вернётся presigned URL такого вида:
Ссылки на S3 и Presigned URL можно использовать с библиотекой GDAL (см. [Установка окружения временной сессии работы с S3](#Установка окружения временной сессии работы с S3)).
При значении параметра download=true произойдёт перенаправление (HTTP 302) на Presigned URL. Клиент HTTP должен поддерживать перенаправление, например для curl должен быть установлен параметр -L или --location
curl -o metadata_BBP.MM22_MSUTM102_20210101T145501_11900200.zip -L "https://api.gptl.ru/processing-order/v0/orders/${number}/products/BBP.MM22_MSUTM102_20210101T145501_11900200/link?file=metadata_BBP.MM22_MSUTM102_20210101T145501_11900200.zip&download=true" -H "Accept: application/json"
Скачать все продукты по конкретному заказу можно такой командой -
curl -Ss "https://api.gptl.ru/processing-order/v0/my/orders/${number}?fields=products" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq -c '.products[].files[] | {name,url}' - | while read -r params; do curl --parallel --parallel-immediate -L "$(jq -r .url <<< $params)" -o "$(jq -r .name <<< $params)" -H "Authorization: Bearer ${access_token}" ; done
Порядок спектральных каналов в информационном продукте
KV1, KVIK
| Название | Диапазон | Номер |
|---|---|---|
| BLUE (синий) | 0.46-0.52 | 1 |
| GREEN (зеленый) | 0.51-0.60 | 2 |
| RED (красный) | 0.63-0.69 | 3 |
| NIR (ближний ИК) | 0.75-0.84 | 4 |
последовательность спектральных каналов по умолчанию: [3, 2, 1, 4]
KV3, KV4, KV5, KV6
| Название | Диапазон | Номер |
|---|---|---|
| BLUE (синий) | 0.46-0.52 | 2 |
| GREEN (зеленый) | 0.51-0.60 | 1 |
| RED (красный) | 0.63-0.69 | 4 |
| NIR (ближний ИК) | 0.75-0.84 | 3 |
последовательность спектральных каналов по умолчанию: [4, 1, 2, 3]
RP; GTNL1
| Название | Диапазон | Номер |
|---|---|---|
| BLUE (синий) | 0.45-0.52 | 6 |
| GREEN (зеленый) | 0.52-0.60 | 3 |
| RED (красный) | 0.61-0.68 | 1 |
| RED_EDGE | 0.67-0.70 | 4 |
| RED_EDGE.1 | 0.70-0.73 | 5 |
| NIR (ближний ИК) | 0.72-0.80 | 2 |
последовательность спектральных каналов по умолчанию: [1, 3, 6, 2]
RP; SSR, SVR
| Название | Диапазон | Номер |
|---|---|---|
| BLUE (синий) | 0.43-0.51 | 1 |
| GREEN (зеленый) | 0.51-0.58 | 2 |
| RED (красный) | 0.60-0.70 | 3 |
| NIR (ближний ИК) | 0.70-0.90 | 4 |
| NIR.1(ближний ИК) | 0.80-0.90 | 5 |
последовательность спектральных каналов по умолчанию: [3,2,1,4,5]
Просмотр снимков через виртуальный TMS-сервис
Сервис виртуального TMS-сервера предназначен для представления покрытий, размещённых в объектовом хранилище S3, в виде тайлов по протоколу OGC TMS. Сервис преобразует покрытие в набор тайлов «на лету» в момент запроса. Снимки для публикации в Геопортале Роскосмоса (секция coverage), можно просмотреть онлайн в полном разрешении. Для этого достаточно открыть в браузере ссылку, содержащую идентификатор покрытия (ссылка также содержит ответ с результатами поиска в секции «coverage» «tms»):
Нормализованные для Геопортала снимки доступны через vtms-сервис анонимно без аутентификации и метки доступа.
Просмотр бесшовных мозаичных покрытий по TMS-протоколу
Сервис бесшовных мозаичных покрытий предназначен для публикации бесшовных мозаичных покрытий по протоколу OGC TMS.
По состоянию на 2020 год опубликован тестовый слой с бесшовными мозаичными покрытиями высокого разрешения 7 регионов РФ: Московская, Ленинградская, Калининградская, Калужская, Белгородская, Брянская области и Республика Крым. Тестовый слой доступен по протоколу TMS:
https://next.gptl.ru/tms?tile=9+3+4&LAYERS=cvrgl
где
X, Y — координаты тайла
Z — уровень тайловой пирамиды (zoom-level).
Работа с данными Фонда через протокол S3
Большая часть оперативного хранилища ЦБГД, доступная по протоколу S3, (далее просто S3) находится в закрытом для анонимного доступа режиме.
Внешний web-сервис может получить доступ к объектам S3:
использовав выданную при регистрации постоянную пару access_key / secret_key
либо создав временную (short-term) сессию с помощью имеющейся метки доступа с соответствующей авторизацией потребителя.
Получение временной сессии работы с S3 хранилищем
Пример запроса временной сессии работы с Объектным хранилищем S3
curl -Ss -X POST "https://s3.gptl.ru" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'Action=AssumeRoleWithWebIdentity' \
-d 'DurationSeconds=3600' \
-d "WebIdentityToken=${access_token}" \
-d 'Version=2011-06-15' \
| xmllint --format -o sts.xml -
в файле sts.xml сохранен ответ службы STS (security token service). Используя данные из ответа можно создать сеанс временной (3600 секунд) сессии работы с объектным хранилищем.
Установка окружения временной сессии работы с S3
Установка переменных окружения для сессии работы с объектным хранилищем S3 производится путем извлечения из sts.xml ключа доступа, секретного ключа и идентификатора временной сессии:
export AWS_ACCESS_KEY_ID=$(xpath sts.xml '//AccessKeyId/text()' )
export AWS_SECRET_ACCESS_KEY=$(xpath sts.xml '//SecretAccessKey/text()' )
export AWS_SESSION_TOKEN=$(xpath sts.xml '//SessionToken/text()' )
export AWS_VIRTUAL_HOSTING=FALSE
export AWS_S3_ENDPOINT=s3.gptl.ru
export GDAL_INGESTED_BYTES_AT_OPEN=1048576
export GDAL_HTTP_MAX_RETRY=5
export GDAL_DISABLE_READDIR_ON_OPEN=EMPTY_DIR
export GDAL_CACHEMAX=10%
export CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE=YES
export CPL_VSIL_CURL_USE_HEAD=NO
export VSI_CACHE_SIZE=268435456
export VSI_CACHE=TRUE
Hint: для удобной работы с контейнером docker, можно сохранить указанные перечисленные переменные окружения (без команды export) в файл, например с именем env.sh.
Работа c aws-cli
Утилита aws-cli предназначена для работы с объектным хранилищем по протоколу S3 в режиме командной строки.
Следующая команда выведет все заказы для пользователя customer_niitp@dep45.niitp (здесь следует подставить email своего потребителя)
aws --endpoint-url https://s3.gptl.ru --region ext-dc1 s3 ls s3://cache-delivery/customer_niitp@dep45.niitp/
Пример риспользования утилиты aws-cli для рекурсивного копирования всех файлов своего заказа в домашнюю директорию:
aws --endpoint-url https://s3.gptl.ru --region ext-dc1 s3 cp --recursive s3://cache-delivery/customer_niitp@dep45.niitp/20210413-485/ ~/
Работа GDAL
Утилита GDAL позволяет напрямую работать с объектным хранилищем по протоколу S3 как с обычной файловой системой посредством драйвера виртуального интерфейса VSI (virtual storage interface).
Предварительно необходимо установить переменные окружения из файла sts.xml (см. Установка окружения временной сессии работы с S3).
Пример для просмотра информации о снимке:
gdalinfo /vsis3/geoportal-public/product-samples/20220726-1070/ETRIS.RP1.GTNL1.4753.3.0.2019-08-31.L0.NTSOMZ_MSK.NTSOMZ_MSK/RP1_34586_03_GEOTON_20190831_051209_051227.SCN1.PMS.L2.tif
Пример работы с presigned URL:
gdalinfo --config CPL_VSIL_CURL_USE_HEAD NO '/vsicurl/https://s3.gptl.ru/cache-delivery/customer_niitp@dep45.niitp/00006-20210126/ETRIS.KV1.MSS.33498.2.0.2018-08-05.L0.FKL_KLG.NTSOMZ_MSK/delivery/KV1_33498_26562_01_KANOPUS_20180805_090323_090423.SCN1.PMS.L2.tif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=cache-delivery-worker/20210126/us-east-1/s3/aws4_request&X-Amz-Date=20210126T125328Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=9c0ff9f3c4a61b4f7dbecb0c32a0a4e7659f282d1fa6da9702570124c4ec5d8f'
Пример работы с контейнеризованным gdal:
sudo docker run --env-file ~/env.sh --user $(id -u):$(id -g) --rm -v /home:/home osgeo/gdal:alpine-small-latest gdalinfo /vsis3/geoportal-public/product-samples/20220726-1070/ETRIS.RP1.GTNL1.4753.3.0.2019-08-31.L0.NTSOMZ_MSK.NTSOMZ_MSK/RP1_34586_03_GEOTON_20190831_051209_051227.SCN1.PMS.L2.tif
Все загруженные нами данные в Хранилище S3 проходят «нормализацию». Поэтому при обращении к нормализованным данным, размещённым в хранилище, ввод-вывод осуществляется только к тем блокам данных, которые относятся к району интереса (параметр –projwin в примере выше).
Интерактивная работа с S3 в QGIS
При настроенных переменных окружения в QGIS можно работать с данными по протоколу S3 (Рисунок 3). Используйте bucket geoportal-public и Object key product-samples/20220726-1070/ETRIS.RP1.GTNL1.4753.3.0.2019-08-31.L0.NTSOMZ_MSK.NTSOMZ_MSK/RP1_34586_03_GEOTON_20190831_051209_051227.SCN1.PMS.L2.tif
или с использованием Presigned URL (Рисунок 4).
Интерактивная работа с S3 с помощью WinSCP
Протокол S3 предназначен прежде всего для криптографически защищенного программного доступа к данным. Тем не менее, из-за широкого распространения протокола, была реализована поддержка в различных программах интерактивной работы, например, WinSCP
Поддерживают протокол S3 только последние версии WinSCP не ниже 5.16 (https://winscp.net)
Endpoint сервисов ЦБГД
Сервис аутентификации (auth service) для получения токена: https://auth.gptl.ru/auth
Базовый адрес сервиса поиска (catalog service): https://api.gptl.ru/catalog/v2/search
S3 объектное хранилище оперативного доступа (доступ из Интернета) https://s3.gptl.ru
Поддержка
Адрес электронной почты разработчиков:
Термины и определения
Потребители ДДЗ — организации и частные лица — конечные потребители данных ДЗЗ, в чьих интересах производится доступ к данным ФФД ДЗЗ и их обработка.
Внешний web-сервис — web-сервис не входящий в ЕТРИС ДЗЗ, например Банк базовых продуктов, КОИС (Цифровая Земля). Каждый внешний web-сервис должен иметь зарегистрированный клиент (client) в Сервисе Авторизации ЕТРИС.
Resource Server (Сервер ресурсов) — все API сервисы (https://api.gptl.ru/) , сервис оперативного хранилища S3 (https://s3.gptl.ru).
Authorization Server (Сервис авторизации ЕТРИС) — http://auth.gptl.ru
Принятые сокращения
ЕТРИС ДЗЗ — Единая территориально-распределенная информационная система дистанционного зондирования Земли
КОИС — Комплекс отраслевых информационных сервисов
НКПОР — Наземный комплекс приёма, обработки и распространения информации
ФФД ДЗЗ — Федеральный фонд данных дистанционного зондирования Земли из космоса
ЦБГД — Центральный банк геоинформационных данных