Guia de início rápido: criar uma coleção STAC no Microsoft Planetary Computer Pro GeoCatalog com Python

2025-05-20

Este guia de início rápido orienta você a criar uma coleção SpatioTemporal Asset Catalog (STAC) e adicioná-la a um Microsoft Planetary Computer Pro GeoCatalog usando Python.

Pré-requisitos

Para concluir este arranque rápido, necessita de:

Uma conta do Azure com uma assinatura ativa. Use o link Criar uma conta gratuitamente.
O seu ambiente configurado para aceder ao Azure, por exemplo, com az login.
Acesso a um GeoCatálogo do "Planetary Computer Pro". Se ainda não tiver acesso, pode criar um novo GeoCatalog.
Um ambiente Python com requests e azure-identity instalado.

python3 -m pip install requests azure-identity

Criar uma coleção STAC JSON

Para criar uma coleção STAC, primeiro você precisa de um arquivo json que defina as propriedades da coleção. Algumas propriedades são necessárias ao criar coleções STAC, conforme descrito na Visão geral da coleção STAC. Outras propriedades podem ser adicionadas dependendo do seu caso de uso e tipo de dados.

Para este tutorial, leia a coleção STAC io-lulc-annual-v02 da API STAC do Planetary Computer Pro. Se você já está usando a coleção STAC em seu GeoCatalog, você pode pular para a próxima seção.

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 estiver a utilizar um ID diferente para a sua coleção, certifique-se de que substitui o id campo pelo valor correto.

Para visualizar os ativos de dados dentro dessa coleção no Explorer, os metadados da coleção devem incluir a extensão Item Assets e ter pelo menos um ativo de item cujo tipo de mídia possa ser visualizado.

Obter um token de acesso

O acesso a um GeoCatalog requer um token para autenticar solicitações. Utilize a biblioteca cliente Azure-identity para Python e recupere um 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 pode ser fornecida como um token de portador no Authorization cabeçalho em solicitações feitas ao seu GeoCatalog.

Adicionar uma coleção a um GeoCatalog

Com os metadados STAC, um token e a URL para seu GeoCatalog, faça uma solicitação à API STAC para adicionar a Coleção.

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

Um código de status indica 201 que sua coleção foi criada. Um código de status indica 409 que uma coleção com esse ID já existe. Consulte Atualizar uma coleção para saber como atualizar uma coleção existente.

Agora pode ler esta coleção no 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()

Você também pode visualizar seu GeoCatalog em seu navegador para ver a nova coleção.

Configurar uma coleção

Cada coleção em um GeoCatalog inclui alguma configuração que controla como os itens STAC e seus ativos de dados são armazenados, indexados e visualizados. Para configurar uma coleção:

Defina uma configuração de renderização para a coleção. Essa configuração de renderização controla como os ativos de item STAC dentro da coleção são renderizados quando visualizados no GeoCatalog Explorer. Os parâmetros específicos usados aqui dependem dos ativos em sua coleção.

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)

Defina um mosaico para a coleção. A configuração de mosaico controla como os itens são consultados, filtrados e combinados para criar uma única exibição dos dados no GeoCatalog Explorer. O exemplo de configuração de mosaico a seguir não aplica nenhum parâmetro ou filtro de consulta extra. Como resultado, quando essa configuração é selecionada dentro do GeoCatalog Explorer, todos os itens dentro da coleção são mostrados, com os itens mais recentes exibidos primeiro.
```
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)
```
O cql campo da configuração de mosaico pode ser usado para filtrar os itens com base em suas propriedades. Por exemplo, se seus itens STAC implementarem o [eo extension][eo], você poderá definir um filtro de "nuvem baixa" (menos de 10% nublado) com
```
"cql": [{"op": "<=", "args": [{"property": "eo:cloud_cover"}, 10]}]
```

Defina as configurações de bloco para a coleção. Isso controla coisas como o nível mínimo de zoom.

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

Atualizar uma coleção

Você pode atualizar uma coleção existente com uma PUT solicitação para o /stac/collections/{collection_id} ponto de extremidade.

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)

Um 200 código de status indica que a coleção foi atualizada com êxito.

Limpeza de recursos

Você pode usar uma DELETE solicitação para remover a coleção do seu GeoCatalog. A exclusão de uma coleção também exclui:

Todos os itens STAC que são filhos dessa coleção.
Todos os bens que são filhos desses itens.
Todos os ativos de nível de coleção dessa coleção.

O guia de início rápido, Adicionar itens STAC a uma coleção, usa essa coleção, portanto, não a exclua ainda se você planeja concluir esse início 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)

Um código de estado indica 204 que a sua Coleção foi eliminada.

Advertência

Se você excluir uma coleção, deverá aguardar pelo menos 45 segundos antes de tentar criar uma nova coleção com um nome/ID idêntico. Se você tentar criar uma nova coleção usando o mesmo nome da coleção excluída, receberá um erro. Se esse erro ocorrer, tente recriar a coleção após uma espera de 45 segundos.

Próximo passo

Adicionar itens a uma coleção STAC

Partilhar via