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 STAC (SpatioTemporal Asset Catalog) e adicioná-la a um GeoCatalog do Microsoft Planetry Computer Pro usando Python.

Pré-requisitos

Para concluir este guia de início rápido, você precisa:

Uma conta do Azure com uma assinatura ativa. Use o link Criar uma conta gratuitamente.
Seu ambiente está configurado para acessar o Azure, por exemplo, com az login.
Acesso a um GeoCatalog do Computador Planetário Pro. Se você ainda não tiver acesso, poderá criar um novo GeoCatalog.
Um ambiente Python com requests e azure-identity instalado.

python3 -m pip install requests azure-identity

Criar um JSON da coleção STAC

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 do tipo de dados.

Para este tutorial, leia a coleção STAC io-lulc-annual-v02 da API STAC do Computador Planetário Pro. Se você já tiver isso como coleção STAC em seu GeoCatalog, poderá 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 você estiver usando uma ID diferente para sua coleção, substitua o id campo pelo valor correto.

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

Obter um token de acesso

Acessar um GeoCatalog requer um token para autenticar solicitações. Use a biblioteca de clientes de identidade do Azure para Python para recuperar um token:

import azure.identity

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

Essa credencial pode ser fornecida como um token de portador no cabeçalho Authorization em solicitações feitas ao 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 de 201 indica que sua Coleção foi criada. Um código de 409 status indica que já existe uma coleção com essa ID. Consulte Atualizar uma coleção para saber como atualizar uma coleção existente.

Agora você pode ler essa coleção no ponto de extremidade /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 exibir o GeoCatalog no navegador para ver a nova coleção.

Configurar uma coleção

Cada coleção em um GeoCatalog inclui algumas configurações que controlam 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 Explorador do GeoCatalog. 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 Explorador geocatalog. A configuração de mosaico de exemplo a seguir não aplica parâmetros ou filtros de consulta adicionais. Como resultado, quando essa configuração é selecionada no Explorador geocatalog, 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 a [eo extensão][eo], você poderá definir um filtro de "nuvem baixa" (menos de 10% nublado) com
```
"cql": [{"op": "<=", "args": [{"property": "eo:cloud_cover"}, 10]}]
```

Definir configurações de bloco para a coleção. Isso controla as 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} endpoint.

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.

Limpar os recursos

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

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

O início rápido, Adicionar Itens STAC a uma coleção, usa essa coleção, então 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 status indica 204 que sua Coleção foi excluída.

Aviso

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óxima etapa

Adicionar itens a uma coleção STAC

Compartilhar via