Azure Planetary Computer Pro libreria client per JavaScript - versione 1.0.0

Il Computer Planetario Pro di Microsoft è un servizio di gestione dei dati geospaziali costruito sull'infrastruttura iperscalabile di Azure. Il GeoCatalog è una risorsa Azure che fornisce capacità fondamentali per assumere, gestire, cercare e distribuire dataset geospaziali utilizzando la specifica aperta SPATIOTemporal Asset Catalog (STAC).

Funzionalità principali

  • Gestione delle collezioni STAC: Crea, leggi, aggiorna ed elimina le collezioni e gli oggetti STAC per organizzare i tuoi dataset geospaziali
  • Configurazione della collezione: Configura opzioni di rendering, mosaici, impostazioni delle tile e query per ottimizzare le prestazioni delle query e la visualizzazione
  • Visualizzazione dei dati: Generare tessere mappe (XYZ, TileJSON, WMTS), anteprima delle immagini, ritagliare tramite GeoJSON o bounding box, estrarre i valori dei punti e calcolare statistiche
  • Operazioni Mosaic: Registra mosaici basati su ricerca STAC per la query e il recupero dati pixel per pixel, genera tile da più elementi e accedi alle funzionalità TileJSON e WMTS
  • Legende della mappa: Recuperare le legende delle classi map (categoriche) e le legende degli intervalli (continue) come immagini JSON o PNG con mappe colore predefinite
  • Data Ingestion: Configurare sorgenti di ingestione (token Managed Identity o SAS), definire le ingestioni dai cataloghi STAC e creare e monitorare le run di ingestione
  • Operazioni API STAC: Operazioni CRUD complete sugli elementi, ricerca con filtri spaziali/temporali e ordinamento, recupero delle proprietà interrogabili e verifica la conformità API
  • Accesso Sicuro: Genera token SAS con durata configurabile per le raccolte, firma gli HREF degli asset per download sicuri e revoca i token—tutto protetto tramite Microsoft Entra ID

Collegamenti chiave:

Come iniziare

Ambienti attualmente supportati

Consulta la nostra politica support per maggiori dettagli.

Prerequisiti

L'endpoint GeoCatalog (catalogUri) si trova nell'portale di Azure nella pagina panoramica della tua risorsa GeoCatalog.

Installare il pacchetto @azure/planetarycomputer

Installa la libreria client di Azure Planetary Computer Pro per JavaScript con npm:

npm install @azure/planetarycomputer

Creare ed autenticare un PlanetaryComputerProClient

Esistono diversi modi per autenticarsi con il servizio Computer Planetario Pro di Microsoft e il modo raccomandato è utilizzare Microsoft Entra ID per un'autenticazione sicura e senza chiave tramite la libreria Azure Identity. Per iniziare:

  1. Installa il pacchetto Azure Identity:
npm install @azure/identity

  1. Registra una nuova applicazione Microsoft Entra ID e concedi l'accesso a Computer Planetario Pro di Microsoft assegnando il ruolo appropriato al tuo responsabile di servizio.

  2. Impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione Microsoft Entra ID come variabili di ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Crea il client usando 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);

Concetti chiave

PlanetaryComputerProClient

PlanetaryComputerProClientè l'interfaccia principale per gli sviluppatori che utilizzano la libreria client Computer Planetario Pro di Microsoft. Il client fornisce accesso a diversi gruppi operativi:

Operazioni STAC (client.stac)

  • Gestione delle collezioni: Crea, aggiorna, elenca ed elimina le collezioni STAC per organizzare i tuoi dataset geospaziali
  • Gestione degli oggetti: Creare, leggere, aggiornare ed eliminare singoli elementi STAC all'interno delle collezioni
  • API di ricerca: Cerca gli elementi usando filtri spaziali e temporali, ordinamento e proprietà interrogabili
  • Configurazione: Gestire opzioni di rendering, mosaici, impostazioni delle tile, query e tipi di partizione
  • Conformità API: Recupera le classi di conformità API STAC e le informazioni sulla landing page

Operazioni dati (client.data)

  • Generazione delle tile: Genera tile di mappe (XYZ, TileJSON, WMTS) da collezioni, oggetti e mosaici
  • Visualizzazione dei dati: creare immagini di anteprima, ritagliare tramite GeoJSON o bounding box, estrarre i valori dei punti e calcolare statistiche
  • Operazioni Mosaic: Registra mosaici basati su ricerca STAC e recupera le tessere mosaico, TileJSON e le capacità WMTS
  • Map Legends: Recuperare le class map e le legende degli intervalli come immagini JSON o PNG
  • Metadati Asset: Recuperare set di matrici di tile e metadati degli asset per collezioni e elementi

Operazioni di Ingestione (client.ingestion)

  • Sorgenti di ingestione: Configurare sorgenti di ingestione utilizzando l'autenticazione tramite Managed Identity o token SAS
  • Definizioni di Ingestione: Definire l'ingestione automatica di cataloghi STAC da fonti di dati pubbliche e private
  • Ingestion Runs: Crea e monitora le run di ingestione con un monitoraggio dettagliato delle operazioni

Operazioni di firma di accesso condiviso (client.sharedAccessSignature)

  • Generazione di token: Genera token SAS con durata configurabile per le collezioni
  • Firma Asset: Firma gli HREF degli asset per download sicuri di asset di storage gestito
  • Revoca dei token: revocare i token quando necessario per controllare l'accesso

GeoCatalogo

Un GeoCatalog è la risorsa Azure di alto livello che memorizza e organizza i tuoi dati geospaziali. Offre:

  • Archiviazione gestita e ridondante per formato raster e data cube
  • Ottimizzazione cloud integrata per tipi di dati supportati
  • Un'API STAC gestita per tutti i dati memorizzati
  • Integrazione con la sicurezza e la gestione dell'identità di Azure tramite Microsoft Entra ID

STAC (Catalogo Risorse SpatioTemporal)

STAC è una specifica aperta per l'organizzazione e la descrizione dei dati geospaziali. Computer Planetario Pro di Microsoft utilizza STAC per fornire:

  • Collezioni: Raggruppamenti logici di dataset geospaziali correlati
  • Elementi: Risorse individuali (ad esempio, immagini satellitari, raster) con metadati
  • Asset: I file dati effettivamente citati da STAC Items

Examples

Questa sezione fornisce frammenti di codice che coprono i processi di lavoro comuni del GeoCatalog. Per esempi completi funzionanti, consulta la cartella degli esempi.

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

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

Ottieni i dettagli degli articoli 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)}`);

Crea una collezione 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");

Registrare e renderizzare le tessere mosaico

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

Estrazione dei valori dei punti

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

Genera tessere mappa

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

Configura la fonte di ingestione

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

Gestione dell'ingestione dei dati

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

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

Risoluzione dei problemi

Generale

La libreria client di Planetary Computer Pro solleverà eccezioni definite in 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

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in tempo reale chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Altro codice di esempio

Per esempi completi funzionanti, vedi i singoli file di esempio:

Scenario Sample
Gestione della collezione STAC stacCreateCollectionSample.ts
Gestione degli Elementi STAC stacCreateItemSample.ts
Ricerca STAC stacSearchSample.ts
Registrazione dei mosaici dataRegisterMosaicsSearchSample.ts
Generazione delle tessere mappate dataGetTileSample.ts
Valori in punti dataGetPointSample.ts
Impostazione dell'ingestione ingestionCreateSourceSample.ts
Gestione dell'ingestione ingestionCreateSample.ts
Token SAS sharedAccessSignatureGetTokenSample.ts
Leggende sulla Mappa dataGetLegendSample.ts

Documentazione aggiuntiva

Contributing

Se desideri contribuire a questa libreria, leggi la guida contributi per saperne di più su come costruire e testare il codice.

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per ulteriori informazioni, visitare il sito cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un cla e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire semplicemente le istruzioni fornite dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando la nostra cla.

Questo progetto ha adottato il codice di comportamento open source Microsoft. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

  • Last updated on