Azure Planetary Computer Pro client library for JavaScript - version 1.0.0

A Microsoft Planetary Computer Pro egy földrajzi adatkezelő szolgáltatás, amely az Azure hiperskálázási infrastruktúrájára épül. A GeoCatalog egy Azure-alapú erőforrás, amely alapvető lehetőségeket biztosít a térinformatikai adathalmazok befogadására, kezelésére, keresésére és terjesztésére a SpatioTemporal Asset Catalog (STAC) nyílt specifikációjával.

Főbb képességek

  • STAC gyűjteménykezelés: Létrehozz, olvass, frissítse és törölje a STAC gyűjteményeket és elemeket, hogy rendszerezze a földi adathalmazaid
  • Gyűjtemény konfiguráció: Konfiguráld a renderelési lehetőségeket, mozaikokat, csempékbeállításokat és lekérdezéseket a lekérdezések teljesítményének és vizualizációjának optimalizálására
  • Adatvizualizáció: Térképlapok generálása (XYZ, TileJSON, WMTS), előnézeti képek, GeoJSON vagy határozó doboz szerinti vágás, pontértékek kinyerése, statisztikák számítása
  • Mosaic műveletek: Regisztrálni a STAC keresésalapú mozaikokat pixel szerinti adatlekérdezéshez és lekérdezéshez, több elemből csempéket generálni, valamint elérni a TileJSON és WMTS funkciókat
  • Térkép Feliratok: Előre meghatározott színtérképes térképek jelvények (kategorizus) és intervallum legendák (folyamatos) előre meghatározott színtérképekkel JSON vagy PNG képként kell letölteni
  • Adatfelvétel: Feltöltési források beállítása (Managed Identity vagy SAS token), STAC katalógusok felvételeinek meghatározása, valamint felvételi futtatások létrehozása és nyomon követése
  • STAC API műveletek: Teljes CRUD műveletek az elemeken, keresés téri/időbeli szűrőkkel és rendezéssel, lekérdezésre alkalmas tulajdonságok lekérése, valamint API megfelelőség ellenőrzése
  • Biztonságos hozzáférés: SAS tokenek generálása konfigurálható időtartamgal a gyűjtésekhez, eszköz HREF-ek aláírása biztonságos letöltésekhez, és tokenek visszavonása – mindezt a Microsoft Entra ID-n keresztül védve

Főbb hivatkozások:

Kezdő lépések

Jelenleg támogatott környezetek

További részletekért lásd a támogató szabályzatunkat

Prerequisites

A GeoCatalog végpont (catalogUri) megtalálható az Azure Portal-ban, a GeoCatalog erőforrás áttekintési oldalán.

Telepítse a(z) @azure/planetarycomputer csomagot

Telepítsd az Azure Planetary Computer Pro klienskönyvtárát JavaScripthez a következőképpen npm:

npm install @azure/planetarycomputer

PlanetaryComputerProClient létrehozása és hitelesítése

Számos módja van a hitelesítésnek a Microsoft Planetary Computer Pro szolgáltatással, és a javasolt mód a Microsoft Entra ID használata biztonságos, kulcs nélküli hitelesítéshez az Azure Identity könyvtáron keresztül. Első lépések:

  1. Telepítse az Azure Identity csomagot:
npm install @azure/identity

  1. Regisztráljon egy új Microsoft Entra ID alkalmazást, és biztosíts hozzáférést a Microsoft Planetary Computer Pro-hoz azzal, hogy a megfelelő szerepet rendeli a szolgáltatási vezetődnek.

  2. Állítsa be a Microsoft Entra ID alkalmazás ügyfélazonosítójának, bérlőazonosítójának és ügyféltitkának értékeit környezeti változóként: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Hozd létre az ügyfél DefaultAzureCredential segítségével:

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

főbb fogalmak

PlanetaryComputerProClient

PlanetaryComputerProClientez a Microsoft Planetary Computer Pro klienskönyvtárat használó fejlesztők elsődleges interfésze. Az ügyfél több műveleti csoporthoz is hozzáférést biztosít:

STAC műveletek (client.stac)

  • Gyűjteménykezelés: Létrehozz, frissítsd, listázd és töröld a STAC gyűjteményeket, hogy rendszerezd a térinformatikai adathalmazaid
  • Elemkezelés: Egyedi STAC elemek létrehozása, olvasása, frissítése és törlése a gyűjteményekben
  • Keresési API: Keress elemeket térbeli és időbeli szűrőkkel, rendezéssel, valamint lekérdezhető tulajdonságokkal
  • Konfiguráció: Renderelési opciók, mozaikok, csempe beállítások, lekérdezések és partíciótípusok kezelése
  • API megfelelőség: STAC API megfelelőségi osztályok és landing page információk lekérése

Adatműveletek (client.data)

  • Csempe generálása: Térképcsempéket generálni (XYZ, TileJSON, WMTS) gyűjteményekből, tárgyakból és mozaikokokból
  • Adatvizualizáció: Előnézetes képek létrehozása, GeoJSON vagy korlátzó doboz alapján vágva, pontértékek kinyerése, statisztikák számítása
  • Mosaic műveletek: STAC keresésalapú mozaikok regisztrálása, mozaik csempék, TileJSON és WMTS képességek visszakeresése
  • Térkép Legendák: Szerezd be az osztálytérkép- és intervallum legendákat JSON vagy PNG képként
  • Eszköz metaadat: Csempe mátrix halmazok és eszköz metaadatok lekérdezése gyűjteményekhez és elemekhez

Felvételi műveletek (client.ingestion)

  • Felvételi források: Feltöltési források beállítása Managed Identity vagy SAS token hitelesítéssel
  • Felvételi definíciók: Határozzuk meg az automatizált STAC katalógusfelvételt nyilvános és magán adatforrásokból
  • Felvételi futások: Részletes műveletkövetéssel hozza létre és figyelje a felvételi futamokat

Megosztott hozzáférési aláírási műveletek (client.sharedAccessSignature)

  • Token generálás: SAS tokenek generálása konfigurálható időtartamgal a gyűjteményekhez
  • Asset aláírás: Asset HREF-ek aláírása biztonságos letöltésekhez menedzselt tárolóeszközök letöltéséhez
  • Token visszavonás: Tokenek visszavonása, ha szükséges a hozzáférés szabályozásához

GeoCatalog

A GeoCatalog az Azure legfelső szintű erőforrása, amely tárolja és rendszerzi a földrajzi adataidat. A következő lehetőségeket biztosítja:

  • Zónaredundáns, kezelt tároló raszter- és adatkockás formátumokhoz
  • Beépített felhőoptimalizálás támogatott adattípusokhoz
  • Egy menedzselt STAC API minden tárolt adathoz
  • Integráció az Azure biztonságával és identitásmenedzsmentjével a Microsoft Entra ID-n keresztül

STAC (SpatioTemporal Asset Catalog)

A STAC egy nyílt specifikáció a földi adatok rendszerezésére és leírására. Microsoft Planetary Computer Pro a STAC-ot használja a következőkért:

  • Gyűjtemények: Kapcsolódó földi adathalmazok logikai csoportosításai
  • Elemek: Egyéni eszközök (pl. műholdképek, raszterek) metaadatokkal
  • Erőforrások: A STAC Items által hivatkozott tényleges adatfájlok

Examples

Ez a rész kódrészleteket tartalmaz, amelyek a GeoCatalog gyakori munkafolyamatait fedik le. A teljes munka példákért lásd a minták könyvtárát.

STAC gyűjtemények listája

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 tárgyak keresése

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

Szerezd meg a STAC tétel részleteit

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

Hozz létre egy STAC gyűjteményt

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

Mozaikcsempéket regisztrálni és renderelni

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

Kinyerési pontértékek

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

Térkép csempék generálása

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

Felvételi forrás beállítása

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

Adatfelvételi menedzsment

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

Szerezz egy SAS tokent

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

Hibaelhárítás

General

A Planetary Computer Pro klienskönyvtár kivételeket hoz fel, amelyeket az Azure Core definiál.

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

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL következőre info: . Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Következő lépések

További mintakód

Teljes munkapéldákért lásd az egyes mintafájlokat:

Scenario Sample
STAC gyűjtési menedzsment stacCreateCollectionSample.ts
STAC Item Management stacCreateItemSample.ts
STAC keresés stacSearchSample.ts
Mosaic regisztráció dataRegisterMosaicsSearchSample.ts
Térkép csempe generálása dataGetTileSample.ts
Pontértékek dataGetPointSample.ts
Felvételi beállítás ingestionCreateSourceSample.ts
Lenyelés kezelése ingestionCreateSample.ts
SAS-token sharedAccessSignatureGetTokenSample.ts
Térképlegendák dataGetLegendSample.ts

További dokumentáció

Contributing

Ha szeretnél hozzájárulni ehhez a könyvtárhoz, kérjük, olvasd el a hozzájárulás útmutatót hogy többet megtudj arról, hogyan lehet elkészíteni és tesztelni a kódot.

Ez a projekt üdvözli a hozzájárulásokat és javaslatokat. A legtöbb hozzájárulás megköveteli, hogy elfogadja a közreműködői licencszerződést (CLA), amely kimondja, hogy önnek joga van a hozzájárulás használatára, és valóban meg kell adnia nekünk a jogosultságokat a hozzájárulás használatára. A részletekért látogasson el a cla.microsoft.com oldalra.

A lekéréses kérelem elküldésekor a CLA-robot automatikusan meghatározza, hogy meg kell-e adnia egy CLA-t, és megfelelően kell-e díszítenie a lekéréses kérelmet (például címkét, megjegyzést). Egyszerűen kövesse a robot utasításait. Ezt csak egyszer kell elvégeznie az összes adattárban a CLA használatával.

Ez a projekt a Microsoft nyílt forráskóddal kapcsolatos viselkedési szabályzata alapján működik. További információért tekintse át a viselkedési szabályzat GYIK dokumentumát, illetve további kérdések vagy megjegyzések esetén írjon az opencode@microsoft.com e-mail-címre.

  • Last updated on