مشاركة عبر

توزيع منطقة الاستهلاك الجيوفضائي

  • مقالة

يوضح لك هذا الدليل كيفية نشر خدمة منطقة الاستهلاك الجيوفضائي (GCZ) المتكاملة مع Azure Data Manager for Energy (ADME).

هام

في حين أن خدمة منطقة الاستهلاك الجيوفضائي (GCZ) هي خدمة متدرجة في منتدى OSDU، فإن لديها قيود من حيث الأمان والاستخدام. سننشر بعض الخدمات والسياسات الإضافية لتأمين البيئة، ولكن نشجعك على متابعة تطوير الخدمة على OSDU Gitlab.

‏‏الوصف

منطقة الاستهلاك الجيوفضائي OSDU (GCZ) هي خدمة تمكن من تعزيز إدارة البيانات الجغرافية المكانية واستخدامها. يبسط GCZ معالجة المعلومات المستندة إلى الموقع. فهو يلخص التعقيدات التقنية، ما يسمح لتطبيقات البرامج بالوصول إلى البيانات الجغرافية المكانية دون الحاجة إلى التعامل مع التفاصيل المعقدة. من خلال توفير خدمات الخرائط الجاهزة للاستخدام، تسهل GCZ التكامل السلس مع التطبيقات التي تدعم OSDU.

إنشاء تسجيل تطبيق في معرف Microsoft Entra

لنشر GCZ، تحتاج إلى إنشاء تسجيل تطبيق في معرف Microsoft Entra. تسجيل التطبيق هو مصادقة واجهات برمجة التطبيقات GCZ مع Azure Data Manager for Energy لتكون قادرة على إنشاء ذاكرة التخزين المؤقت للبيانات الجغرافية المكانية.

  1. راجع إنشاء تسجيل تطبيق في معرف Microsoft Entra للحصول على إرشادات حول كيفية إنشاء تسجيل تطبيق.
  2. امنح إذن تسجيل التطبيق لقراءة البيانات ذات الصلة في Azure Data Manager for Energy. راجع كيفية إضافة أعضاء إلى مجموعة OSDU للحصول على مزيد من الإرشادات.

الإعداد

هناك خياران رئيسيان للتوزيع لخدمة GCZ:

  • Azure Kubernetes Service (AKS): نشر خدمة GCZ على نظام مجموعة AKS. يوصى بخيار النشر هذا لبيئات الإنتاج. يتطلب المزيد من الإعداد والتكوين والصيانة. كما أن لديها بعض القيود في صور الحاوية المتوفرة.
  • Windows: نشر خدمة GCZ على Windows. يوصى بخيار النشر هذا لبيئات التطوير والاختبار، حيث إنه من الأسهل الإعداد والتكوين، ويتطلب صيانة أقل.

توزيع منطقة الاستهلاك الجيوفضائي (GCZ) على خدمة Azure Kubernetes (AKS)

تعرف على كيفية نشر منطقة الاستهلاك الجيوفضائي (GCZ) على خدمة Azure Kubernetes (AKS).

هام

يقتصر النشر الحالي ل GCZ باستخدام AKS على تكوين افتراضي للمخططات المضمنة، يرجى مراجعة OSDU GitLab للحصول على معلومات حول المخططات المدعومة. لإضافة أو تغيير المخططات (أي الإصدارات الأحدث) يجب إنشاء صورة حاوية مخصصة.

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

توزيع مخطط HELM لمنطقة الاستهلاك الجيوفضائي (GCZ)

  1. استنساخ مستودع GCZ إلى البيئة المحلية الخاصة بك:

    git clone https://community.opengroup.org/osdu/platform/consumption/geospatial.git

  2. تغيير الدليل إلى geospatial المجلد:

    cd geospatial/devops/azure/charts/geospatial

  3. تعريف المتغيرات للتوزيع:

    # Define the variables for Azure Data Manager for Energy
AZURE_DNS_NAME="<instanceName>.energy.azure.com"  # Example: demo.energy.azure.com
DATA_PARTITION_ID="<dataPartitionId>" # Data partition ID. Example: opendes
AZURE_TENANT_ID="<tenantId>" # Entra ID tenant ID. Example: 557963fb-ede7-4a88-9e3e-19ace7f1e36b 
AZURE_CLIENT_ID="<clientId>" # App Registration client ID. Example: b149dc73-ed8c-4ad3-bbaf-882a208f87eb
AZURE_CLIENT_SECRET="<clientSecret>" # App Registration client secret.
CALLBACK_URL="http://localhost:5050" #ie: http://localhost:8080

# Define the variables for AKS
AKS_NAME="<aksName>" # Name of the AKS cluster. Example: gcz-aks-cluster.
RESOURCE_GROUP="<resourceGroupName>" # Name of the resource group. Example: gcz-rg.
NAMESPACE="ignite" # Name of the AKS namespace you want to deploy to. We recommend to leave it default.
GCZ_IGNITE_SERVICE="ignite-service" # Name of the ignite service. We recommend to leave it default.
GCZ_IGNITE_NAMESPACE=$NAMESPACE
CHART=osdu-gcz-service
VERSION=0.1.0

  4. إنشاء مخطط HELM:

    cat > osdu_gcz_custom_values.yaml << EOF
# This file contains the essential configs for the gcz on azure helm chart

################################################################################
# Specify the values for each service.
#
global:
ignite:
    namespace: $NAMESPACE
    name: ignite
    image:
    name: community.opengroup.org:5555/osdu/platform/consumption/geospatial/gridgain-community
    tag: 8.8.34
    configuration:
    gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE"
    gcz_ignite_service: "$GCZ_IGNITE_SERVICE"
provider:
    namespace: $NAMESPACE
    image:
    repository: community.opengroup.org:5555
    name: osdu/platform/consumption/geospatial/geospatial-provider-master
    tag: latest
    service:
    type: LoadBalancer
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
transformer:
    namespace: $NAMESPACE
    image:
    repository: community.opengroup.org:5555
    name: osdu/platform/consumption/geospatial/geospatial-transformer-master
    tag: latest
    service:
    type: LoadBalancer
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
    configuration:
    datapartitionid: $DATA_PARTITION_ID
    clientId: $AZURE_CLIENT_ID
    tenantId: $AZURE_TENANT_ID
    callbackURL: $CALLBACK_URL
    searchQueryURL: "https://$AZURE_DNS_NAME/api/search/v2/query"
    searchCursorURL: "https://$AZURE_DNS_NAME/api/search/v2/query_with_cursor"
    schemaURL: "https://$AZURE_DNS_NAME/api/schema-service/v1/schema"
    entitlementsURL: "https://$AZURE_DNS_NAME/api/entitlements/v2"
    fileRetrievalURL: "https://$AZURE_DNS_NAME/api/dataset/v1/retrievalInstructions"
    crsconvertorURL: "https://$AZURE_DNS_NAME/api/crs/converter/v3/convertTrajectory"
    storageURL: "https://$AZURE_DNS_NAME/api/storage/v2/records"
    clientSecret: $(echo "$AZURE_CLIENT_SECRET" | base64)
    gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE"
    gcz_ignite_service: "$GCZ_IGNITE_SERVICE"   
EOF

  5. تغيير نوع الخدمة إلى LoadBalancer لملفات provider تكوين الخدمات و transformer .

    cat > ../provider/templates/service.yaml << EOF
apiVersion: v1
kind: Service
metadata:
    name: gcz-provider
    namespace: {{ $.Values.global.provider.namespace }}
    annotations:
        {{- range $key, $value := $.Values.global.provider.service.annotations }}
        {{ $key }}: {{ $value | quote }}
        {{- end }}
spec:
    selector:
        app: provider
    ports:
    - port: 80
        protocol: TCP
        targetPort: 8083
    type: {{ $.Values.global.provider.service.type }}
EOF

cat > ../transformer/templates/service.yaml << EOF
apiVersion: v1
kind: Service
metadata:
    name: gcz-transformer
    namespace: {{ $.Values.global.transformer.namespace }}
    annotations:
        {{- range $key, $value := $.Values.global.transformer.service.annotations }}
        {{ $key }}: {{ $value | quote }}
        {{- end }}
spec:
    selector:
        app: transformer
    ports:
    - port: 80
        protocol: TCP
        targetPort: 8080
    type: {{ $.Values.global.transformer.service.type }}
EOF

  6. المصادقة على نظام مجموعة Azure Kubernetes Service (AKS):

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME --admin

  7. توزيع تبعيات HELM:

    helm dependency build

  8. نشر مخطط GCZ HELM:

    helm install $CHART ../$CHART --values osdu_gcz_custom_values.yaml

  9. تحقق من النشر:

    kubectl get pods -n $NAMESPACE

    الآن يجب أن تشاهد pods للخدمات igniteproviderو وtransformer.

  10. بعد ذلك، لاحظ عناوين IP الخارجية للخدمات provider و transformer .

    kubectl get service -n $NAMESPACE

    يتم استخدام عناوين IP هذه للاتصال بنقاط نهاية واجهة برمجة تطبيقات GCZ.

توزيع منطقة الاستهلاك الجيوفضائي (GCZ) على جهاز ظاهري يعمل بنظام Windows

تعرف على كيفية نشر منطقة الاستهلاك الجيوفضائي (GCZ) على Windows. يوصى بخيار النشر هذا لبيئات التطوير والاختبار، حيث إنه من الأسهل إعداده وتكوينه، ويتطلب صيانة أقل.

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

  • Azure Data Manager لمثيل الطاقة. إذا لم يكن لديك Azure Data Manager لمثيل الطاقة، فشاهد إنشاء Azure Data Manager لمثيل الطاقة.
  • جهاز ظاهري يعمل بنظام Windows. إذا لم يكن لديك جهاز ظاهري يعمل بنظام Windows، فشاهد إنشاء جهاز ظاهري ل Windows في Azure. من الممكن أيضا استخدام جهازك المحلي.
  • Java JDK 17 مثبت على الجهاز الظاهري ل Windows. إذا لم يكن لديك Java مثبتا، فشاهد تثبيت Java على Windows.
  • العقدة 18.19.1 (LTS) المثبتة على الجهاز الظاهري ل Windows. إذا لم تكن العقدة مثبتة لديك، فشاهد تثبيت Node.js وnpm على Windows.
  • Python 3.11.4 أو أحدث مثبت على الجهاز الظاهري ل Windows. إذا لم يكن Python مثبتا لديك، فشاهد تثبيت Python على Windows.
    • تأكد من إضافة pip أثناء عملية التثبيت. إذا نسيت إضافة pip، يمكنك تثبيته يدويا.

نشر GCZ على Windows

  1. الاتصال بجهاز Windows الظاهري الخاص بك.

  2. قم بتنزيل الملفات التالية من مستودع OSDU GitLab:

    1. موفر GCZ
    2. محول GCZ
    3. تبعيات Python

  3. افتح PowerShell كمسؤول وانتقل إلى المجلد حيث قمت بتنزيل الملفات.

  4. قم بتشغيل الأوامر التالية لاستخراج الملفات:

    Expand-Archive -Path .\GCZ_PROVIDER.zip -DestinationPath C:\gcz\
Expand-Archive -Path .\GCZ_TRANSFORMER.zip -DestinationPath C:\gcz\
Expand-Archive -Path .\GCZ_PYTHON_DEPENDENCIES.zip -DestinationPath C:\gcz\

  5. تكوين متغيرات البيئة:

    $ADME_HOSTNAME = "<adme-hostname>" # ADME Hostname, e.g. "https://contoso.energy.azure.com"
$GCZ_DATA_PARTITION_ID = "<data-partition-id>" # ADME Data Partition ID, e.g. "opendes"
$GCZ_QUERY_URL = "$ADME_HOSTNAME/api/search/v2/query" # ADME Query Endpoint
$GCZ_QUERY_CURSOR_URL = "$ADME_HOSTNAME/api/search/v2/query_with_cursor" # ADME Query with Cursor Endpoint
$GCZ_SCHEMA_URL = "$ADME_HOSTNAME/api/schema-service/v1/schema" # ADME Schema Endpoint
$GCZ_ENTITLEMENT_SERVICE_URL = "$ADME_HOSTNAME/api/entitlements/v2" # ADME Entitlement Service Endpoint
$GCZ_FILE_RETRIEVAL_URL = "$ADME_HOSTNAME/api/dataset/v1/retrievalInstructions" # ADME File Retrieval Endpoint
$GCZ_CONVERT_TRAJECTORY_URL = "$ADME_HOSTNAME/api/crs/converter/v3/convertTrajectory" # ADME Convert Trajectory Endpoint
$GCZ_STORAGE_URL = "$ADME_HOSTNAME/api/storage/v2/records/" # ADME Storage Endpoint

    لمزيد من متغيرات البيئة، راجع وثائق OSDU GitLab.

  6. تحقق من صحة ملفات التكوين لموفر GCZ والمحول عن طريق فتح ملفات التكوين في محرر نص وتحديث القيم إذا لزم الأمر.

    • كاسب: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • محول: C:\gcz\gcz-transformer-core\config\application.yml

    هام

    إذا قمت بإجراء تغييرات على المخططات في ملفات التكوين، يجب عليك التأكد من تمثيل هذه المخططات في كل من ملفات التكوين.

  7. (اختياري) تثبيت تبعيات Python (مطلوب فقط لإقبول سجل جيد).

    pip install -r C:\gcz\gcz-transformer-core\src\main\resources\script\requirements.txt --no-index --find-links python-dependencies

  8. ابدأ تشغيل محول GCZ.

    C:\gcz\transformer\transformer.bat local

  9. إنشاء موفر GCZ.

    cd C:\gcz\gcz-provider\gcz-provider-core
npm install
npm start

بشكل افتراضي، يستمع http://localhost:8083 الموفر ويستمع المحول إلى http://localhost:8080.

نشر واجهات برمجة تطبيقات GCZ بشكل عام (اختياري)

إذا كنت ترغب في كشف واجهات برمجة تطبيقات GCZ بشكل عام، يمكنك استخدام Azure API Management (APIM). تسمح لنا إدارة واجهة برمجة تطبيقات Azure بعرض خدمة GCZ على الإنترنت بشكل آمن، حيث لا تحتوي خدمة GCZ بعد على المصادقة والتخويل المضمنة. من خلال APIM يمكننا إضافة نهج لتأمين واجهات برمجة التطبيقات ومراقبتها وإدارتها.

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

  • مثيل Azure API Management. إذا لم يكن لديك مثيل إدارة واجهة برمجة تطبيقات Azure، فشاهد إنشاء مثيل إدارة واجهة برمجة تطبيقات Azure.
  • يتم نشر واجهات برمجة تطبيقات GCZ وتشغيلها.

هام

سيحتاج مثيل Azure API Management إلى إدخاله في شبكة ظاهرية قابلة للتوجيه إلى مجموعة AKS لتكون قادرة على الاتصال بواجهة برمجة تطبيقات GCZ.

إضافة واجهات برمجة تطبيقات GCZ إلى Azure API Management

تنزيل مواصفات GCZ OpenAPI

  1. قم بتنزيل مواصفة OpenAPI على الكمبيوتر المحلي.

  2. افتح كل ملف مواصفات OpenAPI في محرر نص واستبدل servers القسم بعناوين IP المقابلة لموازن تحميل خدمات AKS GCZ (IP الخارجي).

    servers:
- url: "http://<GCZ-Service-External-IP>/ignite-provider"

إضافة واجهات برمجة تطبيقات GCZ إلى Azure API Management

  1. انتقل إلى خدمة Azure API Management في مدخل Microsoft Azure.

  2. في جزء التنقل الأيسر، حدد واجهات برمجة التطبيقات.

  3. حدد + Add API.

  4. حدد OpenAPI.

  5. حدد Select a file وقم بتحميل gcz-openapi-provider.yaml الملف.

  6. في حقل لاحقة عنوان URL لواجهة برمجة التطبيقات، أدخل ignite-provider.

  7. حدد إنشاء.

  8. كرر الخطوات للملفgcz-openapi-transformer.yaml، ولكن استخدم gcz/transformer/admin كلاحقة عنوان URL لواجهة برمجة التطبيقات.

    إضافة واجهة برمجة تطبيقات GCZ إلى APIM

تكوين النهج

بعد ذلك، نحتاج إلى تكوين النهج للتحقق من صحة رموز ويب JSON المميزة (JWT).

تحتاج إلى المعلومات التالية:

  • معرف مستأجر Microsoft Entra ID الخاص بك.
  • معرف عميل Azure Data Manager for Energy (أو معرف العميل الذي يصدر الرمز المميز إذا كان منفصلا).

إشعار

إذا كان لديك العديد من تسجيلات التطبيقات التي تصدر الرموز المميزة، يمكنك إضافة عناصر متعددة <application-id> إلى <client-application-ids> العنصر.

  1. في واجهة برمجة التطبيقات التي تم إنشاؤها Geospatial Consumption Zone - Provider حديثا، تأكد من تحديد جميع العمليات .

  2. ضمن Inbound processing، حدد ... ثم Code editor.

  3. الصق تعريف النهج التالي في المحرر:

    <policies>
    <!-- Throttle, authorize, validate, cache, or transform the requests -->
    <inbound>
        <base />
        <validate-azure-ad-token tenant-id="%tenant-id%" failed-validation-httpcode="401">
        <client-application-ids>
            <application-id>%client-id%</application-id>
        </client-application-ids>
    </inbound>
    <!-- Control if and how the requests are forwarded to services  -->
    <backend>
        <base />
    </backend>
    <!-- Customize the responses -->
    <outbound>
        <base />
    </outbound>
    <!-- Handle exceptions and customize error responses  -->
    <on-error>
        <base />
    </on-error>
</policies>

  4. استبدل %tenant-id% بمعرف مستأجر Microsoft Entra ID الخاص بك، و %client-id% بمعرف عميل Azure Data Manager for Energy.

  5. حدد حفظ.

  6. كرر الخطوات لواجهة Geospatial Consumption Zone - Transformer برمجة التطبيقات.

اختبار خدمة GCZ

  1. قم بتنزيل مجموعة عميل واجهة برمجة التطبيقات من OSDU GitLab واستوردها إلى عميل واجهة برمجة التطبيقات الذي تختاره (على سبيل المثال، Postman).

  2. أضف متغيرات البيئة التالية إلى عميل API الخاص بك:

    • PROVIDER_URL - عنوان URL لواجهة برمجة تطبيقات موفر GCZ.
    • AMBASSADOR_URL - عنوان URL لواجهة برمجة تطبيقات محول GCZ.
    • access_token - رمز مميز صالح للوصول إلى ADME.

  3. للتحقق من أن GCZ يعمل كما هو متوقع، قم بتشغيل استدعاءات واجهة برمجة التطبيقات في المجموعة.

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

بعد النشر الناجح ل GCZ، يمكنك:

  • تصور بيانات GCZ باستخدام GCZ WebApps من OSDU GitLab.

هام

تطبيقات ويب GCZ قيد التطوير حاليا ولا تدعم المصادقة. نوصي بنشر WebApps في شبكة خاصة وكشفها باستخدام Azure Application Gateway أو Azure Front Door لتمكين المصادقة والتخويل.

يمكنك أيضا استيعاب البيانات في Azure Data Manager لمثيل الطاقة:

المراجع

  • للحصول على معلومات حول منطقة الاستهلاك الجيوفضائي، راجع OSDU GitLab.