Configura gli override delle compilazioni con l'API Dataform

Questo documento mostra come creare ed eseguire un risultato di compilazione con override della compilazione utilizzando l'API Dataform.

Informazioni sugli override della compilazione dell'API Dataform

Per eseguire il flusso di lavoro SQL, Dataform compila il codice in SQL per creare un risultato di compilazione. Quindi, durante una chiamata del flusso di lavoro, Dataform esegue il risultato della compilazione in BigQuery.

Per impostazione predefinita, Dataform utilizza le impostazioni nel file delle impostazioni del flusso di lavoro per creare il risultato della compilazione. Per isolare i dati eseguiti in fasi diverse del ciclo di vita di sviluppo, puoi eseguire l'override delle impostazioni predefinite con gli override della compilazione.

Passando le richieste dell'API Dataform nel terminale, puoi creare ed eseguire un singolo risultato di compilazione con override della compilazione. Puoi creare il risultato della compilazione di un'area di lavoro o di un committish Git selezionato.

Per creare un risultato di compilazione con override della compilazione, devi generare la richiesta dell'API Dataform compilationResults.create. Nella richiesta, devi specificare un'origine, un'area di lavoro o un commitish Git, che Dataform dovrà compilare nel risultato della compilazione. Nell'oggetto CodeCompilationConfig della richiesta compilationResults.create, puoi configurare gli override della compilazione.

Puoi quindi eseguire il risultato della compilazione creato in una richiesta dell'API Dataform workflowInvocations.create.

Puoi configurare i seguenti override di compilazione utilizzando l'API Dataform:

Progetto Google Cloud: progetto Google Cloud in cui Dataform esegue il risultato della compilazione, impostato in workflow_settings.yaml come defaultProject o in dataform.json come defaultDatabase.

Prefisso tabella
Prefisso personalizzato aggiunto a tutti i nomi delle tabelle nel risultato della compilazione.
Suffisso schema
Suffisso personalizzato aggiunto allo schema delle tabelle definite in defaultDataset in workflow_settings.yaml, defaultSchema in dataform.json o nel parametro schema nel blocco config di una tabella.

Valore di una variabile di compilazione: valore di una variabile di compilazione da utilizzare nel risultato della compilazione. Puoi utilizzare le variabili di compilazione per eseguire le tabelle in modo condizionale.

In alternativa agli override delle compilazioni dell'API Dataform, che puoi utilizzare solo per un risultato della compilazione, puoi configurare gli override della compilazione delle aree di lavoro nella console Google Cloud.

Per scoprire modi alternativi per configurare gli override delle compilazioni in Dataform, consulta Introduzione al ciclo di vita del codice.

Prima di iniziare

  1. Nella console Google Cloud, vai alla pagina Dataform.

    Vai a Dataform

  2. Seleziona o crea un repository.

  3. Seleziona o crea un'area di lavoro di sviluppo.

Imposta un'origine dei risultati della compilazione

Per generare la richiesta dell'API Dataform compilationResults.create, devi specificare un'origine per il risultato della compilazione.

Puoi impostare un'area di lavoro Dataform o un ramo Git, un tag Git o un'SHA di commit Git come origine nella richiesta compilationResults.create.

Imposta un'area di lavoro come origine dei risultati della compilazione

  • Nella richiesta compilationResults.create, compila la proprietà workspace con il percorso di un'area di lavoro Dataform selezionata nel seguente formato:
{
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

Sostituisci quanto segue:

  • PROJECT_NAME con il nome del tuo progetto Google Cloud.
  • LOCATION con la località del repository Dataform, configurata nelle impostazioni del flusso di lavoro.
  • REPOSITORY_NAME con il nome del tuo repository Dataform.
  • WORKSPACE_NAME con il nome della tua area di lavoro Dataform.

Il seguente esempio di codice mostra la proprietà workspace nella richiesta compilationResults.create impostata su un'area di lavoro denominata "sales-test":

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

Imposta un commitish Git come origine dei risultati della compilazione

  • Nella richiesta compilationResults.create, compila la proprietà gitCommitish con l'algoritmo SHA di commit, tag o ramo Git selezionato nel seguente formato:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Sostituisci GIT_COMMITISH con il ramo Git selezionato, il tag Git o una SHA di commit Git per il risultato della compilazione.

Il seguente esempio di codice mostra la proprietà gitCommitish nella richiesta compilationResults.create impostata su "staging":

{
  "gitCommitish": "staging"
}

Esegui l'override del progetto Google Cloud predefinito

Per creare tabelle temporanee o di produzione in un progetto Google Cloud separato da quello utilizzato per lo sviluppo, puoi passare un ID progetto Google Cloud diverso nell'oggetto CodeCompilationConfig della richiesta compilationResults.create dell'API Dataform.

Il passaggio di un ID progetto predefinito separato nella richiesta compilationResults.create sostituisce l'ID progetto Google Cloud predefinito configurato nel file delle impostazioni del flusso di lavoro, ma non sostituisce gli ID progetto Google Cloud configurati nelle singole tabelle.

  • Per eseguire l'override dell'ID progetto Google Cloud predefinito, imposta la proprietà defaultDatabase sull'ID progetto Google Cloud selezionato nell'oggetto CodeCompilationConfig nel seguente formato:

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

Sostituisci PROJECT_NAME con l'ID del progetto Google Cloud che vuoi impostare per il risultato della compilazione.

Aggiungi un prefisso della tabella

Per identificare rapidamente le tabelle dal risultato della compilazione, puoi aggiungere un prefisso a tutti i nomi delle tabelle nel risultato della compilazione passando il prefisso della tabella nell'oggetto CodeCompilationConfig nella richiesta compilationResults.create dell'API Dataform.

  • Per aggiungere un prefisso di tabella, imposta la proprietà tablePrefix nell'oggetto CodeCompilationConfig nel seguente formato:
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

Sostituisci PREFIX con il suffisso che vuoi aggiungere, ad esempio _staging. Ad esempio, se defaultDataset in workflow_settings.yaml è impostato su dataform, Dataform creerà tabelle nello schema dataform_staging.

Aggiungi un suffisso dello schema

Per separare i dati di sviluppo, gestione temporanea e produzione, puoi aggiungere un suffisso agli schemi in un risultato di compilazione passando il suffisso dello schema nell'oggetto CodeCompilationConfig nella richiesta compilationResults.create dell'API Dataform.

  • Per aggiungere un suffisso dello schema, imposta la proprietà schemaSuffix nell'oggetto CodeCompilationConfig nel seguente formato:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Sostituisci SUFFIX con il suffisso che vuoi aggiungere, ad esempio _staging. Ad esempio, se defaultDataset in workflow_settings.yaml è impostato su dataform, Dataform creerà tabelle nello schema dataform_staging.

Nota: il parametro CodeCompilationConfig schemaSuffix sostituisce gli schemi configurati nel blocco config dei singoli file.

Esegui file selezionati in modo condizionale con variabili di compilazione

Per eseguire una tabella selezionata solo in un'impostazione di esecuzione specifica, puoi creare una variabile di compilazione per l'impostazione di esecuzione e poi passare il suo valore nell'oggetto CodeCompilationConfig nella richiesta compilationResults.create dell'API Dataform.

Per eseguire una tabella in modo condizionale in una specifica impostazione di esecuzione utilizzando l'API Dataform, segui questi passaggi:

  1. Crea una variabile di compilazione e aggiungila alle tabelle selezionate.

  2. Imposta la coppia chiave-valore YOUR_VARIABLE e VALUE nel blocco codeCompilationConfig di una richiesta di compilazione dell'API Dataform nel seguente formato:

    {
 "codeCompilationConfig": {
   "vars": {
     "YOUR_VARIABLE": "VALUE"
   }
 }
}

  3. Sostituisci YOUR_VARIABLE con il nome della variabile, ad esempio executionSetting.

  4. Sostituisci VALUE con il valore della variabile per questo risultato di compilazione che soddisfa la condizione when impostata nelle tabelle selezionate.

Il seguente esempio di codice mostra la variabile executionSetting passata a una richiesta di compilazione dell' API Dataform:

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

Eseguire un risultato di compilazione con override

Il seguente esempio di codice mostra un ID risultato della compilazione passato in una richiesta workflowInvocations.create:

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

Passaggi successivi