ColdFusion and GCP Storage

Поиск

Последнее обновление 2 июн. 2023 г.

Overview

Google Cloud Storage enables the storage and retrieval of data at any time. You can use Google Cloud Storage to serve content, store data for disaster recovery and archival, and make large clusters of data available for download.

ColdFusion (2021 release) supports AWS S3 storage and Azure Blob storage. In ColdFusion (2023 release), we have extended the capabilities of multi-cloud service by adding a GCP storage service so that you can access a wide variety of cloud storage services.

Like AWS S3, GCP storage also deals with buckets and objects.

Bucket: Each project can contain multiple buckets, which are containers to store your objects. For example, you might create a photos bucket for all the image files your app generates and a separate videos bucket.
Object: An individual file, such as, an image called holiday.png.

Get started

Install gcpstorage package

To install the package gcpstorage, use one of the following methods:

ColdFusion Administrator

Navigate to ColdFusion Administrator > Package Manager.
In the section Available Packages, search for gcpstorage.
Select the package and click Install.

The installed package then gets listed in the Available Packages section.

ColdFusion Package Manager

Follow the steps below:

Navigate to <CF_HOME>/cfusion/bin. Enter the command:
1. Windows: cfpm.bat
2. Non-Windows: ./cfpm.sh
Enter the command, install gcpstorage.

Wait for the package to get installed.

Get credentials to access GCP Storage

When you interact with GCP, you specify your GCP security credentials to verify your credentials and check whether you have permission to access the resources that you are requesting.

GCP uses the security credentials to authenticate and authorize your requests.

For more information, see GCP API Keys Overview.

Add cloud service credentials and configuration

In ColdFusion, there is a method getCloudService() that gives you a handle to create objects for accessing various cloud services.

The syntax of the service handle is as follows:

service=getCloudService(cloudCred,cloudConfig), where:

cloudCred: Defines the credentials for the cloud service. It could either be a struct or a string (also known as credential alias).
cloudConfig: Defines the cloud service configuration details. It could either be a struct or a string (also known as config alias).

ColdFusion Administrator

Set credentials

In the ColdFusion Administrator, click Data & Services > Cloud Credentials.

An alias is a named representation of a cloud service and its configuration details. You can set the config alias through ColdFusion Administrator.

After entering the details, click Add Credential.

Set configuration options

In the ColdFusion Administrator, click Data & Services > Cloud Configuration.

Enter the following details, like configuration Alias, Vendor, and the name of the service.

Create the object

Once you've created the aliases for GCP credential and configuration options, you can create the object by using the getCloudService API, and include the following in your CFM.

storageObject= getCloudService("gcpCred", "gcpConf")

Application.cfc

You can specify the file containing the GCP credentials and configuration options in Application.cfc. For example,

component{
    this.name ="gcp"
      void function onApplicationStart(){
    application.gcpCred = {
        projectId : "my-project",
        credentialJsonFilePath : "path-to-creds.json"
    };
    alias.gcpConf = {
        serviceName : "STORAGE",                      
          alias : "gcpConfig",
          retrySettings : {
                   initialRetryDelay : "2s",   
                   initialRpcTimeout : "2s",   
                   maxAttempts : 5 ,    
                   maxRetryDelay : "30s", 
                   maxRpcTimeout : "30s", 
                   retryDelayMultiplier : 2 ,  
                   rpcTimeoutMultiplier : 2,  
                   totalTimeOut : "60s"
                  },
         transportOptions : {
                   connectTimeout : "5000",   
                   readTimeout : "5000"  
                   }

    };
    }
}

Create an object. Use the snippet below:

storageObject = getCloudService(application.gcpCred, application.gcpConf)

On CFM page

On a CFM page, you can specify the GCP credentials and configuration options in one of the four methods, specified below:

Credential and configuration aliases

After you've created the aliases for GCP credential and configuration options (in app.cfc or administrator) , you can use these aliases in the getCloudService handle as shown below:

Mention where the alias was created. Either in app.cfc or administrator.

<cfscript> 
  // define the credential and the configuration aliases in the ColdFusion Admin 
  storageObject=getCloudService("gcpCred","gcpConf") 
  // code below. 
  ........... 
</cfscript>

Credential alias and configuration struct

<cfscript> 
    // Using credential alias and struct for service config 
    gcpConf = { 
            "alias":"gcpConf", 
            "serviceName" : "STORAGE"
          
    } 
    storageObject= getCloudService("gcpCred", gcpConf) 
   
    // code below 
    ..................... 
</cfscript>

Configuration alias and credential struct

<cfscript> 
    // Using config alias and struct for service credentials 
    // GCP credentials 
    gcpCreds={ 
      "vendorName":"GCP", 
      "alias": "gcpCred", 
      "projectId":"1234", 
      " credentialJsonFilePath ": "file path"
    } 
    storageObject= getCloudService(gcpCreds, "gcpConf") 
    // code below 
    ..................................... 
</cfscript>

Credential and configuration structs

<cfscript> 
  // Using Structs for both cloud credential and config 
 gcpCreds={ 
      "vendorName":"GCP", 
      "alias": "gcpCred", 
      "projectId":"1234", 
      " credentialJsonFilePath ": "file path"
    }
    gcpConf = { 
            "alias":"gcpConf", 
            "serviceName" : "STORAGE", 
            "clientOverrideConfig":{ 
                "retryPolicy":{ 
                  "numRetries":4 
                } 
            }, 
            "httpClientConfig":{ 
                "maxConnections":50 
            } 
      }
  storageObject= getCloudService(gcpCreds, gcpConf) 
   
  // code below 
  ................................................................... 
</cfscript>

Add credentials and configuration using CFSetup

Add:

Cloudconfiguration: add cloudconfigutaion alias=gcp_config serviceName=STORAGE <cf_alias_name>
Cloudconfiguration: add cloudconfigutaion alias=gcp_config serviceName=STORAGE maxRpcTimeout=50s retryDelayMultiplier=5 maxAttempts=8 maxRetryDelay=40s rpcTimeoutMultiplier=3 totalTimeout=50s <cf_alias_name>
Cloudcredential: add cloudcredential vendorName=”GCP” alias=<cloudcredential_alias> projectId=<project_id> credentialJSONFilePath=<credential_JSON_File_Path> <cf_alias_name>

Show:

Cloudconfiguration: show cloudconfiguration <cf_alias_name>
Cloudcredential: show cloudconfiguration <cloudconfiguration_name>

Set:

Cloudconfiguration: set cloudconfiguration <cloudconfiguration_name> initialRetryDelay=2s initialRpcTimeout=40s maxAttempts=5 maxRetryDelay=30s maxRpcTimeout=40s retryDelayMultiplier=3 rpcTimeoutMultiplier=2 totalTimeout=40s <cf_alias_name>
Cloudcredential: set cloudcredential <cloudcredential_name> projectId=<project_id> credentialJSONFilePath=<credential_JSON_File_Path> <cf_alias_name>

Get:

Cloudconfiguration: get cloudconfiguration <cloudconfiguration_name> <cf_alias_name>
Cloudcredential: get cloudcredential <cloudcredential_name> <cf_alias_name>

APIs for storage object

Description

Create the root object. If the root does not exist, the root gets created.

Syntax

root(bucketname, createIfNotExists)

Returns

A bucket object.

Parameters

bucketName: The name of the bucket to be created.
createIfNotExists: True or False. If the bucket doesn't exist, it gets created.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	rootObj=storageService.root("bucket_test",true);
</cfscript>

Description

Get the root object with additional parameters.

Syntax

createRoot(requestParameters)

Returns

A bucket object.

Parameters

Parameter	Description	Required
name	Name of the bucket to be created.	Yes
acl	Define who has access to your buckets and objects, as well as what level of access they have. Valid values are: Reader Writer Owner For more information, see GCP Storage Access Control List.	No
defaultAcl	Set a default object, if you want to avoid setting up ACLs every time. You can change the default object ACL, and then add objects to the bucket. For more information, see Default ACLs.	No
enable	Enable versioning of the bucket. True/False.	No
requesterPays	Enable requester pays on the bucket.	No
indexPage	The URL of the page that confirms the creation of the bucket.	No
notFoundPage	The URL of the page that displays when the bucket creation is unsuccessful.	No
rules	Configure the replication setting of dual-region Cloud Storage buckets.	No
rpo	Create the bucket with replication. Valid values are: ASYNC_TURBO DEFAULT For more information, see Configure replication.	No
storageClass	Storage class of the object. Valid values are STANDARD, NEARLINE, COLDLINE, ARCHIVE. For more information, see Storage Class.	No
location	Location of the bucket to be created.	No
cors	CORS configuration of the bucket. For more information, see Configure CORS.	No
labels	The key-value pair assigned to the bucket as a unique label.	No
defaultKmsKeyName	The Cloud KMS key used to encrypt this object, if the object is encrypted by such a key.	No
defaultEventBasedHold	Whether or not the object is subject to an event-based hold.	No
retentionPeriod	The time when the bucket can be deleted, based on the retention policy.	No
iamConfiguration	Control access to your buckets and objects.	No
logging	Enable logging on the bucket.	No
customPlacementConfig	A query string parameter that lets you set or retrieve the regions that make up a dual-region bucket. For more information, see Custom placement.	No

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	createBucketStruct = {
		"name" : "bucket_test",      
		"storageClass" : "STANDARD",
		"location" : "US",
		"requesterPays" : "false", 
		"enable" : "false",
		"defaultEventBasedHold" : "false",
		"labels" : {
		    "name" : "test_bucket",
		    "owner" : "user1"
	            },
		 "retentionPeriod" : "10", 
		 "customPlacementConfig" : ["US-EAST1","US-WEST1"],
		 "iamConfiguration" : {
		        "isUniformBucketLevelAccessEnabled" : true,
		        "publicAccessPrevention" : "INHERITED"
		}
	}
	rootObj2=storageService.createRoot(createBucketStruct);
</cfscript>

Description

Create a bucket.

Syntax

bucket(bucketName,createIfNotExists)

Returns

A bucket object

Parameters

bucketName: The name of the bucket to be created.
createIfNotExists: True or False. If the bucket doesn't exist, it gets created.

EXAMPLE

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
</cfscript>

Description

Create a bucket with additional parameters.

Syntax

createBucket(requestParameters)

Returns

A bucket object.

Parameters

Parameter	Description	Required
name	Name of the bucket to be created.	Yes
acl	Define who has access to your buckets and objects, as well as what level of access they have. Valid values are: Reader Writer Owner For more information, see GCP Storage Access Control List.	No
defaultAcl	Set a default object, if you want to avoid setting up ACLs every time. You can change the default object ACL, and then add objects to the bucket. For more information, see Default ACLs.	No
enable	Enable versioning of the bucket. True/False.	No
requesterPays	Enable requester pays on the bucket.	No
indexPage	The URL of the page that confirms the creation of the bucket.	No
notFoundPage	The URL of the page that displays when the bucket creation is unsuccessful.	No
rules	Configure the replication setting of dual-region Cloud Storage buckets.	No
rpo	Create the bucket with replication. Valid values are: ASYNC_TURBO DEFAULT For more information, see Configure replication.	No
storageClass	Storage class of the object. Valid values are STANDARD, NEARLINE, COLDLINE, ARCHIVE. For more information, see Storage Class.	No
location	Location of the bucket to be created.	No
cors	CORS configuration of the bucket. For more information, see Configure CORS.	No
labels	The key-value pair assigned to the bucket as a unique label.	No
defaultKmsKeyName	The Cloud KMS key used to encrypt this object, if the object is encrypted by such a key.	No
defaultEventBasedHold	Whether or not the object is subject to an event-based hold.	No
retentionPeriod	The time when the bucket can be deleted, based on the retention policy.	No
iamConfiguration	Control access to your buckets and objects.	No
logging	Enable logging on the bucket.	No
customPlacementConfig	A query string parameter that lets you set or retrieve the regions that make up a dual-region bucket. For more information, see Custom placement.	No

Example

<cfscript >
    storageService = getCloudService(application.gcpCred, application.gcpConf)
	createBucketStruct = {
    "name": "bucket_test",
    "storageClass": "STANDARD",
    "location": "US",
    "rules": [{
        "action": {
            "type": "delete"
        },
        "condition": {
            "daysSinceNoncurrentTime": 7
        }
    }],
    "acl": [{
        "entity": {
            "project": {
                projectrole: "EDITORS",
                projectid: "101345678996"
            }
        },
        "role": "READER"
    }],
    "defaultAcl": [{
        "entity": {
            "user": "test@xyz.com"
        },
        "role": "OWNER"
    }]
}

	rootObj2 = storageService.createBucket(createBucketStruct); 
</cfscript>

Description

Retrieve a list of all buckets in a storage account.

Syntax

listAll()

Returns

A list of buckets.

Example

<cfscript>
	cred = {
		projectId : "my-gcp-project",
		credentialJsonFilePath : "File-path-creds.json"
	};
	conf = {
		serviceName : "storage"
	};
	st = getCloudService(cred, conf);
	
	arrayBuckets=st.listall()
	writeDump(arrayBuckets)
</cfscript>

Description

Retrieve a list of buckets in a storage account based on some conditions.

Syntax

listAll(requestParameters)

Returns

A list of buckets.

Parameters

Parameter	Description	Required
fields	Array of fields, like ACL, BILLING, etc.	No
pageSize	Number to denote the number of buckets to display on a page.	No
pageToken	Represents a part of the larger results to display.	No
prefix	Filter those buckets that start with the prefix.	No
userProject	Set of properties to return.Valid values are: full: Include all properties. noAcl: Omit owner, acl, and defaultObjectAcl properties.	No

Example

<cfscript>
    cred = {
		projectId : "my-gcp-project",
		credentialJsonFilePath : "File-path-creds.json"
	};
	conf = {
		serviceName : "STORAGE"
	};
	storageService = getCloudService(cred, conf);
        paramStruct={"prefix":"cfbucket","pageSize":50}
	writeDump("#storageService.listAll(paramStruct)#");	
</cfscript>

Description

Delete a bucket.

Syntax

delete(bucketName)

Returns

A struct with status.

Parameters

bucketName: The name of the bucket to be deleted.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketList=storageService.delete("bucket_test");
</cfscript>

Example- Delete with Struct

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketOption = {
		bucketName : "bucket_test",
		versions : true,
		forceDelete : {
			timeout : 60,
			unit : "SECONDS"  
		}
	}
       delresponse= storageService.delete(bucketOption)
</cfscript>

APIs for bucket object

Description

Get a list of all objects inside a bucket.

Syntax

listAll()

Returns

A struct with list of objects.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)			
	bucketList=storageService.listAll();
</cfscript>

Description

List all objects in a bucket by passing a struct.

Returns

A struct with list of objects.

Parameters

Parameter	Description
fields	Array of fields like ACL, BILLING, CORS, etc.
pageSize	Number of records to display on a page.
pageToken	Encoded field containing the name of the last item (bucket) in the returned list.
prefix	Display buckets whose names begin with this prefix.
userProject	The name of the GCP project.

Example

<cfscript >
        storageService = getCloudService(application.gcpCred, application.gcpConf)
	bucketObj = storageService.bucket("bucket_test", true);

	liststruct = {
    	    currentDirectory: true,
    	    prefix: "key",
    	    delimeter: "1",
    	    pagesize: 1,
    	    versions: true,
    	    fields: ["BUCKET", "ETAG"],
    	    userproject: "project_id",
    	    startoffset: "key23/43",
    	    endoffset: "key34"
	}

	objList1 = bucketObj.listAll(liststruct);

</cfscript>

Description

Delete an object in a bucket.

Syntax

delete(objectKey)

Returns

A struct with status.

Parameters

objectKey: The key that identifies the object.

Example

<cfscript >
    storageService = getCloudService(application.gcpCred, application.gcpConf)
	bucketObj = storageService.bucket("bucket_test", true);

	uploadStruct = {
    	"srcFile": SRC_FILE_PATH,
    	"blobInfo": {
        "blobId": {
            "name": "key123"
    	    }
    	}
	}

	uploadResponse = bucketObj.uploadFile(uploadStruct);

	delResponse = bucketObj.delete(key123);

</cfscript>

Description

Delete an object in the bucket. Use struct of request parameters in the method.

Syntax

delete(requestParameters)

Returns

A struct with status.

Parameters

Parameter	Description
bucketName	The name of the bucket to be deleted.
metaGenerationMatch	Identifies the metadata version. True if matches.
metagenerationNotMatch	True/False.
versions	The version of the object.
userProject	The name of the GCP project.
forceDelete	True/false. Forcibly delete the object.

Example

<cfscript >
    storageService = getCloudService(application.gcpCred, application.gcpConf)
	bucketObj = storageService.bucket("bucket_test", true);

	uploadStruct = {
   	 "srcFile": SRC_FILE_PATH,
    	"blobInfo": {
        "blobId": {
            "name": "key123"
        	}
    	}
	}
	uploadResponse = bucketObj.uploadFile(uploadStruct);

	deleteOptions = {
    	blobId: {
        	name: "key123",
        	generation: GENERATION_ID
    	}
	}
	delResponse = bucketObj.delete(deleteOptions); 
</cfscript>

Description

Retrieve the location of a bucket.

Syntax

getLocation()

Returns

A struct with status and location.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);			
	objLocation=bucketObj.getLocation();
</cfscript>

Description

Uploads a file to a bucket.

Syntax

UploadFile(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
srcFile	The path of the file that you want to upload in the bucket.	Yes
buffersize	The size of the buffer object.
key	Unique identifier of the object.	Yes
blobInfo	Struct of blobId: Bucket Name generation	Yes
acl	Access controls on the bucket. For more information, see this doc.	No
cacheControl	Specify the caching behavior as defined here.	No
contentDisposition	Specify the content format of the object as defined here.	No
contentEncoding	Specify the type of encoding on the object as defined here.	No
contentLanguage	The language of the object that you want to upload.	No
contentType	The HTTPS content type of the response object.	No
crc32	The crc32 hash for the object.	No
crc32HexString	The crc32 hex strimg for the object.	No
eventBasedHold	An object hold that are metadata flags on an object. For more information, see Object holds. There are two types of holds: Event-based Temporary	No
md5	The md5 checksum of the object.	No
md5HexString	The md5 hex string of the object.	No
metadata	The key value pair of the object as a struct.	No
storageClass	Storage class of the object. Valid values are STANDARD, NEARLINE, COLDLINE, ARCHIVE. For more information, see Storage Class.	No
temporaryHold	Whether to place a temporary hold on the object.	No
timestorageclassupdated	The time at which the object's storage class was last changed.	No
customtime	User-defined timestamp for the object.	No
blobWriteOption	Struct of: crc32cMatch : false/true detectContentType : false/true disableGzipContent :false/true, doesNotExist: false/true, generationMatch : false/true, gnerationNotMatch : false/true, metagenerationMatch:false/true, metagenerationNotMatch : false/true, encryptionKey:"", userProject: "" kmskeyname:""	No

Example

<cfscript>
			storageService = getCloudService(application.gcpCred,application.gcpConf)
			bucketObj=storageService.bucket("bucket_test",true);
			
			uploadRequest={
				"srcFile" : <SRC_FILE_PATH>,
				"blobInfo" : {		
							"blobId" : {
										"bucket" : "bucket_test",
										"name" : "key12"
									   },
							"crc32" : "aR2qLw==",
							"crc32HexString" : "615232714c773d3d",                   
							"eventBasedHold" : false,
							"md5" : "sQqNsWTgdUEFt6mb5y4/5Q==",
							"md5HexString" : "7351714e735754676455454674366d623579342f35513d3d",
							"metadata" : {
											"key1" : "value1"
										 },
							"storageClass" : "STANDARD",
							"temporaryHold" : "false",
							"acl" : [{
								  "entity" : {
											  "group" : GROUP_ID
											 },        
								  "role" : "READER"     
							}]
				},
				"blobWriteOption" : [{
					crc32cMatch : true,
					detectContentType : true,
					encryptionKey:"TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g=",
					userProject: "projectid"
				}]
			}
        	uploadResponse=bucketObj.uploadFile(uploadRequest);
			
</cfscript>

Description

Uploads an object to a bucket.

Syntax

uploadObject(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
object	Object to be uploaded to the bucket.	Yes
blobInfo	Struct of "blobId" : { "name" : "" }	Yes
blobWriteOption	Specify the write options of the blob.	No

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	uploadStruct = {
                "object" : serializeJSON({empName="James", age="26"}),
                "blobInfo" : {
                    "blobId" : {
                        "name" : "key123"
                    },
                    "storageClass" : "STANDARD",
                    "temporaryHold" : "false"
                }
            }
                    
        uploadResponse=bucketObj.uploadObject(uploadStruct); 
			
</cfscript>

Description

Download a file from a bucket.

Syntax

downloadToFile(structParameters)

Returns

A struct with status

Parameters

Parameter	Description	Required
destinationfilepath	The path where the file is to be downloaded.	Yes
key	When you interact with GCP, you specify your GCP security credentials to verify your credentials and check whether you have permission to access the resources that you are requesting. GCP uses the security credentials to authenticate and authorize your requests. For more information, see GCP API Keys Overview.	Yes
decryptionkey	To download an object stored in cloud storage that is encrypted with a customer-supplied decryptionkey.	No
userproject	The project id of GCP.	No
shouldreturnrawinputstream	Whether the request must return a raw input stream, instead of decompressing the data.	No

Example

<cfscript>
			storageService = getCloudService(application.gcpCred,application.gcpConf)
			bucketObj=storageService.bucket("bucket_test",true);
			
			downloadStruct = {
		        "destinationfilepath" : DESTINATION_PATH,
		        "key" : "key12",
				"decryptionkey":"TIbv/fjexq+VmtXzAlc63J4z5kFmWJ6NdAPQulQBT7g="
		    }
			downloadResponse=rootObj.downloadToFile(downloadStruct);
			
</cfscript>

Description

Download an object from the bucket.

Syntax

downloadObject(structParameters)

Returns

A struct with status and object.

Parameters

Parameter	Description	Required
blobInfo	Struct of { "blobId" : { "name" : "key-name" } }	Yes
blobSourceOption	Struct of: decryptionKey : "", generationMatch : "", generationNotMatch : "", metatGenerationMatch : "", metaGenerationNotMatch : "", shouldReturnRawInputStream : "", userProject : ""	No

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
			downloadStruct = {
                "blobInfo" : {
                    "blobId" : {
                        "name" : "key12"
                    }
                },
		blobSourceOption : [{          
                         userProject : PROJECT_ID
                           }]
            }
                    
            downloadResponse=bucketObj.downloadObject(downloadStruct); 
		
</cfscript>

Description

Update data inside a bucket.

Syntax

updateBucket(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
bucketinfo	Struct containing: enable: Whether to enable the bucket. requesterPays: Enable requester pays on the bucket. labels: The key-value pair assigned to the bucket as a unique label. indexPage: The URL of the page that confirms the creation of the bucket. notfoundPage: The URL of the page that displays when the bucket creation is unsuccessful. logging: Enable logging on the bucket. Struct of logbucket and logobjectprefix. rules: Configure the replication setting of dual-region Cloud Storage buckets. acl: Define who has access to your buckets and objects, as well as what level of access they have. Valid values are- Reader, Writer , and Owner defaultkmskeyname: The Cloud KMS key used to encrypt this object, if the object is encrypted by such a key. rpo: Create the bucket with replication. Valid values are: ASYNC_TURBO and DEFAULT. cors: CORS configuration of the bucket. iamconfiguration: Control access to your buckets and objects. defaulteventbasedhold: Whether or not the object is subject to an event-based hold. For more information, see https://cloud.google.com/storage/docs/object-holds#hold-types retentionperiod: The time when the bucket can be deleted, based on the retention policy. For nore information, see https://cloud.google.com/storage/docs/bucket-lock#retention-policy storageclass: Storage class of the object. Valid values are STANDARD, NEARLINE, COLDLINE, ARCHIVE. For more information, see https://cloud.google.com/storage/docs/storage-classes Примечание. Data retention policy for a Cloud Storage bucket that governs how long objects in the bucket must be retained. The feature also allows you to lock the data retention policy, permanently preventing the policy from being reduced or removed.	No
buckettargetOption	Struct of: userProject: The name of the GCP project. metagenerationmatch: Identifies the metadata version. True if matches. metagenerationnotmatch: True/False	No

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
		updatestruct= {
				bucketinfo:{
					"requesterPays" : "false",
					"labels" : {
					   "name" : "bucket_test",
					   "owner" : "abc"
					  }, 
					"acl" : [{
						  "entity" : {
									  "user" : "xyz@abc.com"
									 },        
						  "role" : "OWNER"     
						  }  
						]
				},
				"buckettargetOption" : {
                    "userProject": PROJECT_ID
					}
			}
				
		bucketObj.updateBucket(updatestruct);
			
</cfscript>

Description

Update object data inside a bucket.

Syntax

updateObject(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
blobInfo	Struct of: acl: Access controls on the bucket. For more information, see this doc. contentEncoding contentLanguage contentType cacheControl contentDisposition metadata eventBasedHold temporaryHold	Yes
blobTargetOption	Struct of: detectContentType disableGzipContent doesNotExist generationMatch generationNotMatch metagenerationMatch metagenerationNotMatch encryptionKey userProject kmskeyname

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
		updatestruct={
				blobinfo:{	
					"blobId" :{
						"name" : "key123"       
					 },
					"contentLanguage" : "en",
					"metadata" :{
						"owner" : "hannah",
						"case" : "1"
				    }
				},
				"blobTargetOption" : {               
					"userProject": PROJECT_ID
			    }
			}
					
		bucketObj.updateObject(updatestruct);
			
</cfscript>

Description

Adds tags to buckets.

Syntax

addTags(structParameter)

Returns

A struct with status.

Parameters

Parameter	Description	Required
key	The name of the key that identifies the tags.	Yes
tags	Struct of name and owner.	Yes

Example

<cfscript>
    cred = {
		projectId : "project-id",
		credentialJsonFilePath : "path-to-creds.json"
	};
	conf = {
		serviceName : "STORAGE"
	};
	storageService = getCloudService(cred, conf)
        createBucketStruct = {
          "name" : "b_d_009",      
          "storageClass" : "STANDARD"      
	}
        bucketObj = storageService.createBucket(createBucketStruct)
        src = "#ExpandPath('..')#/files/test.txt";
        key = "key12"
			
	uploadStruct = {
	    "srcFile" : src,
	    "key" : key
        }
	uploadResponse=bucketObj.uploadFile(uploadStruct);
	writeDump(uploadResponse)
	//break;
        addTagStruct =
	{
		"key":"key12",
		"tags": 
		{
		    "key" : "key12", 
			"tags" : {"name" : "test_bucket","owner" : "john"}
		}
	}
	tagResponse=bucketObj.addTags(addTagStruct)
	writedump(tagResponse);
</cfscript>

Description

Enable requester pay on a bucket.

Syntax

enableRequesterpay(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
bucketGetOption	A struct containing userProject.	Yes
buckettargetOption	A struct containing userProject.	Yes

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	rpstruct = {
				bucketGetOption : [{
					userProject : PROJECT_ID
				}],
				 buckettargetOption : [{
					userProject : PROJECT_ID
				 }]
			};
	bucketObj.enableRequesterPay(rpstruct);
			
</cfscript>

Description

Disable requester pay on a bucket.

Syntax

disableRequesterpay(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
bucketGetOption	A struct containing userProject.	Yes
buckettargetOption	A struct containing userProject.	Yes

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
		rpstruct = {
				bucketGetOption : [{
					userProject : PROJECT_ID
				}],
				 buckettargetOption : [{
					userProject : PROJECT_ID
				 }]
			};
				
		bucketObj.disableRequesterPay(rpstruct);
			
</cfscript>

Description

Check if requester pay is enabled on a bucket.

Syntax

getRequesterPayStatus(structParameters)

Returns

A struct with request pay status.

Parameters

Parameter	Description	Required
bucketGetOption	A struct containing userProject.	Yes
buckettargetOption	A struct containing userProject.	Yes

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	rpstruct = {
				bucketGetOption : [{
					userProject : PROJECT_ID
				}],
				 buckettargetOption : [{
					userProject : PROJECT_ID
				 }]
			};
		
	writedump(bucketObj.getRequesterPayStatus(rpstruct));
			
</cfscript>

Description

Copy objects from one bucket to the other.

Syntax

copy(requestParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
megaBytesCopiedPerChunk	The size of the object being copied per chunk.	No
source	Struct containing the name of the bucket and the name of the key	Yes
target	Struct of { "blobId" : { "name" : "key-name" } }	Yes
blobTargetOption	A struct containing the name of the project and whether the bob exists. blobTargetOption: { userProject, DoesNotExist }	No

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
		copyRequest ={
				megaBytesCopiedPerChunk : 2,
				source : {
					bucket : "source_bucket_name",
					name : "source_key"
				},
				sourceOptions :{
                    userProject : PROJECT_ID
                },
				target : {
					blobInfo: {
						blobId : {
							name : "key123"
						 }
					},
					blobTargetOption: [{
						userProject : PROJECT_ID
					}]
				}
			}
			
		bucketObj.copy(copyRequest);
			
</cfscript>

Description

Retrieve the metadata information of the object.

Syntax

getObjectMetadata(objectName)

Returns

A struct with obejct metadata.

Parameter

objectName: The name of the object.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	uploadRequest={
				"srcFile" : <SRC_FILE_PATH>,
				"blobInfo" : {		
					"blobId" : {
						"bucket" : "bucket_test",
						"name" : "key12"
					}
				}
			}
        uploadResponse=bucketObj.uploadFile(uploadRequest);
			
	writedump(bucketObj.getObjectMetadata("key12")):
			
</cfscript>

Description

Retrieve the information about the object.

Syntax

getObjectDetails(objectName)

Returns

A struct with obejct metadata.

Parameter

objectName: The name of the object.

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
		uploadRequest={
				"srcFile" : <SRC_FILE_PATH>,
				"blobInfo" : {		
					"blobId" : {
						"bucket" : "bucket_test",
						"name" : "key12"
					}
				}
			}
        	uploadResponse=bucketObj.uploadFile(uploadRequest);
			
		writedump(bucketObj.getObjectDetails("key12")):
			
</cfscript>

Description

Retrieve the metadata of the object.

Syntax

getBucketMetadata()

Returns

A struct with metadata of bucket.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	writedump(bucketObj.getBucketMetadata()):
			
</cfscript>

Description

Merge various objects to one.

Syntax

composeObject(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
addSource	Array of the keys of the objects that you want to merge.	Yes
setTarget	Struct of { "blobId" : { "name" : "key-name" } }	Yes
setTargetOptions	The name of the GCP project	No

Example

<cfscript>
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test",true);
			
		uploadStruct1 = {
                "srcFile" : src1,
				"blobInfo" : {
                    "blobId" : {
                        "name" : "key1"
                    }
				}
            }
			
		uploadStruct2 = {
                "srcFile" : src2,
				"blobInfo" : {
                    "blobId" : {
                        "name" : "key2"
                    }
				}
            }
            
            bucketObj.uploadFile(uploadStruct1);
            bucketObj.uploadFile(uploadStruct2);
			
		composeRequest = {
					addSource : ["key1","key2"],
					setTarget : {
						BlobId : {
							Name : "key12"
									}           
								 }
				}           
	    bucketObj.composeObject(composeRequest);
			
</cfscript>

Description

Protect your data in the cloud storage if you feel that objects can be inadvertently deleted or replaced.

<cfscript>
		cred = {
			projectId : "project-id",
			credentialJsonFilePath : "path-to-creds-file.json"
		};
		conf = {
			serviceName : "STORAGE"
		};
		 
		storageService = getCloudService(application.gcpCred,application.gcpConf)
		bucketObj=storageService.bucket("bucket_test_22",true);
			
		bucketObj.enableVersioning();
			
		list= bucketObj.listallversions();
			
		writedump(bucketObj.getVersioningStatus());
			
		bucketObj.suspendversioning();
			
	</cfscript>

Description

You define a lifecycle configuration on a bucket. The configuration contains a set of rules which apply to current and future objects in the bucket. When an object meets the criteria of one of the rules, Cloud Storage automatically performs a specified action on the object.

Using the SetRules method, you can add lifecycle rules on the bucket.

Syntax

setRules(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
rules	The lifecycle configuration that you want to set on a bucket. For more information, see Object Lifecycle Management.	Yes
action	Specify the action of the object. The supported values are: Delete SetStorageClass AbortIncompleteMultipartUpload	Yes
condition	The conditions which an object must meet before the action defined in the rule occurs on the object. For more information, see Lifecycle conditions.	Yes

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	rules = { rules :[{
					    "action" : {
							"type" : "delete"
						},
					    "condition" :{			
							"daysSinceNoncurrentTime": 7
						}
					},
				    {
					    "action" : {
						    "type": "SetStorageClass",
						    "storageClass": "NEARLINE"
						},
					    "condition" : {
							"age" : 11,
							"matchesPrefix" : ["blob","delete"],
							"matchesSuffix" : ["test","edu"]
						}
				  }]}
			
		bucketObj.setRules(rules);
			
</cfscript>

Description

Remove lifecycle rules from an object.

Syntax

deleteRules()

Returns

A struct with status.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	bucketObj.deleteRules();
</cfscript>

Description

Retrieve the lifecycle rules of an object.

Syntax

getRules()

Returns

A struct with rules and status.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);
			
	writedump(bucketObj.getRules());
</cfscript>

Description

Add policies on a bucket. For more information on Identity and Access Management, see IAM.

Syntax

setIamPolicy(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
addIdentity	Struct of: { role : <>, identity : [{<identity_Type> : <identity_Value>} ] }	No
removeIdentity	Struct of: { role : <>, identity : [{<identity_Type> : <identity_Value>} ] }	No
bindings	A connection between principals who have a role, which has a set of permissions, and that position.	No
etag	HTTP 1.1 Entity tag for the policy.	No
version	The IAM policy version.	No

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);

	addMemberRequest ={
        addIdentity : {
            Identity: [{"user":"mukumar@adobe.com"}],role: "roles/storage.objectViewer" 
            }                 
        }
	writedump(bucketObj.setIamPolicy(addMemberRequest));
	writeDump(bucketObj.getIamPolicy())
</cfscript>

Description

Retrieve the IAM policies that were applied to a bucket.

Syntax

getIamPolicies()

Returns

A struct with status.

Example

<cfscript>
	storageService = getCloudService(application.gcpCred,application.gcpConf)
	bucketObj=storageService.bucket("bucket_test",true);

	addMemberRequest ={
        addIdentity : {
            Identity: [{"user":"mukumar@adobe.com"}],role: "roles/storage.objectViewer" 
            }                 
        }
	writedump(bucketObj.setIamPolicy(addMemberRequest));
	writeDump(bucketObj.getIamPolicy())
</cfscript>

Description

Generates a URL to get an object.

Syntax

signUrl(structParameters)

Returns

A struct with status.

Parameters

Parameter	Description	Required
key	The key to identify the object in the bucket.	No
duration	The duration that the signed URL should be valid for	No
timeUnit	The time unit for the duration.	No
httpMethod	The HTTP method to use with the signed URL. The default is GET.	No
version	The version of the object.	No
signer	The service account signer to sign the URL.	No
withBucketBoundHostname	A bucket-bound hostname. For more information, see this doc.	No
withContentType	Specify if the signature should include the blob's content-type.	No
withExtHeaders	Specify if the signature should contain the blob’s headers.	No
hostName	The host name to be used for the bucket.	No
withMd5	Specify if the signature must include the blob's md5.	No
withPathStyle	Generate a path-style URL.	No
queryParams	Specify if the URL must contain additional query parameters.	No
signatureVersion	Use the version of the signature, v2 or v4.	No
withVirtualHostedStyle	Use a virtual hosted-style hostname.	No

Example

<cfscript>
    storageService = getCloudService(application.gcpCred,application.gcpConf)
    bucketObj = storageService.bucket("<bucketName>");
    // Generate a V4-signed URL to download an object.   
    signUrlOption = {
        key : "<objectName>",
        duration : 15,
        timeUnit : "MINUTES",
        signatureVersion : "V4"
    }
    writedump(bucketObj.signUrl(signUrlOption));
    // Generate a PUT-signed URL that is used to upload an object.
    signUrlOption = {
        key : "abc.txt",
        duration : 15,
        timeUnit : "MINUTES",
        httpMethod : "PUT",
        withExtHeaders : {
            "Content-Type": "application/octet-stream"
        },
        signatureVersion : "V4"
    }
    writedump(bucketObj.signUrl(signUrlOption))
</cfscript>