Pustaka klien Azure Planetary Computer Pro untuk JavaScript - versi 1.0.0

Microsoft Planetary Computer Pro adalah layanan manajemen data geospasial yang dibangun di atas infrastruktur hyperscale Azure. GeoCatalog adalah sumber daya Azure yang menyediakan kemampuan dasar untuk menyerap, mengelola, mencari, dan mendistribusikan himpunan data geospasial menggunakan spesifikasi terbuka SpatioTemporal Asset Catalog (STAC).

Kemampuan utama

  • Manajemen Koleksi STAC: Membuat, membaca, memperbarui, dan menghapus koleksi dan item STAC untuk mengatur himpunan data geospasial Anda
  • Konfigurasi Koleksi: Mengonfigurasi opsi render, mosaik, pengaturan petak peta, dan kueri untuk mengoptimalkan performa dan visualisasi kueri
  • Visualisasi Data: Hasilkan ubin peta (XYZ, TileJSON, WMTS), pratinjau gambar, potong dengan GeoJSON atau kotak pembatas, ekstrak nilai titik, dan komputasi statistik
  • Operasi Mosaik: Daftarkan mosaik berbasis pencarian STAC untuk kueri dan pengambilan data berdasarkan piksel, buat ubin dari beberapa item, dan akses kemampuan TileJSON dan WMTS
  • Legenda Peta: Ambil legenda peta kelas (kategoris) dan legenda interval (berkelanjutan) sebagai gambar JSON atau PNG dengan peta warna yang telah ditentukan sebelumnya
  • Penyerapan Data: Siapkan sumber penyerapan (Identitas Terkelola atau token SAS), tentukan penyerapan dari katalog STAC, dan buat serta pantau eksekusi penyerapan
  • Operasi API STAC: Operasi CRUD penuh pada item, cari dengan filter dan penyortiran spasial/temporal, ambil properti yang dapat dikueri, dan periksa kesesuaian API
  • Akses Aman: Hasilkan token SAS dengan durasi yang dapat dikonfigurasi untuk pengumpulan, tandatangani HREF aset untuk unduhan aman, dan cabut token—semuanya diamankan melalui Microsoft Entra ID

Tautan kunci:

Memulai Langkah Pertama

Lingkungan yang didukung saat ini

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Titik akhir GeoCatalog (catalogUri) dapat ditemukan di portal Azure di halaman gambaran umum sumber daya GeoCatalog Anda.

Pasang paket @azure/planetarycomputer

Instal pustaka klien Azure Planetary Computer Pro untuk JavaScript dengannpm:

npm install @azure/planetarycomputer

Membuat dan mengautentikasi PlanetaryComputerProClient

Ada beberapa cara untuk mengautentikasi dengan layanan Microsoft Planetary Computer Pro dan cara yang disarankan adalah dengan menggunakan Microsoft Entra ID untuk autentikasi tanpa kunci yang aman melalui pustaka Azure Identity. Untuk memulai:

  1. Instal paket Azure Identity:
npm install @azure/identity

  1. Daftarkan aplikasi Microsoft Entra ID baru dan berikan akses ke Microsoft Planetary Computer Pro dengan menetapkan peran yang sesuai ke perwakilan layanan Anda.

  2. Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi Microsoft Entra ID sebagai variabel lingkungan: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Buat klien menggunakan 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);

Konsep Utama

PlanetaryComputerProClient

PlanetaryComputerProClientadalah antarmuka utama untuk pengembang yang menggunakan pustaka klien Microsoft Planetary Computer Pro. Klien menyediakan akses ke beberapa grup operasi:

Operasi STAC (client.stac)

  • Manajemen Koleksi: Membuat, memperbarui, mencantumkan, dan menghapus koleksi STAC untuk mengatur himpunan data geospasial Anda
  • Manajemen Item: Membuat, membaca, memperbarui, dan menghapus item STAC individual dalam koleksi
  • Search API: Mencari item menggunakan filter spasial dan temporal, pengurutan, dan properti yang dapat dikueri
  • Konfigurasi: Kelola opsi render, mosaik, pengaturan petak peta, kueri, dan jenis partisi
  • Kesesuaian API: Mengambil kelas kesesuaian API STAC dan informasi halaman arahan

Operasi Data (client.data)

  • Pembuatan Ubin: Hasilkan ubin peta (XYZ, TileJSON, WMTS) dari koleksi, item, dan mosaik
  • Visualisasi Data: Buat gambar pratinjau, potong dengan GeoJSON atau kotak pembatas, ekstrak nilai titik, dan komputasi statistik
  • Operasi Mosaik: Mendaftarkan mosaik berbasis pencarian STAC dan mengambil ubin mosaik, TileJSON, dan kemampuan WMTS
  • Legenda Peta: Ambil peta kelas dan legenda interval sebagai gambar JSON atau PNG
  • Metadata Aset: Mengambil kumpulan matriks petak peta dan metadata aset untuk koleksi dan item

Operasi Penyerapan (client.ingestion)

  • Sumber Penyerapan: Menyiapkan sumber penyerapan menggunakan Identitas Terkelola atau autentikasi token SAS
  • Definisi Penyerapan: Tentukan penyerapan katalog STAC otomatis dari sumber data publik dan pribadi
  • Eksekusi Penyerapan: Membuat dan memantau eksekusi penyerapan dengan pelacakan operasi terperinci

Operasi Tanda Tangan Akses Bersama (client.sharedAccessSignature)

  • Pembuatan Token: Hasilkan token SAS dengan durasi yang dapat dikonfigurasi untuk koleksi
  • Penandatanganan Aset: Menandatangani HREF aset untuk mengunduh aset penyimpanan terkelola dengan aman
  • Pencabutan Token: Cabut token bila diperlukan untuk mengontrol akses

Katalog Geografis

GeoCatalog adalah sumber daya Azure tingkat atas yang menyimpan dan mengatur data geospasial Anda. Ini menyediakan:

  • Penyimpanan terkelola redundan zona untuk format raster dan kubus data
  • Pengoptimalan cloud bawaan untuk jenis data yang didukung
  • API STAC terkelola untuk semua data yang disimpan
  • Integrasi dengan keamanan dan manajemen identitas Azure melalui Microsoft Entra ID

STAC (Katalog Aset SpatioTemporal)

STAC adalah spesifikasi terbuka untuk mengatur dan mendeskripsikan data geospasial. Microsoft Planetary Computer Pro menggunakan STAC untuk menyediakan:

  • Koleksi: Pengelompokan logis himpunan data geospasial terkait
  • Item: Aset individual (misalnya, citra satelit, raster) dengan metadata
  • Aset: File data aktual yang direferensikan oleh Item STAC

Examples

Bagian ini menyediakan cuplikan kode yang mencakup alur kerja GeoCatalog umum. Untuk contoh kerja lengkap, lihat direktori sampel .

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

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

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

Membuat Koleksi 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");

Daftarkan dan Render Ubin Mosaik

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

Ekstrak Nilai Poin

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

Hasilkan Ubin Peta

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

Menyiapkan Sumber Penyerapan

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

Manajemen Penyerapan Data

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

Dapatkan Token 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

Pustaka klien Planetary Computer Pro akan memunculkan pengecualian yang ditentukan di 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

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/logger.

Langkah berikutnya

Kode sampel lainnya

Untuk contoh kerja lengkap, lihat file sampel individual:

Skenario Sample
Manajemen Koleksi STAC stacCreateCollectionSample.ts
Manajemen Item STAC stacCreateItemSample.ts
Pencarian STAC stacSearchSample.ts
Pendaftaran Mosaik dataRegisterMosaicsSearchSample.ts
Pembuatan Ubin Peta dataGetTileSample.ts
Nilai Poin dataGetPointSample.ts
Pengaturan Penyerapan ingestionCreateSourceSample.ts
Manajemen Penyerapan ingestionCreateSample.ts
SAS Token sharedAccessSignatureGetTokenSample.ts
Legenda Peta dataGetLegendSample.ts

Dokumentasi tambahan

Contributing

Jika Anda ingin berkontribusi ke library ini, silakan baca panduan contributor untuk mempelajari lebih lanjut cara membuat dan menguji kode.

Proyek ini menyambut kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Saat Anda mengirimkan permintaan pull, cla-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat FAQ Kode Etik atau hubungi opencode@microsoft.com untuk mengajukan pertanyaan atau komentar tambahan.

  • Last updated on