Спецификация программных интерфейсов ЦБГД для работы с Фондом данных ДЗЗ

Содержание

History

Состав данных Фонда доступных по программному интерфейсу

С помощью описанного программного интерфейса можно получить данные с Космических систем «Ресурс-П» и «Канопус-В» двух уровней обработки:

Формат файлов продуктов: GeoTIFF, Cloud-Optimized GeoTIFF.

Разрядность: 8 или 16 бит на пиксель.

Картографическая проекция: WGS84 (EPSG:4326), UTM, ГСК-2011.

Обзорная схема использования API

На рисунке 1 показана обзорная схема использования API.

API

Рисунок 1 - Обзорная схема использования API

Аутентификация потребителей

Под потребителями понимаются организации и частные лица — конечные потребители данных ДЗЗ, в чьих интересах производится доступ к данным ФФД ДЗЗ и их обработка. По состоянию на 2020 год всего в ЦБГД зарегистрировано 17000 учётных записей. Среди них более 1000 учётных записей федеральных и региональных органов власти. Эта информация на ежедневной основе актуализируется сотрудниками НЦ ОМЗ. Разумно использовать эту информацию о потребителях для авторизации внешних (по отношению к ЕТРИС ДЗЗ) web-сервисов. Личный кабинет потребителя — https://auth.gptl.ru/auth/realms/etris/account

Авторизация внешнего web-сервиса для работы с web-сервисами ЦБГД

Под внешним web-сервисом понимается web-сервис не входящий в ЕТРИС ДЗЗ. Внешними web-сервисами являются: Банк базовых продуктов, КОИС (Цифровая Земля), ГИС ОПД «Потребитель», другие информационные системы (ИС). Для каждого внешнего web-сервиса (с собственным URL) должен быть зарегистрирован client (OpenID-Connect). Необходимо прислать по электронной почте название латинскими буквами подключаемой информационной системы для присвоения client_id, а также список разрешённых redirect_url на подключаемую информационную систему. Пока эта процедура производится в ручном режиме запросом к разработчикам ЦБГД. Поддерживается авторизация в виде authorization code, когда подключаемый web-сервис имеет как серверную составляющую, так и 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”.

img2

Рисунок 2 – Подтверждение доступа внешнего web-сервиса к ресурсам ЕТРИС от имени потребителя

Когда пользователь подтвердит полномочия 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 -l -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 (метка обмена). Обмен истекшей метки доступа запускается на back-end.

refresh_token=$( jq -r '.refresh_token' access_token.json)
access_token=$(curl -l -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 -l -Ss -G -X GET "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" 
                    }
                }
    ]
    }
  ]
}

Заказ создания Информационного продукта

Информационный продукт создаётся из данных сеанса съёмки (уровень обработки L0 или L1). За основу для обработки берётся идентификатор ETRIS.id, полученный из результатов поиска. Сейчас доступно два варианта заказа создания информационного продукта (ИП):

Заказ создания информационного продукта с помощью 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

Отправка запроса на создание информационного продукта:

curl -X POST\
-H "Authorization: Bearer ${access_token}"\
-H "Accept: application/json"\
-H "Content-Type: application/json"\ 
https://api.gptl.ru/processing-order/v0/my/orders \
--data @processing_order_params.json

Ответ сервиса создания информационного продукта

Сервис создания информационного продукта возвращает ответ.

В теле ответа в секции payment_params указано, является ли информационный продукт платным для конкретного потребителя. В случае, когда продукт платный, в ответе содержится ссылка на платёжный шлюз Сбербанка с указанием суммы и деталей платежа. Если информационный продукт бесплатный, то в секции содержится "order_id": "free".

Пример ответа:

{
  "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,
    "order_id": "free"
  },
  "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 "https://api.gptl.ru/processing-order/v0/my/orders/${order_id}" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" 

Возможные состояния статусов: created, paid, processing, suspended, partial_completed, completed, canceled, failed.

order statuses flow diagram

Пример ответа:

{
  "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,
    "order_id": "free"
  },
  "bbp_order": null,
  "created_at": "2021-02-12T16:39:12.543459+03:00"
}

Получение информационного продукта

Получение информационного продукта

curl "https://api.gptl.ru/processing-order/v0/my/orders/${order_id}?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/${order_id}?fields=products" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq -r '.products[].files[].url' -

затем вызвать формирование Presigned-URL

curl "https://api.gptl.ru/processing-order/v0/my/orders/${order_id}/products/${identifier}/link?file=${file_name}&download=false" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" 

В ответе при значении параметра download=false вернётся presigned URL такого вида:

https://s3.gptl.ru/cache-delivery/customer_niitp%40dep45.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.SCN21.PMS_c13c7d31834f26befee2f566a8e12bfa5d2d1545/KV4_10068_07118_00_KANOPUS_20191126_035042_035139.SCN21.PMS.L2.tif?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=cache-delivery-worker%2F20210216%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210216T153046Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=677e4048be0d33aeeccdad0a929678743b93bdc8c095899c78d274435a7e59c9

Ссылки на S3 и Presigned URL можно использовать с библиотекой GDAL (см. [Установка окружения временной сессии работы с S3](#Установка окружения временной сессии работы с S3)).

При значении параметра download=true произойдёт перенаправление (HTTP 302) на Presigned URL. Клиент HTTP должен поддерживать перенаправление, например для curl должен быть установлен параметр -L или --location

curl -O -L "https://api.gptl.ru/processing-order/v0/orders/20210407-476/products/BBP.MM22_MSUTM102_20210101T145501_11900200/link?file=metadata_BBP.MM22_MSUTM102_20210101T145501_11900200.zip&download=true" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}"

Скачать все продукты по конкретному заказу можно такой командой -

curl -Ss "https://api.gptl.ru/processing-order/v0/my/orders/${order_id}?fields=products" -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" | jq -r '.products[].files[].url' - | xargs -n1 curl -O -L -H "Accept: application/json" -H "Authorization: Bearer ${access_token}" 

Порядок спектральных каналов в информационном продукте

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»):

https://vtms.gptl.ru/preview?url=s3://restored-geotiffs/KV1/PSS/2019/ETRIS.KV1.PSS.37230.3.0.2019-04-08.L2B.FKL_KLG.NTSOMZ_MSK.2020-01-31T053543Z.tiff

Нормализованные для Геопортала снимки доступны через 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:

  1. использовав выданную при регистрации постоянную пару access_key / secret_key

  2. либо создав временную (short-term) сессию с помощью имеющейся метки доступа с соответствующей авторизацией потребителя.

Получение временной сессии работы с S3 хранилищем

Пример запроса временной сессии работы с Объектным хранилищем S3

curl -l -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 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 s3 ls s3://cache-delivery/customer_niitp@dep45.niitp/

Пример риспользования утилиты aws-cli для рекурсивного копирования всех файлов своего заказа в домашнюю директорию:

aws --endpoint-url https://s3.gptl.ru s3 cp --recursive s3://cache-delivery/customer_niitp@dep45.niitp/20210413-485/ ~/

Работа GDAL

Утилита GDAL позволяет напрямую работать с объектным хранилищем по протоколу S3 как с обычной файловой системой посредством драйвера виртуального интерфейса VSI (virtual storage interface).

Предварительно необходимо установить переменные окружения из файла sts.xml (см. Установка окружения временной сессии работы с S3).

Пример для просмотра информации о снимке:

gdalinfo /vsis3/restored-geotiffs/KV1/MSS/2014/ETRIS.KV1.MSS.10521.2.0.2014-06-14.L2B1.NTSOMZ_MSK.NTSOMZ_MSK.2019-11-13T041542Z.tiff

Пример вырезания фрагмента из ЦМР и сохранения фрагмента в локальную файловую систему:

gdal_translate -projwin 32.0 46.0 35.0 44.0  /vsis3/elevation/SRTMGL1.003/SRTMGL1.003.vrt ./clip.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/webdata/geoportal/KV6/MSS/2020/ETRIS.KV6.MSS.8310.1.0.2020-06-26.L2B1.FKL_KLG.NTSOMZ_MSK.2020-06-30T063038Z.tiff

Все загруженные нами данные в Хранилище S3 проходят «нормализацию». Поэтому при обращении к нормализованным данным, размещённым в хранилище, ввод-вывод осуществляется только к тем блокам данных, которые относятся к району интереса (параметр –projwin в примере выше).

Интерактивная работа с S3 в QGIS

При настроенных переменных окружения в QGIS можно работать с данными по протоколу S3 (Рисунок 3).

img2

Рисунок 3

или с использованием Presigned URL (Рисунок 4).

img2

Рисунок 4

Интерактивная работа с S3 с помощью WinSCP

Протокол S3 предназначен прежде всего для криптографически защищенного программного доступа к данным. Тем не менее, из-за широкого распространения протокола, была реализована поддержка в различных программах интерактивной работы, например, WinSCP

Поддерживают протокол S3 только последние версии WinSCP не ниже 5.16 (https://winscp.net)

img2

Рисунок 5 - Настройка WinSCP для работы с S3

Endpoint сервисов ЦБГД

Сервис аутентификации (auth service) для получения токена: https://auth.gptl.ru/auth

Базовый адрес сервиса поиска (catalog service): https://api.gptl.ru/catalog/v2/search

S3 объектное хранилище оперативного доступа (доступ из Интернета) https://s3.gptl.ru

Поддержка

Адрес электронной почты разработчиков:

boris.raychenko@niitp.ru

Термины и определения

Потребители ДДЗ — организации и частные лица — конечные потребители данных ДЗЗ, в чьих интересах производится доступ к данным ФФД ДЗЗ и их обработка.

Внешний web-сервис — web-сервис не входящий в ЕТРИС ДЗЗ, например Банк базовых продуктов, КОИС (Цифровая Земля). Каждый внешний web-сервис должен иметь зарегистрированный клиент (client) в Сервисе Авторизации ЕТРИС.

Resource Server (Сервер ресурсов) — все API сервисы (https://api.gptl.ru/) , сервис оперативного хранилища S3 (https://s3.gptl.ru).

Authorization Server (Сервис авторизации ЕТРИС) — http://auth.gptl.ru

Identity Server (Сервис идентификации или Личный кабинет ЕТРИС) — https://id.gptl.ru

Принятые сокращения

ЕТРИС ДЗЗ — Единая территориально-распределенная информационная система дистанционного зондирования Земли

КОИС — Комплекс отраслевых информационных сервисов

НКПОР — Наземный комплекс приёма, обработки и распространения информации

ФФД ДЗЗ — Федеральный фонд данных дистанционного зондирования Земли из космоса

ЦБГД — Центральный банк геоинформационных данных