Azure Planetary Computer Pro 클라이언트 라이브러리 for JavaScript - 버전 1.0.0

Microsoft 플래네터리 컴퓨터 프로 는 Azure의 하이퍼스케일 인프라 위에 구축된 지리공간 데이터 관리 서비스입니다. 지오카탈로그는 시공간 자산 카탈로그(STAC) 오픈 사양을 사용하여 지리공간 데이터셋을 수집, 관리, 검색 및 배포하는 기본 기능을 제공하는 Azure 리소스입니다.

주요 기능

STAC 컬렉션 관리: STAC 컬렉션과 항목을 생성, 읽기, 업데이트, 삭제하여 지리공간 데이터셋을 정리할 수 있습니다
컬렉션 구성: 렌더 옵션, 모자이크, 타일 설정, 쿼리 가능 요소를 구성하여 쿼리 성능과 시각화를 최적화하세요
데이터 시각화: 지도 타일(XYZ, TileJSON, WMTS) 생성, 미리보기 이미지, GeoJSON 또는 경계 상자로 자르기, 포인트 추출, 통계 계산
모자이크 연산: 픽셀 단위 데이터 쿼리 및 검색을 위해 STAC 검색 기반 모자이크를 등록하고, 여러 항목에서 타일을 생성하며, TileJSON 및 WMTS 기능에 접근하세요
지도 흔적: 클래스 지도 흔적(범주형)과 구간 흔적(연속형)을 JSON 또는 PNG 이미지로 미리 정의한 색상 맵으로 조회할 수 있습니다
데이터 인제스션: 인제스 소스(관리 식별 또는 SAS 토큰)를 설정하고, STAC 카탈로그에서 인젝션을 정의하며, 인제스 실행을 생성하고 모니터링합니다
STAC API 연산: 항목에 대한 완전한 CRUD 연산, 공간/시간 필터 및 정렬 검색, 쿼리 가능한 속성 검색, API 적합성 확인
보안 접근: 컬렉션을 위한 설정 가능한 지속 시간이 있는 SAS 토큰 생성, 안전한 다운로드를 위한 자산 HREF 서명, 토큰 취소 — 모두 Microsoft Entra ID를 통해 보호됩니다

키 링크:

시작하기

현재 지원되는 환경

Node.js의 LTS 버전
Safari, Chrome, Edge 및 Firefox의 최신 버전입니다.

자세한 내용은 저희 support 정책을 참조하세요.

사전 요구 사항

Azure 서비스 구독
Microsoft 플래네터리 컴퓨터 프로 지오카탈로그 자료입니다. 리소스는 Azure Portal, Azure PowerShell, 또는 Azure CLI를 통해 생성할 수 있습니다.

GeoCatalog 엔드포인트(catalogUri)는 Azure Portal의 GeoCatalog 리소스 개요 페이지에서 찾을 수 있습니다.

`@azure/planetarycomputer` 패키지 설치

JavaScriptnpm용 Azure Planetary Computer Pro 클라이언트 라이브러리를 설치하세요:

npm install @azure/planetarycomputer

`PlanetaryComputerProClient`를 만들고 인증하기

Microsoft 플래네터리 컴퓨터 프로 서비스와 인증하는 방법은 여러 가지가 있으며, 권장되는 방법은 Azure Identity 라이브러리를 통한 안전하고 키 없는 인증을 위해 Microsoft Entra ID를 사용하는 것입니다. 시작하려면:

Azure Identity 패키지를 설치하세요:

npm install @azure/identity

새로운 Microsoft Entra ID 애플리케이션을 등록하고, 서비스 책임자에게 적합한 역할을 할당하여 Microsoft 플래네터리 컴퓨터 프로 에 대한 접근 권한을 부여하세요.
Microsoft Entra ID 애플리케이션의 클라이언트 ID, 테넌트 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);

주요 개념

플래네터리컴퓨터프로클라이언트

PlanetaryComputerProClientMicrosoft 플래네터리 컴퓨터 프로 클라이언트 라이브러리를 사용하는 개발자들의 주요 인터페이스입니다. 클라이언트는 여러 연산 그룹에 접근할 수 있게 합니다:

STAC 운영 (`client.stac`)

컬렉션 관리: 지리 공간 데이터셋을 정리하기 위해 STAC 컬렉션을 생성, 업데이트, 목록 및 삭제할 수 있습니다
항목 관리: 컬렉션 내 개별 STAC 항목을 생성, 읽기, 업데이트, 삭제
검색 API: 공간 및 시간 필터, 정렬, 쿼리 가능한 속성을 사용하여 항목을 검색할 수 있습니다
구성: 렌더 옵션, 모자이크, 타일 설정, 쿼리 가능 요소, 파티션 유형 관리
API 적합성: STAC API 적합성 클래스 및 랜딩 페이지 정보를 조회하기

데이터 연산 (`client.data`)

타일 생성: 컬렉션, 아이템, 모자이크에서 지도 타일(XYZ, TileJSON, WMTS)을 생성합니다
데이터 시각화: 미리보기 이미지 생성, GeoJSON 또는 경계 상자로 자르기, 포인트 추출, 통계 계산
모자이크 작업: STAC 검색 기반 모자이크를 등록하고 모자이크 타일, TileJSON, WMTS 기능을 검색합니다
맵 범례: 클래스 지도 및 구간 선례를 JSON 또는 PNG 이미지로 불러옵니다
자산 메타데이터: 컬렉션 및 항목의 타일 매트릭스 세트 및 자산 메타데이터를 조회합니다

섭취 작업 (`client.ingestion`)

인제스 소스: 관리 신원 또는 SAS 토큰 인증을 사용하여 인제스 소스를 설정하세요
인지스 정의: 공공 및 비공개 데이터 소스에서 자동 STAC 카탈로그 인데스팅을 정의합니다
인지스 런: 자세한 작업 추적과 함께 인제스트 런을 생성하고 모니터링할 수 있습니다

공유 접근 서명 연산 (`client.sharedAccessSignature`)

토큰 생성: 컬렉션에 대해 설정 가능한 지속 시간을 가진 SAS 토큰 생성
자산 서명: 자산 HREF에 서명하여 관리되는 저장 자산의 안전한 다운로드를 수행합니다
토큰 취소: 접근 통제를 위해 필요 시 토큰을 취소합니다

지오카탈로그

지오카탈로그는 지리 공간 데이터를 저장하고 정리하는 최상위 Azure 리소스입니다. 이 콘솔은 다음과 같은 기능을 제공합니다.

래스터 및 데이터 큐브 포맷을 위한 존 중복 관리형 스토리지
지원되는 데이터 타입에 대한 내장 클라우드 최적화
저장된 모든 데이터를 위한 관리형 STAC API
Microsoft Entra ID를 통한 Azure의 보안 및 신원 관리와의 통합

STAC (시공간 자산 카탈로그)

STAC는 지리공간 데이터를 조직하고 기술하기 위한 오픈 명세입니다. Microsoft 플래네터리 컴퓨터 프로 는 STAC를 사용하여 다음을 제공합니다:

컬렉션: 관련 지리공간 데이터셋의 논리적 그룹화
항목: 메타데이터가 포함된 개별 자산(예: 위성 이미지, 래스터)
자산: STAC 항목이 참조하는 실제 데이터 파일

예제

이 섹션은 일반적인 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

General

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

로깅

로깅을 사용하도록 설정하면 오류에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 환경 변수AZURE_LOG_LEVEL를 info .로 설정합니다. 또는 런타임에 setLogLevel에서 @azure/logger를 호출하여 로깅을 활성화할 수 있습니다:

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

setLogLevel("info");

로그를 사용하도록 설정하는 방법에 대한 자세한 지침은 @azure/로거 패키지 문서를 참조하세요.

다음 단계

추가 샘플 코드

완전한 작업 예제는 개별 샘플 파일을 참조하세요:

시나리오	Sample
STAC 컬렉션 관리	stacCreateCollectionSample.ts
STAC 품목 관리	stacCreateItemSample.ts
STAC 검색	stacSearchSample.ts
모자이크 등록	dataRegisterMosaicsSearchSample.ts
맵 타일 생성	dataGetTileSample.ts
포인트 가치	dataGetPointSample.ts
입력 설정	ingestionCreateSourceSample.ts
섭취 관리	ingestionCreateSample.ts
SAS 토큰	sharedAccessSignatureGetTokenSample.ts
지도 전설	dataGetLegendSample.ts

추가 설명서

Contributing

이 라이브러리에 기여하고 싶으시다면, 코드 빌드 및 테스트 방법에 대해 더 알고 싶다면 기여 가이드를 읽어보시기 바랍니다.

이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여는 귀하가 귀하의 기여를 사용할 권리를 부여할 권리가 있음을 선언하는 CLA(기여자 사용권 계약)에 동의해야 합니다. 자세한 내용은 cla.microsoft.com 를 참조하십시오.

끌어오기 요청을 제출하면 CLA 봇은 CLA를 제공하고 PR을 적절하게 데코레이팅해야 하는지 여부를 자동으로 결정합니다(예: 레이블, 주석). 봇에서 제공하는 지침을 따르기만 하면 됩니다. CLA를 사용하여 모든 리포지토리에서 한 번만 이 작업을 수행해야 합니다.

이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 준수 사항 FAQ를 참조하거나 opencode@microsoft.com에 추가 질문 또는 의견을 알려주세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-07-02