Azure Planetary Computer Pro biblioteca cliente para JavaScript - versão 1.0.0

O Microsoft Planetary Computer Pro é um serviço de gestão de dados geoespaciais construído sobre a infraestrutura hiperescala da Azure. O GeoCatalog é um recurso do Azure que fornece capacidades fundamentais para ingerir, gerir, pesquisar e distribuir conjuntos de dados geoespaciais utilizando a especificação aberta SpatioTemporal Asset Catalog (STAC).

Capacidades chave

  • Gestão de Coleções STAC: Crie, leia, atualize e elimine coleções e itens STAC para organizar os seus conjuntos de dados geoespaciais
  • Configuração da Coleção: Configure opções de renderização, mosaicos, definições de tiles e queryables para otimizar o desempenho das consultas e visualização
  • Visualização de Dados: Gerar blocos de mapa (XYZ, TileJSON, WMTS), pré-visualizar imagens, recortar por GeoJSON ou caixa delimitadora, extrair valores de pontos e calcular estatísticas
  • Operações Mosaic: Registar mosaicos baseados em pesquisa STAC para consulta e recuperação de dados pixel a pixel, gerar tiles a partir de múltiplos itens e aceder às capacidades TileJSON e WMTS
  • Legendas de Mapa: Recuperar legendas de mapas de classe (categóricas) e legendas de intervalo (contínuas) como imagens JSON ou PNG com mapas de cor predefinidos
  • Ingestão de Dados: Configurar fontes de ingestão (Managed Identity ou token SAS), definir ingestiones a partir de catálogos STAC e criar e monitorizar execuções de ingestão
  • Operações de API STAC: Operações CRUD completas em itens, pesquisa com filtros espaciais/temporais e ordenação, recuperação de propriedades consultáveis e verificação da conformidade com a API
  • Acesso Seguro: Gerar tokens SAS com duração configurável para coleções, assinar HREFs de ativos para downloads seguros e revogar tokens — tudo protegido via Microsoft Entra ID

Ligações principais:

Como Começar

Ambientes atualmente suportados

Consulte a nossa política de suporte para obter mais detalhes.

Pré-requisitos

O endpoint do GeoCatalog (catalogUri) pode ser encontrado no portal do Azure, na página de visão geral do seu recurso GeoCatalog.

Instalar o pacote @azure/planetarycomputer

Instale a biblioteca cliente Azure Planetary Computer Pro para JavaScript comnpm:

npm install @azure/planetarycomputer

Criar e autenticar um PlanetaryComputerProClient

Existem várias formas de autenticação com o serviço Microsoft Planetary Computer Pro e a recomendada é usar o Microsoft Entra ID para autenticação segura e sem chave através da biblioteca Azure Identity. Para começar:

  1. Instale o pacote Azure Identity:
npm install @azure/identity

  1. Registe uma nova aplicação Microsoft Entra ID e conceda acesso ao Microsoft Planetary Computer Pro, atribuindo o papel adequado ao seu principal de serviço.

  2. Defina os valores do ID do cliente, ID do inquilino e segredo do cliente da aplicação Microsoft Entra ID como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. Crie o 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);

Conceitos-chave

PlanetaryComputerProClient

PlanetaryComputerProClienté a interface principal para programadores que utilizam a biblioteca cliente Microsoft Planetary Computer Pro. O cliente fornece acesso a vários grupos de operações:

Operações STAC (client.stac)

  • Gestão de Coleções: Crie, atualize, liste e elimine coleções STAC para organizar os seus conjuntos de dados geoespaciais
  • Gestão de Itens: Criar, ler, atualizar e eliminar itens individuais do STAC dentro das coleções
  • API de Pesquisa: Pesquisa de itens usando filtros espaciais e temporais, ordenação e propriedades consultáveis
  • Configuração: Gerir opções de renderização, mosaicos, definições de mosaicos, consultáveis e tipos de partição
  • Conformidade com a API: Recuperar as classes de conformidade com a API STAC e informações sobre a página de destino

Operações de Dados (client.data)

  • Geração de Tiles: Gerar tiles de mapas (XYZ, TileJSON, WMTS) a partir de coleções, itens e mosaicos
  • Visualização de Dados: Criar imagens de pré-visualização, recortar por GeoJSON ou bounding box, extrair valores de pontos e calcular estatísticas
  • Operações Mosaic: Registar mosaicos baseados em pesquisa STAC e recuperar mosaicos de mosaicos, capacidades TileJSON e WMTS
  • Legendas do Mapa: Recuperar legendas de mapa de classes e intervalos como imagens JSON ou PNG
  • Metadados de Ativo: Recuperar conjuntos de matrizes de tiles e metadados de ativos para coleções e itens

Operações de Ingestão (client.ingestion)

  • Fontes de Ingestão: Configure fontes de ingestão usando autenticação por Identidade Gerida ou token SAS
  • Definições de Ingestão: Defina a ingestão automática de catálogos STAC a partir de fontes de dados públicas e privadas
  • Corridas de Ingestão: Crie e monitorize as Execuções de Ingestão com um acompanhamento detalhado da operação

Operações de Assinatura de Acesso Partilhado (client.sharedAccessSignature)

  • Geração de Tokens: Gerar tokens SAS com duração configurável para coleções
  • Assinatura de Ativos: Assinar HREFs de ativos para downloads seguros de ativos de armazenamento gerido
  • Revogação de Tokens: Revogar tokens quando necessário para controlar o acesso

GeoCatálogo

Um GeoCatálogo é o recurso principal do Azure que armazena e organiza os seus dados geoespaciais. Dispõe o seguinte:

  • Armazenamento gerido e redundante de zona para formatos raster e cubo de dados
  • Otimização na cloud incorporada para tipos de dados suportados
  • Uma API STAC gerida para todos os dados armazenados
  • Integração com a segurança e gestão de identidade do Azure através do Microsoft Entra ID

STAC (Catálogo de Ativos SpatioTemporal)

STAC é uma especificação aberta para organizar e descrever dados geoespaciais. A Microsoft Planetary Computer Pro utiliza o STAC para fornecer:

  • Coleções: Agrupamentos lógicos de conjuntos de dados geoespaciais relacionados
  • Itens: Ativos individuais (por exemplo, imagens de satélite, rasters) com metadados
  • Ativos: Os ficheiros de dados reais referenciados pelos Itens STAC

Exemplos

Esta secção fornece excertos de código que cobrem fluxos de trabalho comuns do GeoCatálogo. Para exemplos completos e funcionais, consulte o diretório de exemplos .

Lista das Coleções 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}`);
}

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

Obtenha Detalhes dos Itens 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)}`);

Criar uma Coleção 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");

Mosaico de Registo e Renderização

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

Extrair Valores de Pontos

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

Gerar Blocos 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 a Fonte de Ingestão

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

Gestão da Ingestão de Dados

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

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

Troubleshooting

General

A biblioteca cliente Planetary Computer Pro irá levantar exceções definidas no 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

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Alternativamente, o registo pode ser ativado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Passos seguintes

Mais código de exemplo

Para exemplos funcionais completos, consulte os ficheiros de exemplo individuais:

Scenario Sample
Gestão de Coleções STAC stacCreateCollectionSample.ts
Gestão de Itens STAC stacCreateItemSample.ts
Busca STAC stacSearchSample.ts
Registo em mosaico dataRegisterMosaicsSearchSample.ts
Geração de Tiles do Mapa dataGetTileSample.ts
Valores de Pontos dataGetPointSample.ts
Configuração de Ingestão ingestionCreateSourceSample.ts
Gestão da Ingestão ingestionCreateSample.ts
SAS Token sharedAccessSignatureGetTokenSample.ts
Lendas do Mapa dataGetLegendSample.ts

Documentação adicional

Contributing

Se quiser contribuir para esta biblioteca, por favor leia o guia contribuição para saber mais sobre como construir e testar o código.

Este projeto acolhe contribuições e sugestões. A maioria das contribuições exige que você concorde com um Contrato de Licença de Colaborador (CLA) declarando que você tem o direito de, e realmente concede, os direitos de usar sua contribuição. Para mais detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar o PR adequadamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta Open Source da Microsoft. Para mais informações, veja as Perguntas Frequentes do Código de Conduta ou contacte opencode@microsoft.com com quaisquer questões ou comentários adicionais.

  • Last updated on