Crea un repository

Questo documento ti aiuta a comprendere il concetto di repository in Dataform e come crearne uno nuovo.

Informazioni sui repository Dataform

Ogni repository Dataform contiene una raccolta di file SQLX e JavaScript che compongono il workflow, nonché pacchetti e file di configurazione Dataform. Interagisci con i contenuti del tuo repository in un workspace di sviluppo.

Dataform mostra i tuoi repository nella pagina Dataform in ordine alfabetico in base agli ID repository. Puoi ordinarli e filtrarli.

• Per visualizzare i repository, nella console Google Cloud , vai alla pagina Dataform.

  Vai a Dataform

Ogni repository Dataform è connesso a un service agent Dataform predefinito o a un account di servizio personalizzato. Puoi selezionare un account di servizio personalizzato solo quando crei un repository. Puoi modificare il service account in un secondo momento.

Per impostazione predefinita, Dataform utilizza un service agent o un account di servizio derivato dal numero del progetto nel seguente formato:

[e-mail]

Dataform utilizza Git per registrare le modifiche e gestire le versioni dei file. Ogni repository Dataform corrisponde a un repository Git. Dopo aver creato un repository Dataform, puoi connetterlo a un repository GitHub, GitLab o Bitbucket remoto.

In un repository Dataform, Dataform archivia il codice del repository. In un repository connesso, il repository di terze parti memorizza il codice del repository. Dataform interagisce con il repository di terze parti per consentirti di modificare ed eseguire i relativi contenuti in un workspace di sviluppo Dataform.

La pagina del repository Dataform è costituita dai seguenti componenti:

Scheda Workspace di sviluppo

Mostra i workspace di sviluppo creati nel repository.

Scheda Log di esecuzione del workflow

Visualizza i log di esecuzione del flusso di lavoro Dataform.

Scheda Release e pianificazione

Consente di esaminare, creare, modificare ed eliminare configurazioni della release e configurazioni del flusso di lavoro.

Scheda Impostazioni

Mostra il nome e la posizione del repository. Per un repository connesso a un repository Git di terze parti, vengono visualizzati l'origine del repository di terze parti, il nome del ramo predefinito e il token segreto. Mostra i pulsanti per connettere il repository a un repository Git di terze parti e per modificare la connessione Git.

Pulsante Crea workspace di sviluppo

Consente di creare un workspace di sviluppo.

Dopo aver creato e inizializzato un'area di lavoro di sviluppo, puoi modificare il file delle impostazioni del workflow per configurare le seguenti impostazioni di Dataform del repository:

• Il database predefinito (ID progettoGoogle Cloud ).
• Lo schema predefinito (ID set di dati BigQuery).
• La località BigQuery predefinita.
• Lo schema predefinito (ID set di dati BigQuery) per le asserzioni.
• Il magazzino, che deve essere impostato su bigquery.
• Variabili definite dall'utente che vengono rese disponibili al codice del progetto durante la compilazione.

Importante: i repository creati in Dataform non sono visibili nei repository BigQuery.

Per ulteriori informazioni sulle impostazioni del repository Dataform, consulta IProjectConfig nella guida di riferimento di Dataform Core.

Impostazioni repository

Quando crei un repository Dataform, devi impostare le seguenti impostazioni del repository:

ID repository

Un ID univoco del repository. Gli ID possono includere solo numeri, lettere, trattini e trattini bassi.

Regione

La regione Dataform per l'archiviazione del repository e dei relativi contenuti.

Questa regione di archiviazione può essere diversa dalla regione di elaborazione in cui Dataform elabora il codice e archivia l'output delle esecuzioni. Per impostazione predefinita, la regione di elaborazione è impostata sulla regione predefinita del set di dati BigQuery. Puoi modificare la regione di elaborazione nel file delle impostazioni del workflow dopo aver creato il repository. Per ulteriori informazioni, vedi Configurare le impostazioni del flusso di lavoro Dataform.

Agente di servizio o account di servizio

L'agente di servizio Dataform o il account di servizio personalizzato associato al repository. Per i nuovi repository, devi fornire un account di servizio personalizzato. Puoi selezionare un account di servizio associato al tuo progettoGoogle Cloud o inserire manualmente un altro account di servizio.

Per impostazione predefinita, Dataform utilizza un service agent o un account di servizio derivato dal numero del progetto nel seguente formato:

[e-mail]

Per eseguire i workflow nel tuo repository devi utilizzare un account di servizio personalizzato, ma l'agente di servizio Dataform predefinito viene comunque utilizzato per tutte le altre operazioni del repository.

Modalità act-as rigorosa

Attiva un controllo di sicurezza aggiuntivo che richiede l'autorizzazione iam.serviceAccounts.actAs per il account di servizio. Per i nuovi repository, viene applicata la modalità actAs rigorosa. Per i repository esistenti, ti consigliamo di utilizzare service account personalizzati e di attivare la modalità act-as rigorosa per garantire un modello di autorizzazioni più sicuro e prevedibile.

Crittografia

Metodo di crittografia per il repository. Puoi utilizzare la crittografia predefinita, una chiave di crittografia Cloud KMS gestita dal cliente unica o una chiave CMEK Dataform predefinita. Per saperne di più sull'utilizzo delle chiavi di crittografia gestite dal cliente (CMEK) in Dataform, consulta Utilizzare le chiavi di crittografia gestite dal cliente.

Dopo aver creato un repository, puoi connetterlo a GitHub o GitLab.

Importante: per creare un repository Dataform connesso a un repository Git remoto che non è incluso nella lista consentita delle norme dataform.restrictGitRemotes, aggiungi prima il repository Git remoto all'elenco allowedValues delle norme, poi crea un nuovo repository Dataform e connettilo al repository remoto. Per saperne di più, consulta Limitare i repository remoti.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Dataform APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Per utilizzare la crittografia CMEK per il repository, abilita la crittografia CMEK dei repository Dataform.

Importante :prima di creare un repository Dataform che vuoi connettere a un repository Git remoto, verifica se la tua organizzazione o il tuo progetto restringe i repository Git remoti con il dataform.restrictGitRemotes criterio dell'organizzazione. Se il criterio è attivo, assicurati che il repository remoto sia incluso nella lista consentita prima di creare il repository Dataform e collegarlo al repository remoto. Per saperne di più, consulta Limitare i repository remoti

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare ed eliminare un repository, chiedi all'amministratore di concederti i seguenti ruoli IAM sui repository:

• Dataform Admin (roles/dataform.admin) - il progetto
• Service Account User (roles/iam.serviceAccountUser): l'account di servizio personalizzato

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Concedi i ruoli richiesti

Per eseguire i workflow nel repository Dataform e in BigQuery, puoi utilizzare un account di servizio personalizzato o il tuo Account Google.

Il account di servizio personalizzato deve disporre dei seguenti ruoli obbligatori:

• Editor dati BigQuery (roles/bigquery.dataEditor) su progetti o set di dati BigQuery specifici a cui Dataform deve accedere in lettura e scrittura. In genere, ciò include il progetto che ospita il repository Dataform.
• BigQuery Data Viewer (roles/bigquery.dataViewer) su progetti o set di dati BigQuery specifici a cui Dataform deve accedere in sola lettura.
• BigQuery Job User (roles/bigquery.jobUser) nel progetto che ospita il repository Dataform.

Per consentire a Dataform di utilizzare il tuo account di servizio personalizzato, l'agente di servizio Dataform predefinito deve disporre dei seguenti ruoli nella risorsa account di servizio personalizzato:

• Creatore token service account (roles/iam.serviceAccountTokenCreator)
• Service Account User (roles/iam.serviceAccountUser)

Per concedere questi ruoli, segui questi passaggi:

1. Nella console Google Cloud vai alla pagina IAM.

   Vai a IAM

2. Fai clic su Concedi l'accesso.

3. Nel campo Nuove entità, inserisci l'ID del tuo account di servizio personalizzato.

4. Nel menu Seleziona un ruolo, seleziona i seguenti ruoli uno alla volta utilizzando Aggiungi un altro ruolo per ogni ruolo aggiuntivo:

   • Editor dati BigQuery
   • Visualizzatore dati BigQuery
   • Utente job BigQuery

5. Fai clic su Salva.

6. Nella Google Cloud console, vai alla pagina Service account.

   Vai ad Account di servizio

7. Seleziona il account di servizio personalizzato.

8. Vai a Entità con accesso e poi fai clic su Concedi l'accesso.

9. Nel campo Nuove entità, inserisci l'ID service agent Dataform predefinito.

   L'ID service agent Dataform predefinito ha il seguente formato:

   [e-mail]
   

   Sostituisci PROJECT_NUMBER con l'ID numerico del tuo progettoGoogle Cloud . Puoi trovare l'ID progetto Google Cloud nella dashboard della consoleGoogle Cloud . Per saperne di più, consulta la sezione Identificazione dei progetti.

10. Nell'elenco Seleziona un ruolo, aggiungi i seguenti ruoli:

    • Utente Service Account
    • Creatore token service account

11. Fai clic su Salva.

Per saperne di più sulla concessione dei ruoli, consulta Concedere a Dataform l'accesso richiesto.

Crea un repository

Per creare un repository Dataform:

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

   Vai a Dataform

2. Fai clic su Crea repository.

3. Nella pagina Crea repository, nel campo ID repository, inserisci un ID univoco.

   Gli ID possono includere solo numeri, lettere, trattini e trattini bassi.

4. Nell'elenco a discesa Regione, seleziona una regione Dataform per archiviare il repository e i relativi contenuti. Seleziona la regione Dataform più vicina alla tua posizione.

   Per un elenco delle regioni Dataform disponibili, consulta Località. La regione del repository non deve corrispondere alla località dei set di dati BigQuery.

   Nel file workflow_settings.yaml puoi impostare la regione di elaborazione in cui Dataform elabora il codice e archivia l'output delle esecuzioni. La regione di elaborazione deve corrispondere alla località dei set di dati BigQuery, ma non alla regione del repository. Per ulteriori informazioni, vedi Configurare le impostazioni del flusso di lavoro Dataform.

5. Nel menu Service account, seleziona un account di servizio personalizzato per il repository.

   Importante: non puoi selezionare l'agente di servizio Dataform predefinito quando crei un repository. Devi utilizzare un account di servizio personalizzato per il repository.

   Nel menu, puoi selezionare un account di servizio personalizzato associato al tuo progettoGoogle Cloud a cui hai accesso. I service account personalizzati vengono utilizzati solo per l'esecuzione del workflow. Tutte le altre operazioni sul repository vengono eseguite dall'agente di servizio Dataform predefinito.

   1. (Facoltativo) Per selezionare un account di servizio non visualizzato nel menu, fai clic su Inserisci manualmente e inserisci un IDaccount di serviziot.

6. Nella sezione Controlli delle autorizzazioni actAs, applica i controlli delle autorizzazioni alle azioni dell'utente sul repository. Per informazioni dettagliate su questi controlli, vedi Utilizzare la modalità Act-as rigorosa.

7. Configura il meccanismo di crittografia selezionato per il repository:

   Attenzione :non puoi modificare il meccanismo di crittografia di un repository Dataform dopo la creazione. Per ulteriori informazioni, consulta Limitazioni di CMEK di Dataform

   Chiave CMEK predefinita

   Dataform mostra la casella di controllo Utilizza la chiave KMS predefinita e la seleziona per impostazione predefinita.

   • Per criptare il repository con la chiave CMEK predefinita di Dataform, lascia selezionata la casella di controllo Utilizza la chiave KMS predefinita.

   Attenzione: se selezioni la casella di controllo Utilizza la chiave KMS predefinita, ma non è impostata alcuna chiave CMEK predefinita di Dataform per il tuo progetto, Dataform applica la crittografia at-rest al repository. Utilizzare le chiavi di crittografia gestite dal cliente.

   Chiave CMEK univoca

   Per criptare il repository con una chiave CMEK univoca, segui questi passaggi:

   1. Se la casella di controllo Utilizza la chiave KMS predefinita è selezionata per impostazione predefinita, deselezionala.
   2. Nella sezione Crittografia, seleziona l'opzione Chiavi di crittografia gestite dal cliente (CMEK).
   3. Nel menu a discesa Seleziona una chiave gestita dal cliente, seleziona una chiave CMEK univoca.

   Crittografia dei dati inattivi

   • Per utilizzare la crittografia predefinita, nella sezione Crittografia, seleziona l'opzione Google-managed encryption key.

   Attenzione: se è impostata una chiave CMEK Dataform predefinita per la regione del repository, devi utilizzare la crittografia CMEK. Non selezionare l'opzione Google-managed encryption key. Per ulteriori informazioni, vedi Limitazioni di CMEK per Dataform.

8. Fai clic su Crea, quindi su Vai ai repository.

Modificare il account di servizio

Devi associare un account di servizio personalizzato a un repository Dataform per l'esecuzione del workflow. Tutte le altre operazioni del repository vengono comunque eseguite dall'agente di servizio Dataform predefinito.

Per modificare il account di servizio per un repository Dataform, segui questi passaggi:

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

   Vai a Dataform

2. Seleziona un repository e poi fai clic su Impostazioni.

   Nota: l'elenco dei repository Dataform include solo i repository creati per lo sviluppo del flusso di lavoro Dataform. I repository per gli asset di BigQuery Studio, come i notebook o le query salvate, vengono gestiti separatamente e non vengono visualizzati in questo elenco.

3. Accanto al campo Service account, fai clic su Modifica service account.

4. Nel menu Service account, seleziona un account di servizio per il repository.

   Nel menu, puoi selezionare un account di servizio personalizzato associato al tuo progettoGoogle Cloud a cui hai accesso.

   1. (Facoltativo) Per selezionare un account di servizio non visualizzato nel menu, fai clic su Inserisci manualmente e inserisci un IDaccount di serviziot.

5. Fai clic su Salva.

Eliminare un repository

Per eliminare un repository e tutti i relativi contenuti:

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

   Vai a Dataform

2. Accanto al repository che vuoi eliminare, fai clic sul menu Altro e poi seleziona Elimina.

3. Nella finestra Elimina repository, inserisci il nome del repository per confermare l'eliminazione.

4. Fai clic su Elimina.

Passaggi successivi

• Per scoprire come connettere un repository Dataform a un repository Git di terze parti, consulta Connettersi a un repository Git di terze parti.
• Per scoprire di più su come le dimensioni del repository influiscono sullo sviluppo in Dataform, consulta Panoramica delle dimensioni del repository.
• Per saperne di più sulla suddivisione di un repository in Dataform, consulta Introduzione alla suddivisione dei repository.
• Per scoprire come configurare le impostazioni di elaborazione di Dataform, vedi Configurare le impostazioni del workflow Dataform.
• Per scoprire come creare e inizializzare uno spazio di lavoro, consulta Creare uno spazio di lavoro.