Démarrage rapide : Créer une collection STAC dans Microsoft Planetary Computer Pro GeoCatalog avec Python

Ce guide de démarrage rapide vous guide pour créer une collection SpatioTemporal Asset Catalog (STAC) et l’ajouter à un GeoCatalog Microsoft Planetary Computer Pro à l’aide de Python.

Conditions préalables

Pour effectuer ce démarrage rapide, les éléments suivants sont requis :

  • Un compte Azure avec un abonnement actif. Utilisez le lien Créer un compte gratuitement.
  • Votre environnement configuré pour accéder à Azure, par exemple avec az login.
  • Accès à un ordinateur planétaire Pro GeoCatalog. Si vous n’avez pas encore accès, vous pouvez créer un geoCatalog.
  • Environnement Python 3.10 (ou version ultérieure) avec requests et azure-identity installé.
python3 -m pip install requests azure-identity

Créer une collection STAC JSON

Pour créer une collection STAC, vous avez d’abord besoin d’un fichier json qui définit les propriétés de la collection. Certaines propriétés sont requises lors de la création de collections STAC, comme décrit dans la vue d’ensemble de la collection STAC. D’autres propriétés peuvent être ajoutées en fonction du cas d’usage et du type de données.

Pour ce tutoriel, lisez la collection STAC io-lulc-annual-v02 à partir de l’API STAC de Planetary Computer Pro. Si vous avez déjà cette collection STAC dans votre GeoCatalog, vous pouvez passer à la section suivante.

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 vous utilisez un ID différent pour votre collection, veillez à remplacer le id champ par la valeur correcte.

Pour visualiser les ressources de données de cette collection dans l’Explorateur, les métadonnées de la collection doivent inclure l’extension Élément Assets et avoir au moins une ressource d’élément dont le type de média peut être visualisées.

Obtenir un jeton d’accès

L’accès à un GeoCatalog nécessite un jeton pour authentifier les demandes. Utilisez la bibliothèque de client Azure-identity pour Python pour récupérer un jeton :

import azure.identity

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

Ces informations d’identification peuvent être fournies en tant que jeton du porteur dans l’en-tête Authorization dans les requêtes adressées à votre GeoCatalog.

Ajouter une collection à un GeoCatalog

Avec les métadonnées STAC, un jeton et l’URL de votre GeoCatalog, faites une demande à l’API STAC pour ajouter la collection.

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

Un code d’état indiquant 201 que votre collection a été créée. Un code d’état indiquant 409 qu’une collection avec cet ID existe déjà. Consultez Mettre à jour une collection pour savoir comment mettre à jour une collection existante.

Vous pouvez maintenant lire cette collection sur le point de terminaison /stac/collections/{collection_id}.

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

Vous pouvez également afficher votre GeoCatalog dans votre navigateur pour afficher la nouvelle collection.

Configurer un regroupement

Chaque collection d’un GeoCatalog inclut une configuration qui contrôle la façon dont les éléments STAC et leurs ressources de données sont stockés, indexés et visualisé. Pour configurer une collection :

  1. Définissez une configuration de rendu pour la collection. Cette configuration de rendu contrôle la façon dont les ressources d’élément STAC dans la collection sont affichées lors de la visualisation dans l’Explorateur GeoCatalog. Les paramètres spécifiques utilisés ici dépendent des ressources de votre collection.

    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. Définissez une mosaïque pour la collection. La configuration de mosaïque contrôle la façon dont les éléments sont interrogés, filtrés et combinés pour créer une vue unique des données sur l’Explorateur GeoCatalog. L’exemple de configuration de mosaïque suivant n’applique aucun paramètre ou filtre de requête supplémentaire. Par conséquent, lorsque cette configuration est sélectionnée dans l’Explorateur GeoCatalog, tous les éléments de la collection sont affichés, avec les éléments les plus récents affichés en premier.

    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)

    Le cql champ de la configuration de mosaïque peut être utilisé pour filtrer les éléments en fonction de leurs propriétés. Par exemple, si vos éléments STAC implémentent le filtre [eo extension][eo], vous pouvez définir un filtre « cloud faible » (moins de 10% cloudy) avec

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

  3. Définissez les paramètres de vignette pour la collection. Cela contrôle les éléments tels que le niveau de zoom minimal.

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

Mettre à jour une collection

Vous pouvez mettre à jour une collection existante avec une requête PUT au point de terminaison /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)

Un code d’état 200 indique que la collection a été correctement mise à jour.

Nettoyer les ressources

Vous pouvez utiliser une DELETE demande pour supprimer la collection de votre GeoCatalog. La suppression d’une collection supprime également :

  1. Tous les éléments STAC qui sont des enfants de cette collection.
  2. Toutes les ressources qui sont des enfants de ces éléments.
  3. Toutes les ressources au niveau de la collection de cette collection.

Le guide de démarrage rapide, Ajouter des éléments STAC à une collection, utilise cette collection afin de ne pas la supprimer si vous envisagez de suivre ce guide de démarrage rapide.

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)

Un code d’état indiquant 204 que votre collection a été supprimée.

Avertissement

Si vous supprimez une collection, vous devez attendre au moins 45 secondes avant de tenter de créer une collection avec un nom /ID identique. Si vous tentez de créer une collection à l’aide du même nom que la collection supprimée, vous recevez une erreur. Si cette erreur se produit, essayez de recréer la collection après une attente de 45 secondes.

Étape suivante

Ajouter des éléments à une collection STAC

Contenu connexe

  • Dernière mise à jour :