Azure Planetary Computer Pro Client Library for JavaScript - version 1.0.0

Der Microsoft Planetary Computer Pro ist ein geospatial Datenmanagement-Service, der auf der hyperskalierten Infrastruktur von Azure basiert. Der GeoCatalog ist eine Azure-Ressource, die grundlegende Funktionen bietet, um georäumliche Datensätze mithilfe der SpatioTemporal Asset Catalog (STAC) offenen Spezifikation zu erfassen, zu verwalten, zu suchen und zu verteilen.

Wichtige Funktionen

  • STAC-Sammlungsverwaltung: Erstellen Sie, lesen, aktualisieren und löschen Sie STAC-Sammlungen und -Objekte, um Ihre geospatialen Datensätze zu organisieren
  • Sammlungskonfiguration: Konfigurieren Sie Renderoptionen, Mosaike, Kacheleinstellungen und Abfrageobjekte, um Abfrageleistung und Visualisierung zu optimieren
  • Datenvisualisierung: Kartenkacheln (XYZ, TileJSON, WMTS) erstellen, Bilder vorschauen, mit GeoJSON oder Begrenzungsbox beschneiden, Punktwerte extrahieren und Statistiken berechnen
  • Mosaikoperationen: Registrieren Sie STAC-suchbasierte Mosaike für pixelweise Datenabfrage und -abruf, generieren Sie Kacheln aus mehreren Elementen und greifen Sie auf TileJSON- und WMTS-Funktionen auf
  • Kartenlegenden: Rufen Sie Klassenkartenlegenden (kategorial) und Intervalllegenden (kontinuierlich) als JSON- oder PNG-Bilder mit vordefinierten Farbkarten ab
  • Datenaufnahme: Einrichtung von Eingabequellen (Managed Identity oder SAS-Token), Definition von Eingaben aus STAC-Katalogen sowie Erstellung sowie Überwachung von Aufnahmeläufen
  • STAC-API-Operationen: Vollständige CRUD-Operationen auf Artikeln, Suche mit räumlichen/zeitlichen Filtern und Sortierung, Abfrage abfragbarer Eigenschaften und Überprüfung der API-Konformität
  • Sicherer Zugriff: Generiere SAS-Token mit konfigurierbarer Dauer für Sammlungen, signiere HREFs von Vermögenswerten für sichere Downloads und widerrufe Token – alles gesichert über Microsoft Entra ID

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

Weitere Details finden Sie in unserer Support-Richtlinie.

Prerequisites

Der GeoCatalog-Endpunkt (catalogUri) ist im Azure-Portal auf der Übersichtsseite Ihrer GeoCatalog-Ressource zu finden.

Installieren Sie das @azure/planetarycomputer-Paket

Installiere die Client-Bibliothek von Azure Planetary Computer Pro für JavaScript mit npm:

npm install @azure/planetarycomputer

Erstellen und Authentifizieren einer PlanetaryComputerProClient

Es gibt mehrere Möglichkeiten, sich mit dem Microsoft Planetary Computer Pro-Dienst zu authentifizieren, und die empfohlene Methode ist die Verwendung von Microsoft Entra ID für eine sichere, schlüssellose Authentifizierung über die Azure Identity-Bibliothek. Um loszulegen:

  1. Installiere das Azure Identity-Paket:
npm install @azure/identity

  1. Registrieren Sie eine neue Microsoft Entra ID-Anwendung und gewähren Sie Ihnen Zugang zu Microsoft Planetary Computer Pro, indem Sie Ihrem Service Principal die passende Rolle zuweisen.

  2. Legen Sie die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der Microsoft Entra ID Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Erstellen Sie den Client mit 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);

Wichtige Begriffe

PlanetaryComputerProClient

PlanetaryComputerProClientist die primäre Schnittstelle für Entwickler, die die Client-Bibliothek Microsoft Planetary Computer Pro verwenden. Der Client bietet Zugriff auf mehrere Operationsgruppen:

STAC-Betrieb (client.stac)

  • Sammlungsverwaltung: Erstellen Sie, aktualisieren, listen und löschen Sie STAC-Sammlungen, um Ihre geospatialen Datensätze zu organisieren
  • Artikelverwaltung: Erstellen Sie, lesen, aktualisieren und löschen Sie einzelne STAC-Einträge innerhalb der Sammlungen
  • Such-API: Suche nach Elementen mit räumlichen und zeitlichen Filtern, Sortier- und abfragbaren Eigenschaften
  • Konfiguration: Verwaltung von Renderoptionen, Mosaiken, Kacheleinstellungen, Abfragen und Partitionstypen
  • API-Konformität: Abruf von STAC-API-Konformitätsklassen und Informationen zur Landingpage

Datenoperationen (client.data)

  • Kachelgenerierung: Generiere Kartenkacheln (XYZ, TileJSON, WMTS) aus Sammlungen, Objekten und Mosaiken
  • Datenvisualisierung: Erstellen Sie Vorschaubilder, schneiden Sie sie mit GeoJSON oder Begrenzungsbox, extrahieren Sie Punktwerte und rechnen Sie Statistiken
  • Mosaikoperationen: Registrieren Sie STAC-suchbasierte Mosaike und rufen Mosaikkacheln, TileJSON- und WMTS-Fähigkeiten ab
  • Kartenlegenden: Klassenkarten- und Intervalllegenden als JSON- oder PNG-Bilder abrufen
  • Asset-Metadaten: Abruf von Kachelmatrixsets und Asset-Metadaten für Sammlungen und Items

Aufnahmeoperationen (client.ingestion)

  • Aufnahmequellen: Einrichtung von Eingabequellen mit Managed Identity oder SAS-Token-Authentifizierung
  • Aufnahmedefinitionen: Definieren Sie automatisierte STAC-Katalogaufnahme aus öffentlichen und privaten Datenquellen
  • Aufnahmeläufe: Erstellen und überwachen Sie Aufnahmeläufe mit detaillierter Betriebsverfolgung

Shared-Access-Signaturoperationen (client.sharedAccessSignature)

  • Token-Generierung: Generiere SAS-Token mit konfigurierbarer Dauer für Sammlungen
  • Asset Signing: Signieren Sie Asset-HREFs für sichere Downloads von Managed Storage Assets
  • Token-Widerruf: Widerrufe Token, wenn nötig zur Kontrolle des Zugriffs

GeoKatalog

Ein GeoCatalog ist die oberste Azure-Ressource, die Ihre georäumlichen Daten speichert und organisiert. Sie bietet:

  • Zonenredundanter, verwalteter Speicher für Raster- und Datenwürfel-Formate
  • Eingebaute Cloud-Optimierung für unterstützte Datentypen
  • Eine verwaltete STAC-API für alle gespeicherten Daten
  • Integration mit Azure's Sicherheits- und Identitätsmanagement über Microsoft Entra ID

STAC (SpatioTemporal Asset Katalog)

STAC ist eine offene Spezifikation zur Organisation und Beschreibung geospatial Daten. Microsoft Planetary Computer Pro verwendet STAC, um Folgendes bereitzustellen:

  • Sammlungen: Logische Gruppierungen verwandter georäumlicher Datensätze
  • Artikel: Einzelne Assets (z. B. Satellitenbilder, Raster) mit Metadaten
  • Assets: Die tatsächlichen Datendateien, auf die von STAC-Items referenziert werden

Examples

Dieser Abschnitt bietet Codeschnipsel, die gängige GeoCatalog-Workflows abdecken. Für vollständige funktionierende Beispiele siehe das Samples-Verzeichnis .

Liste der STAC-Sammlungen

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

Suche nach STAC-Objekten

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

Details zu STAC-Artikeln erhalten

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

Erstellen Sie eine STAC-Sammlung

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

Mosaikfliesen registrieren und rendern

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

Punktwerte extrahieren

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

Kartenkacheln generieren

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

Einrichtung der Aufnahmequelle

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

Datenerfassungsverwaltung

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

Hol dir einen 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

Allgemein

Die Client-Bibliothek von Planetary Computer Pro erzeugt Ausnahmen, die in Azure Core definiert sind.

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

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann das Logging zur Laufzeit aktiviert werden, indem setLogLevel im @azure/logger aufgerufen wird:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Weitere Beispielcode

Für vollständige Arbeitsbeispiele siehe die einzelnen Beispieldateien:

Scenario Beispiel
STAC-Sammlungsmanagement stacCreateCollectionSample.ts
STAC-Gegenstandsverwaltung stacCreateItemSample.ts
STAC-Suche stacSearchSample.ts
Mosaik-Registrierung dataRegisterMosaicsSearchSample.ts
Kartenkachelgenerierung dataGetTileSample.ts
Punktwerte dataGetPointSample.ts
Aufnahme-Setup ingestionCreateSourceSample.ts
Aufnahmemanagement ingestionCreateSample.ts
SAS-Token sharedAccessSignatureGetTokenSample.ts
Kartenlegenden dataGetLegendSample.ts

Zusätzliche Dokumentation

Contributing

Wenn Sie zu dieser Bibliothek beitragen möchten, lesen Sie bitte den beitragenden Leitfaden, um mehr darüber zu erfahren, wie man den Code erstellt und testet.

Dieses Projekt begrüßt Beiträge und Vorschläge. Die meisten Beiträge erfordern, dass Sie einem Mitwirkenden-Lizenzvertrag (CLA) zustimmen, der erklärt, dass Sie das Recht haben, uns tatsächlich die Rechte zur Nutzung Ihres Beitrags zu gewähren. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie eine Pullanfrage einreichen, bestimmt ein CLA-Bot automatisch, ob Sie eine CLA bereitstellen und die PR entsprechend dekorieren müssen (z. B. Bezeichnung, Kommentar). Folgen Sie einfach den Anweisungen des Bots. Sie müssen dies nur einmal über alle Reposs hinweg tun, indem Sie unsereN CLA verwenden.

Dieses Projekt hat den Microsoft Open Source Code of Conductübernommen. Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Kommentare haben.

  • Last updated on