Azure Planetary Computer Pro biblioteca cliente para JavaScript - versión 1.0.0

El Ordenador Planetario de Microsoft Pro es un servicio de gestión de datos geoespaciales construido sobre la infraestructura hiperescala de Azure. El GeoCatálogo es un recurso de Azure que proporciona capacidades fundamentales para ingerir, gestionar, buscar y distribuir conjuntos de datos geoespaciales utilizando la especificación abierta SpatioTemporal Asset Catalog (STAC).

Principales funcionalidades

  • Gestión de colecciones STAC: Crea, lee, actualiza y elimina colecciones y elementos STAC para organizar tus conjuntos de datos geoespaciales
  • Configuración de la colección: Configura opciones de renderizado, mosaicos, ajustes de mosaicos y consultas para optimizar el rendimiento de las consultas y la visualización
  • Visualización de datos: Generar mosaicos de mapa (XYZ, TileJSON, WMTS), previsualizar imágenes, recortar por GeoJSON o caja delimitadora, extraer valores de puntos y calcular estadísticas
  • Operaciones Mosaic: Registrar mosaicos basados en búsqueda STAC para consulta y recuperación de datos píxel a píxel, generar mosaicos a partir de múltiples elementos y acceder a las capacidades de TileJSON y WMTS
  • Leyendas de mapas: Recuperar leyendas de mapas de clase (categóricas) y leyendas de intervalo (continuas) como imágenes JSON o PNG con mapas de color predefinidos
  • Ingestión de datos: Configurar fuentes de ingestión (token de Identidad Gestionada o SAS), definir las ingestiones a partir de catálogos STAC y crear y supervisar las ingestiones
  • Operaciones de API STAC: Operaciones completas de CRUD sobre los ítems, búsqueda con filtros espaciales/temporales y ordenación, recuperación de propiedades consultables y comprobación de la conformidad con la API
  • Acceso seguro: Genera tokens SAS con duración configurable para colecciones, firma HREFs de activos para descargas seguras y revoca tokens, todo ello protegido mediante Microsoft Entra ID

Vínculos clave:

Cómo empezar

Entornos admitidos actualmente

Consulta nuestra política soporte para más detalles.

Prerequisites

El endpoint de GeoCatalog (catalogUri) se puede encontrar en el Azure Portal, en la página de resumen de tu recurso GeoCatalog.

Instalación del paquete @azure/planetarycomputer

Instala la biblioteca cliente de Azure Planetary Computer Pro para JavaScript con npm:

npm install @azure/planetarycomputer

Creación y autenticación de un PlanetaryComputerProClient

Existen varias formas de autenticarse con el servicio Ordenador Planetario de Microsoft Pro y la recomendada es utilizar Microsoft Entra ID para una autenticación segura y sin clave a través de la biblioteca Azure Identity. Primeros pasos:

  1. Instala el paquete Azure Identity:
npm install @azure/identity

  1. Registra una nueva solicitud Microsoft Entra ID y concede acceso a Ordenador Planetario de Microsoft Pro asignando el rol adecuado a tu principal de servicio.

  2. Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación Microsoft Entra ID como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Crea el cliente 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);

Conceptos clave

PlanetaryComputerProClient

PlanetaryComputerProClientes la interfaz principal para desarrolladores que utilizan la biblioteca cliente Ordenador Planetario de Microsoft Pro. El cliente proporciona acceso a varios grupos de operaciones:

Operaciones STAC (client.stac)

  • Gestión de colecciones: Crea, actualiza, lista y elimina colecciones STAC para organizar tus conjuntos de datos geoespaciales
  • Gestión de artículos: Crear, leer, actualizar y eliminar elementos individuales de STAC dentro de colecciones
  • API de búsqueda: Buscar elementos usando filtros espaciales y temporales, ordenación y propiedades consultables
  • Configuración: Gestionar opciones de renderizado, mosaicos, ajustes de mosaicos, consultas y tipos de partición
  • Conformidad con API: Recuperar la información de las clases de conformidad con la API STAC y la página de destino

Operaciones de datos (client.data)

  • Generación de mosaicos: Generar mosaicos de mapas (XYZ, TileJSON, WMTS) a partir de colecciones, elementos y mosaicos
  • Visualización de datos: Crear imágenes de previsualización, recortar mediante GeoJSON o caja delimitadora, extraer valores de puntos y calcular estadísticas
  • Operaciones Mosaic: Registrar mosaicos basados en búsqueda STAC y recuperar mosaicos de mosaicos, capacidades de TileJSON y WMTS
  • Leyendas de mapas: Recuperar las leyendas de mapa de clases e intervalos como imágenes JSON o PNG
  • Metadatos de activos: Recuperar conjuntos de matrices de mosaicos y metadatos de activos para colecciones y elementos

Operaciones de Ingestión (client.ingestion)

  • Fuentes de ingestión: Configurar fuentes de ingestión usando autenticación por token de Identidad Gestionada o SAS
  • Definiciones de ingestión: Definir la ingesta automatizada de catálogos STAC a partir de fuentes de datos públicas y privadas
  • Intake Runs: Crea y monitoriza los intakes runs con un seguimiento detallado de las operaciones

Operaciones de firma de acceso compartido (client.sharedAccessSignature)

  • Generación de tokens: Generar tokens SAS con duración configurable para colecciones
  • Firma de activos: Firma los HREFs de activos para descargas seguras de activos de almacenamiento gestionado
  • Revocación de tokens: Revoca tokens cuando sea necesario para controlar el acceso

GeoCatálogo

Un GeoCatálogo es el recurso de Azure de primer nivel que almacena y organiza tus datos geoespaciales. Proporciona:

  • Almacenamiento gestionado redundante por zonas para formatos raster y cubo de datos
  • Optimización en la nube integrada para tipos de datos soportados
  • Una API STAC gestionada para todos los datos almacenados
  • Integración con la seguridad y gestión de identidades de Azure a través de Microsoft Entra ID

STAC (Catálogo de Activos EspacioTemporales)

STAC es una especificación abierta para organizar y describir datos geoespaciales. Ordenador Planetario de Microsoft Pro utiliza STAC para proporcionar:

  • Colecciones: Agrupaciones lógicas de conjuntos de datos geoespaciales relacionados
  • Elementos: Activos individuales (por ejemplo, imágenes satelitales, rasteres) con metadatos
  • Activos: Los archivos de datos reales referenciados por STAC Items

Examples

Esta sección proporciona fragmentos de código que cubren flujos de trabajo comunes de GeoCatalog. Para ejemplos completos de funcionamiento, consulta el directorio de ejemplos .

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

Búsqueda de artículos 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}`);
}

Obtén los detalles del artículo 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)}`);

Crear una colección 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");

Registrar y renderizar mosaicos

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

Extraer valores de puntos

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

Generar losetas de mapa

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

Configurar la fuente de ingestió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 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}`);

Gestión de la Ingestión de Datos

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

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

Solución de problemas

General

La biblioteca cliente de Planetary Computer Pro generará excepciones definidas en 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}`);
  }
}

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Alternativamente, el registro puede activarse en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Pasos siguientes

Más código de ejemplo

Para ejemplos completos de funcionamiento, véanse los archivos de muestra individuales:

Scenario Muestra
Gestión de Colecciones STAC stacCreateCollectionSample.ts
Gestión de ítems STAC stacCreateItemSample.ts
Búsqueda STAC stacSearchSample.ts
Registro en mosaico dataRegisterMosaicsSearchSample.ts
Generación de Mosaicos de Mapa dataGetTileSample.ts
Valores en puntos dataGetPointSample.ts
Configuración de la ingestión ingestionCreateSourceSample.ts
Gestión de la ingestión ingestionCreateSample.ts
SAS Token sharedAccessSignatureGetTokenSample.ts
Leyendas del mapa dataGetLegendSample.ts

Documentación adicional

Contributing

Si quieres contribuir a esta biblioteca, por favor lee la guía contribución para aprender más sobre cómo construir y probar el código.

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para obtener más detalles, visite cla.microsoft.com.

Al enviar una solicitud de incorporación de cambios, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

  • Last updated on