Delen via

Georuimtelijke verbruikszone implementeren

  • Artikel

De OSDU Georuimtelijke Verbruikszone (GCZ) is een service die een verbeterd beheer en gebruik van georuimtelijke gegevens mogelijk maakt. De GCZ stroomlijnt de verwerking van op locatie gebaseerde informatie. Het abstraheert technische complexiteiten, waardoor softwaretoepassingen toegang hebben tot georuimtelijke gegevens zonder ingewikkelde details te hoeven verwerken. Door kant-en-klare kaartservices te bieden, faciliteert de GCZ naadloze integratie met toepassingen met OSDU-functionaliteit.

Deze handleiding laat zien hoe u de GCZ-service (Georuimtelijke Verbruikszone) implementeert die is geïntegreerd met Azure Data Manager for Energy (ADME).

Een app-registratie maken in Microsoft Entra-id

Als u de GCZ wilt implementeren, moet u een app-registratie maken in Microsoft Entra ID. De app-registratie wordt gebruikt om de GCZ-API's te verifiëren met Azure Data Manager for Energy om de cache van de georuimtelijke gegevens te genereren.

  1. Zie Een app-registratie maken in Microsoft Entra ID voor instructies voor het maken van een app-registratie.

  2. Ververleent de app-registratie toestemming om de relevante gegevens te lezen in Azure Data Manager for Energy. Zie Leden toevoegen aan een OSDU-groep voor verdere instructies.

Instellingen

Er zijn twee belangrijke implementatieopties voor de GCZ-service:

  • Azure Kubernetes Service (AKS):implementeer de GCZ-service op een AKS-cluster. Deze implementatieoptie wordt aanbevolen voor productieomgevingen. Het vereist meer moeite om in te stellen, te configureren en te onderhouden.
  • Windows: Implementeer de GCZ-service op een Windows. Deze implementatieoptie wordt aanbevolen voor ontwikkel- en testomgevingen.

Georuimtelijke verbruikszone (GCZ) implementeren in Azure Kubernetes Service (AKS)

Meer informatie over het implementeren van Georuimtelijke Verbruikszone (GCZ) in Azure Kubernetes Service (AKS).

Vereisten

Helm-grafiek georuimtelijke verbruikszone (GCZ) implementeren

  1. Kloon de GCZ-opslagplaats naar uw lokale omgeving:

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

  2. Wijzig de map in de geospatial map:

    cd geospatial/devops/azure/charts/geospatial

  3. Variabelen definiëren voor de implementatie:

    # 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. Maak de HELM-grafiek:

    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. Wijzig het servicetype in LoadBalancer voor de provider configuratiebestanden en transformer services.

    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. Controleer het configuratiebestand application.yml van de transformator om ervoor te zorgen dat de juiste schema's zijn opgenomen.

    nano ../transformer/application.yml

  7. Controleer het configuratiebestand koop-config.jsonvan de provider.

    nano ../provider/koop-config.json

  8. Verifiëren bij het AKS-cluster (Azure Kubernetes Service):

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

  9. AKS-naamruimte maken:

    kubectl create namespace $NAMESPACE

  10. HELM-afhankelijkheden implementeren:

    helm dependency build

  11. Implementeer de GCZ HELM-grafiek:

    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. Controleer de implementatie:

    kubectl get pods -n $NAMESPACE

    Nu ziet u de pods voor de ignite, provideren transformer services.

  13. Noteer vervolgens de externe IP-adressen voor de provider en transformer services.

    kubectl get service -n $NAMESPACE

    Deze IP-adressen worden gebruikt om verbinding te maken met de GCZ API-eindpunten.

Belangrijk

Als u de configuratiebestanden (bijvoorbeeld application.yml of koop-config.json) wilt bijwerken, moet u de AKS-configuratie (configmap) bijwerken en vervolgens de bestaande pods voor de provider en transformer services verwijderen. De pods worden opnieuw gemaakt met de nieuwe configuratie. Als u de configuratie wijzigt met behulp van de GCZ-API's, blijven de wijzigingen niet behouden nadat een pod opnieuw is opgestart.

Georuimtelijke verbruikszone (GCZ) implementeren op een virtuele Windows-machine

Meer informatie over het implementeren van Georuimtelijke Verbruikszone (GCZ) in Windows. Deze implementatieoptie wordt aanbevolen voor ontwikkel- en testomgevingen, omdat het eenvoudiger is om in te stellen en te configureren en minder onderhoud vereist.

Vereisten

GCZ implementeren in Windows

  1. Maak verbinding met uw virtuele Windows-machine.

  2. Download de volgende bestanden uit de GitLab-opslagplaats osdu:

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

  3. Open PowerShell als beheerder en navigeer naar de map waarin u de bestanden hebt gedownload.

  4. Voer de volgende opdrachten uit om de bestanden te extraheren:

    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. Configureer de omgevingsvariabelen:

    $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

    Zie de documentatie van OSDU GitLab voor meer omgevingsvariabelen.

  6. Valideer de configuratiebestanden voor de GCZ Provider en Transformer door de configuratiebestanden in een teksteditor te openen en de waarden indien nodig bij te werken.

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

    Belangrijk

    Als u wijzigingen aanbrengt in de schema's in de configuratiebestanden, moet u ervoor zorgen dat deze schema's worden weergegeven in beide configuratiebestanden.

  7. (optioneel) Installeer Python-afhankelijkheden (alleen vereist voor Bronlogboekinterpolatie).

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

  8. Start de GCZ-transformator.

    C:\gcz\transformer\transformer.bat local

  9. Bouw de GCZ-provider.

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

De provider luistert standaard op http://localhost:8083 en de transformer luistert op http://localhost:8080.

GCZ-API's openbaar publiceren (optioneel)

Als u de GCZ-API's openbaar wilt maken, kunt u Azure API Management (APIM) gebruiken. Met Azure API Management kunnen we de GCZ-service veilig beschikbaar maken op internet, omdat de GCZ-service nog geen ingebouwde verificatie en autorisatie heeft. Via APIM kunnen we beleidsregels toevoegen om de API's te beveiligen, bewaken en beheren.

Vereisten

  • Een Azure API Management-exemplaar. Als u geen Exemplaar van Azure API Management hebt, raadpleegt u Een Azure API Management-exemplaar maken.
  • De GCZ-API's worden geïmplementeerd en uitgevoerd.

Belangrijk

Het Azure API Management-exemplaar moet worden geïnjecteerd in een virtueel netwerk dat routeerbaar is voor het AKS-cluster om te kunnen communiceren met de GCZ-API's.

De GCZ-API's toevoegen aan Azure API Management

De GCZ OpenAPI-specificaties downloaden

  1. Download de twee OpenAPI-specificatie naar uw lokale computer.

  2. Open elk OpenAPI-specificatiebestand in een teksteditor en vervang de servers sectie door de bijbehorende IP-adressen van de Load Balancer van de AKS GCZ Services.

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

De GCZ-API's toevoegen aan Azure API Management

  1. Navigeer naar uw Azure API Management-service in Azure Portal.

  2. Selecteer API's in het navigatiedeelvenster aan de linkerkant.

  3. Selecteer + API toevoegen.

  4. Selecteer OpenAPI.

  5. Selecteer Een bestand selecteren en het gcz-openapi-provider.yaml bestand uploaden.

  6. Voer in het achtervoegsel van de API-URL het veld inignite-provider.

  7. Selecteer Maken.

  8. Herhaal de stappen voor het gcz-openapi-transformer.yaml bestand, maar gebruik gcz/transformer/admin het achtervoegsel van de API-URL.

    GCZ-API toevoegen aan APIM

Beleid configureren

Vervolgens moeten we het beleid configureren om de JSON-webtokens (JWT) te valideren.

U hebt de volgende informatie nodig:

  • Uw Microsoft Entra ID-tenant-id.
  • De Azure Data Manager for Energy-client-id (of de client-id die een token uitgeeft, indien gescheiden).

Notitie

Als u meerdere app-registraties hebt die tokens uitgeven, kunt u meerdere <application-id> elementen toevoegen aan het <client-application-ids> element.

  1. Zorg ervoor dat alle bewerkingen zijn geselecteerd in de zojuist gemaakte Geospatial Consumption Zone - Provider API.

  2. Selecteer onder Binnenkomende verwerking de optie ... en vervolgens code-editor.

  3. Plak de volgende beleidsdefinitie in de editor:

    <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. Vervang door %tenant-id% uw Microsoft Entra ID-tenant-id en %client-id% door de Azure Data Manager for Energy-client-id.

  5. Selecteer Opslaan.

  6. Herhaal de stappen voor de Geospatial Consumption Zone - Transformer API.

De GCZ-service testen

  1. Download de API-clientverzameling uit het OSDU GitLab en importeer deze in uw API-client (bijvoorbeeld Bruno, Postman).

  2. Voeg de volgende omgevingsvariabelen toe aan uw API-client:

    • PROVIDER_URL - De URL naar de GCZ Provider-API.
    • AMBASSADOR_URL - De URL naar de GCZ Transformer-API.
    • access_token - Een geldig ADME-toegangstoken.

  3. Als u wilt controleren of de GCZ werkt zoals verwacht, voert u de API-aanroepen uit in de verzameling.

Volgende stappen

Nadat u een geslaagde implementatie van GCZ hebt, kunt u het volgende doen:

  • Visualiseer uw GCZ-gegevens met behulp van de GCZ WebApps uit het OSDU GitLab.

Belangrijk

De GCZ WebApps zijn momenteel in ontwikkeling en bieden geen ondersteuning voor verificatie. U wordt aangeraden de WebApps in een particulier netwerk te implementeren en deze beschikbaar te maken met behulp van Azure-toepassing Gateway of Azure Front Door om verificatie en autorisatie in te schakelen.

U kunt ook gegevens opnemen in uw Azure Data Manager for Energy-exemplaar:

Verwijzingen

  • Zie OSDU GitLab voor informatie over georuimtelijke verbruikszone.