Exécuter Mainframe Connector en mode autonome

Cette page explique comment installer Mainframe Connector sur Cloud Run, transcoder des données, les enregistrer dans BigQuery et les exporter depuis BigQuery.

Mainframe Connector version 5.13.0 et ultérieure permet d'exécuter Mainframe Connector en tant que job autonome sur Google Cloud. Cette fonctionnalité vous permet d'exécuter Mainframe Connector en tant que job par lot conteneurisé, par exemple en tant que job Cloud Run, job Google Kubernetes Engine ou dans un conteneur Docker. Cette option vous permet d'éviter d'installer Mainframe Connector localement sur votre mainframe. Elle facilite également l'intégration de l'analyse de vos fichiers QSAM (Queued Sequential Access Method) de mainframe aux workflows ETL (Extract, Transform, Load) existants.

Lorsque vous utilisez la version autonome de Mainframe Connector, vous devez configurer vous-même le workflow ETL qui charge le fichier QSAM dans Google Cloud .

Avant de commencer

  • Déployez le connecteur Mainframe sur Cloud Run.
  • Créez un compte de service ou identifiez un compte de service existant à utiliser avec Mainframe Connector. Ce compte de service doit disposer des autorisations nécessaires pour accéder aux buckets Cloud Storage, aux ensembles de données BigQuery et à toute autre ressource Google Cloud que vous souhaitez utiliser.
  • Assurez-vous que le compte de service que vous avez créé dispose du rôle Demandeur Cloud Run.
  • Assurez-vous que les données du mainframe sont déjà disponibles sur Google Cloud en tant que fichier QSAM.

Transcoder des données à l'aide de Mainframe Connector en mode autonome sur Cloud Run

Mainframe Connector vous permet d'exécuter Mainframe Connector en tant que job autonome sur Google Cloudde deux manières :

Avantages des commandes qsam

Les commandes qsam offrent les avantages suivants :

  • Compatible avec les types de données composites, y compris la clause OCCURS (listes), la clause REDEFINES et les enregistrements imbriqués. Pour en savoir plus sur ces types de données, consultez la documentation sur le transcodage qsam.
  • Permet de configurer le processus de transcodage à l'aide d'un fichier de configuration du transcodeur. Cette fonctionnalité offre plus de flexibilité lors du décodage des données vers Google Cloudet de l'encodage des données vers le mainframe.
  • Permet de créer un ensemble de données de débordement, qui est un tableau des erreurs de transcodage pouvant être utilisé pour l'inspection des erreurs.
  • Il est compatible avec plusieurs formats d'entrée et de sortie. Cette fonctionnalité vous permet de charger vos données vers et depuis différents entrepôts de données.

Exécuter le connecteur Mainframe en mode autonome à l'aide des commandes qsam

Pour transcoder vos données à l'aide de Mainframe Connector en mode autonome à l'aide des commandes qsam, procédez comme suit :

  1. Créez un fichier YAML avec des commandes pour effectuer les opérations suivantes :

    • Lire votre ensemble de données
    • Transcodez-la dans un format compatible.
    • Importez-le dans Cloud Storage.

    L'ensemble de données d'entrée doit être un fichier QSAM avec une longueur d'enregistrement fixe ou variable. Vous pouvez utiliser l'exemple de fichier YAML suivant pour lire votre ensemble de données, le transcoder au format ORC et l'importer dans Cloud Storage.

    Dans l'exemple suivant, nous utilisons le DataPath Cloud Storage pour INFILE, OUTFILE, COPYBOOK et 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"

    Remplacez les éléments suivants :

    • INFILE : nom du fichier d'entrée.
    • OUTFILE : nom du fichier de sortie.
    • COPYBOOK_PATH : chemin d'accès au DD du copybook.
    • TRANSCODE_CONFIGURATION_PATH : chemin d'accès au fichier de configuration du transcodage.
    • LOG_PROJECT : nom du projet de journal.

    Voici un exemple de fichier 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. Créez un fichier job.yaml à l'aide de la commande suivante.

    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

    Remplacez les éléments suivants :

    • JOB par le nom de votre job Cloud Run Les noms de job doivent comporter un maximum de 49 caractères et être uniques par région et par projet.
    • IMAGE : URL de l'image de conteneur du job (par exemple, us-docker.pkg.dev/cloudrun/container/job:latest).
    • LOCATION_OF_THE_COMMAND_YAML_FILE : emplacement du fichier YAML que vous avez créé à l'étape précédente.

  3. Déployez la nouvelle tâche à l'aide de la commande suivante :

    gcloud run jobs replace job.yaml

  4. Exécutez le job à l'aide de la commande suivante :

    gcloud run jobs execute JOB_NAME

    Remplacez JOB_NAME par le nom de la tâche.

Pour en savoir plus sur la création et l'exécution d'un job Cloud Run, consultez Créer un job et Exécuter un job.

Exécuter Mainframe Connector en mode autonome à l'aide de la commande gsutil cp

Pour transcoder vos données à l'aide de Mainframe Connector en mode autonome à l'aide de la commande gsutil cp, procédez comme suit :

  1. Créez un fichier YAML avec des commandes pour effectuer les opérations suivantes :

    • Lire votre ensemble de données
    • Transcoder au format ORC
    • Importez-le dans Cloud Storage.

    L'ensemble de données d'entrée doit être un fichier QSAM avec une longueur d'enregistrement fixe ou variable. Vous pouvez utiliser l'exemple de fichier YAML suivant pour lire votre ensemble de données, le transcoder au format ORC et l'importer dans Cloud Storage.

    Dans l'exemple suivant, lisez les données de l'ensemble de données INFILE et la mise en page des enregistrements à partir de 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

    Remplacez les éléments suivants :

    • INFILE : nom du fichier d'entrée.
    • INFILE_DSN : nom du fichier de nom de source de données (DSN) d'entrée.
    • INFILE_DSN_FILEPATH : chemin d'accès au fichier DSN d'entrée.
    • COPYBOOK_FILEPATH : chemin d'accès au DD du copybook.
    • LOG_PROJECT : nom du projet de journal.

    Voici un exemple de fichier 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

    Pour obtenir la liste complète des variables d'environnement compatibles avec Mainframe Connector, consultez Variables d'environnement.

    Si vous souhaitez consigner les commandes exécutées au cours de ce processus, vous pouvez activer les statistiques de chargement.

  2. Créez un fichier job.yaml à l'aide de la commande suivante.

    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

    Remplacez les éléments suivants :

    • JOB par le nom de votre job Cloud Run Les noms de job doivent comporter un maximum de 49 caractères et être uniques par région et par projet.
    • IMAGE : URL de l'image de conteneur du job (par exemple, us-docker.pkg.dev/cloudrun/container/job:latest).
    • LOCATION_OF_THE_COMMAND_YAML_FILE : emplacement du fichier YAML que vous avez créé à l'étape précédente.

  3. Déployez la nouvelle tâche à l'aide de la commande suivante :

    gcloud run jobs replace job.yaml

  4. Exécutez le job à l'aide de la commande suivante :

    gcloud run jobs execute JOB_NAME

    Remplacez JOB_NAME par le nom de la tâche.

Pour en savoir plus sur la création et l'exécution d'un job Cloud Run, consultez Créer un job et Exécuter un job.

Exporter une table BigQuery vers un ensemble de données Mainframe

Vous pouvez exporter une table BigQuery dans un ensemble de données mainframe en créant un fichier YAML qui exécute une lecture SQL à partir du fichier QUERY DD et exporte l'ensemble de données résultant vers Cloud Storage en tant que fichier binaire, comme suit.

Les étapes à suivre pour créer et exécuter le job Cloud Run sont les mêmes que celles mentionnées dans la section Transcoder des données à l'aide de Mainframe Connector en mode autonome sur Cloud Run. La seule différence réside dans les instructions mentionnées dans le fichier YAML. Le connecteur Mainframe propose deux façons d'exporter une table BigQuery :

  • À l'aide des commandes qsam (version 5.16.0 et ultérieures)

  • Avec la commande bq export

Utiliser les commandes 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}

Remplacez les éléments suivants :

  • QUERY_PATH : requête SQL à exécuter. Le résultat de la requête sera encodé dans un fichier binaire.
  • OUTFILE : bucket Cloud Storage qui contiendra le fichier binaire de sortie.
  • COPYBOOK_PATH : chemin d'accès au DD du copybook.
  • TRANSCODE_CONFIGURATION_PATH : chemin d'accès au fichier de configuration du transcodeur.
  • LOG_PROJECT : nom du projet de journal.
  • PROJECT_ID : ID du projet dans lequel vous souhaitez exécuter la requête.
  • LOCATION : région ou emplacement multirégional où la requête sera exécutée. Nous vous recommandons d'exécuter la requête dans un emplacement proche des données. La valeur par défaut est "US".

Voici un exemple de fichier 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}

Utiliser la commande 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"

Remplacez les éléments suivants :

  • COPYBOOK_FILEPATH : chemin d'accès au DD du copybook.
  • LOG_PROJECT : nom du projet de journal.
  • PROJECT_NAME : nom du projet dans lequel vous souhaitez exécuter la requête.
  • LOCATION : emplacement où la requête sera exécutée. Nous vous recommandons d'exécuter la requête dans un emplacement proche des données.
  • BUCKET : URI Cloud Storage qui contiendra le fichier binaire de sortie.

Voici un exemple de fichier 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"