Code-Assets mit Ordnern und Repositories organisieren

Dieses Dokument bietet eine konzeptionelle Übersicht über das System von Ordnern und Repositories. Außerdem werden die Dataform API-Felder und -Methoden zusammengefasst, die für die Arbeit mit Ordnern und Repositories verwendet werden.

Die Dataform API bietet Ressourcen, mit denen Sie Code-Assets in einer hierarchischen Struktur organisieren können, die einem typischen Dateisystem eines Betriebssystems ähnelt. Diese Struktur ermöglicht auch die Übernahme von IAM-Richtlinien (Identity and Access Management), sodass Berechtigungen entlang des Pfads weitergegeben werden können.

können mit der Ordnerstruktur interagieren.

In der folgenden Liste werden die wichtigsten Begriffe definiert, die zur Beschreibung des Ordner- und Repository-Systems verwendet werden:

Ordner
Ein Ordner ist der grundlegende Container zum Organisieren von Ressourcen, ähnlich wie ein Standardordner im Dateisystem. Damit können Sie andere Ordner und Repositories organisieren und Ressourcen in Ordner verschieben und aus Ordnern entfernen. Sie können Berechtigungen auf der Ordnerebene erteilen. Diese Berechtigungen werden auf alle Inhalte übertragen.
Stammordner des Nutzers
Ein Nutzer-Stammordner repräsentiert den persönlichen Speicherplatz eines Nutzers. Sie enthält alle Ordner und Repositories, die ein Nutzer erstellt oder auf die er zugreift. Ein Nutzerstammordner ist nicht Teil des Unterbaums eines Teamordners. Ein Nutzerstammordner ist ein virtuelles Konzept, dem keine API-Ressource zugeordnet ist.
Teamordner
Ein Teamordner ähnelt einem Ordner, ist aber für die Zusammenarbeit im Team konzipiert, ähnlich wie eine geteilte Ablage in Google Drive. Sie bietet einen dedizierten Bereich für wichtige Code-Assets und unterstützt strengere Berechtigungen für die Freigabe und den Zugriff auf die wichtigsten Assets eines Teams.
Datei
Im Kontext dieser Ordnerstruktur wird eine Datei durch eine Dataform-Repository-Ressource dargestellt. Jedes Repository enthält ein einzelnes Datei-Asset, z. B. ein Notebook, eine gespeicherte Abfrage, einen Datenbereich oder eine Datenaufbereitung.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die entsprechenden IAM-Rollen für das Projekt, den Ordner oder die Ressource zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Aufgaben in diesem Dokument benötigen.

Berechtigungen, die für einen Ordner erteilt werden, werden auf alle darin enthaltenen Ordner und Dateien übertragen.

Die folgenden Rollen gelten für Ordner und Dateien:

Rolle Gewährt am Berechtigungen und Anwendungsfälle
Code-Inhaber (roles/dataform.codeOwner) Ordner oder Datei Gewährt vollständige Kontrolle über eine Ressource zum Verwalten von Code-Assets. Ein Nutzer mit dieser Rolle kann alle Aktionen ausführen, einschließlich des Löschens der Ressource, des Festlegens der IAM-Richtlinie und des Verschiebens der Ressource.
Code-Editor (roles/dataform.codeEditor) Ordner oder Datei Ermöglicht das Bearbeiten und Verwalten von Inhalten. Ein Nutzer mit dieser Rolle kann Ordnern Inhalte hinzufügen, Dateien bearbeiten und die IAM-Richtlinie für einen Ordner oder eine Datei abrufen. Diese Rolle ist auch für den Zielordner erforderlich, wenn eine Ressource verschoben wird.
Code Commenter (roles/dataform.codeCommenter) Ordner oder Datei Ermöglicht das Kommentieren von Code-Assets oder ‑Ordnern.
Code Viewer (roles/dataform.codeViewer) Ordner oder Datei Gewährt Lesezugriff. Ein Nutzer mit dieser Rolle kann den Inhalt von Ordnern und Dateien abfragen.
Code Creator (roles/dataform.codeCreator) Projekt Berechtigung zum Erstellen neuer Ordner und Dateien in einem Projekt.

Die folgenden Rollen sind speziell für die Verwaltung von Teamordnern vorgesehen:

Rolle Gewährt am Berechtigungen und Anwendungsfälle
Teamordnerinhaber (roles/dataform.teamFolderOwner) Teamordner Gewährt vollständige Kontrolle über einen Teamordner zum Verwalten von Code-Assets. Ein Nutzer mit dieser Rolle kann den Teamordner löschen und seine IAM-Richtlinie festlegen.
Team Folder Contributor (roles/dataform.teamFolderContributor) Teamordner Ermöglicht die Inhaltsverwaltung in einem Teamordner. Ein Nutzer mit dieser Rolle kann einen Teamordner aktualisieren.
Team Folder Commenter (roles/dataform.teamFolderCommenter) Teamordner Ermöglicht das Kommentieren eines Teamordners und der darin enthaltenen Code-Assets.
Betrachter für Teamordner (roles/dataform.teamFolderViewer) Teamordner Lesezugriff auf einen Teamordner und dessen Inhalt. Ein Nutzer mit dieser Rolle kann einen Teamordner aufrufen und seine IAM-Richtlinie abrufen.
Team Folder Creator (roles/dataform.teamFolderCreator) Projekt Gewährt die Berechtigung, neue Teamordner in einem Projekt zu erstellen.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Ausführen der Aufgaben in diesem Dokument erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

  • So erstellen Sie einen Ordner:
    • folders.create für den übergeordneten Nutzerordner, Teamordner oder das übergeordnete Projekt
    • folders.addContents für den übergeordneten Ordner oder Teamordner
  • Eigenschaften eines Ordners abrufen: folders.get für den Ordner
  • Inhalte eines Ordners oder Teamordners abfragen: folders.queryContents auf den Ordner
  • Ordner aktualisieren: folders.update für den Ordner
  • Ordner löschen: folders.delete auf den Ordner
  • IAM-Richtlinie für einen Ordner abrufen: folders.getIamPolicy für den Ordner
  • IAM-Richtlinie für einen Ordner festlegen: folders.setIamPolicy für den Ordner
  • Ordner verschieben:
    • folders.move für den Ordner, der verschoben wird
    • folders.addContents für den Zielordner oder Teamordner (nicht erforderlich, wenn Sie in einen Stammordner verschieben)
  • Teamordner erstellen: teamFolders.create für das Projekt
  • Teamordner löschen: teamFolders.delete auf den Teamordner
  • IAM-Richtlinie für einen Teamordner abrufen: teamFolders.getIamPolicy für den Teamordner
  • IAM-Richtlinie für einen Teamordner festlegen: teamFolders.setIamPolicy im Teamordner
  • Attribute eines Teamordners abrufen: teamFolders.get auf den Teamordner
  • Teamordner aktualisieren: teamFolders.update im Teamordner
  • Repository erstellen:
    • repositories.create für den übergeordneten Nutzerordner, Teamordner oder das übergeordnete Projekt
    • folders.addContents für den übergeordneten Ordner oder Teamordner
  • Repository lesen: repositories.readFile im Repository
  • In ein Repository schreiben: repositories.commit im Repository
  • Repository verschieben:
    • repositories.move für das Repository, das verschoben wird
    • folders.addContents für den übergeordneten Zielnutzerordner, Teamordner oder das Zielprojekt (nicht erforderlich, wenn in einen Stammordner verschoben wird)
  • Attribute eines Repositorys abrufen: repositories.get im Repository
  • Repository aktualisieren: repositories.update im Repository
  • Repository löschen: repositories.delete auf dem Repository

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um vollen Zugriff auf die Verwaltung der Code-Assets in Ihrem Projekt zu erhalten:

IAM-Richtlinienübernahme

Der IAM-Zugriff für Ordner- und Repository-Ressourcen basiert auf einer hierarchischen Struktur. Diese Hierarchie sorgt dafür, dass Zugriffsrichtlinien von übergeordneten Ordnern an ihre Inhalte weitergegeben werden.

Wenn eine IAM-Richtlinie für einen Ordner festgelegt ist, gelten die durch diese Richtlinie gewährten Berechtigungen auch für alle Repositorys und verschachtelten Unterordner im Unterbaum des Ordners. Das hat folgende Konsequenzen:

  • Berechtigungen werden über die Ordnerhierarchie übernommen. Wenn einem Nutzer eine bestimmte Rolle für einen Ordner auf hoher Ebene zugewiesen wird, hat er die in dieser Rolle enthaltenen Berechtigungen für alle Ressourcen in diesem Ordner und seinen Unterordnern.
  • Die Berechtigungen, die ein Nutzer für eine Ressource hat, bestehen aus den Richtlinien, die direkt für diese Ressource festgelegt sind, und allen Richtlinien, die von jedem Ordner in ihrem Pfad bis zum Stamm übernommen werden.

Daher benötigen Sie keine Berechtigungen auf Projektebene, um Aktionen für Ressourcen auszuführen, die sich tief in einer Ordnerstruktur befinden. Sie benötigen nur die richtige Berechtigung für einen beliebigen Ordner im Pfad zu dieser Ressource. Wenn Sie beispielsweise ein Repository in einem Unterordner erstellen möchten, benötigen Sie die erforderlichen Berechtigungen für den jeweiligen Unterordner oder einen seiner übergeordneten Ordner, einschließlich des Ordners der obersten Ebene.

Im Folgenden finden Sie Best Practices für das Anwenden von IAM-Richtlinien auf Ordner und Repositories:

  • Wenden Sie IAM-Richtlinien auf den obersten Ordner in der Hierarchie an, in dem die Berechtigungen einheitlich benötigt werden. Wenn ein Team beispielsweise Zugriff auf alle Daten im Verzeichnis des Teams benötigt, weisen Sie die erforderlichen Rollen auf der Ebene des Teamordners und nicht auf der Ebene der einzelnen Projektunterordner zu.
  • Gewähren Sie Nutzern oder Diensten immer nur den Mindestsatz an Berechtigungen, die für die Ausführung ihrer Aufgaben erforderlich sind. Vermeiden Sie es, umfassende Rollen zuzuweisen, wenn Sie spezifischere Rollen und Berechtigungen auf Ordnerebene verwenden können.

IAM-Rollen, die beim Erstellen von Ressourcen gewährt werden

Die folgenden Rollen werden automatisch bei der Ressourcenerstellung gewährt:

Sie können mit der Config API eine bestimmte Rolle beim Erstellen einer Ressource zuweisen.

Sie erhalten nicht automatisch Rollen, wenn Sie neue Ordner oder Repositories im Unterbaum eines Teamordners erstellen.

Beschränkungen

Für Ordner und Repositories gelten die folgenden Einschränkungen:

  • Ordner können nur bis zu fünf Ebenen verschachtelt werden.
  • Nachdem Sie ein Repository in einen Ordner verschoben haben, sind das Repository und seine untergeordneten Ressourcen nicht in Cloud Asset Inventory sichtbar.
  • An einem einzelnen Verschiebevorgang können maximal 100 Ressourcen beteiligt sein.
  • Eine sehr große Anzahl von Ordnern (Hunderttausende) verlangsamt die Leistung bei der Arbeit mit Ordnern.

Ressourcen organisieren

In den folgenden Abschnitten wird beschrieben, wie Sie Ordner-, Teamordner- und Repository-Ressourcen mit der Dataform API organisieren können.

Ordnerressourcen

In der folgenden Tabelle werden die API-Felder für Ordner beschrieben:

Feld Beschreibung
containing_folder Ein Verweis auf den übergeordneten Ordner oder den Namen des Teamordners. Sie können hier eine Ordner-ID oder eine Teamordner-ID angeben. Wenn Sie dieses Feld nicht festlegen, handelt es sich um einen Stammordner.
display_name Der für den Nutzer sichtbare Name der Ressource. Das Feld display_name muss gemäß den folgenden Regeln eindeutig sein:
  • Alle Ordner im Nutzerstammverzeichnis müssen eindeutige Anzeigenamen haben. Anzeigenamen von Repositorys im Nutzerstammverzeichnis dürfen jedoch mit anderen Repository- und Ordnernamen übereinstimmen.
  • Innerhalb eines Ordners müssen Anzeigenamen für alle Ordner und Repositories in diesem Ordner eindeutig sein.
  • In einem Teamordner müssen Anzeigenamen für alle Ordner und Repositories in diesem Teamordner eindeutig sein.
  • Anzeigenamen von Teamordnern müssen im gesamten Projekt eindeutig sein.

In der folgenden Tabelle werden die wichtigsten projects.locations.folders-API-Methoden beschrieben:

API-Methode Beschreibung
create Erstellt einen neuen Ordner.
get Ruft die Attribute eines Ordners ab.
patch Aktualisiert die Eigenschaften eines Ordners, z. B. seinen Namen.
queryFolderContents Listet die Elemente in einem Ordner auf.
move Verschiebt den Ordner und den gesamten Unterbaum in einen neuen übergeordneten Ordner. Ein Verschiebevorgang ist atomar. Das bedeutet, dass er nur erfolgreich ist, wenn alle Ressourcen im Unterbaum des Ordners ordnungsgemäß verschoben werden und es keine Teilausfälle gibt.
delete Löscht den Ordner. Der Vorgang ist nur erfolgreich, wenn der Ordner leer ist.
setIamPolicy Weist dem Ordner Rollen zu. Zugewiesene Rollen werden automatisch auf den gesamten Unterbaum des Ordners übertragen.

Das folgende Beispiel zeigt, wie Sie einen Ordner auf Stammebene erstellen:

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"

Ersetzen Sie Folgendes:

  • DISPLAY_NAME: Der für Nutzer sichtbare Name der Ressource.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: Der Standort des Dataform-Repositorys, in dem Ressourcen erstellt werden.

Das folgende Beispiel zeigt, wie Sie einen Ordner erstellen, der in einem anderen Ordner verschachtelt ist:

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"

Ersetzen Sie Folgendes:

  • DISPLAY_NAME: Der für Nutzer sichtbare Name der Ressource.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: Der Standort des Dataform-Repositorys, in dem Ressourcen erstellt werden.
  • PARENT_FOLDER_ID: die ID des vorhandenen Ordners, in dem Sie den neuen Ordner erstellen möchten.

Das folgende Beispiel zeigt, wie Sie einen Ordner in einen anderen Ordner verschieben:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: Der Standort des Dataform-Repositorys.
  • DESTINATION_PARENT_FOLDER_ID: die ID des Ordners, in den Sie den Zielordner verschieben möchten.
  • FOLDER_ID_TO_MOVE: Die ID des Ordners, den Sie verschieben.

Teamordnerressourcen

In der folgenden Tabelle werden die wichtigsten projects.locations.teamFolders-API-Methoden beschrieben:

API-Methode Beschreibung
create Erstellt einen neuen Teamordner.
get Ruft die Attribute eines Teamordners ab.
patch Aktualisiert die Eigenschaften eines Teamordners, z. B. seinen Namen.
queryContents Listet die Elemente in einem Teamordner auf.
delete Löscht den Teamordner. Der Vorgang ist nur erfolgreich, wenn der Teamordner leer ist.
setIamPolicy Weist dem Teamordner Rollen zu. Zugewiesene Rollen werden automatisch auf den gesamten Unterbaum des Teamordners übertragen.

Das folgende Beispiel zeigt, wie der Inhalt eines Teamordners abgefragt wird:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: der Standort der Dataform-Ressourcen.
  • TEAM_FOLDER_ID: die ID des Dataform-Teamordners, den Sie abfragen.

Repository-Ressourcen

Sie können vorhandene Repository-Ressourcen in Ordner- und Teamordnerressourcen mit dem Feld containing_folder am Ordnerknoten organisieren.

In der folgenden Tabelle werden die API-Methoden für Repositories beschrieben:

In der folgenden Tabelle werden die wichtigsten projects.locations.repositories-API-Methoden beschrieben:

API-Methode Beschreibung
create Erstellt ein neues Repository.
get Ruft die Attribute eines Repositorys ab.
patch Aktualisiert die Attribute eines Repositorys, z. B. den Namen.
move Verschiebt das Repository in einen neuen übergeordneten Ordner.
delete Löscht das Repository.
setIamPolicy Weist dem Repository Rollen zu. Gewährte Rollen werden automatisch auf den gesamten Unterbaum des Repositorys übertragen.

Das folgende Beispiel zeigt, wie Sie ein Repository im Stammknoten des Nutzers erstellen und dabei setAuthenticatedUserAdmin auf true festlegen:

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"

Ersetzen Sie Folgendes:

  • REPOSITORY_DISPLAY_NAME: Ein nutzerfreundlicher Name für das Repository.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: der Speicherort für das Repository.
  • REPOSITORY_ID: die ID des neuen Repositorys.

Das folgende Beispiel zeigt, wie Sie ein Repository in einem Teamordner erstellen:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: Der Standort, an dem Ressourcen erstellt werden. Dies muss derselbe Ort wie der Ort von CONTAINING_TEAM_FOLDER_ID sein.
  • CONTAINING_TEAM_FOLDER_ID: die ID des spezifischen Teamordners, in dem Sie das neue Repository platzieren möchten.
  • REPOSITORY_ID: die ID für das neue Repository.

Das folgende Beispiel zeigt, wie ein Repository in den Stammordner verschoben wird:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: Der Speicherort des Repositorys.
  • REPOSITORY_ID: die ID des Repositorys, das Sie auf die Stammebene verschieben möchten.

Beschäftigte Ressourcen

Ein Ordner, Teamordner oder Repository ist „beschäftigt“, wenn er aktiv an einem Verschiebevorgang beteiligt ist, entweder als das zu verschiebende Objekt oder als das Ziel des Verschiebevorgangs. Das System verhindert, dass belegte Ressourcen die folgenden Aktionen ausführen, um die Datenintegrität während der Migration zu gewährleisten:

  • Das Objekt ist das Ziel eines anderen Verschiebevorgangs.
  • Sie ist das Ziel eines anderen Verschiebevorgangs.
  • Ein Vorfahre eines Move-Objekts sein.
  • Das Objekt ist Gegenstand eines Löschvorgangs.

Nächste Schritte