Avvio rapido: Inserire un singolo elemento STAC in una raccolta in un GeoCatalog di Computer Planetario Pro di Microsoft

2025-06-25

In questa guida introduttiva si inseriscono elementi SpatioTemporal Asset Catalog (STAC) in una raccolta in Microsoft Planetary Computer Pro GeoCatalog usando l'API di inserimento di singoli elementi. Gli elementi STAC sono il blocco fondamentale di STAC che contiene proprietà per le query e collegamenti agli asset di dati.

Prerequisiti

Prima di iniziare questa guida introduttiva, è necessario completare la guida introduttiva per creare una raccolta STAC con Microsoft Planetary Computer Pro GeoCatalog o avere un GeoCatalog con una raccolta STAC per gli elementi che si intende inserire.

Ignorare il frammento di codice seguente se è stata creata la raccolta STAC all'interno del terminale/script corrente. In caso contrario, è necessario impostare il geocatalog_url e collection_id usando il codice Python seguente:

# Put the URL to your Microsoft Planetary Computer Pro GeoCatalog Explorer (not including '/api') here.
# Make sure there's no trailing '/'
geocatalog_url = "<your-geocatalog-url>"
# collection_id is "spatio-quickstart" if you're following the collection quickstart
collection_id = "<your-collection-id>"

Creare metadati dell'elemento

I metadati degli elementi STAC sono univoci per gli asset che si stanno catalogando. Contiene tutte le informazioni necessarie per catalogare i dati, insieme ai puntatori alla posizione in cui sono archiviati i dati.

Suggerimento

Non sono disponibili elementi STAC per i dati? Per accelerare la creazione di elementi STAC, abbiamo un'esercitazione dettagliata e abbiamo anche uno strumento open source denominato STAC Forge.

Per questo avvio rapido, si usano asset ed elementi STAC della raccolta 10 m Annual Land Use Land Cover di Computer Planetario.

import requests

response = requests.get(
    "https://planetarycomputer.microsoft.com/api/stac/v1/search",
    params={"collections": "io-lulc-annual-v02", "ids": "23M-2023,23L-2023,24M-2023,24L-2023"},
)

item_collection = response.json()

Utilizzare l'API SAS open del Planetary Computer per ottenere token SAS di breve durata per gli asset.

sas_token = requests.get(
    "https://planetarycomputer.microsoft.com/api/sas/v1/token/io-lulc-annual-v02"
).json()["token"]

for item in item_collection["features"]:
    for asset in item["assets"].values():
        asset["href"] = "?".join([asset["href"], sas_token])

Questo SAS Token è necessario per consentire al GeoCatalog di copiare i dati dall'open Planetary Computer. Per altre informazioni su come Planetary Computer Pro accede ai dati, vedere Origini di inserimento .

STAC richiede che la collection proprietà degli elementi STAC corrisponda alla raccolta in cui si trovano. Se necessario, aggiornare gli elementi in modo che corrispondano all'ID raccolta in uso.

for item in item_collection["features"]:
    item["collection"] = collection_id

Ottenere un token di accesso

Planetary Computer Pro richiede un token di accesso per autenticare le richieste tramite Microsoft Entra. Usare la libreria client Azure-Identity per Python per ottenere un token.

import azure.identity

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

Aggiungere elementi a una raccolta

Gli elementi possono essere aggiunti a una raccolta pubblicando un oggetto Item o ItemCollection all'endpoint /stac/collections/{collection_id}/items.

response = requests.post(
    f"{geocatalog_url}/stac/collections/{collection_id}/items?api-version=2025-04-30-preview",
    headers=headers,
    json=item_collection
)
print(response.status_code)

Un 202 codice di stato indica che gli elementi sono stati accettati per l'inserimento. Controllare il codice JSON della risposta se si ottiene un codice di stato 40x, ad esempio print(response.json()).

Planetary Computer Pro inserisce in modo asincrono gli elementi nel GeoCatalog. L'intestazione location include un URL che puoi interrogare regolarmente per monitorare lo stato del processo di ingestione.

import time
import datetime

location = response.headers["location"]

while True:
    response = requests.get(location, headers={"Authorization": f"Bearer {token.token}"})
    status = response.json()["status"]
    print(datetime.datetime.now().isoformat(), status)
    if status not in {"Pending", "Running"}:
        break
    time.sleep(5)

Once the items are ingested, use the `/stac/collections/{collection_id}/items` or `/stac/search` endpoints to get a paginated list of items, including your newly ingested items. If the ingestion fails or you encounter errors, consult the [troubleshooting guide](./troubleshooting-ingestion.md) and the [list of error codes](./error-codes-ingestion.md).

```python
items_response = requests.get(
    f"{geocatalog_url}/stac/collections/{collection_id}/items",
    headers={"Authorization": f"Bearer {token.token}"},
    params={"api-version": "2025-04-30-preview"},
)
items_ingested = items_response.json()
print(f"Found {len(items_ingested['features'])} items")

In alternativa, eseguire una ricerca:

search_response = requests.get(
    f"{geocatalog_url}/stac/search",
    headers={"Authorization": f"Bearer {token.token}"},
    params={"api-version": "2025-04-30-preview", "collection": collection_id},
)
#print(search_response.json())

È possibile visualizzare gli elementi visitando Esplora dati dopo aver configurato la raccolta STAC per la visualizzazione.

Eliminare elementi da una raccolta

Gli elementi possono essere eliminati da una raccolta con una richiesta DELETE all'endpoint dei dettagli dell'elemento.

item_id = item_collection["features"][0]["id"]
delete = requests.delete(
    f"{geocatalog_url}/stac/collections/{collection_id}/items/{item_id}",
    headers=headers,
    params={"api-version": "2025-04-30-preview"},
)
print(delete.status_code)

Pulire le risorse

Vedere Creare una raccolta STAC con Microsoft Planetary Computer Pro GeoCatalog per la procedura per eliminare un'intera raccolta e tutti gli elementi e gli asset sottostanti.

Passaggi successivi

Dopo aver aggiunto alcuni elementi, è necessario configurare i dati per la visualizzazione.

Configurazione della raccolta in Microsoft Planetary Computer Pro

Condividi tramite