Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Risolvere i problemi relativi a Dataform

Questo documento mostra come risolvere i problemi relativi a Dataform.

Accesso a BigQuery negato

Si verifica il seguente errore quando attivi una chiamata di pipeline prima di concedere a Dataform l'accesso a BigQuery:

Access Denied: Project PROJECT_ID: User does not have bigquery.jobs.create permission in project PROJECT_ID.

Per risolvere questo errore, concedi a Dataform l'accesso a BigQuery.

Il token di accesso per un repository remoto viene rifiutato

Si verifica il seguente errore quando il token di autenticazione per un repository di terze parti connesso non ha accesso a quel repository:

The access token for remote repository REPOSITORY_NAME was rejected

Per risolvere questo errore, controlla le autorizzazioni richieste nel tuo provider Git e aggiorna di conseguenza il token di autenticazione di Secret Manager. Per saperne di più sull'autenticazione dei repository Git di terze parti in Dataform, consulta Connettersi a un repository Git di terze parti.

Il limite di concorrenza delle query BigQuery è stato superato

Si verifica il seguente errore quando il numero di query simultanee eseguite su BigQuery supera il limite di concorrenza delle query BigQuery :

Exceeded rate limits: too many concurrent queries for this project_and_region

Per risolvere questo errore, riduci il numero di query parallele a meno di 250 nei seguenti modi:

In Dataform, classifica le azioni con i tag, ed esegui solo i tag selezionati alla volta.
In Dataform, introduci le dipendenze tra le azioni.
In Dataform, dividi le esecuzioni delle azioni tra progetti diversi Google Cloud .

Per istruzioni su come risolvere questo errore in BigQuery, consulta Risolvere i problemi relativi a quote e limiti errori.

La quota di BigQuery è stata superata

Si verifica il seguente errore quando il numero di richieste API che Dataform invia a BigQuery supera la quota di BigQuery:

Quota exceeded: Your user_method exceeded quota for concurrent api requests
per user per method.

Per risolvere questo errore, riduci il numero di query parallele a meno di 250 nei seguenti modi:

In Dataform, classifica le azioni con i tag, ed esegui solo i tag selezionati alla volta.
In Dataform, introduci le dipendenze tra le azioni.
In Dataform, dividi le esecuzioni delle azioni tra progetti diversi Google Cloud .

Per istruzioni su come risolvere questo errore in BigQuery, consulta Risolvere i problemi relativi a quote e limiti errori.

Errori di chiamata della pipeline BigQuery

Si verificano i seguenti errori durante l'esecuzione di un flusso di lavoro su BigQuery:

Errori di chiamata della pipeline che iniziano con messaggi di errore di BigQuery.

Per risolvere questi errori, consulta Messaggi di errore di BigQuery.

La compilazione non riesce

Si verificano i seguenti errori durante la compilazione a causa delle dimensioni o del numero di query compilate:

Compilation timed out. Reduce the complexity of your project to ensure it can compile within limits.
Compilation exceeded its allowed heap memory limits. Reduce the complexity of your project to ensure it can compile within limits.
Compilation exceeded its allowed ArrayBuffer or string memory limits. Reduce the complexity of your project to ensure it can compile within limits.

Per risolvere questi errori, segui questi passaggi:

Aggiorna Dataform Core all'ultima versione.
Esamina il flusso di lavoro per identificare e ridurre le inefficienze.
Riduci le dimensioni delle query SQL.

Riduci la quantità di operazioni JavaScript in memoria, ad esempio:

config { config {type: "table" }}
js {
    const tooBig = new Uint8Array(110_000_000);
}
SELECT ...

Dividi il repository.

Per saperne di più sui limiti delle risorse di compilazione di Dataform, consulta Quote e limiti.

Proprietà `includeDependentAssertions` in conflitto

Si verifica il seguente errore durante la compilazione quando il parametro includeDependentAssertions viene impostato per la stessa azione con valori diversi all'interno di un file:

Conflicting "includeDependentAssertions" properties are not allowed. Dependency
dependencyName has different values set for this property.

Per risolvere questo errore, modifica il file e rimuovi le ripetizioni in conflitto del parametro includeDependentAssertions.

Per saperne di più sull'utilizzo del parametro includeDependentAssertions per impostare le asserzioni come dipendenze, consulta Impostare le asserzioni di un'azione selezionata come dipendenze.

L'associazione del account di servizio tra progetti è bloccata

Si verifica il seguente errore quando tenti di utilizzare un account di servizio personalizzato di un progetto diverso dal repository Dataform e l'operazione viene bloccata da un vincolo della policy dell'organizzazione:

The caller does not have permission to act as service account: SERVICE_ACCOUNT_EMAIL

Per risolvere questo errore, procedi come segue:

Identifica il Google Cloud progetto in cui si trova il account di servizio personalizzato.
In quel progetto, disattiva il vincolo della policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. Per saperne di più, consulta Consentire l'associazione dei service account tra progetti.
Assicurati che l'entità chiamante disponga del ruolo Utente account di servizio (roles/iam.serviceAccountUser) nel service account personalizzato.

Per saperne di più, consulta Gestire l'associazione account di servizio tra progetti.

Errori di dipendenza `@dataform/core`

Si verificano i seguenti errori durante la compilazione se la dipendenza dataform-core in package.json non è aggiornata:

Failed to resolve @dataform/core

@dataform/core version should be X.X.X or newer

La dipendenza @dataform/core è obbligatoria in package.json. Quando inizializzi il primo workspace nel repository, Dataform popola automaticamente package.json con la versione corrente di @dataform/core. Devi aggiornare @dataform/core all'ultima versione quando viene rilasciata.

Per risolvere questi errori, aggiorna @dataform/core all'ultima versione.

Autorizzazione per le credenziali dell'utente finale negata

Si verifica il seguente errore quando esegui il workload utilizzando le credenziali utente per un Account Google, ma Dataform non dispone delle autorizzazioni necessarie:

Dataform does not have the necessary permissions to run your workload using end user credentials. Error details: Account restricted: https://accounts.google.com/info/servicerestricted?...

Questo errore può verificarsi se la tua organizzazione utilizza regole di accesso sensibile al contesto che limitano l'accesso ai Google Cloud servizi in base all'identità e al contesto dell'utente.

Per risolvere questo errore, potresti dover aggiornare la configurazione dell'accesso sensibile al contesto per consentire a Dataform di utilizzare le credenziali utente dell'Account Google. Per farlo, devi esentare l'ID client OAuth di Dataform nella configurazione del livello di accesso. Per informazioni dettagliate sull'esenzione delle applicazioni, consulta Configurare i livelli di accesso per le applicazioni supportate.

Per ottenere l'ID client OAuth per Dataform, contatta l'assistenza clienti Google Cloud.

Impossibile risolvere `dataform.json`

Si verifica il seguente errore quando inizializzi un workspace Dataform, ma il processo di inizializzazione non riesce a installare tutti i pacchetti:

Uncaught Error: Failed to resolve dataform.json

Per risolvere questo errore, apri package.json nel workspace e fai clic su Installa pacchetti.

Impossibile risolvere `workflow_settings.yaml`

Si verifica il seguente errore quando inizializzi un workspace Dataform, ma il processo di inizializzazione non riesce a installare tutti i pacchetti:

Uncaught Error: Failed to resolve workflow_settings.yaml

Per risolvere questo errore, apri workflow_settings.yaml nel workspace e fai clic su Installa pacchetti.

Le destinazioni dei pacchetti `git+` non sono supportate

Si verifica il seguente errore quando definisci i pacchetti in package.json con destinazioni con il prefisso git+:

'git+' prefixed package targets are not currently supported. However,
in most cases they can be used via a '.tar.gz' suffixed target instead.

Dataform non supporta le destinazioni dei pacchetti con il prefisso git+.

Per risolvere questo errore, genera un URL tar.gz del pacchetto e aggiorna la destinazione del pacchetto in package.json. Per saperne di più sull'installazione dei pacchetti in Dataform, consulta Installare un pacchetto.

Il timeout dell'installazione del pacchetto è scaduto

Si verifica il seguente errore quando le dimensioni dei pacchetti definiti in package.json superano le dimensioni massime delle dipendenze NPM:

API request error: Package installation timed out

Per risolvere questo errore, rimuovi i pacchetti ridondanti da package.json. Assicurati che il file package.json non contenga @dataform/cli e che le dimensioni totali delle dipendenze NPM definite non superino i 200 MB.

Se le configurazioni di release fanno riferimento a commitish Git, assicurati che i package.json file nelle relative destinazioni siano validi.

Autorizzazione negata per agire come account di servizio

Si verifica il seguente errore quando l'entità che esegue l'azione non dispone dell'autorizzazione iam.serviceAccounts.actAs nel account di servizio effettivo:

Permission denied: Principal CALLER_EMAIL is missing 'iam.serviceAccounts.actAs' permission on service account SERVICE_ACCOUNT_EMAIL.

Questo errore può verificarsi durante le seguenti azioni:

Creazione o aggiornamento di un repository.
Creazione o aggiornamento di una configurazione del flusso di lavoro.
Creazione di una chiamata del flusso di lavoro.
Aggiornamento di una configurazione di release.

Per risolvere questo errore, concedi il ruolo Utente account di servizio (roles/iam.serviceAccountUser) all'entità nel service account effettivo. Per saperne di più, consulta Concedere i ruoli IAM richiesti.

Impossibile raggiungere il registro dei pacchetti privati

Si verifica il seguente errore quando l'autenticazione Dataform per un pacchetto privato scade:

Permission denied when fetching one or more npm packages. Please verify that
private registry authentication details are valid for each npm registry

Per risolvere questo errore, verifica che i dettagli di autenticazione del registro privato siano validi per ogni registro NPM. Per saperne di più, consulta Autenticare un pacchetto privato.

Impossibile raggiungere il repository remoto

Si verifica uno dei seguenti errori quando Dataform non riesce a connettersi al repository Git remoto:

Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

Error during remote operation: SSH connection to remote repository 'REMOTE_REPOSITORY_URL' timed out.

Error during remote operation: `Read timed out`.

Error during remote operation: `Connection time out`.

Error during remote operation: The remote repository 'REMOTE_REPOSITORY_URL' closed connection during remote operation.

Il modo per risolvere questi errori di connessione dipende dal fatto che l'errore sia permanente o temporaneo.

Errori di connessione permanenti

Se l'errore si verifica costantemente a ogni tentativo di compilazione o durante la configurazione iniziale del repository, l'errore di connessione è permanente. La connessione non è configurata correttamente o le credenziali sono scadute. Per risolvere questo errore, segui questi passaggi:

Verifica che l'host del repository Git sia accessibile da internet pubblico.
Se il repository Git remoto non è accessibile tramite internet pubblico, utilizza Developer Connect per connetterti in modo sicuro da Dataform.
Verifica che il token di autenticazione o le chiavi SSH siano validi, non scaduti e abbiano accesso al repository.
Segui tutti i passaggi descritti in Connettersi a un repository Git di terze parti.

Errori di connessione temporanei o intermittenti

Se l'errore si verifica sporadicamente durante le esecuzioni pianificate o quando vengono attivati più flussi di lavoro contemporaneamente, l'errore di connessione è temporaneo. La connessione di rete esterna al repository remoto potrebbe essere temporaneamente inaffidabile.

Per ottimizzare l'affidabilità della produzione ed evitare errori di connessione temporanei, segui queste best practice:

Evita compilazioni commitish frequenti in produzione: la chiamata diretta di CreateCompilationResult su un commitish Git, come main o un tag Git specifico, richiede a Dataform di eseguire una nuova clonazione Git e installare i pacchetti in rete a ogni esecuzione. L'attivazione di compilazioni commitish frequenti su più pipeline aumenta la dipendenza dalla rete esterna e la latenza di esecuzione.
Utilizza le configurazioni di release: per l'esecuzione in produzione, utilizza le configurazioni di release. Una configurazione di release compila il repository in base a una pianificazione controllata e salva il risultato di compilazione immutabile. Le esecuzioni dei flussi di lavoro downstream utilizzano immediatamente questo risultato memorizzato nella cache senza eseguire query sul repository Git esterno.
Sfalsa le esecuzioni pianificate: quando pianifichi più compilazioni o attivatori di release, sfalsa le pianificazioni cron per distribuire il carico di rete. Ad esempio, sfalsa le pianificazioni di 5-10 minuti anziché eseguire tutti i job contemporaneamente.
Aggiungi nuovi tentativi nei flussi di lavoro di orchestrazione: quando orchestri le compilazioni Dataform da scheduler esterni come Managed Service for Apache Airflow, configura i nuovi tentativi automatici con backoff esponenziale sull'operatore per gestire correttamente l'inaffidabilità temporanea della rete. Ad esempio, in un DAG Airflow che utilizza DataformCreateCompilationResultOperator, configura i nuovi tentativi nel seguente modo:

from datetime import timedelta
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
)

create_compilation_result = DataformCreateCompilationResultOperator(
    task_id="create_compilation_result",
    project_id="PROJECT_ID",
    region="REGION",
    repository_id="REPOSITORY_ID",
    compilation_result={
        "git_commitish": "GIT_COMMITISH",
    },
    retries=5,
    retry_delay=timedelta(minutes=2),
    retry_exponential_backoff=True,
)

Repository non visibili in Dataform

Alcuni repository Dataform potrebbero essere visualizzati nelle ricerche di Cloud Asset Inventory o nei controlli delle autorizzazioni IAM, ma non in Dataform in Google Cloud console.

Per scoprire come identificare l'origine di questi repository utilizzando le etichette, consulta Identificare i repository per gli asset BigQuery.

Il secret per un repository remoto non è accessibile

Si verifica il seguente errore quando l'agente di servizio Dataform non riesce ad accedere al secret di Secret Manager per un repository di terze parti connesso:

Dataform's service account is unable to reach the configured secret.
Make sure the secret exists and is shared with your Dataform service account:
SERVICE_ACCOUNT_ID.

Per risolvere questo errore, verifica che l'agente di servizio Dataform abbia accesso al secret.

Il service account non è visibile nel menu a discesa

Quando configuri un repository o una chiamata del flusso di lavoro, il menu Service account potrebbe non elencare un account di servizio personalizzato esistente.

Dataform utilizza l'API Identity and Access Management per elencare i service account. È necessaria l'autorizzazione iam.serviceAccounts.list a livello di progetto.

Per risolvere il problema, procedi in uno dei seguenti modi:

Fai clic su Inserisci manualmente e inserisci l'ID del account di servizio.
Chiedi all'amministratore del progetto di concederti il ruolo Visualizzatore account di servizio (roles/iam.serviceAccountViewer) o un altro ruolo che includa l'autorizzazione iam.serviceAccounts.list nel progetto.

Argomento sconosciuto: tags

Si verifica il seguente errore quando la versione della CLI Dataform non riconosce l'argomento tags:

Unknown argument: tags