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 la 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 les requêtes de l'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 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 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 commit Git, pour que Dataform puisse compiler dans le résultat de 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éée dans une requête workflowInvocations.create de l'API Dataform.

Vous pouvez configurer les forçages 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 de tables défini dans 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 d'ignorer les remplacements de compilation de l'API Dataform pour n'utiliser qu'un seul résultat de compilation, vous pouvez configurer les remplacements de compilation de l'espace de travail dans la console Google Cloud.

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 la source des résultats de compilation

Pour envoyer 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, un tag Git ou un commit Git Git comme 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 d'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 dans 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 commit Git comme source de résultat de compilation

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

Remplacez GIT_COMMITISH par la branche Git, le tag Git ou le commit Git de votre choix 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 dataform.json, mais ne remplace 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 souhaité 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 facilement les tables à partir du résultat de la compilation, vous pouvez ajouter un préfixe à tous les noms de tables 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 defaultSchema dans dataform.json est défini sur dataform, Dataform crée 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 defaultSchema dans dataform.json est défini sur dataform, Dataform crée des tables dans le schéma dataform_staging.

Remarque:Le paramètre CodeCompilationConfig schemaSuffix 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 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 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 les paires 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