快速入門：使用 Python 在Microsoft行星計算機 Pro GeoCatalog 中建立 STAC 集合

2025-06-23

本快速入門會引導您建立 SpatioTemporal 資產目錄（STAC）集合，並使用 Python 將它新增至Microsoft行星電腦專業 GeoCatalog。

先決條件

若要完成本快速入門，您需要：

具有有效訂閱的 Azure 帳戶。使用免費建立帳戶的連結。
您的環境已設定為存取 Azure ，例如使用 az login。
存取行星電腦專業 GeoCatalog。如果您還沒有存取權，您可以建立新的 GeoCatalog。
已安裝和 requests 的 azure-identity Python 環境。

python3 -m pip install requests azure-identity

建立 STAC 集合 JSON

若要建立 STAC 集合，您必須先有定義集合屬性的 json 檔案。建立 STAC 集合時需要某些屬性，如 STAC 集合概觀中所述。視您的使用案例和數據類型而定，可以新增其他屬性。

在本教學課程中，請閱讀行星計算機專業版 STAC API 中的 io-lulc-annual-v02 STAC集合。如果您已經在 GeoCatalog 中將此項目當成 STAC 集合，您可以跳到下一節。

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

如果您使用集合的不同標識符，請務必將 id 欄位取代為正確的值。

若要在檔案總管中可視化此集合中的數據資產，集合元數據應包含專案資產延伸模組，且至少有一個專案資產可以可視化其媒體類型。

取得存取令牌

存取 GeoCatalog 需要令牌來驗證要求。使用適用於 Python 的 Azure 身分識別用戶端連結庫來擷取令牌：

import azure.identity

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

您可以在對 GeoCatalog 提出的要求中 Authorization ，以持有人令牌的形式提供此認證。

將集合新增至 GeoCatalog

使用 STAC 元數據、令牌和 GeoCatalog 的 URL，向 STAC API 提出要求以新增集合。

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

的狀態代碼 201 表示已建立您的集合。的狀態代碼 409 表示具有該標識碼的集合已經存在。如需如何更新現有集合，請參閱更新集合。

您現在可以在 /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()

您也可以在瀏覽器中檢視您的 GeoCatalog，以查看新的集合。

設定集合

GeoCatalog 中的每個集合都包含一些設定，可控制 STAC 專案及其數據資產的儲存方式、編製索引及可視化。若要設定集合：

定義集合的轉譯組態。此轉譯組態可控制在 GeoCatalog Explorer 中可視化時，如何轉譯集合內的 STAC 項目資產。這裡所使用的特定參數取決於您集合中的資產。

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)

定義集合的馬賽克。馬賽克設定會控制如何查詢、篩選和合併專案，以在 GeoCatalog Explorer 上建立數據的單一檢視。下列範例馬賽克組態不會套用任何額外的查詢參數或篩選。因此，在 GeoCatalog Explorer 內選取此組態時，會顯示集合中的所有專案，並先顯示最新的專案。
```
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)
```
cql馬賽克組態的欄位可用來根據其屬性來篩選專案。例如，如果您的 STAC 項目實作 [eo extension][eo]，您可以使用定義「低雲端」（小於 10% 多雲）篩選
```
"cql": [{"op": "<=", "args": [{"property": "eo:cloud_cover"}, 10]}]
```

定義集合的磚設定。這會控制縮放層級下限等專案。

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

更新集合

您可以使用對端點的要求PUT來更新現有的集合/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)

200狀態代碼表示已成功更新集合。

清理資源

您可以使用 DELETE 要求從 GeoCatalog 移除集合。刪除集合也會刪除：

屬於該集合子系的所有 STAC 專案。
所有屬於這些專案子系的資產。
該集合的所有集合層級資產。

將 STAC 專案新增至集合的快速入門會使用此集合，因此如果您打算完成該快速入門，則尚未將其刪除。

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)

的狀態代碼 204 表示您的集合已刪除。

警告

如果您刪除集合，您至少必須等候 45 秒，才能嘗試建立具有相同名稱/標識元的新集合。如果您嘗試使用與已刪除集合相同的名稱來建立新的集合，您會收到錯誤。如果發生此錯誤，請嘗試在 45 秒等候之後重新建立集合。

後續步驟

將專案新增至 STAC 集合

共用方式為