Gérer les macros, les préférences et les arguments d'exécution

Cette page explique comment définir des préférences, des macros et des arguments d'exécution dans les pipelines Cloud Data Fusion.

Termes clés

Macros
Les macros
sont des espaces réservés dans les configurations de plug-ins Cloud Data Fusion. Elles sont représentées par des variables entre ${ }, comme ${input_file_path}. Les macros apportent de la flexibilité à vos pipelines en vous permettant d'utiliser des valeurs d'espace réservé, qui sont remplacées par des valeurs réelles au moment de l'exécution. Cela permet une configuration dynamique des paramètres, tels que les chemins d'accès aux fichiers et les noms de tables.
Préférences
Les préférences
sont des configurations prédéfinies qui s'appliquent à différents niveaux dans Cloud Data Fusion, y compris au système lui-même, aux espaces de noms, aux applications (qui contiennent des pipelines) et aux programmes individuels dans les pipelines. Les préférences vous permettent de définir des valeurs par défaut pour les configurations courantes. Les valeurs par défaut peuvent être héritées par les pipelines et les programmes de niveau inférieur, ce qui réduit les tâches de configuration répétitives.
Arguments d'exécution
Les arguments d'exécution
sont des paires clé/valeur qui fournissent des valeurs pour les macros et peuvent remplacer les préférences lorsque vous déployez ou exécutez un pipeline. Ils sont hautement personnalisables et vous permettent d'ajuster les configurations pour chaque exécution de pipeline, sans modifier le pipeline ni les préférences sous-jacents.

Configurer des macros

Pour utiliser une macro pour une valeur de propriété de plug-in, procédez comme suit :

  1. Dans Cloud Data Fusion Studio, accédez au nœud du plug-in et cliquez sur "Properties" (Propriétés).
  2. Accédez au champ dans lequel vous souhaitez utiliser une macro, puis cliquez sur M à côté du champ.
  3. Saisissez une clé pour la macro. Par exemple, dans les propriétés du plug-in de la source de fichier, saisissez la clé suivante dans le champ "Format" : ${format.type}.

Définir les valeurs des macros

Définissez les valeurs des macros avant de prévisualiser les données d'un pipeline et avant d'exécuter un pipeline. Vous pouvez définir des valeurs de macros aux emplacements suivants :

  • Plug-ins Argument Setter
  • Arguments d'exécution
  • Préférences de l'application
  • Préférences d'espace de noms
  • Préférences système

L'exécution d'un pipeline avec des macros effectue les opérations suivantes :

  • Cloud Data Fusion vérifie d'abord si le pipeline inclut un plug-in de définition d'arguments :
    • S'il possède un setter d'arguments, Cloud Data Fusion utilise les valeurs des macros qui y figurent.
    • S'il n'y a pas de setter d'arguments ou si des macros ne sont pas attribuées dans le setter d'arguments, Cloud Data Fusion utilise plutôt les valeurs des arguments d'exécution du pipeline.
  • Les arguments d'exécution héritent des macros des préférences de l'application.
  • Les préférences des applications héritent des macros des préférences des espaces de noms
  • Les préférences d'espace de noms héritent des macros des préférences système.

Exemples

Les macros sont souvent utilisées dans les champs de chemin d'accès. Au lieu d'utiliser des chemins codés en dur, vous pouvez utiliser des chemins dynamiques. Par exemple, dans un plug-in source Cloud Storage, vous pouvez remplacer la valeur du chemin d'accès par plusieurs macros. La valeur suivante divise les éléments de bucket, de dossier et de fichier : gs://${bucket.name}/${folder}/${file.name}.

L'exemple suivant charge des données à partir d'un bucket statique et d'un fichier dont le nom n'est pas statique. Saisissez le nom du bucket et utilisez une macro pour le nom de fichier : gs://<BUCKET_NAME>/${folder}/${file.name}.

Pour en savoir plus, consultez Macros et fonctions de macro.

Configurer les préférences

La section suivante décrit la hiérarchie des préférences, où les préférences sont définies, héritées ou remplacées.

Définir les préférences système

Vous pouvez définir des préférences pour le système. Étant donné que les noms de macros doivent être uniques, chaque préférence s'applique à tous les pipelines qui utilisent cette macro.

Par exemple, vous disposez d'un pipeline avec une source de base de données et vous utilisez des macros pour le nom et le nom d'utilisateur de la base de données. Vous pouvez définir les préférences de base de données et de nom d'utilisateur dans les préférences système. Chaque espace de noms et chaque pipeline de cette instance héritent de ces préférences.

Pour définir les préférences système, procédez comme suit :

  1. Dans Cloud Data Fusion Studio, cliquez sur Administrateur système > Configuration.
  2. Cliquez sur Préférences système > Modifier les préférences système.
  3. Dans la boîte de dialogue Préférences, saisissez de nouvelles préférences ou modifiez celles existantes.
  4. Cliquez sur Enregistrer et fermer. Ces préférences sont disponibles dans tous les espaces de noms, applications et pipelines.

Définir les préférences d'espace de noms

Vous pouvez définir des préférences pour des espaces de noms individuels.

Lorsque vous définissez des préférences d'espace de noms, toutes les préférences système héritées s'affichent. Lorsque vous définissez des préférences pour un espace de noms, vous pouvez remplacer les préférences héritées en définissant des valeurs différentes. Vous pouvez également ajouter de nouvelles préférences d'espace de noms.

Pour définir les préférences d'espace de noms, procédez comme suit :

  1. Dans Cloud Data Fusion Studio, cliquez sur Administrateur système > Configuration.
  2. Cliquez sur Espaces de noms, puis sélectionnez un espace de noms pour ouvrir sa page de configuration.
  3. Pour modifier les préférences héritées ou en ajouter d'autres, accédez à l'onglet "Préférences", puis cliquez sur Modifier. Une boîte de dialogue Préférences s'ouvre. Vous pouvez y saisir une nouvelle préférence ou remplacer les préférences système héritées. Cliquez sur Ajouter, puis saisissez la clé et la nouvelle valeur de la macro.
  4. Cliquez sur Enregistrer et fermer. Une préférence d'espace de noms est créée avec la nouvelle valeur, qui prévaut sur la préférence système.

Définir les préférences des applications

Vous pouvez définir des préférences pour chaque pipeline déployé dans un espace de noms. Lorsque vous définissez des préférences d'application, toutes les préférences système et d'espace de noms héritées s'affichent. Lorsque vous définissez des préférences pour une application, vous pouvez remplacer les préférences héritées en définissant des valeurs différentes ou ajouter de nouvelles préférences pour l'application :

  1. Dans Cloud Data Fusion Studio, cliquez sur , puis sur le menu Espace de noms pour sélectionner l'espace de noms dans lequel vous souhaitez ajouter des préférences d'application.
  2. Cliquez sur Centre de contrôle.
  3. Cliquez sur l'icône en forme de clé à molette Définir vos préférences. Une liste de toutes les préférences héritées s'affiche.
  4. Pour modifier les préférences héritées ou en ajouter d'autres, accédez à l'onglet "Préférences", puis cliquez sur Modifier. Une boîte de dialogue Préférences s'ouvre. Vous pouvez y saisir une nouvelle préférence ou remplacer les préférences système héritées. Cliquez sur Ajouter, puis saisissez la clé et la nouvelle valeur de la macro.
  5. Cliquez sur Enregistrer et fermer. La préférence de l'application est créée avec la nouvelle valeur, qui remplace les préférences du système ou de l'espace de noms. Lorsque vous exécutez le pipeline déployé, les préférences de l'application s'affichent sous forme d'arguments d'exécution que vous pouvez éventuellement modifier.

Configurer des arguments d'exécution

Configurez des arguments d'exécution pour fournir des valeurs aux macros et, éventuellement, remplacer les préférences lorsque vous déployez ou exécutez un pipeline.

Arguments d'exécution pour prévisualiser les données

Pour définir les valeurs de chaque macro du pipeline lorsque vous prévisualisez les données dans Cloud Data Fusion Studio, cliquez sur Liste > Configurer.

Arguments d'exécution pour exécuter des pipelines déployés

Si un pipeline inclut des macros, vous devez ajouter des arguments d'exécution après le déploiement du pipeline pour définir les valeurs des macros.

Lorsque vous déployez un pipeline avec des macros, cliquez sur le menu déroulant  à côté de Exécuter pour ouvrir la boîte de dialogue Arguments d'exécution et définir les valeurs de chaque macro.

Définir les préférences de pipeline

Pour définir les préférences d'un pipeline, procédez comme suit :

  1. Dans Cloud Data Fusion Studio, cliquez sur Liste > Déployé, puis sélectionnez un pipeline déployé pour l'afficher.
  2. Dans le canevas du pipeline, cliquez sur le menu déroulant  à côté de Exécuter. La boîte de dialogue Arguments d'exécution s'ouvre.
  3. Dans la boîte de dialogue Arguments d'exécution qui s'ouvre, spécifiez la valeur de chaque macro du pipeline.

Présentation des préférences, des macros et des arguments d'exécution

Vous pouvez configurer des préférences aux niveaux suivants :

  • Préférences système : le niveau le plus élevé où vous définissez les préférences, telles que les valeurs par défaut, pour l'ensemble de l'instance.
  • Préférences de l'espace de noms : héritent des préférences du système. Vous pouvez définir des préférences pour un espace de noms spécifique.
  • Préférences de l'application : hérite des préférences de l'espace de noms. Ils peuvent être propres à des applications individuelles (contenant des pipelines).
  • Arguments d'exécution : paires clé/valeur qui remplacent les préférences à des niveaux supérieurs.

Si vous définissez une préférence au niveau des préférences système, les valeurs des macros sont automatiquement renseignées dans les préférences d'espace de noms, les préférences d'application et les arguments d'exécution.

Si vous définissez des préférences au niveau de l'espace de noms, elles s'affichent dans la liste des préférences héritées dans les préférences de l'application. Si un pipeline utilise une macro définie dans une préférence, les arguments d'exécution utilisent la paire clé-valeur définie dans la préférence. Vous pouvez remplacer les valeurs des préférences à chaque niveau de préférence et dans les arguments d'exécution.

Utilisez des préférences, des macros et des arguments d'exécution pour les cas d'utilisation suivants :

  • Développer un pipeline Intégrez des macros là où vous avez besoin de valeurs dynamiques pour les propriétés du plug-in.
  • Facultatif : définissez vos préférences. Définissez des valeurs par défaut pour les macros dans les préférences à différents niveaux.
  • Déployer et exécuter un pipeline Lorsque vous exécutez un pipeline, les événements suivants se produisent :
    • Les préférences du niveau concerné, telles que les préférences système ou d'espace de noms, sont appliquées.
    • Tous les arguments d'exécution que vous fournissez remplacent les valeurs attribuées aux macros dans les préférences.
    • Cloud Data Fusion résout les macros en substituant leurs valeurs à partir des arguments d'exécution (ou des préférences si aucun argument d'exécution n'est fourni).

Exemple

Un pipeline comporte un récepteur BigQuery dont la valeur du nom de table doit changer de manière dynamique. Pour configurer cette fonctionnalité, procédez comme suit :

  1. Définissez la macro. Dans les propriétés du récepteur, utilisez la macro suivante dans le champ Nom de la table : ${output_table}..
  2. Définissez la préférence. Dans les préférences de l'application, définissez une préférence pour ${output_table} avec la valeur par défaut suivante : data_staging.
  3. Définissez l'argument d'exécution. Lorsque vous exécutez le pipeline, fournissez un argument d'exécution, par exemple output_table=final_analytics_data.

Lors de l'exécution du pipeline, la macro ${output_table}, est remplacée par final_analytics_data.

Étapes suivantes