Azure Planetary Computer Pro client library for JavaScript - version 1.0.0

Microsoft Planetary Computer Pro 是一款建立在 Azure 超大規模基礎設施上的地理空間資料管理服務。 GeoCatalog 是一項 Azure 資源，提供基礎功能，利用時空資產目錄（SpatioTemporal Asset Catalog，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 入口網站的 GeoCatalog 資源總覽頁面中找到。

安裝 `@azure/planetarycomputer` 套件

安裝 Azure Planetary Computer Pro JavaScript 用戶端函式庫，使用：npm

npm install @azure/planetarycomputer

建立和驗證 `PlanetaryComputerProClient`

有多種方式可以與 Microsoft Planetary Computer Pro 服務進行驗證，建議使用 Microsoft Entra ID，透過 Azure 身份函式庫進行安全且無鑰匙的認證。開始之前：

安裝 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);

重要概念

行星電腦專業客戶端

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 代幣
資產簽署：簽署資產 HREF，以安全下載管理儲存資產
代幣撤銷：必要時撤銷代幣以控制存取權限

地理目錄

GeoCatalog 是 Azure 的頂層資源，用來儲存和組織你的地理空間資料。這提供了以下內容：

區域冗餘、管理式儲存，適用於點陣圖與資料立方體格式
內建支援資料型態的雲端優化
一個可管理的 STAC API 來管理所有儲存的資料
透過 Microsoft Entra ID 與 Azure 的安全與身份管理整合

STAC（時空資產目錄）

STAC 是一個開放規範，用於組織與描述地理空間資料。 Microsoft Planetary Computer Pro 使用 STAC 來提供：

集合：相關地理空間資料集的邏輯分組
項目：個別資產（例如衛星影像、柵格）及元資料
資產：由 STAC 項目參考的實際資料檔案

Examples

本節提供涵蓋常見 GeoCatalog 工作流程的程式碼片段。完整的工作範例請參見 samples 目錄。

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

General

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}`);
  }
}

Logging

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，執行時也可以透過呼叫 setLogLevel 中的 @azure/logger 來啟用日誌：

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱@azure/記錄器套件檔。

下一步

劇本	範例
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

如果你想為這個函式庫貢獻，請閱讀 contributing guide，了解更多如何建置與測試程式碼。

此項目歡迎參與和建議。大部分的捐款都要求您同意「參與者許可協定」（CLA），宣告您有權，而且實際上確實會授與我們使用您貢獻的許可權。詳情請瀏覽 cla.microsoft.com。

當您提交提取要求時，CLA-Bot 會自動判斷您是否需要提供 CLA 並適當裝飾 PR（例如標籤、批註）。只要遵循 Bot 所提供的指示即可。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用了 Microsoft 開放原始碼管理辦法。如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡 opencode@microsoft.com。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-02