Guida introduttiva: Creare una raccolta STAC nella Microsoft Planetary Computer Pro GeoCatalog con Python

2025-05-20

Questa guida introduttiva illustra come creare una raccolta SpatioTemporal Asset Catalog (STAC) e aggiungerla a un GeoCatalog di Microsoft Planetary Computer Pro usando Python.

Prerequisiti

Per completare questo avvio rapido, avrai bisogno di:

Un account Azure con una sottoscrizione attiva. Usare il collegamento Crea un account gratuitamente.
L'ambiente configurato per accedere ad Azure, ad esempio con az login.
Accesso a un GeoCatalogo di un Computer Planetario. Se non si ha già accesso, è possibile creare un nuovo GeoCatalog.
Ambiente Python con requests e azure-identity installato.

python3 -m pip install requests azure-identity

Creare un codice JSON della raccolta STAC

Per creare una raccolta STAC è necessario innanzitutto un file JSON che definisce le proprietà della raccolta. Alcune proprietà sono necessarie per la creazione di raccolte STAC, come descritto nella panoramica della raccolta STAC. È possibile aggiungere altre proprietà a seconda del caso d'uso e del tipo di dati.

Per questo tutorial, leggere la raccolta STAC io-lulc-annual-v02 dall'API STAC di Planetary Computer Pro. Se hai già questa come raccolta STAC nel tuo GeoCatalog, puoi passare alla sezione successiva.

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

Se si usa un ID diverso per la raccolta, assicurarsi di sostituire il id campo con il valore corretto.

Per visualizzare gli asset di dati all'interno di questa raccolta in Esplora, i metadati della raccolta devono includere l'estensione Item Assets e avere almeno un asset elemento il cui tipo di supporto può essere visualizzato.

Ottenere un token di accesso

Per l'accesso a geoCatalog è necessario un token per autenticare le richieste. Usare la libreria client Azure-Identity per Python per recuperare un token:

import azure.identity

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

Questa credenziale può essere fornita come Bearer token nell'intestazione Authorization nelle richieste effettuate al GeoCatalog.

Aggiungere una raccolta a un GeoCatalog

Con i metadati STAC, un token e l'URL di GeoCatalog, effettuare una richiesta all'API STAC per aggiungere la raccolta.

# 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 codice di stato di 201 indica che la raccolta è stata creata. Un codice di stato indica 409 che esiste già una raccolta con tale ID. Vedere Aggiornare una raccolta per informazioni su come aggiornare una raccolta esistente.

Ora puoi leggere questa raccolta presso l'endpoint /stac/collections/{collection_id}.

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

È anche possibile visualizzare geoCatalog nel browser per visualizzare la nuova raccolta.

Configurare una raccolta

Ogni raccolta in un GeoCatalog include alcune configurazioni che controllano il modo in cui gli elementi STAC e i relativi asset di dati vengono archiviati, indicizzati e visualizzati. Per configurare una raccolta:

Definire una configurazione di rendering per la raccolta. Questa configurazione di rendering controlla il modo in cui gli asset degli elementi STAC all'interno della raccolta sono visualizzati in GeoCatalog Explorer. I parametri specifici usati qui dipendono dagli asset nella raccolta.

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)

Definire un mosaico per la raccolta. La configurazione del mosaico controlla il modo in cui gli elementi vengono sottoposti a query, filtrati e combinati per creare una singola visualizzazione dei dati in GeoCatalog Explorer. La configurazione di mosaico di esempio seguente non applica parametri di query o filtri aggiuntivi. Di conseguenza, quando questa configurazione viene selezionata all'interno di GeoCatalog Explorer, vengono visualizzati tutti gli elementi all'interno della raccolta, con gli elementi più recenti visualizzati per primi.
```
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)
```
Il cql campo della configurazione del mosaico può essere utilizzato per filtrare gli elementi in base alle relative proprietà. Ad esempio, se gli elementi STAC implementano l'eo [estensione][eo], è possibile definire un filtro "bassa nuvola" (meno di 10% nuvoloso) con
```
"cql": [{"op": "<=", "args": [{"property": "eo:cloud_cover"}, 10]}]
```

Definire le impostazioni dei riquadri per la raccolta. Questo controlla elementi come il livello minimo di ingrandimento.

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

Aggiornare una raccolta

È possibile aggiornare una raccolta esistente con una PUT richiesta all'endpoint /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": "2025-04-30-preview"},
)
print(response.status_code)

Un 200 codice di stato indica che la raccolta è stata aggiornata correttamente.

Pulire le risorse

È possibile usare una DELETE richiesta per rimuovere la raccolta da GeoCatalog. L'eliminazione di una raccolta comporta anche l'eliminazione di:

Tutti gli elementi STAC figlio di tale raccolta.
Tutti gli asset figlio di tali elementi.
Tutti gli asset a livello di quella raccolta.

L'avvio rapido Add STAC Items to a collection (Aggiungi elementi STAC a una raccolta) utilizza questa raccolta, quindi non eliminarla ancora se hai intenzione di completare l'avvio rapido.

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 codice di stato indica 204 che la raccolta è stata eliminata.

Avvertimento

Se si elimina una raccolta, è necessario attendere almeno 45 secondi prima di tentare di creare una nuova raccolta con un nome/ID identico. Se si tenta di creare una nuova raccolta usando lo stesso nome della raccolta eliminata, viene visualizzato un errore. Se si verifica questo errore, provare a ricreare la raccolta dopo un'attesa di 45 secondi.

Passo successivo

Aggiungere elementi a una raccolta STAC

Condividi tramite