Inicio rápido: Creación de una colección de STAC en Microsoft Planetary Computer Pro GeoCatalog con Python

Esta guía de inicio rápido le muestra cómo crear una colección de SpatioTemporal Asset Catalog (STAC) y agregarla a una instancia de Microsoft Planetary Computer Pro GeoCatalog mediante Python.

Prerrequisitos

Para completar este inicio rápido necesita instalar:

  • Una cuenta de Azure con una suscripción activa. Use el vínculo Crear una cuenta de forma gratuita.
  • El entorno está configurado para acceder a Azure, por ejemplo, con az login.
  • Acceso a un equipo planetario Pro GeoCatalog. Si aún no tiene acceso, puede crear un nuevo GeoCatalog.
  • Un entorno de Python con requests e azure-identity instalado.
python3 -m pip install requests azure-identity

Crea un JSON de colección STAC

Para crear una colección STAC, primero necesita un archivo JSON que defina las propiedades de la colección. Algunas propiedades son necesarias al crear colecciones de STAC, como se describe en información general de la colección de STAC. Otras propiedades se pueden agregar en función del caso de uso y del tipo de datos.

Para este tutorial, lea la colección io-lulc-annual-v02 STAC de la API STAC de Planetary Computer Pro. Si ya tiene esto como una colección de STAC en su GeoCatalog, puede ir directamente a la siguiente sección.

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

Si usa un identificador diferente para la colección, asegúrese de reemplazar el id campo por el valor correcto.

Para visualizar los recursos de datos de esta colección en el Explorador, los metadatos de la colección deben incluir la extensión Activos de elementos y tener al menos un recurso de elemento cuyo tipo de medio se pueda visualizar.

Obtención de un token de acceso

El acceso a geocatalog requiere un token para autenticar solicitudes. Use la biblioteca cliente azure-identity para Python para recuperar un token:

import azure.identity

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

Esta credencial se puede proporcionar como un token de portador en el Authorization encabezado en las solicitudes realizadas a GeoCatalog.

Agregar una colección a geocatalog

Con los metadatos de STAC, un token y la dirección URL de GeoCatalog, realice una solicitud a la API de STAC para agregar la colección.

# 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": "2025-04-30-preview"},
)
print(response.status_code)

Un código de estado de 201 indica que se creó la colección. Un código de estado de 409 indica que ya existe una colección con ese identificador. Consulte Actualización de una colección para obtener información sobre cómo actualizar una colección existente.

Ahora puede leer esta colección en el /stac/collections/{collection_id} punto de conexión.

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

También puede ver su GeoCatálogo en el navegador para consultar la nueva colección.

Configuración de una colección

Cada colección de geocatalog incluye alguna configuración que controla cómo se almacenan, indexan y visualizan los elementos de STAC y sus recursos de datos. Para configurar una colección:

  1. Defina una configuración de representación para la colección. Esta configuración de representación controla cómo se representan los recursos de elementos de STAC dentro de la colección cuando se visualizan en el Explorador de GeoCatalog. Los parámetros específicos que se usan aquí dependen de los recursos de la colección.

    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": "2025-04-30-preview"}
)
print(response.status_code)

  2. Defina un mosaico para la colección. La configuración de mosaico controla cómo se consultan, filtran y combinan los elementos para crear una vista única de los datos en el Explorador de GeoCatalog. La siguiente configuración de mosaico de ejemplo no aplica ningún filtro ni parámetros de consulta adicionales. Como resultado, cuando se selecciona esta configuración dentro del Explorador de GeoCatalog, se muestran todos los elementos de la colección, con los elementos más recientes mostrados en primer lugar.

    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": "2025-04-30-preview"}
)
print(response.status_code)

    El cql campo de la configuración del mosaico se puede usar para filtrar los elementos en función de sus propiedades. Por ejemplo, si los elementos de STAC implementan el filtro [eo extensión][eo], podría definir un filtro de "nube baja" (menos del 10 % de nube) con

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

  3. Defina la configuración del icono para la colección. Esto controla las cosas como el nivel de zoom mínimo.

    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": "2025-04-30-preview"}
)

Actualizar una colección

Puede actualizar una colección existente con una PUT solicitud al /stac/collections/{collection_id} punto de conexión.

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

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

Un 200 código de estado indica que la colección se actualizó correctamente.

Limpieza de recursos

Puede usar una DELETE solicitud para quitar la colección de GeoCatalog. Al eliminar una colección también se eliminan:

  1. Todos los elementos de STAC que son elementos secundarios de esa colección.
  2. Todos los recursos que son elementos secundarios de esos elementos.
  3. Todos los recursos de nivel de colección de esa colección.

En el inicio rápido, Agregar elementos de STAC a una colección, se usa esta colección, por lo que no se elimina aún si tiene previsto completar ese inicio rápido.

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

Un código de estado de 204 indica que se eliminó la colección.

Advertencia

Si elimina una colección, debe esperar al menos 45 segundos antes de intentar crear una nueva colección con un nombre o identificador idénticos. Si intenta crear una nueva colección con el mismo nombre que la colección eliminada, recibirá un error. Si se produce este error, intente volver a crear la colección después de una espera de 45 segundos.

Paso siguiente

Agregar elementos a una colección STAC

Contenido relacionado

  • Last updated on