Google Cloud Storage Objects Connector

Google Cloud Storage Objects Connector: Allows to store, search, download, and delete objects in Google Cloud.

Properties

Operation

Defines the operation executed by the adapter

Possible values:

Search: Searches for information (buckets or objects) in the Google Cloud Storage
Required parameters: bucketName, objectName
Upload: Uploads or creates buckets and objects to the Google Cloud Storage
Required parameters: bucketName, objectName, bucketRegion, storageClass, fileLocation, contentType
Download: Downloads an object from the Google Cloud Storage
Required parameters: bucketName, objectName
Delete: Deletes a bucket or an object in the Google Cloud Storage
Required parameters: bucketName, objectName
CopyObject: Copies an Object from a bucket to another one. There are several possibilities to copy objects:
Required parameters: bucketName, objectName
- Copy object within a bucket and change its name.
  Required parameters: targetObjectName
- Copy object into another bucket and change its name.
  Required parameters: targetObjectName, targetBucketName
- Copy object into another bucket and remain its name.
  Required parameters: targetBucketName
MoveOrRenameBucket. Moves or renames a whole bucket.
Required parameters: bucketName, targetBucketName, targetBucketRegion
- If target bucket name already exists, the output is an error.
- If any object in target bucket already exists and overwrite option is checked, existing objects are overwritten. If overwrite option is unchecked, output is an error.
Since a bucket can be moved to another geographic region, you must be aware of the limitations associated with moving it to other geographic regions. More information on bucket locations.
MoveOrRenameObject: Moves or renames an object
Required parameters: bucketName, objectName, targetBucketName, targetObjectName

If the object already exists in target bucket and overwrite option is checked, existing object is overwritten. If overwrite option is unchecked, output is an error.
UpdateObjectStorageClass: Changes storageClass related with object. Property storageClass is closely related with bucket region. For example, when creating a bucket the region must be specified.
Required parameters: bucketName, objectName, storageClass

Not all possible values are allowed for every object/bucket. It depends on bucket specifications and object itself. More information on storage classes.
A regional bucket can only store regional objects. In this case, storageClass can only be changed in nearline or coldline.
A multi-regional bucket can only store multi-regional objects. In this case storageClass can only be changed in nearline or coldline.
Possible values:
- Object is stored in regional or multi-regional bucket: coldline, nearline
- Object is stored in nearline bucket and bucket region is regional or multi-regional: coldline, regional. If bucket region is not regional or multi-regional: only coldline
- Object is stored in coldline bucket and bucket region is regional or multi-regional: nearline, regional. If bucket region is not regional or multi-regional: only nearline
If a regional region is specified, e.g. europe-west1, it is implicitly specified that default storageClass is regional, nearline or coldline, but never multi-regional.
Same happens if a multi-regional region is specified, e.g. us: It is implicitly specified that default storageClass is multi-regional, nearline or coldline, but never regional.
AddGrantsPermission: Adds an ACL permission to an object or a bucket. If the object or bucket already has a ACL permission, nothing happens.
Required parameters:
- For this operation parameters permissionEntity, permissionRole, permissionName and, if set, PermissionProjectRole are required.
- Add permission to an object: objectName and bucketName
- Add permission to a bucket: bucketName
If a new permission is added to a bucket, the bucket gets the permission, but not the objects inside. This means that anyone can see a public bucket and the list of its objects, but can't get access to any of the objects. An extra permission is required for this.
RevokeGrantsPermission: Removes an ACL permission from an object or bucket. If the object or bucket has no ACL permission, nothing happens.
Required parameters:
- For this operation parameters permissionEntity, permissionRole, permissionName and, if set, permissionProjectRole are required.
- Remove permission from object: objectName and bucketName
- Remove permission from bucket: bucketName

Parameters

`Adapter`	Adapter main class (do not change!) Possible values: de.softproject.integration.adapter.google.cloud.storage.GoogleCloudStorageObjectAdapter: Main class (default)
`serviceAccountFile`	Path to the JSON file containing the service account key to authenticate to the Google Cloud Storage Possible values: System path, e. g. `C:\X4\V_5.9\Server\X4DB\1\ExampleProcess\GoogleCloud\Config\serviceAccountFile.json` X4db url, e. g. `x4db://1/ExampleProcess/GoogleCloud/Config/serviceAccountFile.json` Xstore url, e. g. `xstore://ExampleProcess/GoogleCloud/Config/serviceAccountFile.json`
`bucketName`	Name of the bucket where a set of objects are organized Possible values: String containing the name Bucket names must meet the following naming rules: Bucket names must contain only lowercase letters, numbers, dashes (`-`), underscores (`_`), and dots (`.`). Names containing dots require verification. Bucket names must start and end with a number or a letter. Bucket names must contain 3 to 63 characters. Names containing dots can contain up to 222 characters, but each dot-separated component can't be longer than 63 characters. Bucket names cannot be represented as an IP address in dotted-decimal notation (e. g. 192.168.5.4). Bucket names cannot begin with the `goog` prefix. Bucket names cannot contain `google` or close misspellings, such as `g00gle`.
`targetBucketName`	Optional. Name of the target bucket. For operations that copy/move/rename a bucket. This parameter has the same restrictions as parameter `bucketName`.
`bucketRegion`	Region where the buckets are defined Possible values: String containing the region Example: Regional location: `europe-west3` (Europe, Frankfurt) Multi-regional location: `eu` (data centers in the European Union)
`targetBucketRegion`	Name of the target bucket's region. For operations that move/rename a bucket and where a target region can be specified. This parameter has the same restrictions as parameter `bucketRegion`.
`storageClass`	Storage class of the bucket and the objects. This parameter is closely related with regions, since a storageClass value can only be assigned to a bucket or object that is related with the choosen `bucketRegion` parameter value. Possible values: Combo with following values `multi_regional` `regional` `nearline` `coldline`
`objectName`	Name of the object. Required for operations `AddGrantsPermission` and `RevokeGrantsPermission`. Possible values: String containing the name Object names must meet the following naming rules: Object names can contain any sequence of valid Unicode characters with a length between 1-1024 bytes, if they are UTF-8 encoded. Object names cannot contain carriage return or line feed characters. Object names cannot start with `.well-known/acme-challenge`. Objects cannot be named `.` or `..`. Examples: `document` `folder/subfolder/document` `document.txt`
`targetObjectName`	For operations that copy/move/rename an object. This parameter has the same restrictions as parameter `objectName`.
`fileLocation`	Path of the file to be uploaded to the Google Cloud Account; This parameter is only valid for the `Upload` operation Possible values: System path, e. g. `C:\X4\V_5.9\Server\X4DB\1\ExampleProcess\GoogleCloudStorageObject/Data/TextDocument.txt` X4db path, e. g. `x4db://1/ExampleProcess/GoogleCloudStorageObject/Data/TextDocument.txt` Xstore path, e. g. `xstore://ExampleProcess/GoogleCloudStorageObject/Data/TextDocument.txt`
`contentType`	Content type of the object to be uploaded Possible values: String containing a valid mime-type for the object to be uploaded, e. g. `text/plain` , `application/xml` etc.
`overwrite`	Indicates if during an operation that moves/copies/renames a bucket or object, buckets or objects with the same name are overwritten. If this option is unchecked and objects/buckets with the same name exist at the target location, the output contains an error. Possible values: `checked` : Existing objects/buckets are overwritten. `unchecked` : Existing objects/buckets are not overwritten, output contains an error.
`permissionEntity`	Type of ACL permission that is created. Possible values: Combo with following values `Project`: Specifies a permission based on a list of project members. Parameter `permissionProjectRole` must be provided to specify from which sublist the members should be selected. `User`: Specifies a permission based on a specific email address, a "public access" permission or access for all Google accounts. `Domain`: Specifies a permission based on a internet domain name thas is associated with G Suite or Cloud Identity. `Group`: Specifies a permission based on a group of Google users. Uses a specific email address that is related to a Google group.
`permissionRole`	Specifies if the permission grants read or write access. Possible values: Combo with following values `READER`: Read access for object/bucket `WRITER`: Read and write access for object/bucket `OWNER`: Managing of object/bucket. Contains access rights of `WRITER`.
`permissionName`	Specifies a specific value that is used in every type of permission. Possible values: depending on the value of `permissionEntity` `permissionEntity="Project"`: Project number. Creates a permission for `OWNERS`, `EDITORS` and `VIEWERS` that are related with this project. `permissionEntity="User"`: `allUsers`: Creates a public permission. `allAuthenticatedUsers`: Creates a permisson for all Google accounts. `<email address>`: Creates a permission for the user registered with this email address. `permissionEntity="Domain"`: `<USERNAME>@<YOUR_DOMAIN>.com`: Creates a permission for owners of a email address that is related to a specific internet domain name. `permissionEntity="Group"`: Email address of a Google group. Creates a permission for all members of this Google group. More information on Google groups.
`permissionProjectRole`	Parameter affects parameters `permissionName` and `permissionEntity` if `permissionEntity="Project"`. Possible values: Combo with following values `OWNERS` `EDITORS` `VIEWERS`

Status values

`1`	The adapter operation was executed successfully
`-1`	An error occurred during the adapter's execution
`0`	Operation `Upload`: the object to be uploaded already exists Operation `Download`: the object to be downloaded doesn't exist Operation `Delete`: the object or bucket to be deleted doesn't exists

Input

For some operations the adapter expects any input document (binary document or a base64 document).

Operation Upload : If the parameter fileLocation is specified, an input document is not required. Otherwise an input is required.
All other operations don't require an input document.

Output

The adapter returns different kind of documents depending on the executed operation:

Operation Upload :
- If the adapter operation was executed successfully (status 1), the adapter returns the input document.
- If an error occurred during the adapter's execution (status -1), the output will be a new document with the error details.
- If the object to be uploaded already exists (status 0), the output corresponds to the input document.

Operation Search:

If the adapter operation was executed successfully (status 1), the adapter returns an XML document with all buckets and theirs objects:

Sample output for the operation Search

XML

<?xml version="1.0" encoding="UTF-8"
<ListObjects>
    <Bucket name="first_bucket">
		<Object contentType="text/plain">example/first_blob</Object>
<Object contentType="text/plain">file.xml</Object>
		<Object contentType="application/x-www-form-urlencoded;charset=UTF-8">newFolder</Object>
		<Object contentType="text/xml">newFolder/xml1 (1).xml</Object>
<Object contentType="text/plain">new_object</Object>
<Object contentType="application/x-www-form-urlencoded;charset=UTF-8">otherFolder</Object
	</Bucket>
    <Bucket name="second_bucket">
		<Object contentType="text/plain">text/Hello</Object>
	</Bucket>
	<Bucket name="x4_upload_test_bucket">
		<Object contentType="image/png">Logo.png</Object>
		<Object contentType="application/xml">inputDocumentX4db.xml</Object>
		<Object contentType="text/plain>testUploadProcess/Input/textFile</Object>
<Object contentType="application/xml">testUploadProcess/Input/xmlFile.xml</Object>
		<Object>wordDocument2</Object>
		<Object contentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document>wordDocumentFromLocationFile</Object
	</Bucket>
</ListObjects>

If an error occurred during the adapter's execution (status -1), the output will be a new document with the error details.

Operation Download:
- If the adapter operation was executed successfully (status 1), the output document is the downloaded object (text, XML, binary doc etc.).
- If an error occurred during the adapter's execution (status -1), the output will be a new document with the error details.
- If the blob or container don’t exist (status 0), the output corresponds to the input document.
Operation Delete:
- If the adapter operation was executed successfully (status 1), the output corresponds to the input document.
- If an error occurred during the adapter's execution (status -1), the output corresponds to the input document.
- If the bucket or object to be deleted don't exist (status 0), the output corresponds to the input document.
Operation CopyObject, MoveOrRenameBucket, MoveOrRenameObject, UpdateObjectStorageClass:
- No output for regular execution. If the operation cannot be executed, the output contains an error.