Mata in data i GeoCatalog med Bulk Ingestion API

Den här artikeln visar hur du matar in många geospatiala datatillgångar samtidigt i en GeoCatalog med hjälp av API:et massinmatning. Först skapar och konfigurerar vi en GeoCatalog-inmatningskälla. När du skapar en inmatningskälla upprättas en säker anslutning mellan en GeoCatalog-resurs och lagringsplatsen för dina befintliga geospatiala data. Därefter skapar vi en STAC-samling (SpatioTemporal Access Catalog) i din GeoCatalog-resurs för att lagra data som matas in. Slutligen använder vi API:et för massinmatning för att initiera arbetsflödet för inmatning. När du är klar med de här stegen matas dina geospatiala data in och är tillgängliga från GeoCatalog-UIs och API:er.

Förutsättningar

I din Azure-abonnemang:

• GeoCatalog
• Azure Storage-konto

En geospatial datauppsättning i blobcontainern för lagringskontot:

• Geospatiala datatillgångar (till exempel GeoTIFF-filer)
• De associerade STAC-objekten Skapar STAC-objekt för dessa tillgångar.
• En STAC-samlings-JSON som refererar till alla STAC-objekt och geospatiala datatillgångar.

I din lokala/utvecklingsmiljö:

• En Python miljö som kör Python 3.10 (eller senare).
• Azure CLI
• Du är inloggad i Azure

Microsoft Planetary Computer Pro måste ha åtkomst till Azure Blob Storage-containern. I den här artikeln skapar och använder vi en tillfällig SAS-tokenautentiseringsuppgift för att bevilja den här åtkomsten. Du kan också använda dessa guider för att konfigurera hanterad identitet eller hårdkodade SAS-token.

• Konfigurera autentiseringsuppgifter för inmatning för Microsoft Planetary Computer Pro med hjälp av hanterad identitet
• Konfigurera autentiseringsuppgifter för inmatning för Microsoft Planetary Computer Pro med sas-token

REST API

Skapa inmatningskälla

Att skapa en inmatningskälla definierar för GeoCatalog vilken källa som ska matas in geospatiala data från och vilken mekanism för autentiseringsuppgifter som ska användas i inmatningsarbetsflödet.

1. Installera de nödvändiga python-modulerna använda pip

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

2. Importera nödvändiga Python-moduler

   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. Ange nödvändiga konstanter enligt din miljö

   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. Skapa SAS-token

   # 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. Hämta åtkomsttoken för GeoCatalog API

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

6. Skapa POST-nyttolast för inmatningskällans API

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

7. Skapa inmatningskällan genom att skicka POST-nyttolasten till slutpunkten för inmatningskällan

   # 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. Verifiera svaret

   # 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}")
   

Anmärkning

Om du kör de här stegen mer än en gång resulterar det i ett 409-svar:

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

Med inmatningskällans API kan du inte skapa mer än en inmatningskälla för samma container-URL. Undvik konflikter genom att rensa alla befintliga inmatningskällor innan du skapar en ny. Mer information finns i Rensa resurser.

Skapa samling

En STAC-samling är en högnivåcontainer för STAC-objekt och deras associerade geospatiala tillgångar. I det här avsnittet skapar vi en STAC-samling i vår GeoCatalog för att lagra de geospatiala data som vi matar in i nästa avsnitt.

1. Importera de moduler som krävs

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

2. Ange nödvändiga konstanter enligt din miljö

   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. Hämta åtkomsttoken för GeoCatalog API

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

4. Skapa en grundläggande STAC-samlingsspecifikation

   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",
   }
   

   Anmärkning

   Den här exempelsamlingsspecifikationen är ett grundläggande exempel på en samling. Mer information om STAC-samlingar och stac open-standarden finns i STAC-översikten. Mer information om hur du skapar en fullständig STAC-samling finns i Skapa STAC-samling.

5. Skapa den nya samlingen med samlings-API:et

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

6. Verifiera svarsresultatet

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

Skapa anslutning och kör arbetsflöde

I det här sista steget använder vi inmatnings-API:et för att initiera ett arbetsflöde för massinmatning.

1. Importera nödvändiga moduler

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

2. Ange nödvändiga konstanter enligt din miljö

   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. Hämta åtkomsttoken för GeoCatalog API

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

4. Skapa POST-nyttolasten för API för massinmatning

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

5. Skicka nyttolasten till bulkdatainmatnings-API:et.

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

6. Verifiera svaret.

   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. Kontrollera statusen för inmatningsarbetsflödet.

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

När arbetsflödet är klart kan du fråga, hämta eller visualisera dina geospatiala data med geoCatalog STAC eller data-API:er eller med Datautforskaren. Om du stöter på problem kan du läsa felsökningsguiden eller listan över felkoder för inmatning.

Rensa resurser

• Ta bort inmatningskälla

  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

Installera Python-SDK:t för Planetary Computer Pro:

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

Skapa inmatningskälla

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']}")

Skapa samling

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

Skapa anslutning och kör arbetsflöde

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

Rensa resurser

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

Mer information finns i referensen Python SDK.

Nästa steg

Nu när du har lagt till några objekt bör du konfigurera data för visualisering.

Samlingskonfiguration i Microsoft Planetary Computer Pro

Relaterat innehåll

• Snabbstart: Mata in ett enda STAC-objekt i en samling i en Microsoft Planetary Computer Pro GeoCatalog
• Snabbstart: Mata in data med webbgränssnittet Microsoft Planetary Computer Pro
• Importera data till Microsoft Planetary Computer Pro
• Inmatningskälla för Microsoft Planetary Computer Pro
• Felsökning av datainmatning
• Felkoder: Microsoft Planetary Computer Pro-inmatning