你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：将一个单个 STAC 项目导入到 Microsoft 地行星计算机 Pro GeoCatalog 的集合中。

2025-05-20

在本快速入门中，使用单个项引入 API 将时空资产目录 (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 m 年度土地利用土地覆盖”集合中的 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()

使用开放的 Planetary Computer 的 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 Planetary Computer Pro GeoCatalog 创建 STAC 集合。

后续步骤

添加一些项后，应配置用于可视化的数据。

Microsoft行星计算机专业版中的集合配置

通过