folders

Creates, updates, deletes, gets or lists a folders resource.

Overview

Name	folders
Type	Resource
Id	google.storage.folders

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
id	string	The ID of the folder, including the bucket name, folder name.
name	string	The name of the folder. Required if not specified by URL parameter.
bucket	string	The name of the bucket containing this folder.
createTime	string (date-time)	The creation time of the folder in RFC 3339 format.
kind	string	The kind of item this is. For folders, this is always storage#folder. (default: storage#folder)
metageneration	string (int64)	The version of the metadata for this folder. Used for preconditions and for detecting changes in metadata.
pendingRenameInfo	object	Only present if the folder is part of an ongoing rename folder operation. Contains information which can be used to query the operation status.
selfLink	string	The link to this folder.
updateTime	string (date-time)	The modification time of the folder metadata in RFC 3339 format.

list

Successful response

Name	Datatype	Description
id	string	The ID of the folder, including the bucket name, folder name.
name	string	The name of the folder. Required if not specified by URL parameter.
bucket	string	The name of the bucket containing this folder.
createTime	string (date-time)	The creation time of the folder in RFC 3339 format.
kind	string	The kind of item this is. For folders, this is always storage#folder. (default: storage#folder)
metageneration	string (int64)	The version of the metadata for this folder. Used for preconditions and for detecting changes in metadata.
pendingRenameInfo	object	Only present if the folder is part of an ongoing rename folder operation. Contains information which can be used to query the operation status.
selfLink	string	The link to this folder.
updateTime	string (date-time)	The modification time of the folder metadata in RFC 3339 format.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	bucket, folder	ifMetagenerationMatch, ifMetagenerationNotMatch	Returns metadata for the specified folder. Only applicable to buckets with hierarchical namespace enabled.
list	select	bucket	delimiter, endOffset, pageSize, pageToken, prefix, startOffset	Retrieves a list of folders matching the criteria. Only applicable to buckets with hierarchical namespace enabled.
insert	insert	bucket	recursive	Creates a new folder. Only applicable to buckets with hierarchical namespace enabled.
delete	delete	bucket, folder	ifMetagenerationMatch, ifMetagenerationNotMatch	Permanently deletes a folder. Only applicable to buckets with hierarchical namespace enabled.
rename	exec	bucket, sourceFolder, destinationFolder	ifSourceMetagenerationMatch, ifSourceMetagenerationNotMatch	Renames a source folder to a destination folder. Only applicable to buckets with hierarchical namespace enabled.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
bucket	string
destinationFolder	string
folder	string
sourceFolder	string
delimiter	string
endOffset	string
ifMetagenerationMatch	string (int64)
ifMetagenerationNotMatch	string (int64)
ifSourceMetagenerationMatch	string (int64)
ifSourceMetagenerationNotMatch	string (int64)
pageSize	integer (int32)
pageToken	string
prefix	string
recursive	boolean
startOffset	string

SELECT examples

get

Returns metadata for the specified folder. Only applicable to buckets with hierarchical namespace enabled.

SELECT
id,
name,
bucket,
createTime,
kind,
metageneration,
pendingRenameInfo,
selfLink,
updateTime
FROM google.storage.folders
WHERE bucket = '{{ bucket }}' -- required
AND folder = '{{ folder }}' -- required
AND ifMetagenerationMatch = '{{ ifMetagenerationMatch }}'
AND ifMetagenerationNotMatch = '{{ ifMetagenerationNotMatch }}';

list

Retrieves a list of folders matching the criteria. Only applicable to buckets with hierarchical namespace enabled.

SELECT
id,
name,
bucket,
createTime,
kind,
metageneration,
pendingRenameInfo,
selfLink,
updateTime
FROM google.storage.folders
WHERE bucket = '{{ bucket }}' -- required
AND delimiter = '{{ delimiter }}'
AND endOffset = '{{ endOffset }}'
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND prefix = '{{ prefix }}'
AND startOffset = '{{ startOffset }}';

INSERT examples

insert

Creates a new folder. Only applicable to buckets with hierarchical namespace enabled.

INSERT INTO google.storage.folders (
data__bucket,
data__id,
data__kind,
data__metageneration,
data__name,
data__selfLink,
data__createTime,
data__updateTime,
data__pendingRenameInfo,
bucket,
recursive
)
SELECT 
'{{ bucket }}',
'{{ id }}',
'{{ kind }}',
'{{ metageneration }}',
'{{ name }}',
'{{ selfLink }}',
'{{ createTime }}',
'{{ updateTime }}',
'{{ pendingRenameInfo }}',
'{{ bucket }}',
'{{ recursive }}'
RETURNING
id,
name,
bucket,
createTime,
kind,
metageneration,
pendingRenameInfo,
selfLink,
updateTime
;

Manifest

# Description fields are for documentation purposes
- name: folders
  props:
    - name: bucket
      value: string
      description: Required parameter for the folders resource.
    - name: bucket
      value: string
      description: >
        The name of the bucket containing this folder.
        
    - name: id
      value: string
      description: >
        The ID of the folder, including the bucket name, folder name.
        
    - name: kind
      value: string
      description: >
        The kind of item this is. For folders, this is always storage#folder.
        
      default: storage#folder
    - name: metageneration
      value: string
      description: >
        The version of the metadata for this folder. Used for preconditions and for detecting changes in metadata.
        
    - name: name
      value: string
      description: >
        The name of the folder. Required if not specified by URL parameter.
        
    - name: selfLink
      value: string
      description: >
        The link to this folder.
        
    - name: createTime
      value: string
      description: >
        The creation time of the folder in RFC 3339 format.
        
    - name: updateTime
      value: string
      description: >
        The modification time of the folder metadata in RFC 3339 format.
        
    - name: pendingRenameInfo
      value: object
      description: >
        Only present if the folder is part of an ongoing rename folder operation. Contains information which can be used to query the operation status.
        
    - name: recursive
      value: boolean

DELETE examples

delete

Permanently deletes a folder. Only applicable to buckets with hierarchical namespace enabled.

DELETE FROM google.storage.folders
WHERE bucket = '{{ bucket }}' --required
AND folder = '{{ folder }}' --required
AND ifMetagenerationMatch = '{{ ifMetagenerationMatch }}'
AND ifMetagenerationNotMatch = '{{ ifMetagenerationNotMatch }}';

Lifecycle Methods

rename

Renames a source folder to a destination folder. Only applicable to buckets with hierarchical namespace enabled.

EXEC google.storage.folders.rename 
@bucket='{{ bucket }}' --required, 
@sourceFolder='{{ sourceFolder }}' --required, 
@destinationFolder='{{ destinationFolder }}' --required, 
@ifSourceMetagenerationMatch='{{ ifSourceMetagenerationMatch }}', 
@ifSourceMetagenerationNotMatch='{{ ifSourceMetagenerationNotMatch }}';