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

Azure Planetary Computer Pro client library for JavaScript - version 1.0.0

Microsoft Planetary Computer Pro 是一款基于 Azure 超大规模基础设施构建的地理空间数据管理服务。 GeoCatalog 是一个 Azure 资源，提供基于时空资产目录（STAC）开放规范的地理空间数据集的基础功能，用于导入、管理、搜索和分发地理空间数据集。

关键功能

STAC集合管理：创建、读取、更新和删除STAC集合和项目，以组织您的地理空间数据集
集合配置：配置渲染选项、马赛克、瓦片设置和可查询工具，以优化查询性能和可视化
数据可视化：生成地图瓦片（XYZ、TileJSON、WMTS）、预览图像、通过GeoJSON或边界框裁剪、提取点值并计算统计数据
马赛克操作：注册基于STAC搜索的马赛克，用于按像素查询和检索数据，从多个项目生成瓦片，并访问TileJSON和WMTS功能
地图图例：检索类地图图例（类别）和区间图例（连续），以JSON或PNG图像形式，带有预定义的色彩映射
数据摄取：建立摄取源（管理身份或 SAS 令牌），定义从 STAC 目录中的采集，并创建和监控摄取运行
STAC API 操作：对项目进行完整的 CRUD 操作，使用空间/时间过滤器和排序搜索，检索可查询属性，检查 API 一致性
安全访问：生成可配置时长的SAS令牌用于收藏，签署资产HREF以实现安全下载，并撤销令牌——所有这些都通过Microsoft Entra ID进行保护

关键链接：

入门

当前支持的环境

Node.js的 LTS 版本
最新版本的 Safari、Chrome、Edge 和 Firefox。

有关更多详细信息，请参阅我们的支持策略。

先决条件

一个 Azure 订阅
一个Microsoft Planetary Computer Pro地理目录资源。你可以通过 Azure 门户、Azure PowerShell 或 Azure CLI 创建资源。

GeoCatalog 端点（catalogUri）可以在 Azure 门户资源的概览页面找到。

安装 `@azure/planetarycomputer` 包

安装 Azure Planetary Computer Pro JavaScript 客户端库，使用：npm

npm install @azure/planetarycomputer

创建和验证 `PlanetaryComputerProClient`

通过Microsoft Planetary Computer Pro服务认证有多种方式，推荐方式是通过Azure身份库使用Microsoft Entra ID进行安全无密钥认证。开始之前：

安装 Azure Identity 套件：

npm install @azure/identity

注册一个新的 Microsoft Entra ID 应用，并通过为您的服务负责人分配合适的角色，授予 Microsoft Planetary Computer Pro 访问权限。
将Microsoft Entra ID 应用程序的客户端 ID、租户 ID 和客户端机密的值设置为环境变量： AZURE_CLIENT_ID、 AZURE_TENANT_ID、 AZURE_CLIENT_SECRET。
使用 DefaultAzureCredential 创建客户端：

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>"; // e.g., "https://your-geocatalog.geocatalogs.azure.com"
const client = new PlanetaryComputerProClient(catalogUri, credential);

重要概念

行星计算机ProClient

PlanetaryComputerProClient是开发者使用 Microsoft Planetary Computer Pro 客户端库的主要接口。客户端提供多个操作组的访问权限：

STAC运营（`client.stac`）

收藏管理：创建、更新、列出和删除STAC收藏以组织您的地理空间数据集
项目管理：创建、读取、更新和删除集合中的单个 STAC 项目
搜索API：使用空间和时间过滤器、排序及可查询属性搜索项目
配置：管理渲染选项、马赛克、瓦片设置、可查询和分区类型
API 一致性：检索 STAC API 一致性类和着陆页信息

数据操作（`client.data`）

图块生成：从收藏、物品和马赛克生成地图瓦片（XYZ、TileJSON、WMTS）
数据可视化：创建预览图像，通过GeoJSON或边界框裁剪，提取点值，计算统计数据
马赛克操作：注册基于STAC搜索的马赛克并检索马赛克瓦片、TileJSON和WMTS功能
地图图例：检索类地图和区间图例，格式为 JSON 或 PNG 图片
资产元数据：检索集合和项目的瓦片矩阵集和资产元数据

摄取操作（`client.ingestion`）

摄取源：使用管理身份或SAS令牌认证设置摄取源
摄取定义：定义来自公共和私有数据源的自动STAC目录摄取
数据导入运行：创建并监控数据获取运行，并跟踪详细的操作

共享访问签名操作（`client.sharedAccessSignature`）

令牌生成：生成可配置时长的SAS令牌用于集合
资产签名：签署资产HREFs以安全下载托管存储资产
令牌撤销：必要时撤销令牌以控制访问

地理目录

GeoCatalog 是 Azure 的顶级资源，用于存储和组织您的地理空间数据。它提供：

区域冗余的管理存储，用于栅格和数据立方体格式
支持的数据类型内置云优化
为所有存储数据提供托管的 STAC API
通过 Microsoft Entra ID 与 Azure 的安全与身份管理集成

STAC（时空资产目录）

STAC是一个用于组织和描述地理空间数据的开放规范。 Microsoft Planetary Computer Pro 使用 STAC 提供：

集合：相关地理空间数据集的逻辑分组
项目：带有元数据的单个资产（如卫星图像、栅格）
资产：STAC项目引用的实际数据文件

例子

本节提供涵盖常见GeoCatalog工作流程的代码片段。完整的工作示例，请参见 sample 目录。

列表 STAC收藏
搜索STAC项目
获取STAC项目详情
创建 STAC 集合
登记与抹漆马赛克瓷砖
提取点数
生成地图瓦片
建立摄取源
数据摄取管理
获取SAS令牌

列表 STAC收藏

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const collections = await client.stac.getCollections();
console.log(`Found ${collections.collections.length} collections`);
for (const collection of collections.collections) {
  console.log(`- ${collection.id}: ${collection.description}`);
}

搜索STAC项目

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const searchResult = await client.stac.search({
  collections: ["naip"],
  datetime: "2021-01-01T00:00:00Z/2022-12-31T23:59:59Z",
  limit: 10,
});
console.log(`Found ${searchResult.features.length} items`);
for (const item of searchResult.features) {
  console.log(`Item ID: ${item.id}, Collection: ${item.collection}`);
}

获取STAC项目详情

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const item = await client.stac.getItem("naip", "ga_m_3308421_se_16_060_20211114");
console.log(`Item ID: ${item.id}`);
console.log(`Assets: ${Object.keys(item.assets)}`);

创建STAC收藏

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const poller = await client.stac.createCollection({
  id: "my-collection",
  type: "Collection",
  stacVersion: "1.0.0",
  description: "A collection of geospatial data",
  license: "proprietary",
  extent: {
    spatial: { boundingBox: [[-180, -90, 180, 90]] },
    temporal: { interval: [[null, null]] },
  },
  links: [],
});
await poller.pollUntilDone();
console.log("Collection created");

登记与抹漆马赛克瓷砖

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const registration = await client.data.registerMosaicsSearch({
  collections: ["naip"],
  filterLang: "cql2-json" as const,
  filter: { op: "=", args: [{ property: "naip:year" }, "2021"] },
});
console.log(`Search ID: ${registration.searchId}`);
const tileJson = await client.data.getSearchTileJson(registration.searchId, {
  assets: ["image"],
});
console.log(`Tile URLs: ${tileJson.tiles}`);

提取点数

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const pointData = await client.data.getItemPoint(
  "naip",
  "ga_m_3308421_se_16_060_20211114",
  -84.41,
  33.65,
  { assets: ["image"] },
);
console.log(`Coordinates: ${pointData.coordinates}`);
console.log(`Values: ${pointData.values}`);

生成地图瓦片

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const tileResponse = await client.data.getTile(
  "naip",
  "ga_m_3308421_se_16_060_20211114",
  "WebMercatorQuad",
  14,
  4322,
  6463,
  { assets: ["image"] },
);
console.log(`Tile size: ${tileResponse.length} bytes`);

建立摄取源

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const source = await client.ingestion.createSource({
  id: "my-storage-source",
  kind: "BlobManagedIdentity",
  connectionInfo: {
    containerUri: "https://mystorage.blob.core.windows.net/geospatial-data",
    objectId: "00000000-0000-0000-0000-000000000000",
  },
});
console.log(`Created source: ${source.id}`);

数据摄取管理

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const ingestion = await client.ingestion.create("my-collection", {
  importType: "StaticCatalog",
  displayName: "My data ingestion",
  sourceCatalogUrl: "https://example.com/catalog.json",
  keepOriginalAssets: true,
  skipExistingItems: true,
});
console.log(`Created ingestion: ${ingestion.id}`);

获取SAS令牌

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
const token = await client.sharedAccessSignature.getToken("naip");
console.log(`Token expires at: ${token.expiresOn}`);
// Sign an asset URL for secure download
const signed = await client.sharedAccessSignature.getUrl(
  "https://storage.blob.core.windows.net/container/asset.tif",
);
console.log(`Signed URL: ${signed.href}`);

Troubleshooting

概况

Planetary Computer Pro 客户端库会触发 Azure Core 中定义的异常。

import { DefaultAzureCredential } from "@azure/identity";
import { PlanetaryComputerProClient } from "@azure/planetarycomputer";
import { RestError } from "@azure/core-rest-pipeline";

const credential = new DefaultAzureCredential();
const catalogUri = "<your-geocatalog-endpoint>";
const client = new PlanetaryComputerProClient(catalogUri, credential);
try {
  await client.stac.getCollection("non-existent-collection");
} catch (e) {
  if (e instanceof RestError) {
    console.log(`Status code: ${e.statusCode}`);
    console.log(`Message: ${e.message}`);
  }
}

伐木业

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，也可以通过在setLogLevel中调用@azure/logger来启用日志：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

有关如何启用日志的更详细说明，可以查看 @azure/记录器包文档。

后续步骤

情景	Sample
STAC收藏管理	stacCreateCollectionSample.ts
STAC项目管理	stacCreateItemSample.ts
STAC检索	stacSearchSample.ts
马赛克注册	dataRegisterMosaicsSearchSample.ts
地图图块生成	dataGetTileSample.ts
积分	dataGetPointSample.ts
摄取设置	ingestionCreateSourceSample.ts
摄入管理	ingestionCreateSample.ts
SAS 令牌	sharedAccessSignatureGetTokenSample.ts
地图图例	dataGetLegendSample.ts

其他文档

了解更多关于 Microsoft Planetary Computer Pro 的信息
请阅读 STAC规范
查看如何部署GeoCatalog资源
了解如何管理对Microsoft Planetary Computer Pro的访问

Contributing

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

此项目欢迎贡献和建议。大多数贡献要求你同意参与者许可协议（CLA），声明你有权（实际这样做）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

提交拉取请求时，CLA 机器人会自动确定是否需要提供 CLA 并适当修饰 PR（例如标签、注释）。只需按照机器人提供的说明进行操作。只需使用 CLA 在所有存储库中执行此操作一次。

该项目已采用 Microsoft开源行为准则。有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。

反馈

此页面是否有帮助？

Last updated on 2026-07-02