本頁面由 Cloud Translation API 翻譯而成。

以獨立模式執行 Mainframe Connector

本頁面說明如何在 Cloud Run 上安裝 Mainframe Connector、轉碼資料、將資料儲存至 BigQuery，以及從 BigQuery 匯出資料。

Mainframe Connector 5.13.0 以上版本支援在 Google Cloud上以獨立作業的形式執行 Mainframe Connector。這項功能可讓您將 Mainframe Connector 做為容器化批次作業執行，例如做為 Cloud Run 作業、Google Kubernetes Engine 作業，或在 Docker 容器中執行。這個選項可協助您避免在本機大型主機上安裝 Mainframe Connector，並輕鬆將大型主機排隊循序存取方法 (QSAM) 檔案剖析作業，整合至現有的擷取、轉換及載入 (ETL) 工作流程。

使用獨立版本的 Mainframe Connector 時，您必須自行設定 ETL 工作流程，將 QSAM 檔案載入 Google Cloud 。

事前準備

在 Cloud Run 上部署 Mainframe Connector。
建立服務帳戶，或找出要與 Mainframe Connector 搭配使用的現有服務帳戶。這個服務帳戶必須具備存取 Cloud Storage 值區、BigQuery 資料集，以及任何其他 Google Cloud 您想使用的資源的權限。
確認您建立的服務帳戶已獲派 Cloud Run 叫用者角色。
確認大型主機資料已在 Google Cloud 上以 QSAM 檔案的形式提供。

在 Cloud Run 上以獨立模式使用 Mainframe Connector 轉碼資料

Mainframe Connector 提供兩種方式，可在 Google Cloud上以獨立工作形式執行 Mainframe Connector：

使用 qsam 指令 (5.16.0 以上版本)
使用 gsutil cp 指令

`qsam` 指令的優點

qsam 指令具備下列優點：

支援複合資料類型，包括 OCCURS 子句 (清單)、REDEFINES 子句和巢狀記錄。如要進一步瞭解這些資料類型，請參閱qsam轉碼參考資料。
支援透過轉碼器設定檔設定轉碼程序。這項功能可讓您在將資料解碼為 Google Cloud，以及將資料編碼回大型主機時，享有更大的彈性。
支援建立溢位資料集，也就是轉碼錯誤資料表，可用於檢查錯誤。
支援多種輸入和輸出格式。這項功能可讓您在各種資料倉儲之間載入資料。

使用 `qsam` 指令以獨立模式執行 Mainframe Connector

如要使用 qsam 指令，透過獨立模式的 Mainframe Connector 轉碼資料，請按照下列步驟操作：

建立 YAML 檔案，內含下列指令：

讀取資料集
將影片轉碼為支援的格式
將其上傳至 Cloud Storage

輸入資料集必須是記錄長度固定或可變的 QSAM 檔案。您可以使用下列 YAML 檔案範例讀取資料集、轉碼為 ORC 格式，然後上傳至 Cloud Storage。

在下列範例中，我們使用 Cloud Storage DataPath 做為 INFILE、OUTFILE、COPYBOOK 和 TRANSCODE_CONFIGURATION 的位置。

environmentVariables:
- name: "INFILE"
  value: "INFILE"
- name: "OUTFILE"
  value: "OUTFILE"
- name: "COPYBOOK"
  value: "COPYBOOK"
- name: "TRANSCODE_CONFIGURATION"
  value: "TRANSCODE_CONFIGURATION"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"

command:
  qsam decode $INFILE $OUTFILE
  --copybook $COPYBOOK
  --transcode-configuration ${TRANSCODE_CONFIGURATION}
  --output-format orc
  --parallelism 8
  --chunk-size "512Mib"

更改下列內容：

INFILE：輸入檔案的名稱。
OUTFILE：輸出檔案的名稱。
COPYBOOK_PATH：副本 DD 的路徑。
TRANSCODE_CONFIGURATION_PATH：轉碼設定檔的路徑。
LOG_PROJECT：記錄專案的名稱。

以下是 YAML 檔案範例：

environmentVariables:
- name: "INFILE"
  value: "gs://my_bucket/my/input.dat"
- name: "OUTFILE"
  value: "gs://my_bucket/my/output.orc"
- name: "COPYBOOK"
  value: "gs://my_bucket/my/copybook.cpy"
- name: "TRANSCODE_CONFIGURATION"
  value: "gs://my_bucket/my/transcode-configuration-file.json"
- name: "LOG_PROJECT"
  value: "the log project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  qsam decode $INFILE $OUTFILE
  --copybook $COPYBOOK
  --transcode-configuration ${TRANSCODE_CONFIGURATION}
  --output-format orc
  --parallelism 8
  --chunk-size "512Mib"

使用下列指令建立 job.yaml 檔案。
```
kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
            command:
            - bash
            - /opt/mainframe-connector/standalone.sh
            - --argsFrom
            - LOCATION_OF_THE_COMMAND_YAML_FILE
```
更改下列內容：
- JOB：Cloud Run 工作的名稱。工作名稱不得超過 49 個字元，且每個區域和專案的工作名稱不得重複。
- IMAGE：工作容器映像檔的網址，例如 us-docker.pkg.dev/cloudrun/container/job:latest。
- LOCATION_OF_THE_COMMAND_YAML_FILE：您在上一步建立的 YAML 檔案位置。
使用下列指令部署新工作：
```
gcloud run jobs replace job.yaml
```
使用下列指令執行作業：
```
gcloud run jobs execute JOB_NAME
```
將 JOB_NAME 改為工作名稱。

如要進一步瞭解如何建立及執行 Cloud Run 工作，請參閱「建立新工作」和「執行工作」。

使用 `gsutil cp` 指令以獨立模式執行 Mainframe Connector

如要使用 gsutil cp 指令，以獨立模式透過 Mainframe Connector 轉碼資料，請按照下列步驟操作：

建立 YAML 檔案，內含下列指令：
- 讀取資料集
- 轉碼為 ORC
- 將其上傳至 Cloud Storage
輸入資料集必須是記錄長度固定或可變的 QSAM 檔案。您可以使用下列 YAML 檔案範例讀取資料集、轉碼為 ORC 格式，然後上傳至 Cloud Storage。

在下列範例中，請從 INFILE 資料集讀取資料，並從 COPYBOOK DD 讀取記錄版面配置。
```
environmentVariables:
- name: "INFILE"
  value: "INFILE"
- name: "INFILE_DSN"
  value: "INFILE_DSN"
- name: "GCSDSNURI"
  value: "INFILE_DSN_FILEPATH"
- name: "COPYBOOK"
  value: "COPYBOOK_FILEPATH"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  gsutil cp gs://outputbucket/output
  --parallelism 8
  --maxChunkSize "512Mib"
  --parser_type=copybook
```
更改下列內容：
- INFILE：輸入檔案的名稱。
- INFILE_DSN：輸入資料來源名稱 (DSN) 檔案的名稱。
- INFILE_DSN_FILEPATH：輸入 DSN 檔案的路徑。
- COPYBOOK_FILEPATH：副本 DD 的路徑。
- LOG_PROJECT：記錄專案的名稱。
以下是 YAML 檔案範例：
```
  environmentVariables:
  - name: "INFILE"
    value: "input.dat"
  - name: "INFILE_DSN"
    value: "input.dat"
  - name: "GCSDSNURI"
    value: "gs://inputbucket/inputfolder"
  - name: "COPYBOOK"
    value: "gs://inputbucket/copybook.cpy"
  - name: "LOG_PROJECT"
    value: "the log project"
  - name: "IBM_JAVA_OPTIONS"
    value: "-XX:+UseContainerSupport"
  command:
    gsutil cp gs://outputbucket/output
    --parallelism 8
    --maxChunkSize "512Mib"
    --parser_type=copybook
```
注意
- 匯入程序會忽略含有 FILLER 後置字元的變數。
- 自 5.12.0 版起，Mainframe Connector 會將變數名稱中的連字號 (「-」) 替換為底線 (「_」)。如要在變數名稱中保留連字號，請將資料庫變數 BQSH_FEATURE_CONVERT_UNDERSCORE_IN_FIELDS_NAME 設為 false，停用這項自動轉換功能。
如需 Mainframe Connector 支援的完整環境變數清單，請參閱「環境變數」。

如要記錄在此程序中執行的指令，可以啟用載入統計資料。
使用下列指令建立 job.yaml 檔案。
```
kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE
            command:
            - bash
            - /opt/mainframe-connector/standalone.sh
            - --argsFrom
            - LOCATION_OF_THE_COMMAND_YAML_FILE
```
更改下列內容：
- JOB：Cloud Run 工作的名稱。工作名稱不得超過 49 個字元，且每個區域和專案的工作名稱不得重複。
- IMAGE：工作容器映像檔的網址，例如 us-docker.pkg.dev/cloudrun/container/job:latest。
- LOCATION_OF_THE_COMMAND_YAML_FILE：您在上一步建立的 YAML 檔案位置。
使用下列指令部署新工作：
```
gcloud run jobs replace job.yaml
```
使用下列指令執行作業：
```
gcloud run jobs execute JOB_NAME
```
將 JOB_NAME 改為工作名稱。

如要進一步瞭解如何建立及執行 Cloud Run 工作，請參閱「建立新工作」和「執行工作」。

將 BigQuery 資料表匯出至大型主機資料集

您可以建立 YAML 檔案，從 QUERY DD 檔案執行 SQL 讀取作業，並將產生的資料集匯出至 Cloud Storage 做為二進位檔案，藉此將 BigQuery 資料表匯出至大型主機資料集，如下所示。

建立及執行 Cloud Run 工作的步驟，與在 Cloud Run 上以獨立模式使用 Mainframe Connector 轉碼資料一節所述相同。唯一的差別在於 YAML 檔案中提及的指令。Mainframe Connector 提供兩種匯出 BigQuery 資料表的方式：

使用 qsam 指令 (5.16.0 以上版本)
使用 bq export 指令

使用 `qsam` 指令

environmentVariables:
  - name: "QUERY"
    value: "QUERY_PATH"
  - name: "OUTFILE"
    value: "OUTFILE"
  - name: "COPYBOOK"
    value: "COPYBOOK_PATH"
  - name: "TRANSCODE_CONFIGURATION"
    value: "TRANSCODE_CONFIGURATION_PATH"
  - name: "PROJECT_ID"
    value: "PROJECT_ID"
  - name: "LOCATION"
    value: "LOCATION"
  - name: "LOG_PROJECT"
    value: "LOG_PROJECT"
  - name: "IBM_JAVA_OPTIONS"
    value: "-XX:+UseContainerSupport"
command:
qsam encode \
  $QUERY
  $OUTFILE
  --copybook ${COPYBOOK_PATH}
  --transcode-configuration ${TRANSCODE_CONFIGURATION_PATH}
  --input-format=BIGQUERY \
  --input-parameter project_id=${PROJECT_ID} \
  --input-parameter location=${LOCATION}

更改下列內容：

QUERY_PATH：要執行的 SQL 查詢。查詢結果會編碼為二進位檔案。
OUTFILE：用於存放輸出二進位檔案的 Cloud Storage bucket。
COPYBOOK_PATH：副本 DD 的路徑。
TRANSCODE_CONFIGURATION_PATH：轉碼器設定檔的路徑。
LOG_PROJECT：記錄專案的名稱。
PROJECT_ID：您要執行查詢的專案 ID。
LOCATION：要執行查詢的地區或多地區。建議您在靠近資料的位置執行查詢。預設值為「美國」。

以下是 YAML 檔案範例：

environmentVariables:
- name: "QUERY"
  value: "gs://my_bucket/my/input.sql"
- name: "OUTFILE"
  value: "gs://my_bucket/my/output.orc"
- name: "COPYBOOK"
  value: "gs://my_bucket/my/copybook.cpy"
- name: "TRANSCODE_CONFIGURATION"
  value: "gs://my_bucket/my/transcode-configuration-file.json"
- name: "PROJECT_ID"
  value: "my-project"
- name: "LOCATION"
  value: "US"
- name: "LOG_PROJECT"
  value: "my-log-project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
  command:
  qsam encode \
    $QUERY
    $OUTFILE
    --copybook ${COPYBOOK_PATH}
    --transcode-configuration ${TRANSCODE_CONFIGURATION_PATH}
    --input-format=BIGQUERY \
    --input-parameter project_id=${PROJECT_ID} \
    --input-parameter location=${LOCATION}

使用 `bq export` 指令

environmentVariables:
- name: "COPYBOOK"
  value: "COPYBOOK_FILEPATH"
- name: "LOG_PROJECT"
  value: "LOG_PROJECT"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  bq export --project_id="PROJECT_NAME" --location="LOCATION" --sql="select * from project.dataset.table" --bucket="BUCKET"

更改下列內容：

COPYBOOK_FILEPATH：副本 DD 的路徑。
LOG_PROJECT：記錄專案的名稱。
PROJECT_NAME：要執行查詢的專案名稱。
LOCATION：執行查詢的位置。建議您在靠近資料的位置執行查詢。
BUCKET：用於存放輸出二進位檔案的 Cloud Storage URI。

以下是 YAML 檔案範例：

environmentVariables:
- name: "COPYBOOK"
  value: "gs://inputbucket/copybook.cpy"
- name: "LOG_PROJECT"
  value: "my-log-project"
- name: "IBM_JAVA_OPTIONS"
  value: "-XX:+UseContainerSupport"
command:
  bq export --project_id="my-project" --run_mode="gcsoutput" --location=US --sql="select * from project.dataset.table" --bucket="gs://outputbucket/data.dat"

以獨立模式執行 Mainframe Connector 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

在 Cloud Run 上以獨立模式使用 Mainframe Connector 轉碼資料

qsam 指令的優點

使用 qsam 指令以獨立模式執行 Mainframe Connector

使用 gsutil cp 指令以獨立模式執行 Mainframe Connector

將 BigQuery 資料表匯出至大型主機資料集

使用 qsam 指令

使用 bq export 指令

以獨立模式執行 Mainframe Connector

`qsam` 指令的優點

使用 `qsam` 指令以獨立模式執行 Mainframe Connector

使用 `gsutil cp` 指令以獨立模式執行 Mainframe Connector

使用 `qsam` 指令

使用 `bq export` 指令