Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

部署示範

示範部署會使用預先定義的原始樣本資料集，提供簡化的體驗。這項服務提供端對端工作流程，可部署 Cortex Framework Dataform 管道進行協調，並使用範例資料初始化對應的 BigQuery 資料集。

事前準備

請先完成「Prerequisites」(必要條件) 頁面中列出的前置作業，再繼續進行示範部署。

取得必要的 IAM 角色和權限

取得必要的 Identity and Access Management (IAM) 權限，在目標 Google Cloud 專案中部署 Cortex Framework 內容。

目標專案的角色

如要取得部署 Cortex Framework 所需的權限，請要求管理員在目標專案中授予您下列 IAM 角色：

BigQuery 工作使用者 (roles/bigquery.jobUser)
BigQuery 資料編輯者 (roles/bigquery.dataEditor)
Dataform 管理員 (roles/dataform.admin)
服務使用情形用戶 (roles/serviceusage.serviceUsageConsumer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

指令觸發 Dataform 存放區建立作業。

如要將要求的角色授予使用者，可以使用下列指令碼：

# Grant BigQuery JobUser to the user
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.jobUser"

# Grant BigQuery DataEditor to the user
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.dataEditor"

# Grant BigQuery Dataform admin to the user
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataform.admin"

# Grant Service Usage Consumer to the user
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/serviceusage.serviceUsageConsumer"

選用：使用服務帳戶取得示範部署作業所需的 IAM 角色

只有在啟用選用 --service_account 參數的示範部署作業中，才需要下列角色。提供服務帳戶可設定資料管道的排程，簡化部署後的工作。您可以在 Dataform 的「發布和排程」分頁中，使用三點選單手動觸發這項工作流程設定。

如要取得部署 Cortex Framework 試用版所需的權限，請要求管理員在來源和目標專案中，授予您服務帳戶權杖建立者 (roles/iam.serviceAccountTokenCreator) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要建立服務帳戶並授予必要角色，可以使用下列指令碼：

# Create the service account
gcloud iam service-accounts create cortex-dataform \
        --description="Service account for Cortex Dataform execution" \
        --display-name="Cortex Dataform Service Account" \
        --project=PROJECT_ID

# Wait for the service account to propagate (IAM eventual consistency)
sleep 10

# Grant BigQuery DataEditor to the service account
gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:cortex-dataform@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/bigquery.dataEditor"

# Grant BigQuery jobUser to the service account
gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:cortex-dataform@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/bigquery.jobUser"

# Grant Dataform Editor to the service account
gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:cortex-dataform@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/dataform.editor"

# Grant the user Service Account Token Creator role on the Cortex service account
gcloud iam service-accounts add-iam-policy-binding \
        cortex-dataform@PROJECT_ID.iam.gserviceaccount.com \
        --member="user:USER_EMAIL" \
        --role="roles/iam.serviceAccountTokenCreator" \
        --project=PROJECT_ID

PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

## Note: In case the commands below should fail with message: 
# "serviceAccount:service-$PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com" not found
# the default dataform service accounts hasn't been yet provisioned for given project.
# In such case, please execute the commands after initial run of `uv run cortex-*`

# Grant the Dataform Service Account the Token Creator role on the Cortex service account
gcloud iam service-accounts add-iam-policy-binding \
        cortex-dataform@PROJECT_ID.iam.gserviceaccount.com \
        --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com" \
        --role="roles/iam.serviceAccountTokenCreator" \
        --project=PROJECT_ID

# Grant the Dataform Service Account the Service Account User role on the Cortex service account
gcloud iam service-accounts add-iam-policy-binding \
        cortex-dataform@PROJECT_ID.iam.gserviceaccount.com \
        --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com" \
        --role="roles/iam.serviceAccountUser" \
        --project=PROJECT_ID

部署作業

請按照下列步驟建立 Python 虛擬環境、同步處理依附元件，並觸發資料管道。請記得使用 Cortex Framework uv 指令碼，將資料資產建構並推送至 Google Cloud 專案，將本機設定轉換為可擴充的即時資料架構。詳情請參閱「必要條件」一節中的「uv 安裝」。

執行示範部署作業

執行下列指令來觸發部署作業。這項程序會執行下列動作：

確認已完成所有必要條件。
將範例資料載入 BigQuery 資料集，做為示範用的原始層。
建構 Dataform 管道，透過 Cortex Framework 資料層處理範例資料。
建立 Dataform 存放區和工作區，然後將編譯的構件與存放區同步。*選用：如果已提供服務帳戶，請建立工作流程排程，並觸發初始 Dataform 工作流程執行作業。--service_account

如要使用預設值部署試用版，請執行下列指令：

uv run cortex-demo --project_id=PROJECT_ID --sap_version s4

如要使用服務帳戶進行示範部署，請執行下列指令：

uv run cortex-demo --project_id=PROJECT_ID \
  --service_account="cortex-dataform@PROJECT_ID.iam.gserviceaccount.com" \
  --create_workflow_configs

驗證

部署完成後：

開啟 Dataform，檢查存放區中建立的新程式碼：
1. 已建立 Dataform 存放區：cortex-framework-demo
2. 在 Dataform 存放區中，開發工作區：demo
3. 已編譯並同步處理的程式碼 (按一下 Compiled graph 即可查看圖表)。
手動執行 Dataform 動作：
1. 在 Google Cloud Dataform 控制台中，從存放區 cortex-framework-demo 開啟 Dataform 工作區：「demo」。
2. 按一下「Start execution」(開始執行)。
3. 點選「執行動作」。
4. 按一下「All actions」(所有動作)。
5. 按一下「Start execution」(開始執行)。
6. 使用「工作流程執行記錄」分頁，監控 Dataform 存放區中所有動作的執行情況。
排定執行 Dataform 動作

只有在部署期間使用 --service_account 和 --create_workflow_configs 參數時，才適用下列步驟：

在 Dataform 控制台中開啟 Dataform 存放區 cortex-framework-demo。 Google Cloud
按一下「版本與排程」
在「Workflow configurations」(工作流程設定) 區段中，點選要執行的動作的三點選單，然後按一下「Start now」(立即開始)。
使用「工作流程執行記錄」分頁，監控 Dataform 存放區中所有動作的執行情況。
前往 BigQuery 控制台，然後按一下 Datasets 即可查看新建立的資料集，並驗證結構定義和資料。已建立的資料集：
- cortex_demo_sap_s4_raw：這個資料集包含來源系統 (在本範例中為 SAP S/4HANA) 的原始資料。
- cortex_demo_sap_s4_data_foundation：這個資料集代表資料基礎層，其中來自原始層的原始資料會經過 CDC 處理。
- cortex_demo_data_product：這個資料集包含經過精簡的示範資料產品、專為供使用者取用而設計的高效能檢視區塊或資料表。
- cortex_demo_samples：這個資料集包含範例消費資料產品的試用資料。

清除示範部署作業資源

成功部署試用版後，您可以移除已使用的 Google Cloud 資源，避免持續產生費用。下列指令碼會刪除建立的 BigQuery 資料集、Dataform 工作區和 Dataform 存放區：

#!/bin/bash

# Define variables using names from uv-run-cortex-demo.md
PROJECT_ID="PROJECT_ID"
SAP_VERSION="s4"

DATAFORM_REGION="us-central1"
SOURCE_SAP_RAW_DATASET_ID="cortex_demo_sap_s4_raw"
TARGET_SAP_FOUNDATION_DATASET_ID="cortex_demo_sap_s4_data_foundation"
if [[ "$SAP_VERSION" == "ecc" ]]; then
  SOURCE_SAP_RAW_DATASET_ID="cortex_demo_sap_ecc_raw"
  TARGET_SAP_FOUNDATION_DATASET_ID="cortex_demo_sap_ecc_data_foundation"
fi
TARGET_DP_DATASET_ID="cortex_demo_data_product"
TARGET_SAMPLES_DATASET_ID="cortex_demo_samples"
REPOSITORY_NAME="cortex-framework-demo"
WORKSPACE_NAME="demo"
SERVICE_ACCOUNT_NAME="cortex-dataform"


# Color codes for formatting status output
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
RED='\033[0;31m'
NC='\033[0m' # No Color

# Helper function to delete a resource and report status
delete_resource() {
    local label=$1
    local url=$2
    local resource_type=$3
    
    echo -n "${label}... "
    
    local temp_file=$(mktemp)
    local code=$(curl -s -o "${temp_file}" -w "%{http_code}" -X DELETE \
        -H "Authorization: Bearer ${ACCESS_TOKEN}" \
        "${url}")
        
    if [ "$code" -eq 200 ] || [ "$code" -eq 204 ]; then
        echo -e "${GREEN}ok${NC}"
    elif [ "$code" -eq 404 ]; then
        echo -e "${YELLOW}skipped, ${resource_type} not found${NC}"
    else
        echo -e "${RED}failed (HTTP ${code})${NC}"
        if [ -s "${temp_file}" ]; then
            echo "  Error details:"
            sed 's/^/    /' "${temp_file}"
        fi
    fi
    rm -f "${temp_file}"
}

echo "Deleting BigQuery datasets..."
for DATASET_ID in "${SOURCE_SAP_RAW_DATASET_ID}" \
                  "${TARGET_SAP_FOUNDATION_DATASET_ID}" \
                  "${TARGET_DP_DATASET_ID}" \
                  "${TARGET_SAMPLES_DATASET_ID}"; do
    echo "deleting ${PROJECT_ID}:${DATASET_ID}"
    bq rm -r -f "${PROJECT_ID}:${DATASET_ID}"
done

ACCESS_TOKEN=$(gcloud auth print-access-token)
delete_resource "Deleting Dataform workspace ${WORKSPACE_NAME}" \
    "https://dataform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${DATAFORM_REGION}/repositories/${REPOSITORY_NAME}/workspaces/${WORKSPACE_NAME}" \
    "workspace"

echo "Deleting Dataform workflow configurations..."
WORKFLOW_CONFIGS_JSON=$(curl -s -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    "https://dataform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${DATAFORM_REGION}/repositories/${REPOSITORY_NAME}/workflowConfigs")

WORKFLOW_CONFIGS=$(echo "${WORKFLOW_CONFIGS_JSON}" | grep '"name":' | sed -E 's/.*"name": "([^"]+)".*/\1/')

if [ -z "${WORKFLOW_CONFIGS}" ]; then
    echo -e "  No workflow configurations found. ${YELLOW}skipped${NC}"
else
    for config in ${WORKFLOW_CONFIGS}; do
        delete_resource "  Deleting workflow config: ${config##*/}" \
            "https://dataform.googleapis.com/v1beta1/${config}" \
            "workflow config"
    done
fi

echo "Deleting Dataform release configurations..."
RELEASE_CONFIGS_JSON=$(curl -s -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    "https://dataform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${DATAFORM_REGION}/repositories/${REPOSITORY_NAME}/releaseConfigs")

RELEASE_CONFIGS=$(echo "${RELEASE_CONFIGS_JSON}" | grep '"name":' | sed -E 's/.*"name": "([^"]+)".*/\1/')

if [ -z "${RELEASE_CONFIGS}" ]; then
    echo -e "  No release configurations found. ${YELLOW}skipped${NC}"
else
    for config in ${RELEASE_CONFIGS}; do
        delete_resource "  Deleting release config: ${config##*/}" \
            "https://dataform.googleapis.com/v1beta1/${config}" \
            "release config"
    done
fi

delete_resource "Deleting Dataform repository ${REPOSITORY_NAME}" \
    "https://dataform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${DATAFORM_REGION}/repositories/${REPOSITORY_NAME}?force=true" \
    "repository"

if gcloud iam service-accounts describe "${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" --project="${PROJECT_ID}" >/dev/null 2>&1; then
    read -p "Do you want to delete the service account ${SERVICE_ACCOUNT_NAME}? (y/N): " -r
    if [[ "$REPLY" =~ ^[Yy]$ ]]; then
        echo -n "Deleting service account ${SERVICE_ACCOUNT_NAME}... "
        ERROR_MSG=$(gcloud iam service-accounts delete "${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" --project="${PROJECT_ID}" --quiet 2>&1)
        EXIT_CODE=$?
        if [ ${EXIT_CODE} -eq 0 ]; then
            echo -e "${GREEN}ok${NC}"
        else
            echo -e "${RED}failed${NC}"
            echo "  Error details:"
            echo "${ERROR_MSG}" | sed 's/^/    /'
        fi
    else
        echo -e "Deleting service account ${SERVICE_ACCOUNT_NAME}... ${YELLOW}skipped (user cancelled)${NC}"
    fi
else
    echo -e "Deleting service account ${SERVICE_ACCOUNT_NAME}... ${YELLOW}skipped, service account not found${NC}"
fi

echo "Cortex Framework demo deployment cleanup complete."

後續步驟

請參閱實際工作環境部署，瞭解如何在實際工作環境中部署 Google Cloud Cortex Framework。
請參閱來源系統整合，瞭解如何連結生產系統。