Dela via

Distribuera geospatial förbrukningszon

  • Artikel

OSDU Geospatial Consumption Zone (GCZ) är en tjänst som möjliggör förbättrad hantering och användning av geospatiala data. GCZ effektiviserar hanteringen av platsbaserad information. Det abstraherar bort tekniska komplexiteter, vilket gör det möjligt för program att komma åt geospatiala data utan att behöva hantera invecklade detaljer. Genom att tillhandahålla karttjänster som är redo att användas underlättar GCZ sömlös integrering med OSDU-aktiverade program.

Den här guiden visar hur du distribuerar tjänsten Geospatial Consumption Zone (GCZ) som är integrerad med Azure Data Manager for Energy (ADME).

Skapa en appregistrering i Microsoft Entra-ID

Om du vill distribuera GCZ måste du skapa en appregistrering i Microsoft Entra-ID. Appregistreringen används för att autentisera GCZ-API:erna med Azure Data Manager for Energy för att kunna generera cacheminnet för geospatiala data.

  1. Mer information om hur du skapar en appregistrering finns i Skapa en appregistrering i Microsoft Entra-ID .

  2. Ge appregistreringsbehörighet för att läsa relevanta data i Azure Data Manager for Energy. Mer information finns i Lägga till medlemmar i en OSDU-grupp .

Ställ in

Det finns två huvudsakliga distributionsalternativ för GCZ-tjänsten:

  • Azure Kubernetes Service (AKS): Distribuera GCZ-tjänsten i ett AKS-kluster. Det här distributionsalternativet rekommenderas för produktionsmiljöer. Det kräver mer arbete för att konfigurera, konfigurera och underhålla.
  • Windows: Distribuera GCZ-tjänsten i ett Windows. Det här distributionsalternativet rekommenderas för utvecklings- och testmiljöer.

Distribuera geospatial förbrukningszon (GCZ) på Azure Kubernetes Service (AKS)

Lär dig hur du distribuerar Geospatial Consumption Zone (GCZ) på Azure Kubernetes Service (AKS).

Förutsättningar

Distribuera HELM-diagram (Geospatial Consumption Zone) (GCZ)

  1. Klona GCZ-lagringsplatsen till din lokala miljö:

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

  2. Ändra katalog till geospatial mappen:

    cd geospatial/devops/azure/charts/geospatial

  3. Definiera variabler för distributionen:

    # 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. Skapa HELM-diagrammet:

    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. Ändra tjänsttyp till LoadBalancer för konfigurationsfilerna provider och transformer tjänsterna.

    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. Granska transformeringskonfigurationsfilen application.yml för att se till att rätt scheman ingår.

    nano ../transformer/application.yml

  7. Granska providerkonfigurationsfilen koop-config.json.

    nano ../provider/koop-config.json

  8. Autentisera till AKS-klustret (Azure Kubernetes Service):

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

  9. Skapa AKS-namnområde:

    kubectl create namespace $NAMESPACE

  10. Distribuera HELM-beroenden:

    helm dependency build

  11. Distribuera GCZ HELM-diagrammet:

    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. Kontrollera distributionen:

    kubectl get pods -n $NAMESPACE

    Nu bör du se poddarna för ignitetjänsterna , provideroch transformer .

  13. Anteckna sedan de externa IP-adresserna provider för tjänsterna och transformer .

    kubectl get service -n $NAMESPACE

    Dessa IP-adresser används för att ansluta till GCZ API-slutpunkterna.

Viktigt!

Om du vill uppdatera konfigurationsfilerna (t.ex. application.yml eller koop-config.json) måste du uppdatera AKS-konfigurationen (konfigurationskartan) och sedan ta bort de befintliga poddarna för provider tjänsterna och transformer . Poddarna återskapas med den nya konfigurationen. Om du ändrar konfigurationen med hjälp av GCZ-API:erna sparas inte ändringarna efter en omstart av podden.

Distribuera geospatial förbrukningszon (GCZ) på en virtuell Windows-dator

Lär dig hur du distribuerar geospatial förbrukningszon (GCZ) i Windows. Det här distributionsalternativet rekommenderas för utvecklings- och testmiljöer eftersom det är enklare att konfigurera och konfigurera och kräver mindre underhåll.

Förutsättningar

Distribuera GCZ i Windows

  1. Anslut till din virtuella Windows-dator.

  2. Ladda ned följande filer från OSDU GitLab-lagringsplatsen:

    1. GCZ-provider
    2. GCZ-transformator
    3. Python-beroenden

  3. Öppna PowerShell som administratör och navigera till mappen där du laddade ned filerna.

  4. Kör följande kommandon för att extrahera filerna:

    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. Konfigurera miljövariablerna:

    $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

    Fler miljövariabler finns i OSDU GitLab-dokumentationen.

  6. Verifiera konfigurationsfilerna för GCZ-providern och transformeraren genom att öppna konfigurationsfilerna i en textredigerare och uppdatera värdena om det behövs.

    • Familjeförsörjare: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformator: C:\gcz\gcz-transformer-core\config\application.yml

    Viktigt!

    Om du gör ändringar i schemana i konfigurationsfilerna måste du se till att dessa scheman visas i båda konfigurationsfilerna.

  7. (valfritt) Installera Python-beroenden (krävs endast för brunnslogginterpolation).

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

  8. Starta GCZ Transformer.

    C:\gcz\transformer\transformer.bat local

  9. Skapa GCZ-providern.

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

Som standard lyssnar providern på http://localhost:8083 och Transformeraren lyssnar på http://localhost:8080.

Publicera GCZ-API:er offentligt (valfritt)

Om du vill exponera GCZ-API:erna offentligt kan du använda Azure API Management (APIM). Med Azure API Management kan vi på ett säkert sätt exponera GCZ-tjänsten för Internet, eftersom GCZ-tjänsten ännu inte har inbyggd autentisering och auktorisering. Via APIM kan vi lägga till principer för att skydda, övervaka och hantera API:erna.

Förutsättningar

Viktigt!

Azure API Management-instansen måste matas in i ett virtuellt nätverk som kan dirigeras till AKS-klustret för att kunna kommunicera med GCZ API:erna.

Lägga till GCZ-API:erna i Azure API Management

Ladda ned GCZ OpenAPI-specifikationerna

  1. Ladda ned de två OpenAPI-specifikationen till din lokala dator.

  2. Öppna varje OpenAPI-specifikationsfil i en textredigerare och ersätt servers avsnittet med motsvarande IP-adresser för AKS GCZ Services Load Balancer.

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

Lägga till GCZ-API:erna i Azure API Management

  1. Gå till azure API Management-tjänsten i Azure Portal.

  2. I det vänstra navigeringsfönstret väljer du API:er.

  3. Välj + Lägg till API.

  4. Välj OpenAPI.

  5. Välj Välj en fil och ladda upp gcz-openapi-provider.yaml filen.

  6. I fältet API URL-suffix anger du ignite-provider.

  7. Välj Skapa.

  8. Upprepa stegen för gcz-openapi-transformer.yaml filen, men använd gcz/transformer/admin som API URL-suffix.

    Lägga till GCZ API i APIM

Konfigurera principer

Därefter måste vi konfigurera principerna för att verifiera JSON-webbtoken (JWT).

Du behöver följande information:

  • Din Microsoft Entra ID klientorganisations-ID.
  • Azure Data Manager for Energy-klient-ID (eller tokenutfärdande klient-ID om det är separat).

Kommentar

Om du har flera appregistreringar som utfärdar token kan du lägga till flera <application-id> element i elementet <client-application-ids> .

  1. Kontrollera att Alla åtgärder har valts i det nyligen skapade Geospatial Consumption Zone - Provider API:et.

  2. Under Inkommande bearbetning väljer du ... och sedan Kodredigerare.

  3. Klistra in följande principdefinition i redigeraren:

    <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. Ersätt %tenant-id% med ditt Klient-ID för Microsoft Entra ID och %client-id% med Azure Data Manager for Energy-klient-ID: t.

  5. Välj Spara.

  6. Upprepa stegen för API:et Geospatial Consumption Zone - Transformer .

Testa GCZ-tjänsten

  1. Ladda ned API-klientsamlingen från OSDU GitLab och importera den till valfri API-klient (t.ex. Bruno, Postman).

  2. Lägg till följande miljövariabler i API-klienten:

    • PROVIDER_URL – URL:en till GCZ-provider-API:et.
    • AMBASSADOR_URL – URL:en till GCZ Transformer-API:et.
    • access_token – En giltig ADME-åtkomsttoken.

  3. Kontrollera att GCZ fungerar som förväntat genom att köra API-anropen i samlingen.

Nästa steg

När du har distribuerat GCZ kan du:

  • Visualisera dina GCZ-data med hjälp av GCZ WebApps från OSDU GitLab.

Viktigt!

GCZ WebApps är under utveckling och stöder inte autentisering. Vi rekommenderar att du distribuerar WebApps i ett privat nätverk och exponerar dem med hjälp av Azure Application Gateway eller Azure Front Door för att aktivera autentisering och auktorisering.

Du kan också mata in data i din Azure Data Manager for Energy-instans:

Referenser

  • Information om geospatial förbrukningszon finns i OSDU GitLab.