Azure Planetary Computer Pro klientská knihovna pro JavaScript - verze 1.0.0

Microsoft Planetární Počítač Pro je služba pro správu geoprostorových dat postavená na hyperscale infrastruktuře Azure. GeoCatalog je Azure zdroj, který poskytuje základní schopnosti pro sběr, správu, vyhledávání a distribuci geospatialních datových sad pomocí otevřené specifikace SpatioTemporal Asset Catalog (STAC).

Klíčové funkce

  • STAC správa kolekcí: Vytvářejte, čtěte, aktualizujte a mažte STAC kolekce a položky pro organizaci vašich geoprostorových datových sad
  • Konfigurace kolekce: Nastavte možnosti renderování, mozaiky, nastavení dlaždic a dotazovatelné prvky pro optimalizaci výkonu dotazů a vizualizace
  • Vizualizace dat: Generujte mapové dlaždice (XYZ, TileJSON, WMTS), náhledové obrázky, ořezujte pomocí GeoJSON nebo ohraničovacího rámečku, extrahujte hodnoty bodů a vypočítávejte statistiky
  • Mosaic Operations: Registrujte mozaiky založené na vyhledávání v STAC pro dotazování a vyhledávání dat podle jednotlivých pixelů, generujte dlaždice z více položek a přistupujte k možnostem TileJSON a WMTS
  • Legendy map: Získejte legendy tříd (kategorická) a intervalové legendy (kontinuální) jako JSON nebo PNG obrázky s předdefinovanými barevnými mapami
  • Vstup dat: Nastavte zdroje ingestů (Managed Identity nebo SAS token), definujte ingestions z katalogů STAC a vytvářejte a monitorujte ingestenční běhy
  • STAC API Operations: Plné CRUD operace na položkách, vyhledávání pomocí prostorových/časových filtrů a třídění, vyhledávání dotazovatelných vlastností a kontrola souladu s API
  • Bezpečný přístup: Generujte SAS tokeny s konfigurovatelnou dobou trvání pro inkasace, podepisujte HREFy aktiv pro bezpečné stahování a odebírejte tokeny – vše zabezpečené pomocí Microsoft Entra ID

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

Další podrobnosti najdete v zásadách podpory.

Předpoklady

Endpoint GeoCatalogu (catalogUri) najdete v Azure Portal na stránce přehledu zdroje vašeho GeoCatalogu.

Nainstalujte balíček @azure/planetarycomputer.

Nainstalujte klientskou knihovnu Azure Planetary Computer Pro pro JavaScript s npm:

npm install @azure/planetarycomputer

Vytvořte a ověřte PlanetaryComputerProClient

Existuje několik způsobů, jak se autentizovat se službou Microsoft Planetární Počítač Pro a doporučeným způsobem je použít Microsoft Entra ID pro bezpečné, bezklíčové autentizování prostřednictvím knihovny Azure Identity. Jak začít:

  1. Install the Azure Identity package:
npm install @azure/identity

  1. Zaregistrujte si novou aplikaci Microsoft Entra ID a udělte přístup k Microsoft Planetární Počítač Pro přiřazením vhodné role vašemu zástupci služby.

  2. Nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace Microsoft Entra ID jako proměnné prostředí: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Create the client using 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);

Klíčové koncepty

PlanetaryComputerProClient

PlanetaryComputerProClientje hlavní rozhraní pro vývojáře využívající klientskou knihovnu Microsoft Planetární Počítač Pro. Klient poskytuje přístup k několika skupinám operací:

Provoz STAC (client.stac)

  • Správa kolekcí: Vytvářejte, aktualizujte, seznamujte a mažte STAC kolekce pro organizaci vašich geoprostorových datových sad
  • Správa položek: Vytvářet, číst, aktualizovat a mazat jednotlivé položky STAC v rámci kolekcí
  • Vyhledávání API: Vyhledávání položek pomocí prostorových a časových filtrů, třídění a dotazovatelných vlastností
  • Konfigurace: Správa možností renderování, mozaik, nastavení dlaždic, dotazovatelných prvků a typů oddílů
  • API Compliance: Získejte třídy souladu STAC API a informace o vstupní stránce

Datové operace (client.data)

  • Generování dlaždic: Generujte mapové dlaždice (XYZ, TileJSON, WMTS) ze sbírek, položek a mozaik
  • Vizualizace dat: Vytvářejte náhledové obrázky, ořezávejte podle GeoJSON nebo ohraničovacího rámečku, extrahujte hodnoty bodů a vypočítávejte statistiky
  • Operace mozaik: Registrujte mozaiky založené na vyhledávání v STAC a získávejte mozaikové dlaždice, schopnosti TileJSON a WMTS
  • Legendy map: Získejte mapy tříd a intervalové legendy jako obrázky JSON nebo PNG
  • Metadata majetku: Získávej sady matic dlaždic a metadata majetku pro kolekce a položky

Operace příjmu (client.ingestion)

  • Zdroje ingesetu: Nastavte zdroje ingestu pomocí Managed Identity nebo SAS token authentication
  • Definice vstupu: Definujte automatizovaný vstup do katalogu STAC z veřejných a soukromých datových zdrojů
  • Ingestion Runs: Vytvářejte a monitorujte ingestční běhy s detailním sledováním operací

Operace sdíleného přístupového podpisu (client.sharedAccessSignature)

  • Generování tokenů: Generujte SAS tokeny s konfigurovatelnou délkou trvání pro kolekce
  • Podepisování majetku: Podepisujte HREFy pro bezpečné stahování spravovaných úložných aktiv
  • Odebrání tokenů: Odebírat tokeny, když je to potřeba pro kontrolu přístupu

GeoCatalog

GeoKatalog je nejvyšší Azure zdroj, který uchovává a organizuje vaše geoprostorová data. Poskytuje:

  • Zónově redundantní, spravované úložiště pro rastrové a datové krychle formáty
  • Vestavěná optimalizace cloudu pro podporované datové typy
  • Spravované STAC API pro všechna uložená data
  • Integrace s bezpečností a správou identity v Azure prostřednictvím Microsoft Entra ID

STAC (Katalog spatioTemporal Asset Catalog)

STAC je otevřená specifikace pro organizaci a popis geoprostorových dat. Microsoft Planetární Počítač Pro používá STAC k poskytnutí:

  • Sbírky: Logické seskupení souvisejících geoprostorových datových sad
  • Položky: Jednotlivé assety (např. satelitní snímky, rastry) s metadaty
  • Aktiva: Skutečné datové soubory odkazované STAC položkami

Examples

Tato sekce poskytuje úryvky kódu pokrývající běžné pracovní postupy GeoCatalogu. Pro kompletní pracovní příklady viz adresář samples .

Seznam STAC sbírek

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

Vyhledávání položek 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}`);
}

Získejte podrobnosti o položce 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)}`);

Vytvořte STAC kolekci

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

Mozaikové dlaždice registru a renderování

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

Extrahujte body

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

Generování mapových dlaždic

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

Nastavení zdroje příjmu

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

Správa vstupu dat

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

Pořiďte si SAS token

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

Klientská knihovna Planetary Computer Pro vyvolá výjimky definované v 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

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků HTTP a odpovědí, nastavte proměnnou AZURE_LOG_LEVEL prostředí na infohodnotu . Případně můžete protokolování povolit za běhu voláním setLogLevel příkazu @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Další kroky

Další ukázkový kód

Pro kompletní pracovní příklady viz jednotlivé ukázkové soubory:

Scénář Sample
Správa sbírky STAC stacCreateCollectionSample.ts
STAC správa položek stacCreateItemSample.ts
STAC Search stacSearchSample.ts
Registrace Mosaic dataRegisterMosaicsSearchSample.ts
Generování mapových dlaždic dataGetTileSample.ts
Bodové hodnoty dataGetPointSample.ts
Nastavení příjmu ingestionCreateSourceSample.ts
Správa příjmu ingestionCreateSample.ts
SAS Token sharedAccessSignatureGetTokenSample.ts
Legendy o mapách dataGetLegendSample.ts

Další dokumentace

Contributing

Pokud chcete přispívat do této knihovny, přečtěte si průvodce pro přispívání a přečtěte si další informace o tom, jak sestavit a otestovat kód.

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která deklaruje, že máte právo a ve skutečnosti nám udělíte práva k používání vašeho příspěvku. Podrobnosti naleznete na cla.microsoft.com.

Když odešlete žádost o přijetí změn, robot CLA automaticky určí, jestli potřebujete poskytnout CLA, a odpovídajícím způsobem vyzdobit žádost o přijetí změn (např. popisek, komentář). Stačí postupovat podle pokynů poskytovaných robotem. Stačí to udělat jen jednou napříč všemi úložištěmi pomocí naší cla.

Tento projekt se řídí Pravidly chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. S případnými dalšími dotazy nebo připomínkami se obraťte na adresu opencode@microsoft.com.

  • Last updated on