Configurer des remplacements de compilation avec l'API Dataform

Ce document explique comment créer et exécuter un résultat de compilation avec des remplacements de compilation à l'aide de l'API Dataform.

À propos des remplacements de compilation de l'API Dataform

Pour exécuter votre workflow SQL, Dataform compile votre code en SQL afin de créer un résultat de compilation. Ensuite, lors d'un appel de workflow, Dataform exécute le résultat de la compilation dans BigQuery.

Par défaut, Dataform utilise les paramètres du fichier dataform.json pour créer le résultat de la compilation. Pour isoler les données exécutées à différentes étapes de votre cycle de développement, vous pouvez remplacer les paramètres par défaut par des remplacements de compilation.

En transmettant des requêtes API Dataform dans le terminal, vous pouvez créer et exécuter un seul résultat de compilation avec des remplacements de compilation. Vous pouvez créer le résultat de la compilation d'un espace de travail ou d'un commit Git sélectionné.

Pour créer un résultat de compilation avec des remplacements de compilation, vous devez envoyer la requête compilationResults.create de l'API Dataform. Dans la requête, vous devez spécifier une source (un espace de travail ou un commitish Git) pour que Dataform puisse être compilé dans le résultat de la compilation. Dans l'objet CodeCompilationConfig de la requête compilationResults.create, vous pouvez configurer des remplacements de compilation.

Vous pouvez ensuite exécuter le résultat de la compilation créé dans une requête workflowInvocations.create de l'API Dataform.

Vous pouvez configurer les remplacements de compilation suivants à l'aide de l'API Dataform:

Projet Google Cloud
Projet Google Cloud dans lequel Dataform exécute le résultat de la compilation, défini dans dataform.json en tant que defaultDatabase.
Préfixe de table
Préfixe personnalisé ajouté à tous les noms de tables dans le résultat de la compilation.
Suffixe du schéma
Suffixe personnalisé ajouté au schéma des tables défini dans defaultSchema dans dataform.json ou dans le paramètre schema du bloc config d'une table.
Valeur d'une variable de compilation
Valeur d'une variable de compilation à utiliser dans le résultat de la compilation. Vous pouvez utiliser des variables de compilation pour exécuter des tables de manière conditionnelle.

Au lieu des remplacements de compilation de l'API Dataform que vous ne pouvez utiliser que pour un seul résultat de compilation, vous pouvez configurer des remplacements de compilation d'espace de travail dans la console Google Cloud.

Pour découvrir d'autres façons de configurer des remplacements de compilation dans Dataform, consultez Présentation du cycle de vie du code.

Avant de commencer

  1. Dans la console Google Cloud, accédez à la page Dataform.

    Accéder à Dataform

  2. Sélectionnez ou créez un dépôt.

  3. Sélectionnez ou créez un espace de travail de développement.

Définir une source de résultats de compilation

Pour générer la requête compilationResults.create de l'API Dataform, vous devez spécifier une source pour le résultat de la compilation.

Vous pouvez définir un espace de travail Dataform, une branche Git, une balise Git ou un SHA du commit Git en tant que source dans la requête compilationResults.create.

Définir un espace de travail comme source de résultats de compilation

  • Dans la requête compilationResults.create, renseignez la propriété workspace avec le chemin d'accès à un espace de travail Dataform sélectionné, au format suivant:
{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

Remplacez les éléments suivants :

  • PROJECT_NAME par le nom de votre projet Google Cloud ;
  • LOCATION par l'emplacement de votre dépôt Dataform, défini dans dataform.json.
  • REPOSITORY_NAME par le nom de votre dépôt Dataform.
  • WORKSPACE_NAME par le nom de votre espace de travail Dataform.

L'exemple de code suivant montre la propriété workspace de la requête compilationResults.create définie sur un espace de travail appelé "sales-test":

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Définir un commitish Git comme source de résultats de compilation

  • Dans la requête compilationResults.create, renseignez la propriété gitCommitish avec la branche Git, la balise ou le SHA de commit sélectionnés, au format suivant:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Remplacez GIT_COMMITISH par la branche Git sélectionnée, le tag Git ou un SHA de commit Git pour le résultat de la compilation.

L'exemple de code suivant montre la propriété gitCommitish de la requête compilationResults.create définie sur "staging":

{
  "gitCommitish": "staging"
}

Ignorer le projet Google Cloud par défaut

Pour créer des tables de préproduction ou de production dans un projet Google Cloud distinct du projet utilisé pour le développement, vous pouvez transmettre un ID de projet Google Cloud différent dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

La transmission d'un ID de projet par défaut distinct dans la requête compilationResults.create remplace l'ID de projet Google Cloud par défaut configuré dans le fichier dataform.json, mais n'ignore pas les ID de projet Google Cloud configurés dans des tables individuelles.

  • Pour remplacer l'ID du projet Google Cloud par défaut, définissez la propriété defaultDatabase sur l'ID du projet Google Cloud sélectionné dans l'objet CodeCompilationConfig, au format suivant:

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

Remplacez PROJECT_NAME par l'ID du projet Google Cloud que vous souhaitez définir pour le résultat de la compilation.

Ajouter un préfixe de table

Pour identifier rapidement les tables à partir du résultat de la compilation, vous pouvez ajouter un préfixe à tous les noms de table dans le résultat de la compilation en transmettant le préfixe de table dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

  • Pour ajouter un préfixe de table, définissez la propriété tablePrefix dans l'objet CodeCompilationConfig au format suivant:
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

Remplacez PREFIX par le suffixe que vous souhaitez ajouter, par exemple _staging. Par exemple, si votre defaultSchema dans dataform.json est défini sur dataform, Dataform créera des tables dans le schéma dataform_staging.

Ajouter un suffixe de schéma

Pour séparer les données de développement, de préproduction et de production, vous pouvez ajouter un suffixe aux schémas dans un résultat de compilation en transmettant le suffixe de schéma dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

  • Pour ajouter un suffixe de schéma, définissez la propriété schemaSuffix dans l'objet CodeCompilationConfig au format suivant:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Remplacez SUFFIX par le suffixe que vous souhaitez ajouter, par exemple _staging. Par exemple, si votre defaultSchema dans dataform.json est défini sur dataform, Dataform créera des tables dans le schéma dataform_staging.

Remarque:Le paramètre schemaSuffix CodeCompilationConfig remplace les schémas configurés dans le bloc config de fichiers individuels.

Exécuter les fichiers sélectionnés de manière conditionnelle avec des variables de compilation

Pour exécuter une table sélectionnée uniquement dans un paramètre d'exécution spécifique, vous pouvez créer une variable de compilation pour le paramètre d'exécution, puis transmettre sa valeur dans l'objet CodeCompilationConfig de la requête compilationResults.create de l'API Dataform.

Pour exécuter une table de manière conditionnelle dans un paramètre d'exécution spécifique à l'aide de l'API Dataform, procédez comme suit:

  1. Créez une variable de compilation et ajoutez-la aux tables sélectionnées.

  2. Définissez la paire clé-valeur YOUR_VARIABLE et VALUE dans le bloc codeCompilationConfig d'une requête de compilation de l'API Dataform au format suivant:

    {
 "codeCompilationConfig": {
   "vars": {
     "YOUR_VARIABLE": "VALUE"
   }
 }
}

  3. Remplacez YOUR_VARIABLE par le nom de votre variable, par exemple executionSetting.

  4. Remplacez VALUE par la valeur de la variable pour ce résultat de compilation qui remplit la condition when définie dans les tables sélectionnées.

L'exemple de code suivant montre la variable executionSetting transmise à une requête de compilation de l'API Dataform:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Exécuter un résultat de compilation avec des remplacements de compilation

L'exemple de code suivant montre un ID de résultat de la compilation transmis dans une requête workflowInvocations.create:

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

Étapes suivantes