Configurare gli override della compilazione con l'API Dataform

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

Informazioni sulle sostituzioni di compilazione dell'API Dataform

Per eseguire il flusso di lavoro SQL, Dataform compila il codice in SQL per creare un risultato della compilation. Poi, durante un'chiamata del workflow, 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 dello sviluppo, puoi eseguire l'override delle impostazioni predefinite con gli override di compilazione.

Passando le richieste dell'API Dataform nel terminale, puoi creare ed eseguire un singolo risultato di compilazione con sostituzioni di compilazione. Puoi creare un risultato di compilazione di uno spazio di lavoro o di un commit Git selezionato.

Per creare un risultato di compilazione con sostituzioni di compilazione, devi inviare la richiesta compilationResults.create dell'API Dataform. Nella richiesta, devi specificare una sorgente, uno spazio di lavoro o un commit Git, affinché Dataform possa compilare il risultato della compilazione. Nell'oggetto CodeCompilationConfig della richiesta compilationResults.create, puoi configurare le sostituzioni della compilazione.

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

Puoi configurare le seguenti sostituzioni di compilazione utilizzando l'API Dataform:

Google Cloud project : Google Cloud project 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 definito 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 alle sostituzioni di compilazione dell'API Dataform che puoi utilizzare solo per un risultato di compilazione, puoi configurare le sostituzioni di compilazione dello spazio di lavoro nella console Google Cloud.

Per scoprire metodi alternativi per configurare le sostituzioni di compilazione 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.

Impostare un'origine del risultato della compilazione

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

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

Impostare uno spazio di lavoro come origine del risultato della compilazione

  • Nella richiesta compilationResults.create, compila la proprietà workspace con il percorso di uno spazio di lavoro Dataform selezionato 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 Google Cloud progetto.
  • LOCATION con la posizione del repository Dataform impostata nelle impostazioni del flusso di lavoro.
  • REPOSITORY_NAME con il nome del repository Dataform.
  • WORKSPACE_NAME con il nome dello spazio di lavoro Dataform.

Il seguente esempio di codice mostra la proprietà workspace nella richiesta compilationResults.create impostata su uno spazio di lavoro denominato "sales-test":

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

Impostare un commitish Git come origine del risultato della compilazione

  • Nella richiesta compilationResults.create, compila la proprietà gitCommitish con il branch, il tag o la SHA del commit Git selezionato nel seguente formato:

    {
  "gitCommitish": "GIT_COMMITISH"
}

Sostituisci GIT_COMMITISH con il branch Git, il tag Git o un SHA commit Git selezionato per il risultato della compilazione.

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

{
  "gitCommitish": "staging"
}

Sostituire il progetto Google Cloud predefinito

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

Se nella richiesta compilationResults.create viene specificato un ID progetto predefinito distinto, viene eseguito l'override dell'ID progetto predefinito configurato nel file delle impostazioni del flusso di lavoro, ma non degli ID progetto configurati nelle singole tabelle.Google Cloud Google Cloud

  • 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' Google Cloud ID progetto che vuoi impostare per il risultato della compilazione.

Aggiungere un prefisso alla 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 dell'API Dataform compilationResults.create.

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

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

Aggiungere un suffisso allo schema

Per separare i dati di sviluppo, di staging e di 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 allo schema, imposta la proprietà schemaSuffix nell'oggetto CodeCompilationConfig nel seguente formato:
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

Sostituisci SUFFIX con il suffisso da 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 i file selezionati in modo condizionale con le 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 relativo valore nell'oggetto CodeCompilationConfig nella richiesta dell'API Dataform compilationResults.create.

Per eseguire una tabella in modo condizionale in un'impostazione di esecuzione specifica utilizzando l'API Dataform:

  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 della compilazione con override della compilazione

Il seguente esempio di codice mostra un ID risultato di 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