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

快速入门：使用 Python 在 Microsoft 行星计算机 Pro GeoCatalog 中创建 STAC 集合

2025-05-20

本快速入门指南介绍如何使用 Python 创建时空资产目录（STAC）集合，并将其添加到 Microsoft 行星计算机的 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 集合概述中所述。可以根据用例和数据类型添加其他属性。

在本教程中，请阅读行星计算机 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，请确保将 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 指示具有该 ID 的集合已存在。请参阅更新集合，了解如何更新现有集合。

现在可以在 /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 浏览器中可视化时如何呈现集合中的 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 资源管理器上创建数据的单个视图。以下示例马赛克配置不应用任何额外的查询参数或筛选器。因此，当在 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 秒才能尝试创建具有相同名称/ID 的新集合。如果尝试使用与已删除集合相同的名称创建新集合，则会收到错误。如果发生此错误，请尝试在 45 秒等待后重新创建集合。

后续步骤

将项添加到 STAC 集合

通过