Configurer des forçages de compilation avec l'API Dataform

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

À propos des forçages 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'une invocation 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 de 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 forçages de compilation.

En transmettant des requêtes d'API Dataform dans le terminal, vous pouvez créer et exécuter un seul résultat de compilation avec des forçages 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 forçages 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 compile dans le résultat de compilation. Dans l'objet CodeCompilationConfig de la requête compilationResults.create, vous pouvez configurer des forçages de compilation.

Vous pouvez ensuite exécuter le résultat de compilation créé 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:

ProjetGoogle Cloud : projet Google Cloud dans lequel Dataform exécute le résultat de la compilation, défini dans workflow_settings.yaml comme defaultProject ou dans dataform.json comme defaultDatabase.

Préfixe de la table
Préfixe personnalisé ajouté à tous les noms de table dans le résultat de 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 compilation. Vous pouvez utiliser des variables de compilation pour exécuter des tables de manière conditionnelle.

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

Pour découvrir d'autres façons de configurer des forçages de compilation dans Dataform, consultez la section 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 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 ou une branche, un tag ou un SHA de commit 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 Google Cloud projet.
  • LOCATION par l'emplacement de votre dépôt Dataform, défini dans les paramètres du 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 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ésultats de compilation

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

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

L'exemple de code suivant montre que la propriété gitCommitish de la requête compilationResults.create est 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 de celui 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.

Transmettre un ID de projet par défaut distinct dans la requête compilationResults.create remplace l'ID de projetGoogle 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 de projet Google Cloud sélectionné dans l'objet CodeCompilationConfig, au format suivant:

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

Remplacez PROJECT_NAME par l'ID de projet Google Cloud que vous souhaitez définir pour le résultat de 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 defaultDataset dans workflow_settings.yaml 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 mise en phase 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ée 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 des fichiers sélectionnés de manière conditionnelle avec des variables de compilation

Pour exécuter un tableau sélectionné 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 de l'API Dataform compilationResults.create.

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 à des 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 répond à 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 forçages 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"
}

Étape suivante