Быстрый старт: Создание коллекции STAC в Microsoft Planetary Computer Pro GeoCatalog с помощью Python

В этом кратком руководстве описано, как создать коллекцию каталога ресурсов SpatioTemporal (STAC) и добавить ее в Microsoft Planetary Computer Pro GeoCatalog с помощью Python.

Предпосылки

Чтобы завершить это краткое начальное руководство, вам требуется:

• Учетная запись Azure с активной подпиской. Используйте ссылку "Создать учетную запись бесплатно".
• Ваша среда настроена для доступа к Azure, например, с помощью az login.
• Доступ к планетарному компьютеру Pro GeoCatalog. Если у вас еще нет доступа, вы можете создать новый GeoCatalog.
• Среда Python версии 3.10 (или более поздней версии) с установленными requests и azure-identity.

python3 -m pip install requests azure-identity

Создание JSON коллекции STAC

Чтобы создать коллекцию STAC, сначала потребуется json-файл, определяющий свойства коллекции. Некоторые свойства требуются при создании коллекций STAC, как описано в обзоре коллекции STAC. Другие свойства можно добавлять в зависимости от варианта использования и типа данных.

Для этого руководства прочитайте коллекцию STAC io-lulc-annual-v02 из STAC API Planetary Computer Pro. Если у вас уже есть эта коллекция STAC в GeoCatalog, перейдите к следующему разделу.

import requests

collection = requests.get(
    "https://planetarycomputer.microsoft.com/api/stac/v1/collections/io-lulc-annual-v02"
).json()
collection.pop("assets", None)  # remove unused collection-level assets
collection["id"] = "mpc-quickstart"
collection["title"] += " (Planetary Computer Quickstart)"

Если для коллекции используется другой идентификатор, обязательно замените id поле правильным значением.

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

Получите токен доступа.

REST API

Для доступа к GeoCatalog требуется маркер для проверки подлинности запросов. Используйте клиентскую библиотеку Azure-identity для Python для получения токена.

import azure.identity

credential = azure.identity.DefaultAzureCredential()
token = credential.get_token("https://geocatalog.spatio.azure.com")
headers = {
    "Authorization": f"Bearer {token.token}"
}

Эти учетные данные можно указать в качестве Bearer token в заголовке Authorization в запросах, сделанных к GeoCatalog.

Добавление коллекции в GeoCatalog

С помощью метаданных STAC, маркера и URL-адреса в GeoCatalog выполните запрос к API STAC, чтобы добавить коллекцию.

# Put the URL to your Planetary Computer Pro GeoCatalog (not including '/stac' or a trailing '/' ) here
geocatalog_url = "<your-geocatalog-url>"

response = requests.post(
    f"{geocatalog_url}/stac/collections",
    json=collection,
    headers=headers,
    params={"api-version": "2026-04-15"},
)
print(response.status_code)

Код 201 состояния указывает, что ваша коллекция была создана. Код 409 состояния указывает, что коллекция с этим идентификатором уже существует. Сведения об обновлении существующей коллекции см. в статье "Обновление коллекции".

Теперь вы можете прочитать эту коллекцию в конечной точке /stac/collections/{collection_id}.

geocatalog_collection = requests.get(
    f"{geocatalog_url}/stac/collections/{collection['id']}",
    headers=headers,
    params={"api-version": "2026-04-15"},
).json()

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

Настройка коллекции

Каждая коллекция в GeoCatalog включает в себя некоторую конфигурацию, которая определяет, как элементы STAC и их ресурсы данных хранятся, индексируются и визуализированы. Чтобы настроить коллекцию, выполните приведенные действия.

1. Определите конфигурацию отрисовки для коллекции. Эта конфигурация отрисовки определяет, как активы элементов STAC в коллекции отображаются при визуализации в программе GeoCatalog Explorer. Определенные параметры, используемые здесь, зависят от ресурсов в коллекции.

   import json
   import urllib.parse
   
   colormap = {
       0: (0, 0, 0, 0),
       1: (65, 155, 223, 255),
       2: (57, 125, 73, 255),
       3: (136, 176, 83, 0),
       4: (122, 135, 198, 255),
       5: (228, 150, 53, 255),
       6: (223, 195, 90, 0),
       7: (196, 40, 27, 255),
       8: (165, 155, 143, 255),
       9: (168, 235, 255, 255),
       10: (97, 97, 97, 255),
       11: (227, 226, 195, 255),
   }
   colormap = urllib.parse.urlencode({"colormap": json.dumps(colormap)})
   render_option = {
       "id": "default",
       "name": "Default",
       "description": "Land cover classification using 9 class custom colormap",
       "type": "raster-tile",
       "options": f"assets=data&exitwhenfull=False&skipcovered=False&{colormap}",
       "minZoom": 6,
   }
   
   response = requests.post(
       f"{geocatalog_url}/stac/collections/{collection['id']}/configurations/render-options",
       json=render_option,
       headers=headers,
       params={"api-version": "2026-04-15"}
   )
   print(response.status_code)
   

2. Определите мозаику для коллекции. Конфигурация мозаики определяет, как элементы запрашиваются, фильтруются и объединяются для создания единого представления данных в обозревателе GeoCatalog. В следующем примере конфигурации мозаики не применяются дополнительные параметры запроса или фильтры. В результате, когда эта конфигурация выбрана в обозревателе GeoCatalog, отображаются все элементы в коллекции с самыми последними элементами, отображаемыми в первую очередь.

   mosaic = {
       "id": "most-recent",
       "name": "Most recent available",
       "description": "Show the most recent available data",
       "cql": [],
   }
   response = requests.post(
       f"{geocatalog_url}/stac/collections/{collection['id']}/configurations/mosaics",
       json=mosaic,
       headers=headers,
       params={"api-version": "2026-04-15"}
   )
   print(response.status_code)
   

   Поле cql конфигурации мозаики можно использовать для фильтрации элементов на основе их свойств. Например, если элементы STAC реализуют [eo расширение][eo], можно определить фильтр "низкооблачный" (менее 10% облачное)

   "cql": [{"op": "<=", "args": [{"property": "eo:cloud_cover"}, 10]}]
   

3. Определение параметров плитки для коллекции. Это управляет такими элементами, как минимальный уровень масштабирования.

   tile_settings = {
     "minZoom": 6,
     "maxItemsPerTile": 35,
   }
   requests.put(
       f"{geocatalog_url}/stac/collections/{collection['id']}/configurations/tile-settings",
       json=tile_settings,
       headers=headers,
       params={"api-version": "2026-04-15"}
   )
   

Обновление коллекции

Можно обновить существующую коллекцию с запросом PUT к конечной точке /stac/collections/{collection_id} .

collection["description"] += " (Updated)"

response = requests.put(
    f"{geocatalog_url}/stac/collections/{collection['id']}",
    headers={"Authorization": f"Bearer {token.token}"},
    json=collection,
    params={"api-version": "2026-04-15"},
)
print(response.status_code)

Код 200 состояния указывает, что коллекция была успешно обновлена.

Очистите ресурсы

Запрос можно использовать для удаления коллекции из вашего GeoCatalog. Удаление коллекции также удаляет:

1. Все элементы STAC, которые являются дочерними элементами этой коллекции.
2. Все ресурсы, являющиеся дочерними элементами указанных объектов.
3. Все ресурсы уровня коллекции этой коллекции.

Краткое руководство по добавлению элементов STAC в коллекцию использует эту коллекцию, поэтому не удаляйте ее, если вы планируете выполнить это краткое руководство.

response = requests.delete(
    f"{geocatalog_url}/stac/collections/{collection['id']}",
    headers={"Authorization": f"Bearer {token.token}"},
    params={"api-version": "2026-04-15"}
)
print(response.status_code)

Код 204 состояния указывает, что коллекция была удалена.

Предупреждение

При удалении коллекции необходимо подождать не менее 45 секунд, прежде чем пытаться создать новую коллекцию с идентичным именем или идентификатором. Если вы пытаетесь создать новую коллекцию, используя то же имя, что и удаленная коллекция, вы получите сообщение об ошибке. Если эта ошибка возникает, попробуйте повторно создать коллекцию после 45-секундного ожидания.

Пакет SDK для Python

Установите Python SDK для Planetary Computer Pro:

pip install azure-planetarycomputer azure-identity

Добавление коллекции в GeoCatalog

from azure.planetarycomputer import PlanetaryComputerProClient
from azure.identity import DefaultAzureCredential

client = PlanetaryComputerProClient(
    endpoint="<your-geocatalog-url>",
    credential=DefaultAzureCredential()
)

# 'collection' is the STAC collection dict defined in the previous section
poller = client.stac.begin_create_collection(body=collection)
result = poller.result()  # Wait for completion
print(result)

Прочитать коллекцию

geocatalog_collection = client.stac.get_collection(collection["id"])

Настройка коллекции

1. Определите конфигурацию отрисовки:

   render_option = {
       "id": "default",
       "name": "Default",
       "description": "Land cover classification using 9 class custom colormap",
       "type": "raster-tile",
       "options": f"assets=data&exitwhenfull=False&skipcovered=False&{colormap}",
       "minZoom": 6,
   }
   
   client.stac.create_render_option(collection["id"], render_option)
   

2. Определите мозаику:

   mosaic = {
       "id": "most-recent",
       "name": "Most recent available",
       "description": "Show the most recent available data",
       "cql": [],
   }
   
   client.stac.add_mosaic(collection["id"], mosaic)
   

3. Определите параметры плитки:

   tile_settings = {
       "minZoom": 6,
       "maxItemsPerTile": 35,
   }
   
   client.stac.replace_tile_settings(collection["id"], tile_settings)
   

Обновление коллекции

collection.description += " (Updated)"
client.stac.replace_collection(collection_id=collection.id, body=collection)

Очистите ресурсы

poller = client.stac.begin_delete_collection(collection.id)
poller.result()  # Wait for deletion to complete

Предупреждение

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

Дополнительные сведения см. в справочнике по пакету SDK Python.

Следующий шаг

Добавление элементов в коллекцию STAC

Связанный контент

• Краткое руководство. Создание коллекции с помощью веб-интерфейса Microsoft Planetary Computer Pro
• Настройка коллекции для визуализации в обозревателе