Accéder aux données Workday avec Spark

Managed Service pour Apache Spark vous permet d'interroger et d'analyser des données d'entreprise externes directement à partir de vos charges de travail Spark. Vous pouvez utiliser le pilote JDBC Workday Live Data Query pour vous connecter à votre locataire Workday, charger des ensembles de données Workday en temps réel dans des DataFrames Spark et intégrer ces données dans votre pipeline d'analyse sur Google Cloud.

Dans ce guide, vous allez configurer Workday Live Data Query, stocker votre clé privée de manière sécurisée dans Secret Manager et utiliser l'extension Google Cloud Data Agent Kit pour exécuter un notebook PySpark dans Visual Studio Code ou l'éditeur Cloud Shell sur Managed Service pour Apache Spark.

Coûts

L'extension Data Agent Kit est disponible sans frais supplémentaires. Toutefois, ce guide utilise les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that you have the permissions required to complete this guide.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Dataproc, Dataplex, Cloud Storage, and Secret Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. Verify that you have the permissions required to complete this guide.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Dataproc, Dataplex, Cloud Storage, and Secret Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    10.

Rôles IAM (Identity and Access Management) requis

Certains rôles IAM sont requis pour exécuter les exemples de cette page. En fonction des règles d'administration, ces rôles ont peut-être déjà été attribués. Pour vérifier les attributions de rôles, consultez Devez-vous attribuer des rôles ?. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Les rôles dont vous avez besoin dépendent de la façon dont votre charge de travail s'exécute. Les environnements d'exécution sans serveur Managed Service pour Apache Spark 2.3 et versions antérieures exécutent les charges de travail en tant que compte de service. Les environnements d'exécution sans serveur Managed Service pour Apache Spark 3.0 et versions ultérieures exécutent par défaut les charges de travail avec vos identifiants d'utilisateur final (EUC). Vous devez donc attribuer des rôles d'accès aux données à votre compte utilisateur plutôt qu'à un compte de service. Si vous spécifiez un compte de service personnalisé pour un environnement d'exécution 3.0 ou ultérieur, la charge de travail s'exécute avec les identifiants du compte de service. Pour en savoir plus, consultez Rôles des déploiements sans serveur.

Rôles utilisateur

Pour obtenir les autorisations nécessaires pour créer une session de notebook interactive Managed Service pour Apache Spark et accéder aux ressources, demandez à votre administrateur de vous accorder les rôles IAM suivants :

  • Utilisez l'environnement d'exécution sans serveur 2.3 ou une version antérieure :
  • Utilisez l'environnement d'exécution sans serveur 3.0 ou version ultérieure : Éditeur Dataproc sans serveur (roles/dataproc.serverlessEditor) sur le projet
  • Lire le pilote JDBC à partir de Cloud Storage avec les identifiants de l'utilisateur final : Lecteur des objets Storage (roles/storage.objectViewer) sur le bucket contenant le pilote
  • Lire le secret de la clé privée depuis Secret Manager avec les identifiants de l'utilisateur final : Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le secret ou le projet

Rôles de compte de service

Attribuez les rôles suivants au compte de service qui exécute votre charge de travail. Les environnements d'exécution sans serveur Managed Service pour Apache Spark 3.0 et versions ultérieures n'ont besoin de ces rôles que si la charge de travail s'exécute avec des identifiants de compte de service au lieu des identifiants de l'utilisateur final (EUC) par défaut.

Pour vous assurer que le compte de service Compute Engine par défaut ou un compte de service personnalisé dispose des autorisations nécessaires pour exécuter des charges de travail Managed Service pour Apache Spark, lire le pilote et accéder aux secrets, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service Compute Engine par défaut ou à un compte de service personnalisé :

Prérequis pour Workday

Avant de vous connecter à Workday à l'aide de Live Data Query, effectuez la configuration suivante :

  1. Téléchargez le pilote JDBC Workday Live Data Query depuis Workday.

  2. Importez le fichier JAR du pilote JDBC téléchargé dans un bucket Cloud Storage de votre projet.

  3. Suivez les étapes de configuration de Live Data Query dans votre locataire Workday, comme décrit dans la documentation sur Workday Live Data Query.

    Lors de la configuration dans Workday, créez un utilisateur du système d'intégration (ISU), enregistrez un client API et générez une paire de clés privées.

  4. Notez les valeurs de configuration Workday suivantes :

    • Hôte Workday : hôte de votre locataire Workday, par exemple services1.workday.com.

    • Nom du locataire : nom de votre locataire Workday.

    • ID client : ID client API enregistré de votre locataire Workday.

    • Nom d'utilisateur ISU : nom d'utilisateur du système d'intégration.

Stocker la clé privée dans Secret Manager

Stockez de manière sécurisée le fichier de clé privée généré lors de la configuration de Workday Live Data Query dans Secret Manager :

  1. Dans Cloud Shell, exécutez la commande suivante pour générer une paire de clés x509 :

    openssl req -x509 -newkey rsa:2048 -keyout private-key.pem -out public-key.cert -sha256 -days 365 -nodes

  2. Pour afficher la clé privée, exécutez la commande suivante :

    cat private-key.pem

  3. Stockez la clé privée dans Secret Manager :

    1. Dans la console Google Cloud , accédez à la page Secret Manager :

      Accéder à Secret Manager

    2. Cliquez sur Créer un secret.

    3. Dans le champ Nom, saisissez un nom pour le secret, par exemple workday-private-key.

    4. Sous Valeur du secret, importez private-key.pem ou collez le contenu de la clé privée, y compris les lignes d'en-tête et de pied de page -----BEGIN PRIVATE KEY----- et -----END PRIVATE KEY-----.

    5. Cliquez sur Créer un secret.

  4. Pour afficher la clé publique, exécutez la commande suivante :

    cat public-key.cert

  5. Dans Workday, recherchez Create x509 Public Key (Créer une clé publique x509), collez la clé publique de public-key.cert, puis cliquez sur OK.

  6. Dans le client API Workday créé précédemment, remplacez le certificat x509 par la nouvelle clé x509.

Configurer le kit Data Agent dans votre IDE

Vous pouvez configurer Data Agent Kit en installant l'extension dans Visual Studio Code ou un autre IDE compatible, ou en utilisant l'extension préinstallée dans l'éditeur Cloud Shell.

Pour configurer le kit Data Agent dans votre IDE ou dans l'éditeur Cloud Shell, procédez comme suit :

  1. Configurez le Data Agent Kit :

    1. Installez l'extension Data Agent Kit.

    2. Configurez le Data Agent Kit.

Créer un notebook

À l'aide du Data Agent Kit, créez un notebook PySpark interactif :

  1. Dans votre IDE ou dans l'éditeur Cloud Shell, ouvrez le panneau Data Agent Kit.

  2. Sous Apache Spark, sélectionnez Nouveau notebook, puis Noyau local.

  3. Sélectionnez un environnement d'exécution dans la liste des environnements d'exécution disponibles (également appelés modèles de session).

  4. Sélectionnez Commencer avec un nouveau notebook.

    Un nouveau notebook s'ouvre avec une cellule initiale contenant le code d'initialisation de la session Spark Connect.

  5. En haut de l'éditeur de notebook, cliquez sur Select Kernel (Sélectionner un kernel), puis sélectionnez un kernel Python local pour votre notebook.

Interroger des données Workday dans PySpark

  1. Dans la première cellule du notebook, installez les bibliothèques clientes requises et configurez les variables d'environnement :

    %pip install dataproc-spark-connect google-cloud-dataproc google-cloud-secret-manager google-cloud-storage

#@title Set up all environment variables

# Replace with your Project ID
%env PROJECT_ID=PROJECT_ID

# Replace with the name of the Secret Manager global secret in the project
%env SECRET_NAME=workday-private-key
# Replace with the version of the secret to use
%env SECRET_VERSION=latest

# Replace with the Cloud Storage bucket where you have the Workday Data Cloud JDBC Driver file stored
%env JDBC_DRIVER_GCS_BUCKET=BUCKET_NAME
# Replace with the name of the Workday Data Cloud JDBC Driver file in the Cloud Storage bucket
%env JDBC_DRIVER_FILE_NAME=ldq-jdbc-driver-1.1.0-all.jar
# Replace with the local directory of the notebook to copy the JDBC Driver File to
%env JDBC_DRIVER_LOCAL_DIRECTORY=/tmp
# Replace with the Driver Class for the Workday Data Cloud JDBC Driver
%env WORKDAY_DRIVER_CLASS=com.workday.ldq.jdbc.Driver

# ------------------------------------------------------------------------------

# Replace with the Workday URL of your tenant
%env WORKDAY_HOST=WORKDAY_HOST
# Replace with your Workday tenant name
%env TENANT_NAME=TENANT_NAME
# Replace with the Client ID of the "API Client"
%env CLIENT_ID=CLIENT_ID
# Replace with the Integration System User username
%env ISU_USERNAME=ISU_USERNAME

  2. Dans une nouvelle cellule, attribuez le rôle d'Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) au compte de service Compute Engine par défaut :

    %%bash
COMPUTE_ENGINE_DEFAULT_SERVICE_ACCOUNT=$(gcloud iam service-accounts list --project="${PROJECT_ID}" \
  --filter="email ~ -compute@developer.gserviceaccount.com" \
  --format="value(email)")

echo "COMPUTE_ENGINE_DEFAULT_SERVICE_ACCOUNT: ${COMPUTE_ENGINE_DEFAULT_SERVICE_ACCOUNT}"

gcloud secrets add-iam-policy-binding ${SECRET_NAME} \
  --project="${PROJECT_ID}" \
  --member="serviceAccount:${COMPUTE_ENGINE_DEFAULT_SERVICE_ACCOUNT}" \
  --role="roles/secretmanager.secretAccessor"

  3. Dans une nouvelle cellule, copiez le pilote JDBC de Cloud Storage vers le répertoire local :

    gsutil cp gs://$JDBC_DRIVER_GCS_BUCKET/$JDBC_DRIVER_FILE_NAME $JDBC_DRIVER_LOCAL_DIRECTORY

  4. Dans une nouvelle cellule, installez la bibliothèque cliente Secret Manager :

    %%bash
pip install google-cloud-secret-manager

  5. Dans une nouvelle cellule, vérifiez que le fichier JAR du pilote est téléchargé localement :

    !gsutil cp gs://$JDBC_DRIVER_GCS_BUCKET/$JDBC_DRIVER_FILE_NAME /tmp/
!ls -lh /tmp/ldq-jdbc-driver-1.1.0-all.jar

  6. Dans une nouvelle cellule, injectez le fichier JAR du pilote Workday dans le répertoire des fichiers JAR PySpark :

    %%bash

echo "Downloading Workday JAR from Cloud Storage..."
# Downloads your specific 1.1.0 driver JAR into the notebook's /tmp folder
gcloud storage cp gs://$JDBC_DRIVER_GCS_BUCKET/$JDBC_DRIVER_FILE_NAME /tmp/

echo "Dynamically finding the PySpark jars directory..."
PYSPARK_JARS=$(python -c "import os, pyspark; print(os.path.join(os.path.dirname(pyspark.__file__), 'jars'))")
echo "Found PySpark jars at: $PYSPARK_JARS"

echo "Injecting Workday driver into PySpark core..."
cp /tmp/$JDBC_DRIVER_FILE_NAME "$PYSPARK_JARS/"

echo "Success! The driver is now a native part of PySpark."

  7. Dans une nouvelle cellule, configurez l'environnement Spark et récupérez la clé privée x509 à partir de Secret Manager :

    #@title Configure the Spark environment and retrieve the x509 private key from Secret Manager

import os
import pyspark
from pyspark.sql import SparkSession
from google.cloud import secretmanager

PROJECT_ID = os.environ["PROJECT_ID"]
SECRET_NAME = os.environ["SECRET_NAME"]
SECRET_VERSION = os.environ["SECRET_VERSION"]
JDBC_DRIVER_LOCAL_DIRECTORY = os.environ["JDBC_DRIVER_LOCAL_DIRECTORY"]
JDBC_DRIVER_FILE_NAME = os.environ["JDBC_DRIVER_FILE_NAME"]
LOCAL_JAR_PATH = JDBC_DRIVER_LOCAL_DIRECTORY + "/" + JDBC_DRIVER_FILE_NAME
WORKDAY_HOST = os.environ["WORKDAY_HOST"]
TENANT_NAME = os.environ["TENANT_NAME"]
CLIENT_ID = os.environ["CLIENT_ID"]
ISU_USERNAME = os.environ["ISU_USERNAME"]
WORKDAY_DRIVER_CLASS = os.environ["WORKDAY_DRIVER_CLASS"]

jdbc_url = f"jdbc:workday://{WORKDAY_HOST}:443/system/information_schema?SSLVerification=CA"

def access_private_key_secret():
    print(f"Fetching secret contents from Secret Manager: {SECRET_NAME}...")
    client = secretmanager.SecretManagerServiceClient()
    secret_name = f"projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/{SECRET_VERSION}"
    response = client.access_secret_version(request={"name": secret_name})
    print(f"Fetched secret contents from Secret Manager: {SECRET_NAME}")
    return response.payload.data.decode("UTF-8")

private_key_content = access_private_key_secret()

  8. Dans une nouvelle cellule, initialisez la session Spark avec la configuration du chemin de classe :

    # Stop the old cached Spark session so your newly downloaded JAR is not ignored!
try:
    spark.stop()
    print("Stopped existing Spark session.")
except Exception:
    pass

print("Initializing fresh Spark session with Classpath configuration...")
print(f"Loading JAR from: {LOCAL_JAR_PATH}")

# Rebuild Spark session with explicit Driver & Executor classpaths
spark = SparkSession.builder \
    .appName("WorkdayJDBC Connection Example") \
    .config("spark.jars", LOCAL_JAR_PATH) \
    .config("spark.driver.extraClassPath", LOCAL_JAR_PATH) \
    .config("spark.executor.extraClassPath", LOCAL_JAR_PATH) \
    .getOrCreate()
print("Spark Session successfully booted with JAR!")

  9. Dans une dernière cellule, lancez la connexion et interrogez Workday :

    import os
import subprocess
import zipfile
from pyspark.sql import SparkSession

LOCAL_JAR_PATH = "/tmp/ldq-jdbc-driver-1.1.0-all.jar"

# Load bucket and file name from your Cell 1 environment variables
GCS_BUCKET = os.environ.get("JDBC_DRIVER_GCS_BUCKET", "BUCKET_NAME")
GCS_FILE = os.environ.get("JDBC_DRIVER_FILE_NAME", "ldq-jdbc-driver-1.1.0-all.jar")
GCS_URI = f"gs://{GCS_BUCKET}/{GCS_FILE}"

# 1. Ensure the JAR file is in the notebook's /tmp directory
if not os.path.exists(LOCAL_JAR_PATH):
    print(f"Downloading {GCS_URI} to {LOCAL_JAR_PATH}...")
    subprocess.run(["gsutil", "cp", GCS_URI, LOCAL_JAR_PATH], check=True)
print(f"JAR verified on disk: {LOCAL_JAR_PATH} ({os.path.getsize(LOCAL_JAR_PATH):,} bytes)")

# 2. Read the real JDBC driver class name (skipping any '#' comment lines!)
with zipfile.ZipFile(LOCAL_JAR_PATH, "r") as z:
    raw_lines = (
        z.read("META-INF/services/java.sql.Driver")
        .decode("utf-8")
        .splitlines()
    )
    # Filter out empty lines and '#' comment lines
    valid_classes = [
        line.strip()
        for line in raw_lines
        if line.strip() and not line.strip().startswith("#")
    ]
    driver_class = valid_classes[0]

print(f"Real Driver Class inside JAR: {driver_class}")

# 3. Get or create the Spark session
spark = SparkSession.builder.appName("WorkdayJDBC Connection Example").getOrCreate()

# 4. Inject the JAR directly into the running Java URLClassLoader (and Scala SparkContext)
jvm = spark.sparkContext._jvm
jar_url = jvm.java.io.File(LOCAL_JAR_PATH).toURI().toURL()

# Add to both the Spark classloader and the current thread's context classloader
jvm.org.apache.spark.util.Utils.getContextOrSparkClassLoader().addURL(jar_url)
jvm.java.lang.Thread.currentThread().getContextClassLoader().addURL(jar_url)
spark.sparkContext._jsc.sc().addJar(LOCAL_JAR_PATH)

# Register the driver class with Spark's JDBC DriverRegistry
jvm.org.apache.spark.sql.execution.datasources.jdbc.DriverRegistry.register(driver_class)
print(f"Successfully registered {driver_class} in Spark's live JVM!")

# 5. Query Workday
print("Querying Workday...")
df_data = (
    spark.read.format("jdbc")
    .option("driver", driver_class)
    .option("url", jdbc_url)
    .option("wd.authn.clientId", CLIENT_ID)
    .option("wd.authn.isu", ISU_USERNAME)
    .option(
        "wd.authn.accessTokenEndpoint",
        f"https://{WORKDAY_HOST}/ccx/oauth2/{TENANT_NAME}/token",
    )
    .option("wd.authn.privateKey", private_key_content)
    .option("query", "SELECT * FROM system.jdbc.catalogs")
    .load()
)

print("Connection Successful! Data Retrieved:")
df_data.show(50, truncate=False)

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • LOCATION : région Google Cloud de votre modèle de session Managed Service pour Apache Spark (par exemple, us-central1).
    • RUNTIME_ID : ID de votre modèle de session Managed Service pour Apache Spark.
    • BUCKET_NAME : nom du bucket Cloud Storage contenant le pilote JDBC Workday.
    • PATH/workday-live-data-query-jdbc-driver.jar : chemin d'accès de l'objet vers le fichier JAR du pilote JDBC Workday dans votre bucket Cloud Storage.
    • WORKDAY_HOST : hôte de votre locataire Workday, par exemple services1.workday.com.
    • TENANT_NAME : nom de votre locataire Workday.
    • CLIENT_ID : ID client API enregistré de votre locataire Workday.
    • ISU_USERNAME : nom d'utilisateur de l'utilisateur du système d'intégration de votre locataire Workday.

  10. Cliquez sur Exécuter la cellule (icône de lecture) à côté de la cellule, ou appuyez sur Maj+Entrée.

    Managed Service pour Apache Spark exécute la requête et affiche la sortie du DataFrame Workday sous la cellule.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce guide ne soient facturées sur votre compte Google Cloud , mettez fin aux sessions interactives actives ou supprimez les ressources créées.

Arrêter des sessions interactives

  1. Dans votre IDE ou dans l'éditeur Cloud Shell, mettez fin à la session de notebook active lorsque votre charge de travail est terminée.

  2. Facultatif : Supprimez le bucket Cloud Storage ou le fichier JAR du pilote JDBC si vous n'en avez plus besoin.

  3. Facultatif : Supprimez le secret de Secret Manager s'il n'est plus nécessaire :

    gcloud secrets delete workday-private-key

Étapes suivantes