Azure Planetary Computer Pro biblioteka klienta dla JavaScript - wersja 1.0.0

Komputer planetarny Microsoft Pro to usługa zarządzania danymi geoprzestrzennymi oparta na hiperskalowej infrastrukturze Azure. GeoCatalog to zasób Azure, który zapewnia podstawowe możliwości pobierania, zarządzania, wyszukiwania i dystrybucji zbiorów danych geoprzestrzennych z wykorzystaniem otwartej specyfikacji SpatioTemporal Asset Catalog (STAC).

Kluczowe możliwości

  • Zarządzanie kolekcjami STAC: Twórz, odczytuj, aktualizuj i usuwaj kolekcje i elementy STAC, aby uporządkować swoje zbiory danych geoprzestrzennych
  • Konfiguracja kolekcji: Konfiguruj opcje renderowania, mozaiki, ustawienia kafelków i zapytania do optymalizacji wydajności zapytań i wizualizacji
  • Wizualizacja danych: generowanie kafelków mapy (XYZ, TileJSON, WMTS), podgląd, przycinanie za pomocą GeoJSON lub ramek ograniczających, wyodrębnianie wartości punktów oraz obliczanie statystyk
  • Operacje mozaikowe: Rejestruj mozaiki oparte na wyszukiwaniu STAC do zapytań i pobierania danych według pikseli, generuj kafelki z wielu elementów oraz korzystaj z możliwości TileJSON i WMTS
  • Legendy map: Pobieranie legend map klas (kategorycznych) oraz legend interwałowych (ciągłych) jako obrazów JSON lub PNG z predefiniowanymi mapami kolorów
  • Pobieranie danych: Konfigurowanie źródeł pobierania (Managed Identity lub token SAS), definiowanie ingestacji z katalogów STAC oraz tworzenie i monitorowanie przebiegów pobierania
  • Operacje API STAC: Pełne operacje CRUD na elementach, wyszukiwanie z filtrami przestrzennymi/temporalnymi i sortowaniem, pobieranie właściwości zapytywalnych oraz sprawdzanie zgodności z API
  • Bezpieczny dostęp: generuj tokeny SAS o konfigurowalnym czasie trwania dla kolekcji, podpisuj HREF aktywów dla bezpiecznych pobrań oraz cofnij tokeny — wszystko zabezpieczone za pomocą Microsoft Entra ID

Kluczowe linki:

Rozpoczęcie pracy

Obecnie obsługiwane środowiska

  • Wersje LTS systemu Node.js
  • Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Zobacz naszą politykę support po więcej szczegółów.

Wymagania wstępne

Endpoint GeoCatalog (catalogUri) można znaleźć w Azure Portal na stronie przeglądowej zasobu GeoCatalog.

Instalowanie pakietu @azure/planetarycomputer

Zainstaluj bibliotekę klienta Azure Planetary Computer Pro dla JavaScript za pomocą npm:

npm install @azure/planetarycomputer

Twórz i uwierzytelnij PlanetaryComputerProClient

Istnieje kilka sposobów uwierzytelniania za pomocą usługi Komputer planetarny Microsoft Pro, a zalecanym sposobem jest użycie Microsoft Entra ID do bezpiecznego, bezkluczowego uwierzytelniania za pośrednictwem biblioteki Azure Identity. Aby rozpocząć pracę:

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

  1. Zarejestruj nową aplikację Microsoft Entra ID i przyznaj dostęp do Komputer planetarny Microsoft Pro, przypisując odpowiednią rolę swojemu przedstawicielowi usługi.

  2. Ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i tajnego hasła klienta aplikacji Microsoft Entra ID jako zmienne środowiskowe: 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);

Najważniejsze pojęcia

PlanetaryComputerProClient

PlanetaryComputerProClientjest głównym interfejsem dla programistów korzystających z biblioteki klienta Komputer planetarny Microsoft Pro. Klient udostępnia kilka grup operacyjnych:

Operacje STAC (client.stac)

  • Zarządzanie kolekcjami: Twórz, aktualizuj, listuj i usuwaj kolekcje STAC, aby uporządkować swoje zbiory danych geoprzestrzennych
  • Zarządzanie przedmiotami: Tworzenie, czytanie, aktualizacja i usuwanie pojedynczych elementów STAC w kolekcjach
  • API wyszukiwania: Wyszukaj elementy za pomocą filtrów przestrzennych i czasowych, sortowania oraz właściwości zapytywalnych
  • Konfiguracja: Zarządzanie opcjami renderowania, mozaikami, ustawieniami kafelków, zapytaniami i typami partycji
  • Zgodność API: Pobierz klasy zgodności z API STAC oraz informacje o stronach docelowych

Operacje danych (client.data)

  • Generowanie kafelków: Generuj kafelki mapy (XYZ, TileJSON, WMTS) z kolekcji, przedmiotów i mozaik
  • Wizualizacja danych: Twórz obrazy podglądowe, przycinaj według GeoJSON lub ramek ograniczających, wyodrębniaj wartości punktów i obliczaj statystyki
  • Operacje mozaikowe: Rejestruj mozaiki oparte na wyszukiwaniu STAC i pobieraj mozaikowe kafelki, możliwości TileJSON i WMTS
  • Legendy map: Pobieranie map klas i legend interwałów jako obrazy JSON lub PNG
  • Metadane zasobów: Pobieranie zestawów macierzy kafelków oraz metadanych zasobów dla kolekcji i elementów

Operacje pobierania (client.ingestion)

  • Źródła pobierania: Konfiguruj źródła pobierania z użyciem uwierzytelniania tokenów Managed Identity lub SAS
  • Definicje pobierania: Definiuj automatyczne pobieranie katalogu STAC z publicznych i prywatnych źródeł danych
  • Uruchomienia pobierania: Tworzenie i monitorowanie przebiegów pobierania z dokładnym śledzeniem operacji

Operacje współdzielonej sygnatury dostępu (client.sharedAccessSignature)

  • Generowanie tokenów: Generuj tokeny SAS z konfigurowalnym czasem trwania dla kolekcji
  • Podpisywanie aktywów: Podpisuj HREF zasobów do bezpiecznego pobierania zarządzanych zasobów pamięci masowej
  • Odwołanie tokenów: Cofnij tokeny, gdy jest to konieczne, aby kontrolować dostęp

GeoCatalog

GeoKatalog to najwyższy zasób Azure, który przechowuje i organizuje Twoje dane geoprzestrzenne. Zapewnia:

  • Magazynowanie zarządzane z redukcją stref dla formatów rastrowych i kostek danych
  • Wbudowana optymalizacja chmury dla obsługiwanych typów danych
  • Zarządzane API STAC dla wszystkich przechowywanych danych
  • Integracja z bezpieczeństwem i zarządzaniem tożsamością w Azure poprzez Microsoft Entra ID

STAC (Katalog Zasobów SpatioTemporal)

STAC to otwarta specyfikacja do organizowania i opisywania danych geoprzestrzennych. Komputer planetarny Microsoft Pro wykorzystuje STAC do zapewnienia:

  • Kolekcje: Logiczne grupowania powiązanych zbiorów danych geoprzestrzennych
  • Elementy: Pojedyncze zasoby (np. obrazy satelitarne, rastre) z metadanymi
  • Aktywa: Rzeczywiste pliki danych odwołane przez elementy STAC

Examples

Ta sekcja zawiera fragmenty kodu obejmujące typowe workflowy GeoCatalog. Pełne przykłady robocze można znaleźć w katalogu próbek .

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

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

Uzyskaj szczegóły dotyczące przedmiotów 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)}`);

Stwórz kolekcję 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");

Kafelki mozaikowe rejestrujące i renderujące

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

Wartości punktów ekstrakcyjne

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

Generuj kafelki mapy

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

Ustaw źródło pobierania

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

Zarządzanie pozyskiwaniem danych

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

Zdobądź żeton 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}`);

Troubleshooting

Ogólne

Biblioteka klienta Planetary Computer Pro będzie generować wyjątki zdefiniowane w 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

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie logowanie można włączyć w czasie działania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentacją pakietu @azure/logger.

Następne kroki

Więcej przykładowego kodu

Pełne przykłady robocze można znaleźć w poszczególnych przykładowych plikach:

Scenario Sample
Zarządzanie kolekcją STAC stacCreateCollectionSample.ts
Zarządzanie przedmiotami STAC stacCreateItemSample.ts
STAC Search stacSearchSample.ts
Rejestracja Mosaic dataRegisterMosaicsSearchSample.ts
Generowanie kafelków mapy dataGetTileSample.ts
Wartości punktowe dataGetPointSample.ts
Konfiguracja pobierania ingestionCreateSourceSample.ts
Zarządzanie spożyciem ingestionCreateSample.ts
Token sygnatury dostępu współdzielonego sharedAccessSignatureGetTokenSample.ts
Legendy mapy dataGetLegendSample.ts

Dodatkowa dokumentacja

Contributing

Jeśli chcesz przyczynić się do tej biblioteki, przeczytaj przewodnik wkład aby dowiedzieć się więcej o budowaniu i testowaniu kodu.

Ten projekt z zadowoleniem przyjmuje wkład i sugestie. Większość kontrybucja wymaga zgody na umowę licencyjną współautora (CLA), deklarując, że masz prawo, a w rzeczywistości przyznaj nam prawa do korzystania z twojego wkładu. Szczegółowe informacje można znaleźć na stronie cla.microsoft.com.

Po przesłaniu żądania ściągnięcia bot CLA automatycznie określi, czy musisz podać cla i odpowiednio ozdobić żądanie ściągnięcia (np. etykieta, komentarz). Po prostu postępuj zgodnie z instrukcjami dostarczonymi przez bota. Należy to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego CLA.

W tym projekcie jest używany Kodeks postępowania firmy Microsoft dla oprogramowania typu open source. Aby uzyskać więcej informacji, zobacz Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania) lub wyślij wiadomość e-mail na adres opencode@microsoft.com w przypadku jakichkolwiek dodatkowych pytań lub komentarzy.

  • Last updated on