Azure Planetary Computer Pro client library for JavaScript - version 1.0.0

Microsoft Planetary Computer Pro, Azure'un hiper ölçekli altyapısı üzerine inşa edilmiş bir coğrafi veri yönetim hizmetidir. GeoCatalog, SpatioTemporal Asset Catalog (STAC) açık spesifikasyonunu kullanarak coğrafi uzamsal veri setlerini almak, yönetmek, arama yapmak ve dağıtmak için temel yetenekler sağlayan bir Azure kaynağıdır.

Önemli özellikler

  • STAC Koleksiyon Yönetimi: Coğrafi tabanlı veri setlerinizi düzenlemek için STAC koleksiyonlarını ve öğelerini oluşturun, okuyun, güncelleyin ve silinin
  • Koleksiyon Yapılandırması: Görüntüleme seçeneklerini, mozaikleri, karo ayarlarını ve sorgulanabilir öğeleri yapılandırarak sorgu performansını ve görselleştirmesini optimize edin
  • Veri Görselleştirme: Harita karoları (XYZ, TileJSON, WMTS) oluşturun, görüntüleri önizlemek, GeoJSON veya sınırlayıcı kutu ile kırpmak, nokta değerlerini çıkarmak ve istatistikleri hesaplamak
  • Mozaik İşlemleri: STAC arama tabanlı mozaikleri piksel bazında veri sorgusu ve geri alma için kaydedin, birden fazla öğeden karo oluşturun ve TileJSON ile WMTS yeteneklerine erişin
  • Harita Efsaneleri: Sınıf harita efsanelerini (kategorik) ve aralık efsanelerini (sürekli) JSON veya PNG görselleri olarak önceden tanımlanmış renk haritalarıyla elde edin
  • Veri Alımı: Alınım kaynaklarını (Yönetilen Kimlik veya SAS tokenı) kurun, STAC kataloglarından alımları tanımlayın ve alım çalışmalarını oluşturup izleyin
  • STAC API Operasyonları: Öğeler üzerinde tam CRUD işlemleri, mekânsal/zamansal filtrelerle arama ve sıralama, sorgulanabilir özellikleri almak ve API uyumluluğunu kontrol etmek
  • Güvenli Erişim: Koleksiyonlar için yapılandırılabilir süreyle SAS tokenları oluşturun, güvenli indirmeler için varlık HREF'lerini imzalayın ve tokenları iptal edin—hepsi Microsoft Entra ID ile güvence altına alın

Önemli bağlantılar:

Başlangıç Yapmak

Şu anda desteklenen ortamlar

Daha fazla detay için destek politikamız adresimize bakınız.

Prerequisites

GeoCatalog uç noktası (catalogUri), Azure portal'da GeoCatalog kaynağınızın genel bakış sayfasında bulunabilir.

@azure/planetarycomputer paketini yükleme

JavaScript için Azure Planetary Computer Pro client library kurulumu :npm

npm install @azure/planetarycomputer

Bir PlanetaryComputerProClient oluşturun ve kimlik doğrulaması yapın.

Microsoft Planetary Computer Pro hizmetiyle kimlik doğrulamanın birkaç yolu vardır ve önerilen yöntem, Azure Identity kütüphanesi üzerinden güvenli, anahtarsız kimlik doğrulama için Microsoft Entra ID'yi kullanmaktır. Başlamak için:

  1. Azure Identity paketini kur:
npm install @azure/identity

  1. Yeni bir Microsoft Entra ID başvurusu kaydedin ve hizmet yöneticisinize uygun rolü atayarak Microsoft Planetary Computer Pro'ya erişim tanıyın.

  2. Microsoft Entra ID uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  3. DefaultAzureCredential kullanarak istemciyi oluşturun:

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

Temel kavramlar

PlanetaryComputerProClient

PlanetaryComputerProClientMicrosoft Planetary Computer Pro istemci kütüphanesini kullanan geliştiriciler için ana arayüzdür. İstemci birkaç işlem grubuna erişim sağlar:

STAC Operasyonları (client.stac)

  • Koleksiyon Yönetimi: Coğrafi uzamsal veri setlerinizi düzenlemek için STAC koleksiyonlarını oluşturun, güncelleyin, listeleyin ve silinin
  • Eşya Yönetimi: Koleksiyonlar içindeki bireysel STAC öğelerini oluştur, okuyun, güncelleyin ve silinin
  • Arama APIsi: Uzaysal ve zamansal filtreler, sıralama ve sorgulanabilir özellikler kullanarak öğeleri arayın
  • Yapılandırma: Render seçeneklerini, mozaikleri, karo ayarlarını, sorgulanabilir öğeleri ve bölüm türlerini yönetin
  • API Uyumluluğu: STAC API uyum sınıflarını ve açılış sayfası bilgilerini alın

Veri İşlemleri (client.data)

  • Karo Üretimi: Koleksiyonlardan, öğelerden ve mozaiklerden harita karoları (XYZ, TileJSON, WMTS) oluşturun
  • Veri Görselleştirme: Önizleme görüntüleri oluşturun, GeoJSON veya sınırlayıcı kutu ile kırpın, puan değerlerini çıkarın ve istatistikleri hesaplayın
  • Mozaik Operasyonları: STAC arama tabanlı mozaikleri kaydedin ve mozaik karolarını, TileJSON ve WMTS yeteneklerini geri alın
  • Harita Efsaneleri: Sınıf haritası ve aralık efsanelerini JSON veya PNG görselleri olarak alın
  • Varlık Metaverisi: Koleksiyonlar ve öğeler için karo matrisi setlerini ve varlık meta verilerini elde edin

Yutma Operasyonları (client.ingestion)

  • Alım Kaynakları: Yönetilen Kimlik veya SAS token doğrulaması kullanarak alım kaynaklarını kurun
  • Alım Tanımları: Kamu ve özel veri kaynaklarından otomatik STAC katalog alımını tanımlayın
  • Tüketim Çalışmaları: Detaylı işlem takibi ile alım çalışmaları oluşturun ve izleyin

Paylaşılan Erişim İmza İşlemleri (client.sharedAccessSignature)

  • Token Üretimi: Koleksiyonlar için yapılandırılabilir süreyle SAS tokenları oluşturun
  • Varlık İmzalama: Yönetilen depolama varlıklarının güvenli indirilmesi için varlık HREF'lerini imzalayın
  • Token İptal: Erişim kontrolü için gerektiğinde tokenları iptal et

GeoCatalog

GeoCatalog, coğrafi verilerinizi depolayan ve düzenleyen en üst düzey Azure kaynağıdır. Şunları sağlar:

  • Raster ve veri küpü formatları için bölge-yedekli, yönetilen depolama
  • Desteklenen veri türleri için yerleşik bulut optimizasyonu
  • Tüm depolanan veriler için yönetilen bir STAC API'si
  • Microsoft Entra ID aracılığıyla Azure'ın güvenlik ve kimlik yönetimi ile entegrasyon

STAC (Uzaylı-Zamansal Varlık Kataloğu)

STAC, coğrafi verileri düzenlemek ve tanımlamak için açık bir spesifikasyondur. Microsoft Planetary Computer Pro, STAC'ı şunları sağlamak için kullanır:

  • Koleksiyonlar: İlgili coğrafi veri setlerinin mantıksal gruplamaları
  • Öğeler: Meta verilerle birlikte bireysel varlıklar (örneğin, uydu görüntüleri, rasterler)
  • Varlıklar: STAC Öğeleri tarafından referans verilen gerçek veri dosyaları

Examples

Bu bölüm, yaygın GeoCatalog iş akışlarını kapsayan kod parçalarını içerir. Tam çalışma örnekleri için örnekler dizinine bakınız.

STAC Koleksiyonlarını Listele

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

STAC Öğeleri Araması

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

STAC Eşya Detaylarını Alı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 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)}`);

STAC Koleksiyonu Oluşturun

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

Mozaik Karoları Kaydet ve Render

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

Çıkarma Noktası Değerleri

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

Harita Karo Oluştur

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

Yutma Kaynağını Kur

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

Veri Alım Yönetimi

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

SAS Token Alı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 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

Planetary Computer Pro istemci kütüphanesi, Azure Core'da tanımlanan istisnaları ortaya çıkaracaktır.

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

Loglamayı etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma etkinleştirilebilir.

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki Adımlar

Daha fazla örnek kod

Tam çalışma örnekleri için bireysel örnek dosyalara bakınız:

Scenario Sample
STAC Koleksiyon Yönetimi stacCreateCollectionSample.ts
STAC Eşya Yönetimi stacCreateItemSample.ts
STAC Arama stacSearchSample.ts
Mozaik Kaydı dataRegisterMosaicsSearchSample.ts
Harita Karo Üretimi dataGetTileSample.ts
Puan Değerleri dataGetPointSample.ts
Yutma Kurulumu ingestionCreateSourceSample.ts
Yutma Yönetimi ingestionCreateSample.ts
SAS Belirteci sharedAccessSignatureGetTokenSample.ts
Harita Efsaneleri dataGetLegendSample.ts

Diğer belgeler

Contributing

Bu kütüphaneye katkıda bulunmak isterseniz, kodun nasıl oluşturulacağı ve test edileceği hakkında daha fazla bilgi edinmek için lütfen katkı rehberi adresini okuyun.

Bu proje katkıları ve önerileri memnuniyetle karşılar. Çoğu katkı, Katkıda Bulunan Lisans Sözleşmesi'ni (CLA) kabul ederek bize katkınızı kullanma hakları verme hakkına sahip olduğunuzu bildirmenizi gerektirir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Çekme isteği gönderdiğinizde, CLA botu otomatik olarak CLA sağlamanız gerekip gerekmediğini belirler ve çekme isteğini uygun şekilde süsler (örneğin, etiket, açıklama). Bot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Cla'mızı kullanarak bunu tüm depolarda yalnızca bir kez yapmanız gerekir.

Bu projede Microsoft Açık Kaynak Kullanım Şartları kabul edilmiştir. Daha fazla bilgi için Code of Conduct FAQ (Kullanım Kuralları Hakkında SSS) konusuna bakın veya sorularınızı ya da görüşlerinizi bildirmek için opencode@microsoft.com adresinden bize ulaşın.

  • Last updated on