フォルダとリポジトリを使用してコードアセットを整理する

このドキュメントでは、フォルダとリポジトリのシステムの概要について説明します。また、フォルダとリポジトリの操作に使用される Dataform API のフィールドとメソッドの概要も説明します。

Dataform API は、一般的なオペレーティングシステムのファイルシステムと同様の階層構造でコードアセットを整理するために使用できるリソースを提供します。この構造により、Identity and Access Management（IAM）ポリシーの継承も可能になり、権限がパスに沿って伝播されます。

次のリストは、フォルダとリポジトリシステムの説明で使用される主な用語を定義しています。

フォルダ: フォルダは、標準のファイルシステムフォルダと同様に、リソースを整理するための基本的なコンテナです。他のフォルダやリポジトリを整理したり、リソースをフォルダに出し入れしたりできます。フォルダノードで権限を付与すると、これらの権限はすべてのコンテンツに伝播されます。
ユーザーのルートフォルダ: ユーザーのルートフォルダは、ユーザーの個人用スペースを表します。ユーザーが作成またはアクセスしたすべてのフォルダとリポジトリが含まれています。ユーザーのルートフォルダは、チームフォルダのサブツリーの一部ではありません。ユーザーのルートフォルダは、関連付けられた API リソースのない仮想コンセプトです。
チームフォルダ: チームフォルダはフォルダに似ていますが、Google ドライブの共有ドライブと同様に、チームのコラボレーションを目的として設計されています。コアコードアセット専用のスペースが提供され、チームのコアアセットに対するより厳格な共有権限とアクセス権限がサポートされます。
ファイル: このフォルダ構造のコンテキストでは、ファイルは Dataform リポジトリリソースで表されます。各リポジトリには、ノートブック、保存済みクエリ、データキャンバス、データ準備などの単一ファイルアセットが含まれています。

必要なロール

このドキュメントのタスクを行うために必要な権限を取得するには、プロジェクト、フォルダ、またはリソースに対する適切な IAM ロールを付与するよう管理者に依頼してください。

フォルダに付与された権限は、そのフォルダ内にあるすべてのフォルダとファイルに伝播されます。

次のロールはフォルダとファイルに適用されます。

ロール	付与対象	権限とユースケース
コードオーナー（`roles/dataform.codeOwner`）	フォルダまたはファイル	コードアセットの管理のために、リソースに対する完全な制御権を付与します。このロールを持つユーザーは、リソースの削除、リソースの IAM ポリシーの設定、リソースの移動など、すべての操作を行うことができます。
コードエディタ（`roles/dataform.codeEditor`）	フォルダまたはファイル	コンテンツの編集と管理ができます。このロールを持つユーザーは、フォルダへのコンテンツの追加、ファイルの編集、フォルダまたはファイルの IAM ポリシーの取得を行うことができます。リソースを移動する場合は、移動先のフォルダに対してもこのロールを持っている必要があります。
コード閲覧者（コメント可）（`roles/dataform.codeCommenter`）	フォルダまたはファイル	コードアセットまたはフォルダにコメントを追加できます。
コード閲覧者（`roles/dataform.codeViewer`）	フォルダまたはファイル	読み取り専用アクセス権を付与します。このロールを持つユーザーは、フォルダとファイルのコンテンツに対してクエリを実行できます。
コード作成者（`roles/dataform.codeCreator`）	プロジェクト	プロジェクト内で新しいフォルダとファイルを作成する権限を付与します。

以下のロールは、チームフォルダの管理に固有のものです。

ロール	付与対象	権限とユースケース
チームフォルダオーナー（`roles/dataform.teamFolderOwner`）	チームフォルダ	コードアセットを管理するためのチームフォルダに対する完全な制御権を付与します。このロールを持つユーザーは、チームフォルダを削除し、チームフォルダの IAM ポリシーを設定できます。
チームフォルダ投稿者（`roles/dataform.teamFolderContributor`）	チームフォルダ	チームフォルダ内のコンテンツを管理できます。このロールを持つユーザーは、チームフォルダを更新できます。
チームフォルダ閲覧者（コメント可）（`roles/dataform.teamFolderCommenter`）	チームフォルダ	チームフォルダとその中に含まれるコードアセットにコメントを追加できます。
チームフォルダ閲覧者（`roles/dataform.teamFolderViewer`）	チームフォルダ	チームフォルダとそのコンテンツに対する読み取り専用アクセス権を付与します。このロールを持つユーザーは、チームフォルダを表示し、チームフォルダの IAM ポリシーを取得できます。
チームフォルダ作成者（`roles/dataform.teamFolderCreator`）	プロジェクト	プロジェクト内で新しいチームフォルダを作成する権限を付与します。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、このドキュメントのタスクを行うために必要な権限が含まれています。必要な権限を正確に確認するには、「必要な権限」セクションを開いてください。

必要な権限

フォルダを作成する:
- 親ユーザーフォルダ、チームフォルダ、またはプロジェクトに対する folders.create
- 親フォルダまたはチームフォルダに対する folders.addContents
フォルダのプロパティを取得する: フォルダに対する folders.get
フォルダまたはチームフォルダのコンテンツをクエリする: フォルダに対する folders.queryContents
フォルダを更新する: フォルダに対する folders.update
フォルダを削除する: フォルダに対する folders.delete
フォルダの IAM ポリシーを取得する: フォルダに対する folders.getIamPolicy
フォルダの IAM ポリシーを設定する: フォルダに対する folders.setIamPolicy
フォルダを移動する:
- 移動するフォルダに対する folders.move
- 移動先のフォルダまたはチームフォルダに対する folders.addContents（ルートフォルダに移動する場合は不要）
チームフォルダを作成する: プロジェクトに対する teamFolders.create
チームフォルダを削除する: チームフォルダに対する teamFolders.delete
チームフォルダの IAM ポリシーを取得する: チームフォルダに対する teamFolders.getIamPolicy
チームフォルダの IAM ポリシーを設定する: チームフォルダに対する teamFolders.setIamPolicy
チームフォルダのプロパティを取得する: チームフォルダに対する teamFolders.get
チームフォルダを更新する: チームフォルダに対する teamFolders.update
リポジトリを作成します。
- 親ユーザーフォルダ、チームフォルダ、またはプロジェクトに対する repositories.create
- 親フォルダまたはチームフォルダに対する folders.addContents
リポジトリの読み取り: リポジトリに対する repositories.readFile
リポジトリに書き込む: リポジトリに対する repositories.commit
リポジトリを移動する:
- 移動するリポジトリに対する repositories.move
- 移動先の親ユーザーフォルダ、チームフォルダ、またはプロジェクトに対する folders.addContents（ルートフォルダに移動する場合は不要）
リポジトリのプロパティを取得する: リポジトリに対する repositories.get
リポジトリを更新する: リポジトリに対する repositories.update
リポジトリを削除する: リポジトリに対する repositories.delete

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

プロジェクト内のコードアセットを管理するための完全アクセス権を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

Dataform 管理者（roles/dataform.admin）
Dataform 編集者（roles/dataform.editor）
Dataform 閲覧者（roles/dataform.viewer）

IAM ポリシーの継承

フォルダとリポジトリのリソースに対する IAM アクセスは、階層構造を利用します。この階層により、アクセスポリシーが親フォルダからそのコンテンツに継承されます。

フォルダに IAM ポリシーが設定されている場合、そのポリシーで付与された権限は、フォルダのサブツリー内のすべてのリポジトリとネストされたサブフォルダにも適用されます。結果として次のようになります。

権限はフォルダ階層を通じて継承されます。ユーザーに上位フォルダの特定のロールが付与されると、そのユーザーは、そのフォルダとそのサブフォルダに含まれるすべてのリソースに対して、そのロールに含まれる権限を有します。
ユーザーがリソースに対して持つ権限は、そのリソースに直接設定されたポリシーと、ルートまでのパス内のすべてのフォルダから継承されたすべてのポリシーで構成されます。

そのため、フォルダ構造の奥にあるリソースに対してアクションを実行するために、プロジェクトレベルの権限は必要ありません。このリソースのパスにあるフォルダに対する適切な権限のみが必要です。たとえば、サブフォルダにリポジトリを作成する場合は、特定のサブフォルダまたはその親フォルダのいずれか（最上位フォルダを含む）に対する必要な権限を持っていなければなりません。

フォルダとリポジトリに IAM ポリシーを適用する際のベストプラクティスは次のとおりです。

権限が均一に必要な階層の最上位のフォルダに IAM ポリシーを適用します。たとえば、チームがチームのディレクトリ内のすべてのデータにアクセスする必要がある場合は、個々のプロジェクトサブフォルダのレベルではなく、チームフォルダのレベルで必要なロールを付与します。
ユーザーまたはサービスがタスクを実行するために必要な最小限の権限を常に付与します。より具体的なフォルダレベルのロールと権限を使用できる場合は、広範なロールの付与を避けます。

リソースの作成時に付与される IAM ロール

リソースの作成時に、次のロールが自動的に付与されます。

チームフォルダのサブツリーにないフォルダを作成したユーザーには、そのフォルダに対する Dataform 管理者ロール（roles/dataform.admin）が自動的に付与されます。
ルートチームフォルダの作成者には、そのチームフォルダに対する Dataform 管理者ロール（roles/dataform.admin）が自動的に付与されます。
projects.locations.repositories リソースで setAuthenticatedUserAdmin を true に設定すると、ユーザーのルートノードにリポジトリを作成したユーザーには、そのリポジトリに対する Dataform 管理者ロール（roles/dataform.admin）が自動的に付与されます。

Config API を使用して、リソースの作成時に特定のロールを付与できます。

チームフォルダのサブツリー内に新しいフォルダやリポジトリを作成しても、ロールは自動的に付与されません。

制限事項

フォルダとリポジトリには次の制限があります。

フォルダをネストできる階層の深さは 5 までです。
リポジトリをフォルダに移動すると、リポジトリとその子リソースが Cloud Asset Inventory に表示されなくなります。
1 回の移動オペレーションに参加できるリソースは最大 100 個です。
フォルダの数が非常に多い（数十万個）場合、フォルダの操作時にパフォーマンスが低下します。

リソースの整理

以降のセクションでは、Dataform API を使用してフォルダ、チームフォルダ、リポジトリリソースを整理する方法について説明します。

フォルダリソース

次の表に、フォルダの API フィールドを示します。

フィールド説明

containing_folder 親フォルダまたはチームフォルダの名前への参照。フォルダ ID またはチームフォルダ ID に設定できます。このフィールドを設定しない場合、これはルートフォルダになります。

フィールド	説明
`containing_folder`	親フォルダまたはチームフォルダの名前への参照。フォルダ ID またはチームフォルダ ID に設定できます。このフィールドを設定しない場合、これはルートフォルダになります。
`display_name`	ユーザーに表示されるリソースの名前。`display_name` フィールドは、次のルールに従って一意である必要があります。ユーザールート内では、すべてのフォルダに一意の表示名が必要です。ただし、ユーザールートにあるリポジトリの表示名は、他のリポジトリやフォルダの名前と重複しても構いません。フォルダ内の表示名は、そのフォルダ内のすべてのフォルダとリポジトリで一意にする必要があります。チームフォルダ内では、表示名はチームフォルダ内のすべてのフォルダとリポジトリで一意である必要があります。チームフォルダの表示名は、プロジェクト全体で一意である必要があります。

display_name

ユーザーに表示されるリソースの名前。display_name フィールドは、次のルールに従って一意である必要があります。

ユーザールート内では、すべてのフォルダに一意の表示名が必要です。ただし、ユーザールートにあるリポジトリの表示名は、他のリポジトリやフォルダの名前と重複しても構いません。
フォルダ内の表示名は、そのフォルダ内のすべてのフォルダとリポジトリで一意にする必要があります。
チームフォルダ内では、表示名はチームフォルダ内のすべてのフォルダとリポジトリで一意である必要があります。
チームフォルダの表示名は、プロジェクト全体で一意である必要があります。

次の表に、主な projects.locations.folders API メソッドを示します。

API メソッド	説明
`create`	新しいフォルダを作成します。
`get`	フォルダのプロパティを取得します。
`patch`	フォルダのプロパティ（名前など）を更新します。
`queryFolderContents`	フォルダ内のアイテムを一覧表示します。
`move`	フォルダとそのサブツリー全体を新しいコンテナフォルダに移動します。移動オペレーションはアトミックです。つまり、フォルダのサブツリー内のすべてのリソースが適切に移動され、部分的な失敗がない場合にのみ成功します。
`delete`	フォルダを削除します。フォルダが空の場合にのみ成功します。
`setIamPolicy`	フォルダにロールを付与します。付与されたロールは、フォルダのサブツリー全体に自動的に伝播されます。

次の例は、ルートレベルのフォルダを作成する方法を示しています。

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"

次のように置き換えます。

DISPLAY_NAME: リソースのユーザーに表示される名前。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: リソースが作成される Dataform リポジトリのロケーション。

次の例は、別のフォルダ内にネストされたフォルダを作成する方法を示しています。

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"

次のように置き換えます。

DISPLAY_NAME: リソースのユーザーに表示される名前。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: リソースが作成される Dataform リポジトリのロケーション。
PARENT_FOLDER_ID: 新しいフォルダを作成する既存のフォルダの ID。

次の例は、フォルダを別のフォルダに移動する方法を示しています。

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"

次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: Dataform リポジトリのロケーション。
DESTINATION_PARENT_FOLDER_ID: ターゲットフォルダの移動先となるフォルダの ID。
FOLDER_ID_TO_MOVE: 移動するフォルダの ID。

チームフォルダリソース

次の表に、主な projects.locations.teamFolders API メソッドを示します。

API メソッド	説明
`create`	新しいチームフォルダを作成します。
`get`	チームフォルダのプロパティを取得します。
`patch`	チームフォルダの名前などのプロパティを更新します。
`queryContents`	チームフォルダ内のアイテムを一覧表示します。
`delete`	チームフォルダを削除します。チームフォルダが空の場合にのみ成功します。
`setIamPolicy`	チームフォルダにロールを付与します。付与されたロールは、チームフォルダのサブツリー全体に自動的に伝播されます。

次の例は、チームフォルダの内容をクエリする方法を示しています。

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"

次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: Dataform リソースのロケーション。
TEAM_FOLDER_ID: クエリする特定の Dataform チームフォルダの ID。

リポジトリリソース

既存のリポジトリリソースは、フォルダノードの containing_folder フィールドを使用して、フォルダリソースとチームフォルダリソースに整理できます。

次の表に、リポジトリの API メソッドを示します。

次の表に、主な projects.locations.repositories API メソッドを示します。

API メソッド	説明
`create`	新しいリポジトリを作成します。
`get`	リポジトリのプロパティを取得します。
`patch`	リポジトリの名前などのプロパティを更新します。
`move`	リポジトリを新しい包含フォルダに移動します。
`delete`	リポジトリを削除します。
`setIamPolicy`	リポジトリにロールを付与します。付与されたロールは、リポジトリのサブツリー全体に自動的に伝播されます。

次の例は、setAuthenticatedUserAdmin を 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"

次のように置き換えます。

REPOSITORY_DISPLAY_NAME: リポジトリのわかりやすい名前。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: リポジトリのロケーション。
REPOSITORY_ID: 新しいリポジトリの ID。

次の例は、チームフォルダ内にリポジトリを作成する方法を示しています。

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"

次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: リソースが作成されるロケーション。これは、CONTAINING_TEAM_FOLDER_ID のロケーションと同じロケーションにする必要があります。
CONTAINING_TEAM_FOLDER_ID: 新しいリポジトリを配置する特定のチームフォルダの ID。
REPOSITORY_ID: 新しいリポジトリの ID。

次の例は、リポジトリをルートフォルダに移動する方法を示しています。

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"

次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
LOCATION: リポジトリが存在するロケーション。
REPOSITORY_ID: ルートレベルに移動するリポジトリの ID。

ビジー状態のリソース

フォルダ、チームフォルダ、リポジトリが移動オペレーションに積極的に関与している場合（移動されるオブジェクトまたは移動の宛先として）、そのフォルダは「ビジー」状態になります。システムは、移動中のデータの整合性を確保するため、ビジー状態のリソースに対して次のアクションを制限します。

別の移動オペレーションの対象になること。
別の移動オペレーションの宛先になること。
移動オブジェクトの祖先になること。
削除オペレーションの対象になること。

次のステップ

BigQuery でコードアセットを整理する方法については、フォルダを使用してコードアセットを整理するとフォルダを作成して管理するをご覧ください。
Dataform リソースの権限の管理の詳細については、IAM によるアクセス制御をご覧ください。
Dataform API メソッドの詳細については、Dataform API をご覧ください。

フォルダとリポジトリを使用してコードアセットを整理する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

必要なロール

必要な権限

IAM ポリシーの継承

リソースの作成時に付与される IAM ロール

制限事項

リソースの整理

フォルダ リソース

チームフォルダ リソース

リポジトリ リソース

ビジー状態のリソース

次のステップ

フォルダとリポジトリを使用してコードアセットを整理する

フォルダリソース

チームフォルダリソース

リポジトリリソース