地理空間消費ゾーンをデプロイする
OSDU 地理空間消費ゾーン (GCZ) は、地理空間データの管理と利用を強化できるサービスです。 GCZ は位置ベースの情報の処理を合理化します。 技術的な複雑さを取り除き、込み入った情報に対処することなく、ソフトウェア アプリケーションが地理空間データにアクセスできるようにします。 すぐに使用できるマップ サービスを提供することで、GCZ は OSDU 対応アプリケーションとのシームレスな統合を容易にします。
このガイドでは、Azure Data Manager for Energy (ADME) と統合された地理空間消費ゾーン (GCZ) サービスをデプロイする方法について説明します。
Microsoft Entra ID でアプリ登録を作成する
GCZ をデプロイするには、Microsoft Entra ID でアプリ登録を作成する必要があります。 アプリ登録は、地理空間データのキャッシュを生成できるように、Azure Data Manager for Energy で GCZ API を認証するために使用されます。
アプリ登録を作成する方法については、「Microsoft Entra ID でアプリ登録を作成する」を参照してください。
Azure Data Manager for Energy の関連データを読み取るアクセス許可をアプリ登録に付与します。 詳細な手順については、OSDU グループにメンバーを追加する方法を参照してください。
セットアップ
GCZ サービスには、主に次の 2 つのデプロイ オプションがあります。
- Azure Kubernetes Service (AKS): AKS クラスターに GCZ サービスをデプロイします。 このデプロイ オプションは、運用環境に推奨されます。 セットアップ、構成、保守には、より多くの労力が必要です。
- Windows: Windows に GCZ サービスを展開します。 このデプロイ オプションは、開発環境とテスト環境に推奨されます。
Azure Kubernetes Service (AKS) に地理空間消費ゾーン (GCZ) をデプロイする
Azure Kubernetes Service (AKS) に地理空間消費ゾーン (GCZ) をデプロイする方法について説明します。
前提条件
- Azure サブスクリプション。 Azure サブスクリプションをお持ちでない場合は、無料アカウントを作成してください。
- 仮想ネットワーク統合を使用した Azure Kubernetes クラスター (AKS)。 詳細な手順については、「Azure Kubernetes Service (AKS) クラスターの作成」と「Azure Container Networking Interface (CNI) ネットワーク」を参照してください。
- Azure Cloud Shell または Azure CLI、kubectl、Git CLI。
地理空間消費ゾーン (GCZ) HELM チャートをデプロイする
GCZ リポジトリをローカル環境にクローンします。
git clone https://community.opengroup.org/osdu/platform/consumption/geospatial.gitディレクトリを
geospatialフォルダーに変更します。cd geospatial/devops/azure/charts/geospatialデプロイの変数を定義します。
# 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.0HELM チャートを作成します。
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サービスの種類を、
providerおよびtransformerサービス構成ファイルのLoadBalancerに変更します。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トランスフォーマー構成ファイル
application.ymlを確認して、正しいスキーマが含まれていることを確認します。nano ../transformer/application.ymlプロバイダー構成ファイル
koop-config.jsonをレビューします。nano ../provider/koop-config.jsonAzure Kubernetes Service (AKS) クラスターに対して認証します。
az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME --adminAKS 名前空間を作成します:
kubectl create namespace $NAMESPACEHELM の依存関係をデプロイします。
helm dependency buildGCZ HELM チャートをデプロイします。
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"デプロイを検証します。
kubectl get pods -n $NAMESPACEこれで、
ignite、provider、およびtransformerサービスのポッドが表示されます。次に、
providerおよびtransformerサービスの外部 IP をメモします。kubectl get service -n $NAMESPACEこれらの IP は、GCZ API エンドポイントへの接続に使用されます。
重要
構成ファイル (application.yml や koop-config.json など) を更新する場合は、AKS 構成 (configmap) を更新してから、provider および transformer サービスの既存のポッドを削除する必要があります。 ポッドは、新しい構成で再作成されます。 GCZ API を使用して構成を変更した場合、ポッドの再起動後に変更は保持されません。
Windows 仮想マシンに地理空間消費ゾーン (GCZ) をデプロイする
Windows に地理空間消費ゾーン (GCZ) をデプロイする方法について説明します。 このデプロイ オプションは、セットアップと構成が容易であり、メンテナンスが少なくて済むため、開発環境とテスト環境に推奨されます。
前提条件
- Azure Data Manager for Energy インスタンス。 Azure Data Manager for Energy インスタンスがない場合は、「Azure Data Manager for Energy インスタンスを作成する」を参照してください。
- Windows 仮想マシン。 Windows 仮想マシンがない場合は、「Azure で Windows 仮想マシンを作成する」を参照してください。 ローカル コンピューターを使用することもできます。
- Windows 仮想マシンにインストールされている Java JDK 17。 Java がインストールされていない場合は、Windows に Java をインストールする方法を参照してください。
- Windows 仮想マシンにインストールされている Node 18.19.1 (LTS)。 Node がインストールされていない場合は、Windows への Node.js と npm のインストール方法を参照してください。
- Windows 仮想マシンにインストールされている Python 3.11.4 以降。 Python がインストールされていない場合は、Windows に Python をインストールする方法を参照してください。
- インストール プロセス中に
pipを追加してください。pipの追加を忘れた場合は、手動でインストールできます。
- インストール プロセス中に
Windows に GCZ をデプロイする
Windows 仮想マシンに接続します。
OSDU GitLab リポジトリから次のファイルをダウンロードします。
管理者として PowerShell を開き、ファイルをダウンロードしたフォルダに移動します。
次のコマンドを実行してファイルを抽出します。
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\環境変数を構成します。
$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 のドキュメントを参照してください。
テキスト エディターで構成ファイルを開き、必要に応じて値を更新することで、GCZ プロバイダーとトランスフォーマーの構成ファイルを検証します。
- プロバイダー:
C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json - トランスフォーマー:
C:\gcz\gcz-transformer-core\config\application.yml
重要
構成ファイル内のスキーマを変更する場合は、これらのスキーマが両方の構成ファイルに示されていることを確認する必要があります。
- プロバイダー:
(省略可能) Python の依存関係をインストールします (ウェル ログ補間にのみ必要)。
pip install -r C:\gcz\gcz-transformer-core\src\main\resources\script\requirements.txt --no-index --find-links python-dependenciesGCZ トランスフォーマーを起動します。
C:\gcz\transformer\transformer.bat localGCZ プロバイダーをビルドします。
cd C:\gcz\gcz-provider\gcz-provider-core npm install npm start
既定では、プロバイダーは http://localhost:8083 でリッスンしており、トランスフォーマーは http://localhost:8080 でリッスンしています。
GCZ API をパブリックに公開する (省略可能)
GCZ API をパブリックに公開する場合は、Azure API Management (APIM) を使用できます。 Azure API Management を使用すると、GCZ サービスに認証と承認がまだ組み込まれていないので、GCZ サービスをインターネットに安全に公開できます。 APIM を使用して、API をセキュリティで保護、監視、管理するためのポリシーを追加できます。
前提条件
- Azure API Management インスタンス。 Azure API Management インスタンスがない場合は、「Azure API Management インスタンスを作成する」を参照してください。
- GCZ API がデプロイされ、実行されます。
重要
GCZ API と通信できるようにするには、AKS クラスターにルーティング可能な仮想ネットワークに Azure API Management インスタンスを挿入する必要があります。
Azure API Management に GCZ API を追加する
GCZ OpenAPI の仕様をダウンロードする
2 つの OpenAPI 仕様をローカル コンピューターにダウンロードします。
各 OpenAPI 仕様ファイルをテキスト エディターで開き、
serversセクションを AKS GCZ サービスのロード バランサーの対応する IP に置き換えます。servers: - url: "http://<GCZ-Service-LoadBalancer-IP>/ignite-provider"
Azure API Management に GCZ API を追加する
Azure portal で Azure API Management サービスに移動します。
左側のナビゲーション ウィンドウで [API] を選択します。
[+ API の追加] を選択します。
OpenAPI を選択します。
[ファイルの選択] を選択し、
gcz-openapi-provider.yamlファイルをアップロードします。[API URL サフィックス] フィールドに「
ignite-provider」と入力します。［作成］ を選択します
gcz-openapi-transformer.yamlファイルで手順を繰り返しますが、gcz/transformer/adminを API URL サフィックスとして使用します。
ポリシーの構成
次に、JSON Web トークン (JWT) を検証するようにポリシーを構成する必要があります。
次の情報が必要です。
- Microsoft Entra ID テナント ID。
- Azure Data Manager for Energy クライアント ID (または別の場合はトークン発行クライアント ID)。
Note
トークンを発行するアプリの登録が複数ある場合は、<client-application-ids> 要素に複数の <application-id> 要素を追加できます。
新しく作成した
Geospatial Consumption Zone - ProviderAPI で、[すべての操作] が選択されていることを確認します。[受信処理] で、[...]、[コード エディター] の準に選択します。
エディターに次のポリシー定義を貼り付けます。
<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>%tenant-id%を Microsoft Entra ID テナント ID に置き換え、%client-id%を Azure Data Manager for Energy クライアント ID に置き換えます。[保存] を選択します。
Geospatial Consumption Zone - TransformerAPI の手順を繰り返します。
GCZ サービスのテスト
OSDU GitLab から API クライアント コレクションをダウンロードし、選択した API クライアント (つまり、Bruno または Postman) にインポートします。
API クライアントに次の環境変数を追加します。
PROVIDER_URL- GCZ プロバイダー API の URL。AMBASSADOR_URL- GCZ トランスフォーマー API の URL。access_token- 有効な ADME アクセス トークン。
GCZ が期待どおりに動作していることを確認するには、コレクション内で API 呼び出しを実行します。
次のステップ
GCZ のデプロイが成功したら、次のことができます。
- OSDU GitLab の GCZ WebApps を使用して GCZ データを視覚化します。
重要
GCZ WebApps は現在開発中であり、認証をサポートしていません。 WebApps をプライベート ネットワークにデプロイし、Azure Application Gateway または Azure Front Door を使用して公開して、認証と承認を有効にすることをお勧めします。
Azure Data Manager for Energy インスタンスにデータを取り込むこともできます。
関連情報
- 地理空間消費ゾーンの詳細については、OSDU GitLab を参照してください。