部署地理空間使用量區域
本指南說明如何部署與適用於能源的 Azure 資料管理員 (ADME) 整合的地理空間使用量區域 (GCZ) 服務。
重要
雖然地理空間使用量區域 (GCZ) 服務是已從 OSDU 論壇淘汰的服務，但在安全性和使用方面有限制。 我們將部署一些額外的服務和原則來保護環境，但建議您遵循 OSDU Gitlab 上的服務開發。
描述
OSDU 地理空間使用量區域 (GCZ) 是一項服務，可增強地理空間資料的管理和使用率。 GCZ 可簡化位置型資訊的處理。 其會抽取技術複雜性，讓軟體應用程式存取地理空間資料，而不需要處理複雜的詳細資料。 藉由提供現成可用的地圖服務，GCZ 有助於與已啟用 OSDU 的應用程式緊密整合。
在 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)。
重要
使用 AKS 的 GCZ 目前部署僅限於所包含結構描述的預設設定，如需支援的結構描述的相關訊息，請參閱 OSDU GitLab。 若要新增或變更結構描述 (亦即較新版本)，將必須建立自訂容器映像。
必要條件
- 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: 557963fb-ede7-4a88-9e3e-19ace7f1e36b AZURE_CLIENT_ID="<clientId>" # App Registration client ID. Example: b149dc73-ed8c-4ad3-bbaf-882a208f87eb AZURE_CLIENT_SECRET="<clientSecret>" # App Registration client secret. CALLBACK_URL="http://localhost:5050" #ie: http://localhost:8080 # 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 VERSION=0.1.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: community.opengroup.org:5555/osdu/platform/consumption/geospatial/gridgain-community tag: 8.8.34 configuration: gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE" gcz_ignite_service: "$GCZ_IGNITE_SERVICE" provider: namespace: $NAMESPACE image: repository: community.opengroup.org:5555 name: osdu/platform/consumption/geospatial/geospatial-provider-master tag: latest service: type: LoadBalancer annotations: service.beta.kubernetes.io/azure-load-balancer-internal: "true" transformer: namespace: $NAMESPACE image: repository: community.opengroup.org:5555 name: osdu/platform/consumption/geospatial/geospatial-transformer-master tag: latest service: type: LoadBalancer annotations: service.beta.kubernetes.io/azure-load-balancer-internal: "true" configuration: datapartitionid: $DATA_PARTITION_ID clientId: $AZURE_CLIENT_ID tenantId: $AZURE_TENANT_ID callbackURL: $CALLBACK_URL 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: {{- range $key, $value := $.Values.global.provider.service.annotations }} {{ $key }}: {{ $value | quote }} {{- end }} 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: {{- range $key, $value := $.Values.global.transformer.service.annotations }} {{ $key }}: {{ $value | quote }} {{- end }} spec: selector: app: transformer ports: - port: 80 protocol: TCP targetPort: 8080 type: {{ $.Values.global.transformer.service.type }} EOF向 Azure Kubernetes Service (AKS) 叢集進行驗證：
az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME --admin部署 HELM 相依性：
helm dependency build部署 GCZ HELM 圖表：
helm install $CHART ../$CHART --values osdu_gcz_custom_values.yaml驗證部署：
kubectl get pods -n $NAMESPACE現在您應該會看到
ignite、provider和transformer服務的 Pod。接下來，請記下
provider和transformer服務的外部 IP。kubectl get service -n $NAMESPACE這些 IP 可用來連線到 GCZ API 端點。
在 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 (外部 IP)。servers: - url: "http://<GCZ-Service-External-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 用戶端 (例如 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。