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

O Computador Planetário Pro da Microsoft é um serviço de gerenciamento de dados geoespaciais construído sobre a infraestrutura em hiperescala do Azure. O GeoCatalog é um recurso do Azure que oferece capacidades fundamentais para ingerir, gerenciar, pesquisar e distribuir conjuntos de dados geoespaciais usando a especificação aberta SpatioTemporal Asset Catalog (STAC).

Principais funcionalidades

  • Gestão de Coleções STAC: Crie, leia, atualize e exclua coleções e itens STAC para organizar seus conjuntos de dados geoespaciais
  • Configuração da Coleção: Configure opções de renderização, mosaicos, configurações de tiles e consultas para otimizar o desempenho das consultas e a visualização
  • Visualização de Dados: Gerar blocos de mapas (XYZ, TileJSON, WMTS), pré-visualizar imagens, recortar por GeoJSON ou caixa delimitadora, extrair valores de pontos e calcular estatísticas
  • Operações Mosaic: Registrar mosaicos baseados em busca STAC para consulta e recuperação de dados pixel a pixel, gerar tiles a partir de múltiplos itens e acessar as capacidades TileJSON e WMTS
  • Legendas de Mapas: 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: Configure fontes de ingestão (token Managed Identity ou SAS), defina ingestiones a partir de catálogos STAC e crie e monitore execuções de ingestão
  • Operações de API STAC: Operações completas de CRUD em itens, busca 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

Links de chave:

Como começar

Ambientes com suporte no momento

Veja nossa política suporte para 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 Computador Planetário Pro da Microsoft, e a recomendável é usar o Microsoft Entra ID para autenticação segura e sem chave via a biblioteca Azure Identity. Para começar:

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

  1. Registre uma nova aplicação Microsoft Entra ID e conceda acesso ao Computador Planetário Pro da Microsoft atribuindo o papel adequado ao seu principal de serviço.

  2. Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo 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 principais

PlanetaryComputerProClient

PlanetaryComputerProClienté a interface principal para desenvolvedores que utilizam a biblioteca cliente Computador Planetário Pro da Microsoft. 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 exclua coleções STAC para organizar seus conjuntos de dados geoespaciais
  • Gerenciamento de Itens: Criar, ler, atualizar e excluir itens individuais do STAC dentro das coleções
  • API de busca: Busque itens usando filtros espaciais e temporais, ordenação e propriedades consultáveis
  • Configuração: Gerenciar opções de renderização, mosaicos, configurações de blocos, consultáveis e tipos de partição
  • Conformidade com 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 blocos 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: Registrar mosaicos baseados em busca STAC e recuperar mosaicos, capacidades TileJSON e WMTS
  • Legendas do Mapa: Recuperar legendas de mapas de classe e intervalos como imagens JSON ou PNG
  • Metadados de Ativos: 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 token Managed Identity ou SAS
  • Definições de Ingestão: Defina a ingestão automatizada de catálogos STAC a partir de fontes de dados públicas e privadas
  • Execuções de Ingestão: Crie e monitore as Execuções de Ingestão com acompanhamento detalhado da operação

Operações de Assinatura de Acesso Compartilhado (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 gerenciado
  • Revogação de Tokens: Revogar tokens quando necessário para controlar o acesso

GeoCatálogo

Um GeoCatálogo é o recurso de alto nível do Azure que armazena e organiza seus dados geoespaciais. Ele fornece:

  • Armazenamento gerenciado e redundante de zona para formatos raster e cubo de dados
  • Otimização em nuvem embutida para tipos de dados suportados
  • Uma API STAC gerenciada para todos os dados armazenados
  • Integração com a segurança e gerenciamento de identidade do Azure via Microsoft Entra ID

STAC (Catálogo de Ativos EspaçoTemporal)

STAC é uma especificação aberta para organizar e descrever dados geoespaciais. Computador Planetário Pro da Microsoft 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 arquivos de dados reais referenciados pelos Itens STAC

Exemplos

Esta seção fornece trechos de código cobrindo fluxos de trabalho comuns do GeoCatalog. Para exemplos completos de trabalho, veja o diretório de exemplos .

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

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

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

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

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

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

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

Resolução de problemas

Geral

A biblioteca cliente Planetary Computer Pro irá abrir 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}`);
  }
}

Registro em log

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 AZURE_LOG_LEVEL ambiente como info. Alternativamente, o logging 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.

Próximas Etapas 

Mais código de exemplo

Para exemplos completos e funcionais, veja os arquivos de exemplo individuais:

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

Documentação adicional

Contributing

Se você 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 recebe contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença de Colaborador) declarando que você tem o direito de, e realmente fazer, conceder-nos os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a 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 de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.

  • Last updated on