GeoCatalog'a Toplu Yükleme API'si ile veri ekleme

Bu makalede, Toplu Alım API'sini kullanarak bir GeoCatalog'a aynı anda birçok jeo-uzamsal veri varlığını nasıl alabileceğiniz gösterilmektedir. İlk olarak bir GeoCatalog Alma Kaynağı oluşturup yapılandıracağız. Alma Kaynağı oluşturmak, GeoCatalog kaynağı ile mevcut jeo-uzamsal verilerinizin depolama konumu arasında güvenli bir bağlantı kurar. Ardından, alınan verileri depolamak için GeoCatalog kaynağınızda bir SpatioTemporal Erişim Kataloğu (STAC) Koleksiyonu oluşturacağız. Son olarak Toplu Alım API'sini kullanarak alım iş akışını başlatacağız. Bu adımları tamamladığınızda jeo-uzamsal verileriniz sisteme aktarılıp GeoCatalog arayüzleri ve API'lerinden erişilebilir.

Önkoşullar

Azure aboneliğinizde:

• GeoCatalog
• Azure Depolama Hesabı

Depolama hesabınızın blob kapsayıcısındaki jeo-uzamsal veri kümesi:

• Jeo-uzamsal veri varlıkları (örneğin, GeoTIFF dosyaları)
• İlişkili STAC Öğeleri, bu varlıklar için STAC Öğeleri oluşturur .
• Tüm STAC Öğelerini ve coğrafi veri varlıklarını referans alan bir STAC Koleksiyonu JSON.

Yerel /geliştirme ortamınızda:

• Python 3.10 (veya üzeri) çalıştıran bir Python ortamı.
• Azure CLI
• Azure'da oturum açtınız

Microsoft Planet Computer Pro'nın Azure Blob Depolama kapsayıcısına erişimi olmalıdır. Bu makalede, bu erişimi vermek için geçici bir SAS belirteci kimlik bilgisi oluşturup kullanacağız. Alternatif olarak, Yönetilen Kimlik veya sabit kodlanmış SAS Belirteçleri ayarlamak için bu kılavuzları kullanabilirsiniz.

• Yönetilen kimlik aracılığıyla Microsoft Planetary Computer Pro'da Veri Yükleme Kimlik Bilgilerini ayarlama
• SAS Belirteçlerini kullanarak Microsoft Planet Computer Pro için Alım Kimlik Bilgilerini ayarlama

REST API

Alma Kaynağı Oluştur

Alma kaynağı oluşturma, GeoCatalog için jeo-uzamsal verilerin hangi kaynaktan alınacağını ve alma iş akışında hangi kimlik doğrulama mekanizmasının kullanılacağını tanımlar.

1. Pip kullanarak Gerekli Python modüllerini yükleme

   pip install pystac-client azure-identity requests azure-storage-blob pyyaml
   

2. Gerekli Python modüllerini içeri aktarma

   import os
   import requests
   from azure.identity import AzureCliCredential
   from datetime import datetime, timedelta, timezone
   import azure.storage.blob
   from urllib.parse import urlparse
   import yaml
   

3. Gerekli sabitleri ortamınıza göre ayarlama

   MPCPRO_APP_ID = "https://geocatalog.spatio.azure.com"
   CONTAINER_URI = "<container_uri>" # The URI for the blob storage container housing your geospatial data
   GEOCATALOG_URI = "<geocatalog uri>" # The URI for your GeoCatalog can be found in the Azure portal resource overview 
   API_VERSION = "2026-04-15"
   

4. SAS Belirtecini oluşturma

   # Parse the container URL
   parsed_url = urlparse(CONTAINER_URI)
   account_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
   account_name = parsed_url.netloc.split(".")[0]
   container_name = parsed_url.path.lstrip("/")
   
   credential = azure.identity.AzureCliCredential()
   blob_service_client = azure.storage.blob.BlobServiceClient(
       account_url=account_url,
       credential=credential,
   )
   
   now = datetime.now(timezone.utc).replace(microsecond=0)
   key = blob_service_client.get_user_delegation_key(
       key_start_time=now + timedelta(hours=-1),
       key_expiry_time=now + timedelta(hours=1),
   )
   
   sas_token = azure.storage.blob.generate_container_sas(
       account_name=account_name,
       container_name=container_name,
       user_delegation_key=key,
       permission=azure.storage.blob.ContainerSasPermissions(
           read=True,
           list=True,
       ),
       start=now + timedelta(hours=-1),
       expiry=now + timedelta(hours=1),
   )
   

5. GeoCatalog API erişim belirtecini alma

   # Obtain an access token
   credential = AzureCliCredential()
   access_token = credential.get_token(f"{MPCPRO_APP_ID}/.default")
   

6. Veri aktarma kaynağı API'si için POST yükü oluşturma

   # Payload for the POST request
   payload = {
       "Kind": "SasToken",
       "connectionInfo": {
           "containerUrl": CONTAINER_URI,
           "sasToken": sas_token,
       },
   }
   

7. POST yükünü alma kaynağı uç noktasına göndererek alma kaynağını oluşturma

   # STAC Collection API endpoint
   endpoint = f"{GEOCATALOG_URI}/inma/ingestion-sources"
   
   # Make the POST request
   response = requests.post(
       endpoint,
       json=payload,
       headers={"Authorization": f"Bearer {access_token.token}"},
       params={"api-version": API_VERSION},
   )
   

8. Yanıtı doğrulama

   # Print the response
   if response.status_code == 201:
       print("Ingestion source created successfully")
       ingestion_source_id = response.json().get("id") #saved for later to enable resource clean up
   else:
       print(f"Failed to create ingestion: {response.text}")
   

Uyarı

Bu adımların birden çok kez arka arkaya çalıştırılması 409 yanıtıyla sonuçlandı:

Container url <container uri> already contains a SAS token ingestion source with id <sas token id>

Alma kaynağı API'si, aynı kapsayıcı URL'si için birden fazla alma kaynağı oluşturmanıza izin vermez. Çakışmaları önlemek için, yeni bir tane oluşturmadan önce mevcut alım kaynaklarını temizlediğinizden emin olun. Ayrıntılar için Kaynakları temizleme bölümüne bakın.

Koleksiyon Oluştur

STAC koleksiyonu, STAC Öğeleri ve ilişkili jeo-uzamsal varlıkları için üst düzey kapsayıcıdır. Bu bölümde, sonraki bölümde aldığımız jeo-uzamsal verileri barındıracak GeoCatalog içinde bir STAC koleksiyonu oluşturacağız.

1. Gerekli modülleri içeri aktarma

   import os
   import requests
   import yaml
   from pprint import pprint
   from azure.identity import AzureCliCredential
   

2. Gerekli sabitleri ortamınıza göre ayarlama

   MPCPRO_APP_ID = "https://geocatalog.spatio.azure.com"
   GEOCATALOG_URI = "<geocatalog uri>" # The URI for your GeoCatalog can be found in the Azure portal resource overview 
   API_VERSION = "2026-04-15"
   
   COLLECTION_ID = "example-collection" #You can your own collection ID
   COLLECTION_TITLE = "Example Collection" #You can your own collection title    
   

3. GeoCatalog API erişim belirtecini alma

   # Obtain an access token
   credential = AzureCliCredential()
   access_token = credential.get_token(f"{MPCPRO_APP_ID}/.default")
   

4. Temel bir STAC koleksiyonu spesifikasyonu oluşturma

   collection = {
       "id": COLLECTION_ID,
       "type": "Collection",
       "title": COLLECTION_TITLE,
       "description": "An example collection",
       "license": "CC-BY-4.0",
       "extent": {
           "spatial": {"bbox": [[-180, -90, 180, 90]]},
           "temporal": {"interval": [["2018-01-01T00:00:00Z", "2018-12-31T23:59:59Z"]]},
       },
       "links": [],
       "stac_version": "1.0.0",
       "msft:short_description": "An example collection",
   }
   

   Uyarı

   Bu örnek koleksiyon belirtimi, bir koleksiyonun temel bir örneğidir. STAC koleksiyonları ve STAC açık standardı hakkında daha fazla bilgi için bkz. STAC'ye genel bakış. Eksiksiz bir STAC koleksiyonu oluşturma hakkında daha fazla bilgi için bkz. STAC Koleksiyonu Oluşturma.

5. Koleksiyon API'siyle yeni koleksiyon oluşturma

   response = requests.post(
       f"{GEOCATALOG_URI}/stac/collections",
       json=collection,
       headers={"Authorization": "Bearer " + access_token.token},
       params={"api-version": API_VERSION},
   )
   

6. Yanıt sonucunu doğrulama

   if response.status_code == 201:
       print("Collection created successfully")
       pprint(response.json())
   else:
       print(f"Failed to create ingestion: {response.text}")
   

Bağlantı Oluşturma ve İş Akışı Çalıştırma

Bu son adımda toplu alım iş akışını başlatmak için alım API'sini kullanıyoruz.

1. Gerekli modülleri içeri aktarma

   import os
   import requests
   import yaml
   from azure.identity import AzureCliCredential
   

2. Gerekli sabitleri ortamınıza göre ayarlama

   MPCPRO_APP_ID = "https://geocatalog.spatio.azure.com"
   GEOCATALOG_URI = "<geocatalog uri>" # The URI for your GeoCatalog can be found in the Azure portal resource overview 
   API_VERSION = "2026-04-15"
   
   COLLECTION_ID = "example-collection" #You can your own collection ID
   catalog_href = "<catalog_href>" #The blob storage location of the STAC Catalog JSON file
   
   skip_existing_items = False
   keep_original_assets = False
   timeout_seconds = 300
   

3. GeoCatalog API erişim belirtecini alma

   # Obtain an access token
   credential = AzureCliCredential()
   access_token = credential.get_token(f"{MPCPRO_APP_ID}/.default")
   

4. Toplu Veri Yükleme API'si için POST yükü oluşturma

   url = f"{GEOCATALOG_URI}/inma/collections/{COLLECTION_ID}/ingestions"
   body = {
       "importType": "StaticCatalog",
       "sourceCatalogUrl": catalog_href,
       "skipExistingItems": skip_existing_items,
       "keepOriginalAssets": keep_original_assets,
   }
   

5. Yükü Toplu Alma API'sine gönderin.

   ing_response = requests.post(
       url,
       json=body,
       timeout=timeout_seconds,
       headers={"Authorization": f"Bearer {access_token.token}"},
       params={"api-version": API_VERSION},
   )
   

6. Yanıtı doğrulayın.

   if ing_response.status_code == 201:
       print("Ingestion created successfully")
       ingestion_id = ing_response.json()["ingestionId"]
       print(f"Created ingestion with ID: {ingestion_id}")
   else:
       print(f"Failed to create ingestion: {ing_response.text}")
   

7. Alma iş akışının durumunu doğrulayın.

   runs_endpoint = (
       f"{geocatalog_url}/inma/collections/{collection_id}/ingestions/{ingestion_id}/runs"
   )
   
   wf_response = requests.post(
       runs_endpoint,
       headers={"Authorization": f"Bearer {access_token.token}"},
       params={"api-version": API_VERSION},
   )
   
   if wf_response.status_code == 201:
       print("Workflow started successfully")
   else:
       print(f"Failed to create ingestion run: {wf_response.text}")
   
   

İş akışı tamamlandıktan sonra GeoCatalog STAC veya veri API'lerini veya Veri Gezgini'ni kullanarak jeo-uzamsal verilerinizi sorgulayabilir, alabilir veya görselleştirebilirsiniz. Sorunlarla karşılaşırsanız sorun giderme kılavuzuna veya alma hata kodları listesine bakın.

Kaynakları temizle

• Alma kaynağını silme

  del_is_endpoint = f"{GEOCATALOG_URI}/inma/ingestion-sources/{ingestion_source_id}"
  del_is_response = requests.delete(
      del_is_endpoint,
      headers={"Authorization": f"Bearer {access_token.token}"},
      params={"api-version": API_VERSION},
  )
  
  if del_is_response.status_code == 200:
      print("Ingestion source deleted successfully")
  else:
      print(f"Failed to delete ingestion source")
  

Python SDK'sı

Planet Computer Pro Python SDK'sını yükleyin:

pip install azure-planetarycomputer azure-identity azure-storage-blob

Alma Kaynağı Oluştur

from azure.planetarycomputer import PlanetaryComputerProClient
from azure.identity import DefaultAzureCredential
from datetime import datetime, timedelta, timezone
from urllib.parse import urlparse
import azure.storage.blob

client = PlanetaryComputerProClient(
    endpoint="<your-geocatalog-url>",
    credential=DefaultAzureCredential()
)

CONTAINER_URI = "<container_uri>"

# Generate SAS token using azure-storage-blob (same as REST API approach)
parsed_url = urlparse(CONTAINER_URI)
account_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
account_name = parsed_url.netloc.split(".")[0]
container_name = parsed_url.path.lstrip("/")

credential = DefaultAzureCredential()
blob_service_client = azure.storage.blob.BlobServiceClient(
    account_url=account_url,
    credential=credential,
)
now = datetime.now(timezone.utc).replace(microsecond=0)
key = blob_service_client.get_user_delegation_key(
    key_start_time=now + timedelta(hours=-1),
    key_expiry_time=now + timedelta(hours=1),
)
sas_token = azure.storage.blob.generate_container_sas(
    account_name=account_name,
    container_name=container_name,
    user_delegation_key=key,
    permission=azure.storage.blob.ContainerSasPermissions(read=True, list=True),
    start=now + timedelta(hours=-1),
    expiry=now + timedelta(hours=1),
)

# Create the ingestion source
ingestion_source = client.ingestion.create_source({
    "kind": "SasToken",
    "connectionInfo": {
        "containerUrl": CONTAINER_URI,
        "sasToken": sas_token,
    },
})
print(f"Ingestion source created: {ingestion_source['id']}")

Koleksiyon Oluştur

collection = {
    "id": "example-collection",
    "type": "Collection",
    "title": "Example Collection",
    "description": "An example collection",
    "license": "CC-BY-4.0",
    "extent": {
        "spatial": {"bbox": [[-180, -90, 180, 90]]},
        "temporal": {"interval": [["2018-01-01T00:00:00Z", "2018-12-31T23:59:59Z"]]},
    },
    "links": [],
    "stac_version": "1.0.0",
    "msft:short_description": "An example collection",
}

poller = client.stac.begin_create_collection(body=collection)
result = poller.result()
print(f"Collection created: {result}")

Bağlantı Oluşturma ve İş Akışı Çalıştırma

COLLECTION_ID = "example-collection"
catalog_href = "<catalog_href>"  # Blob storage location of the STAC Catalog JSON file

ingestion = client.ingestion.create(COLLECTION_ID, {
    "importType": "StaticCatalog",
    "sourceCatalogUrl": catalog_href,
    "skipExistingItems": False,
    "keepOriginalAssets": False,
})
ingestion_id = ingestion.id
print(f"Created ingestion with ID: {ingestion_id}")

# Start the ingestion workflow
run = client.ingestion.create_run(COLLECTION_ID, ingestion_id)
print("Workflow started successfully")

Kaynakları temizle

client.ingestion.delete_source(ingestion_source["id"])
print("Ingestion source deleted successfully")

Daha fazla bilgi için bkz. Python SDK başvurusu.

Sonraki Adımlar

Artık birkaç öğe eklediğinize göre, verileri görselleştirme için yapılandırmanız gerekir.

Microsoft Planet Computer Pro'da koleksiyon yapılandırması

İlgili içerik

• Hızlı Başlangıç: Microsoft Planet Computer Pro GeoCatalog'da Bir Koleksiyona Tek Bir STAC Öğesi Alma
• Hızlı Başlangıç: Microsoft Planetary Computer Pro web arabirimini kullanarak verileri alma
• Microsoft Planet Computer Pro'ya veri alma
• Microsoft Gezegen Bilgisayarı Pro için veri kaynağı
• Veri alımı sorunlarını giderme
• Hata kodları: Microsoft Gezegen Bilgisayarı Pro işleme