快速入門：使用 Python 在 Microsoft Planetary Computer Pro GeoCatalog 中建立 STAC 集合

本快速入門會引導您建立 SpatioTemporal 資產目錄 (STAC) 集合，並使用 Python 將其新增至 Microsoft Planetary Computer Pro GeoCatalog。

先決條件

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

具有有效訂閱的 Azure 帳戶。使用免費建立帳戶的連結。
您的環境已設定為存取 Azure，例如透過 az login。
Planetary Computer Pro GeoCatalog 的存取權。如果您還沒有存取權，可以建立新的 GeoCatalog。
已安裝包含 requests 和 azure-identity 的 Python 環境。

python3 -m pip install requests azure-identity

建立 STAC 集合 JSON

若要建立 STAC 集合，您必須先有定義集合屬性的 json 檔案。建立 STAC 集合時需要某些屬性，詳述於 STAC 集合概觀中。您可以依據自己的使用案例和資料類型，新增其他屬性。

在本教學課程中，請讀取 Planetary Computer Pro 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 欄位取代為正確的值。

若要在 Explorer 中將此集合中的資料資產視覺化，集合的中繼資料應包含 Item Assets (英文) 延伸模組，且至少有一個項目資產的媒體類型可視覺化。

取得存取令牌

存取 GeoCatalog 需要權杖來驗證要求。使用適用於 Python 的 Azure-identity (英文) 用戶端程式庫來擷取權杖：

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 延伸模組][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 集合

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-10