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 de paramètres du workflow 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 les requêtes API Dataform au terminal, vous pouvez créer et exécuter un seul résultat de compilation avec des remplacements de compilation. Vous pouvez créer un résultat de 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 générer 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 se compile 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 workflow_settings.yaml sur defaultProject ou dans dataform.json en tant que defaultDatabase.

Préfixe de table
Préfixe personnalisé ajouté à tous les noms de table dans le résultat de la compilation.
Suffixe de schéma
Suffixe personnalisé ajouté au schéma des tables définies dans defaultDataset dans workflow_settings.yaml, defaultSchema dans dataform.json, ou dans le paramètre schema dans le 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 la page Présentation du cycle de vie du code.

Avant de commencer

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

    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 des résultats de la 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 ou une branche Git, un tag Git ou un commit SHA de commit Git en tant que source dans la requête compilationResults.create.

Définir un espace de travail comme source des 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é, en respectant le 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 les paramètres de workflow.
  • 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 en tant que source des résultats de la compilation

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

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

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

{
  "gitCommitish": "staging"
}

Remplacer 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 de paramètres de workflow, mais ne remplace pas les ID de projet Google Cloud configurés dans des tables individuelles.

  • Pour remplacer l'ID de 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, en respectant le 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 dans 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 defaultDataset dans workflow_settings.yaml 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 defaultDataset dans workflow_settings.yaml 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 des fichiers individuels.

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

Pour n'exécuter une table sélectionnée que 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 à l'objet CodeCompilationConfig dans 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 de 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 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