Esegui Mainframe Connector in modalità autonoma

Questa pagina descrive come installare Mainframe Connector su Cloud Run, transcodificare i dati, salvarli in BigQuery ed esportarli da BigQuery.

Mainframe Connector versione 5.13.0 e successive supporta l'esecuzione di Mainframe Connector come job autonomo su Google Cloud. Questa funzionalità ti consente di eseguire Mainframe Connector come job batch containerizzato, ad esempio come job Cloud Run, job Google Kubernetes Engine o all'interno di un container Docker. Questa opzione ti aiuta a evitare di installare Mainframe Connector localmente sul tuo mainframe e semplifica l'integrazione dell'analisi dei file QSAM (queued sequential access method) del mainframe nei flussi di lavoro ETL (extract, transform, and load) esistenti.

Quando utilizzi la versione standalone di Mainframe Connector, devi configurare autonomamente il flusso di lavoro ETL che carica il file QSAM in Google Cloud .

Prima di iniziare

  • Esegui il deployment di Mainframe Connector su Cloud Run.
  • Crea un service account o identifica un account di serviziot esistente da utilizzare con Mainframe Connector. Questo account di servizio deve disporre delle autorizzazioni per accedere ai bucket Cloud Storage, ai set di dati BigQuery e a qualsiasi altra risorsa che vuoi utilizzare. Google Cloud
  • Assicurati che al account di servizio che hai creato sia assegnato il ruolo Invoker Cloud Run.
  • Assicurati che i dati del mainframe siano già disponibili su Google Cloud come file QSAM.

Transcodifica dei dati utilizzando Mainframe Connector in modalità standalone su Cloud Run

Mainframe Connector offre due modi per eseguire Mainframe Connector come job autonomo su Google Cloud:

Vantaggi dei comandi qsam

I comandi qsam offrono i seguenti vantaggi:

  • Supporta tipi di dati composti, tra cui la clausola OCCURS (elenchi), la clausola REDEFINES e i record nidificati. Per saperne di più su questi tipi di dati, consulta qsam transcoding reference.
  • Supporta la configurazione del processo di transcodifica tramite un file di configurazione del transcodificatore. Questa funzionalità offre una maggiore flessibilità durante la decodifica dei dati in Google Cloud e la codifica dei dati nel mainframe.
  • Supporta la creazione di un set di dati di overflow, ovvero una tabella di errori di transcodifica che può essere utilizzata per l'ispezione degli errori.
  • Supporta più formati di input e output. Questa funzionalità ti consente di caricare i dati da e verso vari data warehouse.

Esegui Mainframe Connector in modalità autonoma utilizzando i comandi qsam

Per transcodificare i dati utilizzando Mainframe Connector in modalità autonoma utilizzando i comandi qsam, segui questi passaggi:

  1. Crea un file YAML con i comandi per eseguire le seguenti operazioni:

    • Leggere il set di dati
    • Eseguirne la transcodifica in un formato supportato
    • Caricalo su Cloud Storage

    Il set di dati di input deve essere un file QSAM con lunghezza del record fissa o variabile. Puoi utilizzare il seguente file YAML di esempio per leggere il set di dati, transcodificarlo nel formato ORC e caricarlo in Cloud Storage.

    Nel seguente esempio, utilizziamo DataPath di Cloud Storage per INFILE, OUTFILE, COPYBOOK e 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"

    Sostituisci quanto segue:

    • INFILE: il nome del file di input.
    • OUTFILE: il nome del file di output.
    • COPYBOOK_PATH: Il percorso del copybook DD.
    • TRANSCODE_CONFIGURATION_PATH: il percorso del file di configurazione della transcodifica.
    • LOG_PROJECT: il nome del progetto di log.

    Di seguito è riportato un esempio di file 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"

  2. Crea un file job.yaml con il seguente comando.

    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

    Sostituisci quanto segue:

    • JOB: il nome del job Cloud Run. I nomi dei job devono contenere al massimo 49 caratteri e devono essere univoci per regione e progetto.
    • IMAGE: l'URL dell'immagine del contenitore del job, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: la posizione del file YAML che hai creato nel passaggio precedente.

  3. Esegui il deployment del nuovo job utilizzando il seguente comando:

    gcloud run jobs replace job.yaml

  4. Esegui il job utilizzando questo comando:

    gcloud run jobs execute JOB_NAME

    Sostituisci JOB_NAME con il nome del job.

Per ulteriori informazioni sulla creazione e l'esecuzione di un job Cloud Run, consulta Creare un nuovo job ed Eseguire un job.

Esegui Mainframe Connector in modalità autonoma utilizzando il comando gsutil cp

Per transcodificare i dati utilizzando Mainframe Connector in modalità autonoma utilizzando il comando gsutil cp, segui questi passaggi:

  1. Crea un file YAML con i comandi per eseguire le seguenti operazioni:

    • Leggere il set di dati
    • Eseguilo la transcodifica in ORC
    • Caricalo su Cloud Storage

    Il set di dati di input deve essere un file QSAM con lunghezza del record fissa o variabile. Puoi utilizzare il seguente file YAML di esempio per leggere il set di dati, transcodificarlo nel formato ORC e caricarlo in Cloud Storage.

    Nell'esempio seguente, leggi i dati dal set di dati INFILE e il layout del record da 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

    Sostituisci quanto segue:

    • INFILE: il nome del file di input.
    • INFILE_DSN: il nome del file DSN (Data Source Name) di input.
    • INFILE_DSN_FILEPATH: il percorso del file DSN di input.
    • COPYBOOK_FILEPATH: Il percorso del copybook DD.
    • LOG_PROJECT: il nome del progetto di log.

    Di seguito è riportato un esempio di file 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

    Per l'elenco completo delle variabili di ambiente supportate da Mainframe Connector, consulta Variabili di ambiente.

    Se vuoi registrare i comandi eseguiti durante questa procedura, puoi attivare le statistiche di caricamento.

  2. Crea un file job.yaml con il seguente comando.

    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

    Sostituisci quanto segue:

    • JOB: il nome del job Cloud Run. I nomi dei job devono contenere al massimo 49 caratteri e devono essere univoci per regione e progetto.
    • IMAGE: l'URL dell'immagine del contenitore del job, ad esempio us-docker.pkg.dev/cloudrun/container/job:latest.
    • LOCATION_OF_THE_COMMAND_YAML_FILE: la posizione del file YAML che hai creato nel passaggio precedente.

  3. Esegui il deployment del nuovo job utilizzando il seguente comando:

    gcloud run jobs replace job.yaml

  4. Esegui il job utilizzando questo comando:

    gcloud run jobs execute JOB_NAME

    Sostituisci JOB_NAME con il nome del job.

Per ulteriori informazioni sulla creazione e l'esecuzione di un job Cloud Run, consulta Creare un nuovo job ed Eseguire un job.

Esporta la tabella BigQuery nel set di dati Mainframe

Puoi esportare la tabella BigQuery nel set di dati del mainframe creando un file YAML che esegue una lettura SQL dal file QUERY DD ed esporta il set di dati risultante in Cloud Storage come file binario, come segue.

I passaggi per creare ed eseguire il job Cloud Run sono gli stessi menzionati nella sezione Transcodifica dei dati utilizzando Mainframe Connector in modalità autonoma su Cloud Run. L'unica differenza sono le istruzioni menzionate nel file YAML. Mainframe Connector offre due modi per esportare la tabella BigQuery:

  • Utilizzo dei comandi qsam (versione 5.16.0 e successive)

  • Utilizzo del comando bq export

Utilizzare i comandi 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}

Sostituisci quanto segue:

  • QUERY_PATH: la query SQL da eseguire. Il risultato della query verrà codificato in un file binario.
  • OUTFILE: il bucket Cloud Storage che conterrà il file binario di output.
  • COPYBOOK_PATH: Il percorso del copybook DD.
  • TRANSCODE_CONFIGURATION_PATH: il percorso del file di configurazione del transcodificatore.
  • LOG_PROJECT: il nome del progetto di log.
  • PROJECT_ID: l'ID progetto in cui vuoi eseguire la query.
  • LOCATION: La regione o la multi-regione in cui verrà eseguita la query. Ti consigliamo di eseguire la query in una località vicina ai dati. Il valore predefinito è US.

Di seguito è riportato un esempio di file 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}

Utilizza il comando 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"

Sostituisci quanto segue:

  • COPYBOOK_FILEPATH: Il percorso del copybook DD.
  • LOG_PROJECT: il nome del progetto di log.
  • PROJECT_NAME: il nome del progetto in cui vuoi eseguire la query.
  • LOCATION: la posizione in cui verrà eseguita la query. Ti consigliamo di eseguire la query in una località vicina ai dati.
  • BUCKET: l'URI Cloud Storage che conterrà il file binario di output.

Di seguito è riportato un esempio di file 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"