Azure Planetary Computer Pro client library for JavaScript - version 1.0.0

Microsoft Planetary Computer Proは、Azureのハイパースケールインフラストラクチャ上に構築された地理空間データ管理サービスです。ジオカタログは、SpatioTemporal Asset Catalog(STAC)オープン仕様を用いて、地理空間データセットの取り込み、管理、検索、配布するための基礎機能を提供するAzureリソースです。

主な機能

STACコレクション管理:STACコレクションやアイテムを作成、読み取り、更新、削除して地理空間データセットを整理できます
コレクション構成:レンダリングオプション、モザイク、タイル設定、クエリアブルを設定し、クエリ性能と可視化を最適化します
データ可視化:地図タイル(XYZ、TileJSON、WMTS)の生成、プレビュー画像の作成、GeoJSONやバウンディングボックスによるトリミング、ポイント値の抽出、統計情報の計算
モザイク操作:ピクセル単位のデータクエリと取得のためにSTAC検索ベースのモザイクを登録し、複数のアイテムからタイルを生成し、TileJSONおよびWMTS機能にアクセスする
Map Legends:カテゴリカルなクラスのマップ表示や連続的な区間表示を、あらかじめ定義されたカラーマップ付きJSONまたはPNG画像で取得できます
データ取り込み:インジェスソース(マネージデンティドIDまたはSASトークン)を設定し、STACカタログからのインジェストを定義し、インジェス実行を作成・監視します
STAC API操作:アイテムに対する完全なCRUD操作、空間・時間フィルターとソートによる検索、クエリ可能なプロパティの取得、API適合性の確認
セキュアアクセス:コレクション用に設定可能な期間を持つSASトークンを生成し、安全なダウンロードのために資産HREFに署名し、トークンを取り消す—すべてMicrosoft Entra IDで保護されます

主要なリンク:

作業の開始

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細はsupportポリシーをご覧ください。

前提条件

Azure サブスクリプション
Microsoft Planetary Computer Pro GeoCatalogのリソースです。リソースはAzure portal、Azure PowerShell、またはAzure CLIを通じて作成できます。

GeoCatalogのエンドポイント(catalogUri)は、Azure portalのGeoCatalogリソースの概要ページにあります。

`@azure/planetarycomputer` パッケージをインストールする

npm を使ってJavaScript用のAzure Planetary Computer Proクライアントライブラリをインストールしてください:

npm install @azure/planetarycomputer

`PlanetaryComputerProClient` を作成して認証する

Microsoft Planetary Computer Proサービスでの認証方法はいくつかあり、推奨されているのはAzure Identityライブラリを通じた安全なキーレス認証のために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);

主な概念

プラネタリーコンピュータプロクライアント

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

インジェスションソース:マネージデンティティIDまたはSASトークン認証を用いてインジェスソースを設定する
インジェス定義:公開および非公開データソースからの自動STACカタログインジェストを定義します
インジェスションラン:詳細な操作追跡を伴うインジェスランを作成・監視

共有アクセス署名操作(`client.sharedAccessSignature`)

トークン生成:コレクションのために設定可能な期間を持つSASトークンを生成します
資産署名:管理ストレージ資産の安全なダウンロードのために資産HREFに署名します
トークン取り消し:アクセスを制御するために必要に応じてトークンを取り消す

ジオカタログ

GeoCatalogは、地理空間データを保存・整理するAzureの最上位リソースです。次の機能を提供します。

ラスタおよびデータキューブフォーマットのためのゾーン冗長管理ストレージ
サポートデータ型向けの組み込みクラウド最適化
すべての保存データを管理する管理型STACAPI
Microsoft Entra IDを通じたAzureのセキュリティおよびアイデンティティ管理との統合

STAC(時空間資産カタログ)

STACは地理空間データの整理と記述のためのオープン仕様です。 Microsoft Planetary Computer ProはSTACを使って以下を提供します:

コレクション:関連する地理空間データセットの論理的グループ化
アイテム:メタデータを含む個別資産(例:衛星画像、ラスタ)
アセット:STACアイテムによって参照される実際のデータファイル

Examples

このセクションでは、一般的なGeoCatalogワークフローをカバーするコードスニペットを提供します。完全な動作例については、サンプルディレクトリをご覧ください。

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/logger パッケージのドキュメントを参照してください。

次のステップ

その他のサンプルコード

完全な作業例については、各サンプルファイルをご参照ください:

シナリオ	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

このライブラリに貢献したい場合は、コードのビルドやテスト方法について詳しく知るために、contributing guideをお読みください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの投稿では、お客様が投稿を使用する権利を当社に付与する権利を有し、実際に行うことを宣言する共同作成者ライセンス契約 (CLA) に同意する必要があります。詳細については、 cla.microsoft.com をご覧ください。

プル要求を送信すると、CLA ボットは、CLA を提供し、PR を適切に装飾する必要があるかどうかを自動的に判断します (ラベル、コメントなど)。ボットによって提供される手順にそのまま従ってください。これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトは、「Microsoft のオープンソースの倫理規定」を採用しています。詳細については、倫理規定についてよくあるご質問を参照するか、opencode@microsoft.com 宛てにご質問またはコメントをお送りください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-02