Gestire macro, preferenze e argomenti di runtime

Questa pagina spiega come impostare preferenze, macro e argomenti di runtime nelle pipeline Cloud Data Fusion.

Termini chiave

Macro
Le macro sono segnaposto all'interno delle configurazioni dei plug-in di Cloud Data Fusion. Sono rappresentate da variabili racchiuse tra ${ }, ad esempio ${input_file_path}. Le macro introducono flessibilità nelle pipeline consentendoti di utilizzare valori segnaposto, che vengono sostituiti con valori effettivi in fase di runtime. Ciò consente la configurazione dinamica di parametri come i percorsi dei file e i nomi delle tabelle.
Preferenze
Le preferenze sono configurazioni predefinite che vengono applicate a vari livelli all'interno di Cloud Data Fusion, tra cui il sistema stesso, gli spazi dei nomi, le applicazioni (che contengono pipeline) e i singoli programmi all'interno delle pipeline. Le preferenze ti consentono di impostare valori predefiniti per le configurazioni utilizzate di frequente. I valori predefiniti possono essere ereditati da pipeline e programmi a livelli inferiori, riducendo le attività di configurazione ripetitive.
Argomenti di runtime
Gli argomenti di runtime sono coppie chiave-valore che forniscono valori per le macro e, potenzialmente, eseguono l'override delle preferenze quando implementi o esegui una pipeline. Sono altamente personalizzabili e ti consentono di modificare le configurazioni in base all'esecuzione della pipeline, senza modificare la pipeline o le preferenze sottostanti.

Configurare le macro

Per utilizzare una macro per un valore della proprietà del plug-in:

  1. In Cloud Data Fusion Studio, vai al nodo del plug-in e fai clic su Proprietà.
  2. Vai al campo in cui vuoi utilizzare una macro e fai clic su M accanto al campo.
  3. Inserisci un tasto per la macro. Ad esempio, nelle proprietà del plug-in Origine file, inserisci la seguente chiave nel campo Formato: ${format.type}.

Impostare i valori delle macro

Imposta i valori per le macro prima di visualizzare l'anteprima dei dati per una pipeline e prima di eseguirla. Puoi impostare i valori delle macro nelle seguenti posizioni:

  • Plug-in Argument Setter
  • Argomenti di runtime
  • Preferenze delle applicazioni
  • Preferenze dello spazio dei nomi
  • Preferenze di sistema

L'esecuzione di una pipeline con macro:

  • Cloud Data Fusion verifica innanzitutto se la pipeline include un plug-in di impostazione degli argomenti:
    • Se ha un setter di argomenti, Cloud Data Fusion utilizza i valori delle macro.
    • Se non è presente un setter di argomenti o se sono presenti macro non assegnate nel setter di argomenti, Cloud Data Fusion utilizza invece i valori negli argomenti di runtime della pipeline.
  • Gli argomenti di runtime ereditano le macro dalle preferenze dell'applicazione.
  • Le preferenze dell'applicazione ereditano le macro dalle preferenze dello spazio dei nomi
  • Le preferenze dello spazio dei nomi ereditano le macro dalle preferenze di sistema.

Esempi

Un utilizzo comune delle macro è nei campi del percorso. Anziché utilizzare percorsi codificati, puoi utilizzare percorsi dinamici. Ad esempio, in un plug-in di origine Cloud Storage puoi sostituire il valore del percorso con più macro. Il seguente valore divide gli elementi bucket, cartella e file: gs://${bucket.name}/${folder}/${file.name}.

L'esempio seguente carica i dati da un bucket statico e da un file con un nome non statico. Inserisci il nome del bucket e utilizza una macro per il nome file: gs://<BUCKET_NAME>/${folder}/${file.name}.

Per saperne di più, vedi Macro e funzioni macro.

Configurare le preferenze

La sezione seguente descrive la gerarchia delle preferenze, in cui le preferenze vengono impostate, ereditate o ignorate.

Impostare le preferenze di sistema

Puoi impostare le preferenze per il sistema. Poiché i nomi delle macro devono essere univoci, ogni preferenza si applica a tutte le pipeline che utilizzano quella macro.

Ad esempio, hai una pipeline con un'origine database e utilizzi macro per il nome del database e il nome utente. Puoi impostare le preferenze per il database e il nome utente nelle preferenze di sistema. Ogni spazio dei nomi e ogni pipeline in quell'istanza ereditano queste preferenze.

Per impostare le preferenze di sistema:

  1. In Cloud Data Fusion Studio, fai clic su Amministratore di sistema > Configurazione.
  2. Fai clic su Preferenze di sistema > Modifica preferenze di sistema.
  3. Nella finestra di dialogo Preferenze, inserisci nuove preferenze o modifica quelle esistenti.
  4. Fai clic su Salva e chiudi. Queste preferenze sono disponibili in tutti gli spazi dei nomi, le applicazioni e le pipeline.

Impostare le preferenze dello spazio dei nomi

Puoi impostare le preferenze per i singoli spazi dei nomi.

Quando imposti le preferenze dello spazio dei nomi, vengono visualizzate le preferenze di sistema ereditate. Quando imposti le preferenze per uno spazio dei nomi, puoi ignorare le preferenze ereditate impostando valori diversi. Puoi anche aggiungere nuove preferenze per lo spazio dei nomi.

Per impostare le preferenze dello spazio dei nomi:

  1. In Cloud Data Fusion Studio, fai clic su Amministratore di sistema > Configurazione.
  2. Fai clic su Spazi dei nomi e seleziona uno spazio dei nomi per aprire la pagina di configurazione.
  3. Per modificare le preferenze ereditate o aggiungerne di nuove, vai alla scheda Preferenze e fai clic su Modifica. Si apre una finestra di dialogo Preferenze in cui puoi inserire una nuova preferenza o ignorare le preferenze di sistema ereditate. Fai clic su Aggiungi e inserisci la chiave e il nuovo valore per la macro.
  4. Fai clic su Salva e chiudi. La preferenza dello spazio dei nomi viene creata con il nuovo valore, che ha la precedenza sulla preferenza di sistema.

Impostare le preferenze dell'applicazione

Puoi impostare le preferenze per ogni pipeline di cui è stato eseguito il deployment in uno spazio dei nomi. Quando imposti le preferenze dell'applicazione, vengono visualizzate le preferenze di sistema e dello spazio dei nomi ereditate. Quando imposti le preferenze per un'applicazione, puoi ignorare le preferenze ereditate impostando valori diversi o aggiungere nuove preferenze per l'applicazione:

  1. In Cloud Data Fusion Studio, fai clic su e poi sul menu Spazio dei nomi per selezionare lo spazio dei nomi in cui vuoi aggiungere le preferenze dell'applicazione.
  2. Fai clic su Centro di controllo.
  3. Fai clic sull'icona a forma di chiave inglese Imposta preferenze. Viene visualizzato un elenco di tutte le preferenze ereditate.
  4. Per modificare le preferenze ereditate o aggiungerne di nuove, vai alla scheda Preferenze e fai clic su Modifica. Si apre una finestra di dialogo Preferenze in cui puoi inserire una nuova preferenza o ignorare le preferenze di sistema ereditate. Fai clic su Aggiungi e inserisci la chiave e il nuovo valore per la macro.
  5. Fai clic su Salva e chiudi. La preferenza dell'applicazione viene creata con il nuovo valore, che sostituisce le preferenze di sistema o dello spazio dei nomi. Quando esegui la pipeline di cui è stato eseguito il deployment, le preferenze dell'applicazione vengono visualizzate come argomenti di runtime, che puoi modificare facoltativamente.

Configurare gli argomenti di runtime

Configura gli argomenti di runtime per fornire valori per le macro e potenzialmente sostituire le preferenze quando esegui il deployment o esegui una pipeline.

Argomenti di runtime per l'anteprima dei dati

Per impostare i valori per ogni macro nella pipeline quando visualizzi l'anteprima dei dati in Cloud Data Fusion Studio, fai clic su Elenco > Configura.

Argomenti di runtime per l'esecuzione delle pipeline di cui è stato eseguito il deployment

Se una pipeline include macro, dopo averla implementata, aggiungi argomenti di runtime, che impostano i valori delle macro.

Quando esegui il deployment di una pipeline con macro, fai clic sul menu a discesa accanto a Esegui per aprire la finestra di dialogo Argomenti di runtime e impostare i valori per ogni macro.

Impostare le preferenze della pipeline

Per impostare le preferenze per una pipeline:

  1. In Cloud Data Fusion Studio, fai clic su Elenco > Eseguito il deployment e seleziona una pipeline di cui è stato eseguito il deployment per visualizzarla.
  2. Nel canvas della pipeline, fai clic sul menu a discesa accanto a Esegui. Si apre la finestra di dialogo Argomenti di runtime.
  3. Nella finestra di dialogo Argomenti di runtime che si apre, specifica il valore per ogni macro nella pipeline.

Panoramica di preferenze, macro e argomenti di runtime

Puoi configurare le preferenze ai seguenti livelli:

  • Preferenze di sistema: il livello più alto in cui imposti le preferenze, come i valori predefiniti, per l'intera istanza.
  • Preferenze dello spazio dei nomi: eredita le preferenze da Preferenze di sistema. Puoi impostare le preferenze per uno spazio dei nomi specifico.
  • Preferenze applicazione: eredita le preferenze da Preferenze spazio dei nomi. Possono essere univoci per singole applicazioni (contenenti pipeline).
  • Argomenti runtime: coppie chiave-valore che sostituiscono le preferenze a livelli superiori.

Se imposti una preferenza a livello di preferenze di sistema, i valori delle macro vengono compilati automaticamente nelle preferenze dello spazio dei nomi, nelle preferenze dell'applicazione e negli argomenti di runtime.

Se imposti le preferenze a livello di spazio dei nomi, queste vengono visualizzate nell'elenco delle preferenze ereditate nelle preferenze dell'applicazione. Se una pipeline utilizza una macro definita in una preferenza, gli argomenti di runtime utilizzano la coppia chiave-valore definita nella preferenza. Puoi sostituire i valori delle preferenze a ogni livello di preferenza e negli argomenti di runtime.

Utilizza preferenze, macro e argomenti di runtime per i seguenti casi d'uso:

  • Sviluppo di una pipeline. Incorpora le macro dove ti servono valori dinamici per le proprietà del plug-in.
  • (Facoltativo) Impostazione delle preferenze. Imposta i valori predefiniti per le macro nelle preferenze a vari livelli.
  • Eseguire il deployment di una pipeline ed eseguirla. Quando esegui una pipeline, si verifica quanto segue:
    • Vengono applicate le preferenze per il livello pertinente, ad esempio le preferenze di sistema o dello spazio dei nomi.
    • Gli argomenti di runtime che fornisci sostituiscono i valori assegnati alle macro nelle preferenze.
    • Cloud Data Fusion risolve le macro sostituendo i relativi valori con gli argomenti di runtime (o le preferenze se non viene fornito un argomento di runtime).

Esempio

Una pipeline ha un sink BigQuery con un valore del nome della tabella che deve cambiare dinamicamente. Per configurare questa funzionalità:

  1. Imposta la macro. Nelle proprietà del sink, utilizza la seguente macro nel campo Nome tabella: ${output_table}.
  2. Imposta la preferenza. Nelle preferenze dell'applicazione, imposta una preferenza per ${output_table} con il seguente valore predefinito: data_staging.
  3. Imposta l'argomento di runtime. Quando esegui la pipeline, fornisci un argomento di runtime, ad esempio output_table=final_analytics_data.

Durante l'esecuzione della pipeline, la macro ${output_table}, viene sostituita da final_analytics_data.

Passaggi successivi