استيعاب البيانات في GeoCatalog باستخدام واجهة برمجة تطبيقات الاستيعاب المجمع

توضح هذه المقالة كيفية استيعاب العديد من أصول البيانات الجغرافية المكانية في وقت واحد في GeoCatalog باستخدام واجهة برمجة تطبيقات الاستيعاب المجمع. أولا، نقوم بإنشاء وتكوين مصدر استيعاب GeoCatalog. إنشاء مصدر استيعاب ينشئ اتصالا آمنا بين مورد GeoCatalog وموقع التخزين لبياناتك الجغرافية المكانية الحالية. بعد ذلك، نقوم بإنشاء مجموعة كتالوج الوصول SpatioTemporal (STAC) داخل مورد GeoCatalog لتخزين البيانات التي يتم استيعابها. وأخيرا، نستخدم واجهة برمجة تطبيقات الاستيعاب المجمع لبدء سير عمل الاستيعاب. عند الانتهاء من إكمال هذه الخطوات، يتم استيعاب بياناتك الجغرافية المكانية ويمكن الوصول إليها من واجهات برمجة تطبيقات GeoCatalog وواجهات برمجة التطبيقات.

المتطلبات الأساسية

في اشتراك Azure الخاص بك:

مجموعة بيانات جغرافية مكانية في حاوية كائن ثنائي كبير الحجم لحساب التخزين الخاص بك:

أصول البيانات الجغرافية المكانية (على سبيل المثال، ملفات GeoTIFF)
تقوم عناصر STAC المقترنة بإنشاء عناصر STAC لهذه الأصول.
مجموعة STAC JSON التي تشير إلى جميع عناصر STAC وأصول البيانات الجغرافية المكانية.

في بيئة التطوير المحلية الخاصة بك:

بيئة Python تشغل Python 3.8 أو أحدث.
Azure CLI
لقد قمت بتسجيل الدخول إلى Azure

يجب أن يكون لدى Microsoft Planetary Computer Pro حق الوصول إلى حاوية Azure Blob Storage. في هذه المقالة، نقوم بإنشاء واستخدام بيانات اعتماد رمز SAS مؤقت لمنح هذا الوصول. بدلا من ذلك، يمكنك استخدام هذه الدلائل لإعداد الهوية المدارة أو رموز SAS المميزة ذات التعليمات البرمجية المضمنة.

إنشاء مصدر الاستيعاب

يحدد إنشاء مصدر استيعاب ل GeoCatalog المصدر الذي لاستيعاب البيانات الجغرافية المكانية منه، وآلية بيانات الاعتماد التي يجب استخدامها في سير عمل الاستيعاب.

تثبيت وحدات Python المطلوبة باستخدام pip

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

استيراد وحدات Python المطلوبة

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

تعيين الثوابت المطلوبة وفقا للبيئة الخاصة بك

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 = "2025-04-30-preview"

إنشاء رمز SAS المميز

# 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),
)

الحصول على رمز مميز للوصول إلى واجهة برمجة تطبيقات GeoCatalog

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

إنشاء حمولة POST لواجهة برمجة تطبيقات مصدر الاستيعاب

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

إنشاء مصدر الاستيعاب عن طريق إرسال حمولة POST إلى نقطة نهاية مصدر الاستيعاب

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

تحقق من الاستجابة

# 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 resoource clean up
else:
    print(f"Failed to create ingestion: {response.text}")

ملاحظة

يؤدي تشغيل هذه الخطوات أكثر من مرة إلى الخلف إلى استجابة 409:

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

لا تسمح لك واجهة برمجة تطبيقات مصدر الاستيعاب بإنشاء أكثر من مصدر استيعاب واحد لنفس عنوان URL للحاوية. لتجنب التعارضات، تأكد من تنظيف أي مصادر استيعاب موجودة قبل إنشاء مصدر جديد. للحصول على التفاصيل، راجع تنظيف الموارد.

إنشاء مجموعة

مجموعة STAC هي الحاوية عالية المستوى لعناصر STAC والأصول الجغرافية المكانية المرتبطة بها. في هذا القسم، نقوم بإنشاء مجموعة STAC داخل GeoCatalog لإيواء البيانات الجغرافية المكانية التي نتناولها في القسم التالي.

استيراد الوحدات النمطية المطلوبة

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

تعيين الثوابت المطلوبة وفقا للبيئة الخاصة بك

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 = "2025-04-30-preview"

COLLECTION_ID = "example-collection" #You can your own collection ID
COLLECTION_TITLE = "Example Collection" #You can your own collection title

الحصول على رمز مميز للوصول إلى واجهة برمجة تطبيقات GeoCatalog

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

إنشاء مواصفات مجموعة STAC أساسية

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

ملاحظة

مواصفات مجموعة العينة هذه هي مثال أساسي لمجموعة. لمزيد من المعلومات حول مجموعات STAC وSTAC القياسية المفتوحة، راجع نظرة عامة على STAC. لمزيد من المعلومات حول إنشاء مجموعة STAC كاملة، راجع إنشاء مجموعة STAC.

إنشاء المجموعة الجديدة باستخدام واجهة برمجة تطبيقات المجموعة

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

تحقق من نتيجة الاستجابة

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

إنشاء اتصال وتشغيل سير العمل

في هذه الخطوة الأخيرة، نستخدم واجهة برمجة تطبيقات الاستيعاب لبدء سير عمل استيعاب مجمع.

استيراد الوحدات النمطية المطلوبة

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

تعيين الثوابت المطلوبة وفقا للبيئة الخاصة بك

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 = "2025-04-30-preview"

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

الحصول على رمز مميز للوصول إلى واجهة برمجة تطبيقات GeoCatalog

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

إنشاء حمولة POST لواجهة برمجة تطبيقات الاستيعاب المجمع

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

إرسال الحمولة إلى واجهة برمجة تطبيقات الاستيعاب المجمع.

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

تحقق من الاستجابة.

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

تحقق من حالة سير عمل الاستيعاب.

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

بمجرد اكتمال سير العمل، يمكنك الاستعلام عن بياناتك الجغرافية المكانية أو استردادها أو تصورها باستخدام GeoCatalog STAC أو واجهات برمجة تطبيقات البيانات، أو باستخدام مستكشف البيانات. إذا واجهت مشكلات، فراجع دليل استكشاف الأخطاء وإصلاحها أو قائمة رموز خطأ الاستيعاب.

تنظيف الموارد

حذف مصدر الاستيعاب

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

الخطوات التالية

الآن بعد أن أضفت بعض العناصر، يجب تكوين البيانات للتصور.

تكوين المجموعة في Microsoft Planetary Computer Pro

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-05-19

استيعاب البيانات في GeoCatalog باستخدام واجهة برمجة تطبيقات الاستيعاب المجمع

المتطلبات الأساسية

إنشاء مصدر الاستيعاب

إنشاء مجموعة

إنشاء اتصال وتشغيل سير العمل

تنظيف الموارد

الخطوات التالية

المحتويات ذات الصلة

الملاحظات

الموارد الإضافية