部署地理空間使用量區域
OSDU 地理空間使用量區域 (GCZ) 是一項服務，可增強地理空間資料的管理和使用率。 GCZ 可簡化位置型資訊的處理。 其會抽取技術複雜性，讓軟體應用程式存取地理空間資料，而不需要處理複雜的詳細資料。 藉由提供現成可用的地圖服務，GCZ 有助於與已啟用 OSDU 的應用程式緊密整合。
本指南說明如何部署與適用於能源的 Azure 資料管理員 (ADME) 整合的地理空間使用量區域 (GCZ) 服務。
在 Microsoft Entra ID 中建立應用程式註冊
若要部署 GCZ，您必須在 Microsoft Entra ID 中建立應用程式註冊。 應用程式註冊可用來向適用於能源的 Azure 數據管理員驗證 GCZ API，以產生地理空間數據的快取。
如需如何建立應用程式註冊的指示，請參閱在 Microsoft Entra ID 中建立應用程式註冊。
授與應用程式註冊權限，以讀取適用於能源的 Azure 資料管理員中的相關資料。 如需進一步指示，請參閱如何將成員新增至 OSDU 群組。
設定
GCZ 服務有兩個主要部署選項：
- 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 容器網路介面 (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.0建立 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將
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.json向 Azure Kubernetes Service (AKS) 叢集進行驗證：
az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME --admin建立 AKS 命名空間：
kubectl create namespace $NAMESPACE部署 HELM 相依性：
helm dependency build部署 GCZ 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服務的 Pod。接下來，請記下
provider和transformer服務的外部 IP。kubectl get service -n $NAMESPACE這些 IP 可用來連線到 GCZ API 端點。
重要
如果您想要更新組態檔 （例如 application.yml 或 koop-config.json），您必須更新 AKS 組態 （configmap），然後刪除 和 transformer 服務的現有 Podprovider。 Pod 將會使用新的組態重新建立。 如果您使用 GCZ API 變更設定，則 Pod 重新啟動之後將不會儲存變更。
在 Windows 虛擬機器上部署地理空間取用區域 (GCZ)
了解如何在 Windows 上部署地理空間取用區域 (GCZ)。 此部署選項建議用於開發和測試環境，因為它更容易設定和配置，而且需要較少的維護。
必要條件
- 用於能源產業的 Azure 資料管理員執行個體。 如果您沒有適用於能源的 Azure 資料管理員執行個體，請參閱建立適用於能源的 Azure 資料管理員執行個體。
- 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-dependencies啟動 GCZ 轉換器。
C:\gcz\transformer\transformer.bat local建置 GCZ 提供者。
cd C:\gcz\gcz-provider\gcz-provider-core npm install npm start
根據預設，提供者會於 http://localhost:8083 接聽，而轉換器會於 http://localhost:8080 接聽。
公開發佈 GCZ API (選用)
如果您想要公開 GCZ API，您可以使用 Azure API 管理 (APIM)。 Azure API 管理可讓我們安全地將 GCZ 服務向網際網路公開，因為 GCZ 服務尚未有內建驗證和授權。 透過 APIM，我們可以新增原則來保護、監視和管理 API。
必要條件
- Azure API 管理執行個體。 如果您沒有 Azure API 管理執行個體，請參閱建立 Azure API 管理執行個體。
- GCZ API 已部署並執行。
重要
Azure API 管理執行個體必須插入可路由至 AKS 叢集的虛擬網路，才能與 GCZ API 通訊。
將 GCZ API 新增至 Azure API 管理
下載 GCZ OpenAPI 規格
將兩個 OpenAPI 規格下載到您的本機電腦。
在文本編輯器中開啟每個 OpenAPI 規格檔案，並將 區
servers段取代為 AKS GCZ 服務負載平衡器的對應 IP。servers: - url: "http://<GCZ-Service-LoadBalancer-IP>/ignite-provider"
將 GCZ API 新增至 Azure API 管理
在 Azure 入口網站中，瀏覽至您的 Azure API 管理服務。
在左導覽窗格中，選取 [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 租用戶識別碼。
- 適用於能源的 Azure 資料管理員用戶端識別碼 (如果不同，則為權杖核發用戶端識別碼)。
注意
如果您有多個應用程式註冊核發權杖，則可以將多個 <application-id> 元素新增至 <client-application-ids> 元素。
在新建立的
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>以您的 Microsoft Entra ID 租用戶識別碼取代
%tenant-id%，並以適用於能源的 Azure 資料管理員用戶端識別碼取代%client-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 應用程式閘道或 Azure Front Door 來公開，以啟用驗證和授權。
您也可以將資料內嵌至 Azure Data Manager for Energy 執行個體：
參考資料
- 如需地理空間取用區域的相關訊息，請參閱 OSDU GitLab。