Клиентская библиотека Azure Planetary Computer Pro для JavaScript — версия 1.0.0

Microsoft Planetary Computer Pro — это сервис управления геопространственными данными, построенный на гипермасштабной инфраструктуре Azure. GeoCatalog — это ресурс Azure, предоставляющий базовые возможности для погружения, управления, поиска и распространения геопространственных наборов данных с использованием открытой спецификации SpatioTemporal Asset Catalog (STAC).

Ключевые возможности

Управление коллекциями STAC: Создавайте, читайте, обновляйте и удаляйте коллекции и элементы STAC для организации ваших геопространственных наборов данных
Конфигурация коллекции: Настройте параметры рендера, мозаики, настройки тайлов и запросы для оптимизации производительности запросов и визуализации
Визуализация данных: генерируйте тайлы карты (XYZ, TileJSON, WMTS), предварительный просмотр изображений, обрезание по GeoJSON или ограничивающему блоку, извлечение значений точек и вычисление статистики
Операции мозаики: Регистрируйте поисковые мозаики STAC для запросов и поиска данных по пикселям, генерируйте тайлы из нескольких элементов и получайте доступ к возможностям TileJSON и WMTS
Legends Map: Получите легенды карт классов (категориальные) и интервальные легенды (непрерывные) в виде JSON или PNG изображений с заранее заданными цветными картами
Погружение данных: Настройте источники введения (управляемая идентичность или токен SAS), определите погружения из каталогов STAC, а также создайте и мониторите запуски
Операции STAC API: полные операции CRUD-обработки элементов, поиск с помощью пространственных/временных фильтров и сортировки, получение запросных свойств и проверка соответствия API
Безопасный доступ: генерируйте токены SAS с настраиваемой длительностью для коллекций, подписывайте HREF активов для безопасных загрузок и отзывайте токены — всё это защищено с помощью Microsoft Entra ID

Ключевые ссылки:

Начало работы

Поддерживаемые в настоящее время среды

Node.js LTS версии
Последние версии Safari, Chrome, Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Необходимые условия

Подписка Azure
Ресурс Microsoft Planetary Computer Pro GeoCatalog. Вы можете создать ресурс через портал Azure, Azure PowerShell или Azure CLI.

Конечную точку GeoCatalog (catalogUri) можно найти в портал Azure на странице обзора вашего ресурса GeoCatalog.

Установите пакет `@azure/planetarycomputer`.

Установите клиентскую библиотеку Azure Planetary Computer Pro для JavaScript с помощью npm:

npm install @azure/planetarycomputer

Создание и проверка подлинности `PlanetaryComputerProClient`

Существует несколько способов аутентификации с помощью сервиса Microsoft Planetary Computer Pro, и рекомендуемый способ — использовать Microsoft Entra ID для безопасной бесключевой аутентификации через библиотеку Azure Identity. Чтобы приступить к работе, выполните приведенные действия.

Install the Azure Identity package:

npm install @azure/identity

Зарегистрируйте новое приложение Microsoft Entra ID и предоставите доступ к Microsoft Planetary Computer Pro, назначив соответствующую роль вашему руководителю сервиса.
Задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения Microsoft Entra ID в качестве переменных среды: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.
Создайте клиент с помощью 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);

Основные понятия

PlanetaryComputerProClient

PlanetaryComputerProClientявляется основным интерфейсом для разработчиков, использующих клиентскую библиотеку Microsoft Planetary Computer Pro. Клиент предоставляет доступ к нескольким группам операций:

Операции STAC (`client.stac`)

Управление коллекциями: Создавайте, обновляйте, перечисляйте и удаляйте коллекции STAC для организации ваших геопространственных наборов данных
Управление элементами: создание, чтение, обновление и удаление отдельных элементов STAC в коллекциях
Поиск API: поиск элементов с помощью пространственных и временных фильтров, сортировки и запросных свойств
Настройка: Управление опциями рендера, мозаиками, настройками тайлов, запросами и типами разделов
Соответствие API: Получить классы соответствия API STAC и информацию о целевой странице

Операции с данными (`client.data`)

Генерация тайлов: генерировать тайлы карты (XYZ, TileJSON, WMTS) из коллекций, предметов и мозаик
Визуализация данных: создание предпросмотрных изображений, обрезание по GeoJSON или ограничивающему блоку, извлечение значений точек и вычисление статистики
Операции с мозаикой: регистрируйте мозаики на основе поиска STAC и извлекайте мозаичные плитки, возможности TileJSON и WMTS
Легенды карты: Получите карту классов и легенды интервалов в виде JSON или PNG изображений
Метаданные активов: Получить наборы матриц тайлов и метаданные активов для коллекций и предметов

Операции поглощения (`client.ingestion`)

Источники погружения: Настройте источники погружения с помощью управляемой идентичности или аутентификации токена SAS
Определения поглощения: Определите автоматизированное ввод каталога STAC из публичных и частных источников данных
Ingestion Runs: Создайте и контролируйте запуски с подробным отслеживанием операций

Операции подписи с общим доступом (`client.sharedAccessSignature`)

Генерация токенов: генерировать токены SAS с настраиваемой длительностью для коллекций
Подпись активов: Sign asset HREFs для безопасного скачивания управляемых хранилищ
Отклик токенов: Отзыв токенов при необходимости для контроля доступа

GeoCatalog

GeoCatalog — это ресурс высшего уровня Azure, который хранит и организует ваши геопространственные данные. Он предоставляет:

Zone-reundant, управляемое хранилище для растровых и кубических форматов
Встроенная облачная оптимизация для поддерживаемых типов данных
Управляемый API STAC для всех хранимых данных
Интеграция с безопасностью и управлением идентификацией Azure через Microsoft Entra ID

STAC (Каталог активов SpatioTemporal)

STAC — это открытая спецификация для организации и описания геопространственных данных. Microsoft Planetary Computer Pro использует STAC для предоставления:

Коллекции: логические группировки связанных геопространственных наборов данных
Элементы: Отдельные ресурсы (например, спутниковые изображения, растры) с метаданными
Активы: Реальные файлы данных, на которые ссылаются STAC Items

Примеры

В этом разделе представлены фрагменты кода, охватывающие распространённые рабочие процессы GeoCatalog. Полные рабочие примеры смотрите каталог образцов .

Список коллекций STAC
Поиск предметов STAC
Получите детали товара STAC
Создание коллекции STAC
Регистрируйте и отобразите мозаичные плитки
Значения точек извлечения
Генерация тайлов карты
Настройка источника введения
Управление вводом данных
Получите токен SAS

Список коллекций 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}`);
}

Поиск предметов 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}`);
}

Получите детали товара 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)}`);

Создать коллекцию 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");

Регистрируйте и отобразите мозаичные плитки

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

Значения точек извлечения

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

Генерация тайлов карты

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

Настройка источника введения

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

Управление вводом данных

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

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

Общая информация

Клиентская библиотека Planetary Computer Pro создаст исключения, определённые в 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

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Дальнейшие действия

Дополнительные примеры кода

Полные рабочие примеры смотрите в отдельных примерных файлах:

Сценарий	Sample
Управление коллекцией STAC	stacCreateCollectionSample.ts
Управление элементами STAC	stacCreateItemSample.ts
Поиск STAC	stacSearchSample.ts
Мозаичная регистрация	dataRegisterMosaicsSearchSample.ts
Генерация тайлов карты	dataGetTileSample.ts
Очки	dataGetPointSample.ts
Настройка Ingestion	ingestionCreateSourceSample.ts
Управление прогнанием	ingestionCreateSample.ts
Токен SAS	sharedAccessSignatureGetTokenSample.ts
Легенды карты	dataGetLegendSample.ts

Дополнительная документация

Узнайте больше о Microsoft Planetary Computer Pro
Прочитайте спецификацию STAC
Посмотрите, как развернуть ресурс GeoCatalog
Понимайте, как управлять доступом к Microsoft Planetary Computer Pro

Contributing

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по созданию и тестированию кода.

Этот проект приветствует взносы и предложения. Большинство вкладов требуют, чтобы вы согласились с соглашением о лицензии участника (CLA), заявив, что у вас есть право, и на самом деле, предоставьте нам права на использование вашего вклада. Для получения подробной информации посетите cla.microsoft.com.

При отправке запроса на вытягивание бот CLA автоматически определяет, нужно ли предоставить соглашение об уровне обслуживания и украсить pr соответствующим образом (например, метка, комментарий). Просто следуйте инструкциям, предоставленным ботом. Это необходимо сделать только один раз во всех репозиториях с помощью нашего CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-07-02