Azure Planetary Computer Pro client library for JavaScript - version 1.0.0

Microsoft Planetary Computer Pro är en geospatial datahanteringstjänst byggd på Azure:s hyperskalinfrastruktur. GeoCatalog är en Azure-resurs som tillhandahåller grundläggande funktioner för att ta in, hantera, söka och distribuera geospatiala dataset med hjälp av SpatioTemporal Asset Catalog (STAC) öppen specifikation.

Viktiga funktioner

  • STAC-samlingshantering: Skapa, läsa, uppdatera och ta bort STAC-samlingar och objekt för att organisera dina geospatiala datamängder
  • Samlingskonfiguration: Konfigurera renderingsalternativ, mosaiker, tile-inställningar och frågebara filer för att optimera frågeprestanda och visualisering
  • Datavisualisering: Generera kartplattor (XYZ, TileJSON, WMTS), förhandsgranska bilder, beskär med GeoJSON eller avgränsningsruta, extrahera punktvärden och beräkna statistik
  • Mosaikoperationer: Registrera STAC-sökningsbaserade mosaiker för pixelvis datasökning och hämtning, generera plattor från flera objekt och få tillgång till TileJSON- och WMTS-funktioner
  • Kartlegender: Hämta klasskartlegender (kategoriska) och intervalllegender (kontinuerliga) som JSON- eller PNG-bilder med fördefinierade färgkartor
  • Datainsamling: Sätt upp inmatningskällor (Managed Identity eller SAS-token), definiera insamlingar från STAC-kataloger och skapa samt övervaka insamlingskörningar
  • STAC API-operationer: Fullständiga CRUD-operationer på objekt, sökning med rumsliga/temporala filter och sortering, hämta frågebara egenskaper och kontrollera API-konformitet
  • Säker åtkomst: Generera SAS-tokens med konfigurerbar varaktighet för inkasso, signera tillgångs-HREF:er för säkra nedladdningar och återkalla tokens – allt säkrat via Microsoft Entra ID

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

Se vår supportpolicy för mer information.

Förutsättningar

GeoCatalog-endpointen (catalogUri) finns i Azure Portal på din GeoCatalog-resurss översiktssida.

Installera @azure/planetarycomputer-paketet

Installera Azure Planetary Computer Pro-klientbiblioteket för JavaScript med npm:

npm install @azure/planetarycomputer

Skapa och autentisera en PlanetaryComputerProClient

Det finns flera sätt att autentisera sig med Microsoft Planetary Computer Pro-tjänsten och det rekommenderade sättet är att använda Microsoft Entra ID för säker, nyckellös autentisering via Azure Identity-biblioteket. Så här kommer du igång:

  1. Installera Azure Identity-paketet:
npm install @azure/identity

  1. Registrera en ny Microsoft Entra ID-applikation och ge tillgång till Microsoft Planetary Computer Pro genom att tilldela lämplig roll till din tjänsteansvarig.

  2. Ange värdena för klient-ID, klient-ID och klienthemlighet för Microsoft Entra-ID-programmet som miljövariabler: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Skapa klienten med 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);

Nyckelbegrepp

PlanetaryComputerProClient

PlanetaryComputerProClientär det primära gränssnittet för utvecklare som använder Microsoft Planetary Computer Pro-klientbiblioteket. Klienten ger tillgång till flera operationsgrupper:

STAC-operationer (client.stac)

  • Samlingshantering: Skapa, uppdatera, lista och ta bort STAC-samlingar för att organisera dina geospatiala datamängder
  • Föremålshantering: Skapa, läsa, uppdatera och ta bort enskilda STAC-objekt inom samlingar
  • Sök-API: Sök efter objekt med hjälp av rumsliga och temporala filter, sortering och frågebara egenskaper
  • Konfiguration: Hantera renderingsalternativ, mosaiker, kakelinställningar, frågebara filer och partitionstyper
  • API-konformitet: Hämta STAC API-konformitetsklasser och information om landningssidan

Dataoperationer (client.data)

  • Tilegenerering: Generera kartplattor (XYZ, TileJSON, WMTS) från samlingar, objekt och mosaiker
  • Datavisualisering: Skapa förhandsvisningsbilder, beskär med GeoJSON eller begränsningsruta, extrahera punktvärden och beräkna statistik
  • Mosaikoperationer: Registrera STAC-sökbaserade mosaiker och hämta mosaikplattor, TileJSON och WMTS-funktioner
  • Kartlegender: Hämta klasskartor och intervalllegender som JSON- eller PNG-bilder
  • Tillgångsmetadata: Hämta tilematrisset och tillgångsmetadata för samlingar och objekt

Intagsoperationer (client.ingestion)

  • Insamlingskällor: Sätt upp insamlingskällor med Managed Identity eller SAS-tokenautentisering
  • Definitioner av intagning: Definiera automatiserad insamling av STAC-kataloger från offentliga och privata datakällor
  • Intagningskörningar: Skapa och övervaka insamlingskörningar med detaljerad driftspårning

Delad åtkomstsignaturoperationer (client.sharedAccessSignature)

  • Tokengenerering: Generera SAS-tokens med konfigurerbar duration för samlingar
  • Asset Signing: Signera tillgångs-HREF:er för säkra nedladdningar av hanterade lagringstillgångar
  • Token-återkallelse: Återkalla tokens när det behövs för att kontrollera åtkomst

GeoCatalog

En GeoCatalog är den övergripande Azure-resursen som lagrar och organiserar din geospatiala data. Den innehåller:

  • Zonredundant, hanterad lagring för raster- och datakubformat
  • Inbyggd molnoptimering för stödda datatyper
  • Ett hanterat STAC-API för all lagrad data
  • Integration med Azure:s säkerhets- och identitetshantering via Microsoft Entra ID

STAC (SpatioTemporal Asset Catalog)

STAC är en öppen specifikation för att organisera och beskriva geospatial data. Microsoft Planetary Computer Pro använder STAC för att tillhandahålla:

  • Samlingar: Logiska grupperingar av relaterade geospatiala datamängder
  • Föremål: Individuella tillgångar (t.ex. satellitbilder, raster) med metadata
  • Tillgångar: De faktiska datafilerna som refereras av STAC-objekt

Examples

Detta avsnitt innehåller kodfragment som täcker vanliga GeoCatalog-arbetsflöden. För kompletta fungerande exempel, se exempelkatalogen .

Lista STAC-samlingar

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

Sök efter STAC-objekt

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

Få detaljer om STAC-föremål

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

Skapa en STAC-samling

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

Registrera och rendera mosaikplattor

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

Extrahera poängvärden

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

Generera kartplattor

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

Sätt upp intagningskälla

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

Datainsamlingshantering

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

Skaffa en 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

Planetary Computer Pro-klientbiblioteket kommer att skapa undantag definierade i 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

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Nästa steg

Mer exempelkod

För kompletta arbetsexempel, se de individuella exempelfilerna:

Scenario Sample
STAC-samlingshantering stacCreateCollectionSample.ts
STAC-produkthantering stacCreateItemSample.ts
STAC-sökning stacSearchSample.ts
Mosaikregistrering dataRegisterMosaicsSearchSample.ts
Generering av kartplattor dataGetTileSample.ts
Poängvärden dataGetPointSample.ts
Intagsinställning ingestionCreateSourceSample.ts
Intagshantering ingestionCreateSample.ts
SAS-token sharedAccessSignatureGetTokenSample.ts
Kartlegender dataGetLegendSample.ts

Ytterligare dokumentation

Contributing

Om du vill bidra till detta bibliotek, läs gärna guiden bidrag för att lära dig mer om hur man bygger och testar koden.

Det här projektet välkomnar bidrag och förslag. De flesta bidrag kräver att du godkänner ett licensavtal för deltagare (CLA) som förklarar att du har rätt att, och faktiskt gör det, ge oss rätten att använda ditt bidrag. Mer information finns på cla.microsoft.com.

När du skickar en pull-begäran avgör en CLA-robot automatiskt om du behöver tillhandahålla ett CLA och dekorera PR på rätt sätt (t.ex. etikett, kommentar). Följ bara anvisningarna från roboten. Du behöver bara göra detta en gång för alla lagringsplatser med vår CLA.

Det här projektet har antagit Microsoft Open Source Code of Conduct (Microsofts regler för uppförande för öppen källkod). Läs Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com om du har några andra frågor eller kommentarer.

  • Last updated on