Organizzare gli asset di codice con cartelle e repository

Questo documento presenta una panoramica concettuale del sistema di cartelle e repository. Inoltre, riepiloga i campi e i metodi dell'API Dataform utilizzati per lavorare con cartelle e repository.

L'API Dataform fornisce risorse che puoi utilizzare per organizzare gli asset di codice in una struttura gerarchica simile a un tipico file system del sistema operativo. Questa struttura consente anche l'ereditarietà delle policy Identity and Access Management (IAM), consentendo la propagazione delle autorizzazioni lungo il percorso.

L'elenco seguente definisce i termini chiave utilizzati per descrivere il sistema di cartelle e repository:

Cartella
Una cartella è il contenitore di base per organizzare le risorse, simile a una cartella del file system standard. Ti consente di organizzare altre cartelle e repository e puoi spostare le risorse all'interno e all'esterno delle cartelle. Puoi concedere autorizzazioni al nodo della cartella e queste autorizzazioni vengono propagate a tutti i contenuti.
Cartella principale dell'utente
Una cartella principale utente rappresenta lo spazio personale di un utente. Contiene tutte le cartelle e i repository che un utente crea o a cui accede. Una cartella principale utente non fa parte della struttura secondaria di una cartella del team. Una cartella principale utente è un concetto virtuale che non ha una risorsa API associata.
Cartella del team
Una cartella del team è simile a una cartella, ma è progettata per la collaborazione del team, in modo simile a un Drive condiviso in Google Drive. Fornisce uno spazio dedicato per gli asset di codice principali e supporta autorizzazioni di condivisione e accesso più rigide per gli asset principali di un team.
File
Nel contesto di questa struttura di cartelle, un file è rappresentato da una risorsa del repository Dataform. Ogni repository contiene un singolo asset di file, ad esempio un blocco note, una query salvata, un canvas di dati o una preparazione dei dati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività descritte in questo documento, chiedi all'amministratore di concederti i ruoli IAM appropriati per il progetto, la cartella o la risorsa.

Le autorizzazioni concesse per una cartella vengono propagate a tutte le cartelle e a tutti i file contenuti al suo interno.

I seguenti ruoli si applicano a cartelle e file:

Ruolo Concesso il giorno Autorizzazioni e casi d'uso
Proprietario del codice (roles/dataform.codeOwner) Cartella o file Concede il controllo completo di una risorsa per la gestione degli asset di codice. Un utente con questo ruolo può eseguire tutte le azioni, tra cui l'eliminazione, l'impostazione della policy IAM e lo spostamento della risorsa.
Editor di codice (roles/dataform.codeEditor) Cartella o file Consente la modifica e la gestione dei contenuti. Un utente con questo ruolo può aggiungere contenuti alle cartelle, modificare i file e ottenere il criterio IAM per una cartella o un file. Questo ruolo è obbligatorio anche nella cartella di destinazione quando sposti una risorsa.
Code Commenter (roles/dataform.codeCommenter) Cartella o file Consente di commentare asset di codice o cartelle.
Code Viewer (roles/dataform.codeViewer) Cartella o file Fornisce l'accesso di sola lettura. Un utente con questo ruolo può eseguire query sui contenuti di cartelle e file.
Code Creator (roles/dataform.codeCreator) Progetto Concede l'autorizzazione per creare nuove cartelle e nuovi file all'interno di un progetto.

I seguenti ruoli sono specifici per la gestione delle cartelle del team:

Ruolo Concesso il giorno Autorizzazioni e casi d'uso
Proprietario della cartella del team (roles/dataform.teamFolderOwner) Cartella del team Concede il controllo completo di una cartella del team per la gestione degli asset di codice. Un utente con questo ruolo può eliminare la cartella del team e impostare il relativo criterio IAM.
Team Folder Contributor (roles/dataform.teamFolderContributor) Cartella del team Consente la gestione dei contenuti all'interno di una cartella del team. Un utente con questo ruolo può aggiornare una cartella del team.
Team Folder Commenter (roles/dataform.teamFolderCommenter) Cartella del team Consente di commentare una cartella del team e gli asset di codice che contiene.
Team Folder Viewer (roles/dataform.teamFolderViewer) Cartella del team Fornisce l'accesso di sola lettura a una cartella del team e ai relativi contenuti. Un utente con questo ruolo può visualizzare una cartella del team e ottenere la relativa policy IAM.
Team Folder Creator (roles/dataform.teamFolderCreator) Progetto Concede l'autorizzazione per creare nuove cartelle del team all'interno di un progetto.

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

Questi ruoli predefiniti contengono le autorizzazioni necessarie per completare le attività descritte in questo documento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

  • Creare una cartella:
    • folders.create sulla cartella utente principale, sulla cartella del team o sul progetto
    • folders.addContents sulla cartella principale o sulla cartella del team
  • Recupera le proprietà di una cartella: folders.get sulla cartella
  • Esegui una query sui contenuti di una cartella o di una cartella del team: folders.queryContents sulla cartella
  • Aggiorna una cartella: folders.update sulla cartella
  • Elimina una cartella: folders.delete sulla cartella
  • Recupera il criterio IAM per una cartella: folders.getIamPolicy sulla cartella
  • Imposta il criterio IAM per una cartella: folders.setIamPolicy sulla cartella
  • Spostare una cartella:
    • folders.move nella cartella in fase di spostamento
    • folders.addContents nella cartella di destinazione o nella cartella del team (non necessario se lo sposti in una cartella principale)
  • Crea una cartella del team: teamFolders.create sul progetto
  • Elimina una cartella del team: teamFolders.delete sulla cartella del team
  • Recupera la policy IAM per una cartella del team: teamFolders.getIamPolicy sulla cartella del team
  • Imposta il criterio IAM per una cartella del team: teamFolders.setIamPolicy sulla cartella del team
  • Recupera le proprietà di una cartella del team: teamFolders.get sulla cartella del team
  • Aggiorna una cartella del team: teamFolders.update sulla cartella del team
  • Crea un repository:
    • repositories.create sulla cartella utente principale, sulla cartella del team o sul progetto
    • folders.addContents sulla cartella principale o sulla cartella del team
  • Leggi un repository: repositories.readFile sul repository
  • Scrivere in un repository: repositories.commit sul repository
  • Sposta un repository:
    • repositories.move sul repository in fase di spostamento
    • folders.addContents sulla cartella utente principale, sulla cartella del team o sul progetto di destinazione (non necessario se lo spostamento avviene in una cartella principale)
  • Recupera le proprietà di un repository: repositories.get sul repository
  • Aggiorna un repository: repositories.update sul repository
  • Elimina un repository: repositories.delete sul repository

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per ottenere l'accesso completo per la gestione degli asset di codice nel tuo progetto, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Ereditarietà delle policy IAM

L'accesso IAM per le risorse di cartelle e repository sfrutta una struttura gerarchica. Questa gerarchia garantisce che le policy di accesso vengano ereditate dalle cartelle principali ai relativi contenuti.

Quando viene impostata una policy IAM su una cartella, le autorizzazioni concesse da questa policy si applicano anche a tutti i repository e alle sottocartelle nidificate nell'albero secondario della cartella. Ciò comporta le seguenti conseguenze:

  • Le autorizzazioni vengono ereditate tramite la gerarchia delle cartelle. Quando a un utente viene concesso un ruolo specifico in una cartella di livello superiore, l'utente dispone delle autorizzazioni incluse in quel ruolo per tutte le risorse contenute nella cartella e nelle relative sottocartelle.
  • Le autorizzazioni di un utente su una risorsa sono costituite dalle policy impostate direttamente su quella risorsa e da tutte le policy ereditate da ogni cartella nel suo percorso fino alla radice.

Di conseguenza, non hai bisogno di autorizzazioni a livello di progetto per eseguire azioni sulle risorse che si trovano in profondità in una struttura di cartelle. È necessaria solo l'autorizzazione appropriata per qualsiasi cartella nel percorso della risorsa. Ad esempio, se vuoi creare un repository in una sottocartella, devi disporre delle autorizzazioni necessarie per la sottocartella specifica o per una delle relative cartelle principali, inclusa la cartella di primo livello.

Di seguito sono riportate le best practice per l'applicazione dei criteri IAM a cartelle e repository:

  • Applica i criteri IAM alla cartella di livello più alto della gerarchia in cui le autorizzazioni sono necessarie in modo uniforme. Ad esempio, se un team ha bisogno di accedere a tutti i dati nella directory del team, concedi i ruoli necessari a livello della cartella del team anziché a livello delle sottocartelle dei singoli progetti.
  • Concedi sempre il set minimo di autorizzazioni necessarie a utenti o servizi per svolgere le loro attività. Evita di concedere ruoli generici quando puoi utilizzare ruoli e autorizzazioni più specifici a livello di cartella.

Ruoli IAM concessi al momento della creazione della risorsa

I seguenti ruoli vengono concessi automaticamente al momento della creazione della risorsa:

  • Gli utenti che creano cartelle che non si trovano in un sottoalbero di cartelle del team ricevono automaticamente il ruolo Dataform Admin (roles/dataform.admin) per queste cartelle.
  • Il creatore di una cartella di gruppo principale riceve automaticamente il ruolo Dataform Admin (roles/dataform.admin) per quella cartella di gruppo.
  • Quando imposti setAuthenticatedUserAdmin su true nella risorsa projects.locations.repositories, gli utenti che creano un repository nel nodo radice dell'utente ricevono automaticamente il ruolo Amministratore Dataform (roles/dataform.admin) nel repository.

Puoi utilizzare l'API Config per concedere un ruolo specifico al momento della creazione della risorsa.

Non ricevi automaticamente alcun ruolo quando crei nuove cartelle o repository all'interno della struttura secondaria di una cartella del team.

Limitazioni

Le cartelle e i repository presentano le seguenti limitazioni:

  • Puoi nidificare le cartelle solo fino a 5 livelli.
  • Dopo aver spostato un repository in una cartella, il repository e le relative risorse secondarie non sono visibili in Cloud Asset Inventory.
  • Un massimo di 100 risorse può partecipare a una singola operazione di spostamento.
  • Un numero molto elevato di cartelle (centinaia di migliaia) rallenta le prestazioni quando si lavora con le cartelle.

Organizza le risorse

Le sezioni seguenti descrivono come organizzare le risorse di cartelle, cartelle del team e repository con l'API Dataform.

Risorse cartella

La tabella seguente descrive i campi API per le cartelle:

Campo Descrizione
containing_folder Un riferimento alla cartella principale o al nome della cartella del team. Puoi impostare questo valore su un ID cartella o un ID cartella del team. Se non imposti questo campo, si tratta di una cartella principale.
display_name Il nome della risorsa visibile all'utente. Il campo display_name deve essere univoco in base alle seguenti regole:
  • All'interno della radice utente, tutte le cartelle devono avere nomi visualizzati univoci. Tuttavia, i nomi visualizzati dei repository nella radice dell'utente possono entrare in conflitto con altri nomi di repository e cartelle.
  • All'interno di una cartella, i nomi visualizzati devono essere univoci in tutte le cartelle e i repository della cartella.
  • All'interno di una cartella del team, i nomi visualizzati devono essere univoci in tutte le cartelle e in tutti i repository della cartella del team.
  • I nomi visualizzati delle cartelle del team devono essere univoci in tutto il progetto.

La tabella seguente descrive i metodi API projects.locations.folders principali:

Metodo API Descrizione
create Crea una nuova cartella.
get Recupera le proprietà di una cartella.
patch Aggiorna le proprietà di una cartella, ad esempio il nome.
queryFolderContents Elenca gli elementi in una cartella.
move Sposta la cartella e l'intero albero secondario in una nuova cartella contenitore. Un'operazione di spostamento è atomica, il che significa che ha esito positivo solo se tutte le risorse nel sottoalbero della cartella vengono spostate correttamente e non si verificano errori parziali.
delete Elimina la cartella. L'operazione va a buon fine solo se la cartella è vuota.
setIamPolicy Concede ruoli alla cartella. I ruoli concessi vengono propagati automaticamente all'intero sottoalbero della cartella.

Il seguente esempio mostra come creare una cartella di primo livello:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "DISPLAY_NAME"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders"

Sostituisci quanto segue:

  • DISPLAY_NAME: il nome visibile all'utente per la risorsa.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione del repository Dataform in cui vengono create le risorse.

Il seguente esempio mostra come creare una cartella nidificata all'interno di un'altra cartella:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "DISPLAY_NAME",
      "containingFolder": "projects/PROJECT_ID/locations/LOCATION/folders/PARENT_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders"

Sostituisci quanto segue:

  • DISPLAY_NAME: il nome visibile all'utente per la risorsa.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione del repository Dataform in cui vengono create le risorse.
  • PARENT_FOLDER_ID: l'ID della cartella esistente in cui vuoi creare la nuova cartella.

L'esempio seguente mostra come spostare una cartella in un'altra cartella:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "destination_containing_folder": "projects/PROJECT_ID/locations/LOCATION/folders/DESTINATION_PARENT_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/folders/FOLDER_ID_TO_MOVE:move"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione del repository Dataform.
  • DESTINATION_PARENT_FOLDER_ID: l'ID della cartella in cui vuoi spostare la cartella di destinazione.
  • FOLDER_ID_TO_MOVE: l'ID della cartella che stai spostando.

Risorse della cartella del team

La tabella seguente descrive i metodi API projects.locations.teamFolders principali:

Metodo API Descrizione
create Crea una nuova cartella del team.
get Recupera le proprietà di una cartella del team.
patch Aggiorna le proprietà di una cartella del team, ad esempio il nome.
queryContents Elenca gli elementi in una cartella del team.
delete Elimina la cartella del team. Ha esito positivo solo se la cartella del team è vuota.
setIamPolicy Assegna ruoli alla cartella del team. I ruoli concessi vengono propagati automaticamente all'intero sottoalbero della cartella del team.

Il seguente esempio mostra come eseguire una query sui contenuti di una cartella del team:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/teamFolders/TEAM_FOLDER_ID:queryContents"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione delle risorse Dataform.
  • TEAM_FOLDER_ID: l'ID della cartella del team Dataform specifica che stai interrogando.

Risorse del repository

Puoi organizzare le risorse del repository esistenti in risorse di cartelle e cartelle di gruppo con il campo containing_folder nel nodo cartella.

La tabella seguente descrive i metodi API per i repository:

La tabella seguente descrive i metodi API projects.locations.repositories principali:

Metodo API Descrizione
create Crea un nuovo repository.
get Recupera le proprietà di un repository.
patch Aggiorna le proprietà di un repository, ad esempio il nome.
move Sposta il repository in una nuova cartella contenitore.
delete Elimina il repository.
setIamPolicy Concede ruoli al repository. I ruoli concessi vengono propagati automaticamente all'intero sottoalbero del repository.

L'esempio seguente mostra come creare un repository nel nodo radice dell'utente impostando setAuthenticatedUserAdmin su true:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "displayName": "REPOSITORY_DISPLAY_NAME",
      "setAuthenticatedUserAdmin": true
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"

Sostituisci quanto segue:

  • REPOSITORY_DISPLAY_NAME: un nome intuitivo per il repository.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione del repository.
  • REPOSITORY_ID: l'ID del nuovo repository.

Il seguente esempio mostra come creare un repository all'interno di una cartella del team:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "containingFolder": "projects/PROJECT_ID/locations/LOCATION/teamFolders/CONTAINING_TEAM_FOLDER_ID"
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione in cui vengono create le risorse. Deve essere la stessa località di CONTAINING_TEAM_FOLDER_ID.
  • CONTAINING_TEAM_FOLDER_ID: l'ID della cartella del team specifica in cui vuoi inserire il nuovo repository.
  • REPOSITORY_ID: l'ID del nuovo repository.

Il seguente esempio mostra come spostare un repository nella cartella radice:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
      "destination_containing_folder": ""
  }' \
  "https://dataform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID:move"

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la posizione in cui esiste il repository.
  • REPOSITORY_ID: l'ID del repository che vuoi spostare al livello radice.

Risorse occupate

Una cartella, una cartella di gruppo o un repository è "occupato" se è coinvolto attivamente in un'operazione di spostamento, come oggetto spostato o destinazione dello spostamento. Il sistema impedisce alle risorse occupate di eseguire le seguenti azioni per garantire l'integrità dei dati durante lo spostamento:

  • Essere l'oggetto di un'altra operazione di spostamento.
  • Essere la destinazione di un'altra operazione di spostamento.
  • Essere un antenato di un oggetto di movimento.
  • Essere l'oggetto di un'operazione di eliminazione.

Passaggi successivi