在本快速入門指南中，您會使用單一項目匯入 API，將 SpatioTemporal Asset Catalog (STAC) 項目匯入至 Microsoft Planetary Computer Pro GeoCatalog 中的集合。 STAC 項目是 STAC 的基本構造單元，其中包含用於查詢的屬性和資料資產的連結。
先決條件
在開始本快速入門教程之前，您應先完成 使用 Microsoft Planetary Computer Pro GeoCatalog 建立 STAC 集合的快速入門教程，或者應擁有一個包含您打算提交的 STAC 集合的 GeoCatalog。
如果您在目前的終端機/腳本內建立 STAC 集合，請略過下列代碼段，否則您必須使用下列 Python 程式代碼來設定geocatalog_url和collection_id：
# Put the URL to your Microsoft Planetary Computer Pro GeoCatalog Explorer (not including '/api') here.
# Make sure there's no trailing '/'
geocatalog_url = "<your-geocatalog-url>"
# collection_id is "spatio-quickstart" if you're following the collection quickstart
collection_id = "<your-collection-id>"
建立項目元數據
STAC 項目元數據是您編目時資產的獨特元數據。 其中包含編錄數據所需的所有資訊，以及數據儲存位置的指標。
小提示
您的資料沒有 STAC 項目？ 為了加速建立 STAC 專案，我們有 詳細的教學課程 ，也有名為 STAC Forge 的開放原始碼工具。
在本快速入門中，您會使用開放的 Planetary Computer 10 公尺年度土地使用土地覆蓋 集合中的 STAC 項目和資產。
import requests
response = requests.get(
"https://planetarycomputer.microsoft.com/api/stac/v1/search",
params={"collections": "io-lulc-annual-v02", "ids": "23M-2023,23L-2023,24M-2023,24L-2023"},
)
item_collection = response.json()
使用開放的行星電腦 SAS API 來取得資產的短暫 SAS 令牌。
sas_token = requests.get(
"https://planetarycomputer.microsoft.com/api/sas/v1/token/io-lulc-annual-v02"
).json()["token"]
for item in item_collection["features"]:
for asset in item["assets"].values():
asset["href"] = "?".join([asset["href"], sas_token])
需要此 SAS 令牌，才能讓您的 GeoCatalog 從開啟的行星電腦複製數據。 如需行星計算機專業人員如何存取數據的詳細資訊，請參閱 擷取來源 。
STAC 要求 STAC 項目的 collection 屬性必須符合其所在的集合。 如有必要，請更新項目以符合您使用的集合 ID。
for item in item_collection["features"]:
item["collection"] = collection_id
取得存取令牌
行星計算機專業人員需要存取令牌，才能透過 Microsoft Entra 來驗證要求。 使用適用於 Python 的 Azure 身分識別 用戶端連結庫來取得令牌。
import azure.identity
credential = azure.identity.AzureCliCredential()
token = credential.get_token("https://geocatalog.spatio.azure.com")
headers = {
"Authorization": f"Bearer {token.token}"
}
將專案新增至集合
專案可以藉由將 Item 或 ItemCollection 物件張貼至 /stac/collections/{collection_id}/items 端點，新增至集合。
response = requests.post(
f"{geocatalog_url}/stac/collections/{collection_id}/items?api-version=2025-04-30-preview",
headers=headers,
json=item_collection
)
print(response.status_code)
202狀態代碼表示已接受您的項目進行處理。 如果您收到 40x 狀態代碼，例如 print(response.json())，請檢查回應 JSON。
Planetary Computer Pro 會以異步方式將項目載入您的 GeoCatalog 中。 標頭 location 包含一個 URL，您可以查詢以監控匯入工作流程的狀態。
import time
import datetime
location = response.headers["location"]
while True:
response = requests.get(location, headers={"Authorization": f"Bearer {token.token}"})
status = response.json()["status"]
print(datetime.datetime.now().isoformat(), status)
if status not in {"Pending", "Running"}:
break
time.sleep(5)
匯入項目之後，請使用 /stac/collections/{collection_id}/items 或 /stac/search 端點來取得項目的分頁清單，包括您剛匯入的項目。
items_response = requests.get(
f"{geocatalog_url}/stac/collections/{collection_id}/items",
headers={"Authorization": f"Bearer {token.token}"},
params={"api-version": "2025-04-30-preview"},
)
items_ingested = items_response.json()
print(f"Found {len(items_ingested['features'])} items")
或搜尋：
search_response = requests.get(
f"{geocatalog_url}/stac/search",
headers={"Authorization": f"Bearer {token.token}"},
params={"api-version": "2025-04-30-preview", "collection": collection_id},
)
#print(search_response.json())
您可以進入 數據瀏覽器 檢視項目，一旦 STAC 集合 配置為可視化。
從集合中刪除專案
項目可以透過 DELETE 請求從集合中刪除，請求發送至項目詳細資訊端點。
item_id = item_collection["features"][0]["id"]
delete = requests.delete(
f"{geocatalog_url}/stac/collections/{collection_id}/items/{item_id}",
headers=headers,
params={"api-version": "2025-04-30-preview"},
)
print(delete.status_code)
清理資源
如需刪除整個集合及其下的所有專案和資產的步驟，請參閱 使用 Microsoft行星計算機專業 GeoCatalog 建立 STAC 集合 。
後續步驟
現在您已新增一些項目，您應該設定用於視覺化的數據。