Udostępnij za pośrednictwem

Wdrażanie strefy zużycia geoprzestrzennych

  • Artykuł

Strefa zużycia geoprzestrzennego OSDU (GCZ) to usługa, która umożliwia ulepszone zarządzanie danymi geoprzestrzennym i korzystanie z tych danych. GCZ usprawnia obsługę informacji opartych na lokalizacji. Wyodrębnia ona złożoność techniczną, umożliwiając aplikacjom oprogramowania dostęp do danych geoprzestrzennych bez konieczności radzenia sobie ze skomplikowanymi szczegółami. Zapewniając gotowe do użycia usługi mapy, GCZ ułatwia bezproblemową integrację z aplikacjami z obsługą OSDU.

W tym przewodniku pokazano, jak wdrożyć usługę Geospatial Consumption Zone (GCZ) zintegrowaną z usługą Azure Data Manager for Energy (ADME).

Tworzenie rejestracji aplikacji w usłudze Microsoft Entra ID

Aby wdrożyć GCZ, należy utworzyć rejestrację aplikacji w usłudze Microsoft Entra ID. Rejestracja aplikacji służy do uwierzytelniania interfejsów API GCZ za pomocą usługi Azure Data Manager for Energy w celu wygenerowania pamięci podręcznej danych geoprzestrzennych.

  1. Aby uzyskać instrukcje dotyczące tworzenia rejestracji aplikacji, zobacz Tworzenie rejestracji aplikacji w usłudze Microsoft Entra ID .

  2. Udziel uprawnienia Rejestracja aplikacji, aby odczytać odpowiednie dane w usłudze Azure Data Manager for Energy. Aby uzyskać dalsze instrukcje, zobacz How to add members to an OSDU group (Jak dodać członków do grupy OSDU).

Ustawienia

Istnieją dwie główne opcje wdrażania usługi GCZ:

  • Azure Kubernetes Service (AKS): wdrażanie usługi GCZ w klastrze usługi AKS. Ta opcja wdrożenia jest zalecana w środowiskach produkcyjnych. Wymaga to większego nakładu pracy w celu skonfigurowania, skonfigurowania i obsługi.
  • Windows: wdróż usługę GCZ w systemie Windows. Ta opcja wdrożenia zalecana dla środowisk deweloperskich i testowych.

Wdrażanie strefy zużycia geoprzestrzennego (GCZ) w usłudze Azure Kubernetes Service (AKS)

Dowiedz się, jak wdrożyć strefę zużycia geoprzestrzennego (GCZ) w usłudze Azure Kubernetes Service (AKS).

Wymagania wstępne

Wdrażanie wykresu HELM strefy zużycia geoprzestrzennych (GCZ)

  1. Sklonuj repozytorium GCZ do środowiska lokalnego:

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

  2. Zmień katalog na geospatial folder:

    cd geospatial/devops/azure/charts/geospatial

  3. Zdefiniuj zmienne dla wdrożenia:

    # 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: aaaabbbb-0000-cccc-1111-dddd2222eeee
AZURE_CLIENT_ID="<clientId>" # App Registration client ID. Example: 00001111-aaaa-2222-bbbb-3333cccc4444
AZURE_CLIENT_SECRET="<clientSecret>" # App Registration client secret. Example: Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
SCOPE="<scope>" # Scope of the App Registration. Example: 00001111-aaaa-2222-bbbb-3333cccc4444/.default
CALLBACK_URL="http://localhost:8080" # Redirect URI of the ADME App Registration (from scope) ie: http://localhost:8080
PRIVATE_NETWORK="true" # Set to false if you want to expose the service publicly using a LoadBalancer. You can still expose the service using an Ingress Controller or Azure API Management at a later stage.

# 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
CHART_VERSION=1.27.0
VERSION=0.27.0

  4. Utwórz wykres 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: gridgain/community
            tag: 8.8.43
        configuration:
            gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE"
            gcz_ignite_service: "$GCZ_IGNITE_SERVICE"
    provider:
        namespace: $NAMESPACE
        entitlementsGroupsURL: "https://$AZURE_DNS_NAME/api/entitlements/v2/groups"
        image:
            repository: community.opengroup.org:5555
            name: osdu/platform/consumption/geospatial/geospatial-provider-master
            tag: latest
        service:
            type: LoadBalancer
        configuration:
            privateNetwork: "$PRIVATE_NETWORK"
    transformer:
        namespace: $NAMESPACE
        image:
            repository: community.opengroup.org:5555
            name: osdu/platform/consumption/geospatial/geospatial-transformer-master
            tag: latest
        service:
            type: LoadBalancer
        configuration:
            privateNetwork: "$PRIVATE_NETWORK"
            datapartitionid: $DATA_PARTITION_ID
            clientId: $AZURE_CLIENT_ID
            tenantId: $AZURE_TENANT_ID
            callbackURL: $CALLBACK_URL
            scope: $SCOPE
            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. Zmień typ usługi na LoadBalancer dla provider plików konfiguracji usług i transformer .

    cat > ../provider/templates/service.yaml << EOF
apiVersion: v1
kind: Service
metadata:
    name: gcz-provider
    namespace: {{ $.Values.global.provider.namespace }}
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "{{ $.Values.global.provider.configuration.privateNetwork }}"
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:
        service.beta.kubernetes.io/azure-load-balancer-internal: "{{ $.Values.global.transformer.configuration.privateNetwork }}"
spec:
    selector:
        app: transformer
    ports:
    - port: 80
      protocol: TCP
      targetPort: 8080
    type: {{ $.Values.global.transformer.service.type }}
EOF

  6. Przejrzyj plik application.yml konfiguracji przekształcania, aby upewnić się, że uwzględniono poprawne schematy.

    nano ../transformer/application.yml

  7. Przejrzyj plik koop-config.jsonkonfiguracji dostawcy .

    nano ../provider/koop-config.json

  8. Uwierzytelnij się w klastrze usługi Azure Kubernetes Service (AKS):

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

  9. Tworzenie przestrzeni nazw usługi AKS:

    kubectl create namespace $NAMESPACE

  10. Wdrażanie zależności programu HELM:

    helm dependency build

  11. Wdróż wykres HELM GCZ:

    helm upgrade -i $CHART . -n $NAMESPACE -f osdu_gcz_custom_values.yaml --set-file global.provider.configLoaderJs="../../../../gcz-provider/gcz-provider-core/config/configLoader.js"

  12. Zweryfikuj wdrożenie:

    kubectl get pods -n $NAMESPACE

    Teraz powinny zostać wyświetlone zasobniki dla igniteusług , provideri transformer .

  13. Następnie zwróć uwagę na zewnętrzne adresy IP dla provider usług i transformer .

    kubectl get service -n $NAMESPACE

    Te adresy IP są używane do nawiązywania połączenia z punktami końcowymi interfejsu API GCZ.

Ważne

Jeśli chcesz zaktualizować pliki konfiguracji (np application.yml . lub koop-config.json), musisz zaktualizować konfigurację usługi AKS (configmap), a następnie usunąć istniejące zasobniki dla provider usług i transformer . Zasobniki zostaną ponownie odtworzone przy użyciu nowej konfiguracji. Jeśli zmienisz konfigurację przy użyciu interfejsów API GCZ, zmiany nie będą utrwalane po ponownym uruchomieniu zasobnika.

Wdrażanie strefy zużycia geoprzestrzennego (GCZ) na maszynie wirtualnej z systemem Windows

Dowiedz się, jak wdrożyć strefę zużycia geoprzestrzennych (GCZ) w systemie Windows. Ta opcja wdrażania jest zalecana w środowiskach deweloperskich i testowych, ponieważ łatwiej jest ją skonfigurować i skonfigurować oraz wymaga mniejszej konserwacji.

Wymagania wstępne

Wdrażanie usługi GCZ w systemie Windows

  1. Połącz się z maszyną wirtualną z systemem Windows.

  2. Pobierz następujące pliki z repozytorium GitLab OSDU:

    1. Dostawca GCZ
    2. Transformator GCZ
    3. Zależności języka Python

  3. Otwórz program PowerShell jako administrator i przejdź do folderu, w którym pobrano pliki.

  4. Uruchom następujące polecenia, aby wyodrębnić pliki:

    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. Skonfiguruj zmienne środowiskowe:

    $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

    Aby uzyskać więcej zmiennych środowiskowych, zobacz dokumentację narzędzia GitLab OSDU.

  6. Zweryfikuj pliki konfiguracji dostawcy GCZ i transformatora, otwierając pliki konfiguracji w edytorze tekstów i aktualizując wartości w razie potrzeby.

    • Dostawca: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformator: C:\gcz\gcz-transformer-core\config\application.yml

    Ważne

    Jeśli wprowadzisz zmiany w schematach w plikach konfiguracji, musisz upewnić się, że te schematy są reprezentowane w obu plikach konfiguracji.

  7. (opcjonalnie) Zainstaluj zależności języka Python (wymagane tylko w przypadku interpolacji dzienników dobrze).

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

  8. Uruchom transformator GCZ.

    C:\gcz\transformer\transformer.bat local

  9. Skompiluj dostawcę GCZ.

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

Domyślnie dostawca nasłuchujehttp://localhost:8083, a funkcja Transformer nasłuchuje na .http://localhost:8080

Publikowanie interfejsów API GCZ publicznie (opcjonalnie)

Jeśli chcesz udostępnić publicznie interfejsy API GCZ, możesz użyć usługi Azure API Management (APIM). Usługa Azure API Management umożliwia bezpieczne uwidocznienie usługi GCZ w Internecie, ponieważ usługa GCZ nie ma jeszcze wbudowanego uwierzytelniania i autoryzacji. Za pomocą usługi APIM możemy dodawać zasady do zabezpieczania, monitorowania interfejsów API i zarządzania nimi.

Wymagania wstępne

  • Wystąpienie usługi Azure API Management. Jeśli nie masz wystąpienia usługi Azure API Management, zobacz Tworzenie wystąpienia usługi Azure API Management.
  • Interfejsy API GCZ są wdrażane i uruchomione.

Ważne

Wystąpienie usługi Azure API Management musi zostać wprowadzone do sieci wirtualnej, która jest routingiem do klastra usługi AKS, aby móc komunikować się z interfejsami API GCZ.

Dodawanie interfejsów API GCZ do usługi Azure API Management

Pobieranie specyfikacji interfejsu OpenAPI GCZ

  1. Pobierz dwie specyfikacje interfejsu OpenAPI na komputer lokalny.

  2. Otwórz każdy plik specyfikacji interfejsu OpenAPI w edytorze tekstów i zastąp sekcję servers odpowiednimi adresami IP modułu równoważenia obciążenia usług AKS GCZ Services.

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

Dodawanie interfejsów API GCZ do usługi Azure API Management

  1. Przejdź do usługi Azure API Management w witrynie Azure Portal.

  2. W okienku nawigacji po lewej stronie wybierz pozycję Interfejsy API.

  3. Wybierz pozycję + Dodaj interfejs API.

  4. Wybierz pozycję OpenAPI.

  5. Wybierz pozycję Wybierz plik i przekaż gcz-openapi-provider.yaml plik.

  6. W polu sufiks adresu URL interfejsu API wprowadź wartość ignite-provider.

  7. Wybierz pozycję Utwórz.

  8. Powtórz kroki dla gcz-openapi-transformer.yaml pliku, ale użyj go gcz/transformer/admin jako sufiksu adresu URL interfejsu API.

    Dodawanie interfejsu API GCZ do usługi APIM

Konfigurowanie zasad

Następnie należy skonfigurować zasady w celu zweryfikowania tokenów sieci Web JSON (JWT).

Potrzebne są następujące informacje:

  • Identyfikator dzierżawy Tożsamości Microsoft Entra.
  • Identyfikator klienta usługi Azure Data Manager for Energy (lub identyfikator klienta wystawiającego tokeny, jeśli jest oddzielny).

Uwaga

Jeśli masz wiele tokenów wystawiających rejestracje aplikacji, możesz dodać wiele <application-id> elementów do <client-application-ids> elementu.

  1. W nowo utworzonym Geospatial Consumption Zone - Provider interfejsie API upewnij się, że wybrano pozycję Wszystkie operacje .

  2. W obszarze Przetwarzanie przychodzące wybierz pozycję ... a następnie edytor kodu.

  3. Wklej następującą definicję zasad w edytorze:

    <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. Zastąp %tenant-id% ciąg identyfikatorem dzierżawy entra firmy Microsoft i %client-id% identyfikatorem klienta usługi Azure Data Manager for Energy.

  5. Wybierz pozycję Zapisz.

  6. Powtórz kroki dla interfejsu Geospatial Consumption Zone - Transformer API.

Testowanie usługi GCZ

  1. Pobierz kolekcję klienta interfejsu API z narzędzia GitLab OSDU i zaimportuj ją do wybranego klienta interfejsu API (tj. Bruno, Postman).

  2. Dodaj następujące zmienne środowiskowe do klienta interfejsu API:

    • PROVIDER_URL - Adres URL interfejsu API dostawcy GCZ.
    • AMBASSADOR_URL - Adres URL interfejsu API przekształcania GCZ.
    • access_token - Prawidłowy token dostępu ADME.

  3. Aby sprawdzić, czy GCZ działa zgodnie z oczekiwaniami, uruchom wywołania interfejsu API w kolekcji.

Następne kroki

Po pomyślnym wdrożeniu usługi GCZ można wykonać następujące czynności:

  • Wizualizowanie danych GCZ przy użyciu aplikacji internetowych GCZ z narzędzia GitLab OSDU.

Ważne

Aplikacje internetowe GCZ są obecnie opracowywane i nie obsługują uwierzytelniania. Zalecamy wdrożenie aplikacji internetowych w sieci prywatnej i ujawnienie ich przy użyciu usługi aplikacja systemu Azure Gateway lub Azure Front Door w celu włączenia uwierzytelniania i autoryzacji.

Możesz również pozyskiwać dane do wystąpienia usługi Azure Data Manager for Energy:

Informacje

  • Aby uzyskać informacje o strefie zużycia geoprzestrzennych, zobacz OSDU GitLab.