GCP Storage Bucket binding spec

Detailed documentation on the GCP Storage Bucket binding component

Component format

To setup GCP Storage Bucket binding create a component of type bindings.gcp.bucket. See this guide on how to create and apply a binding configuration.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5. spec:
  6.   type: bindings.gcp.bucket
  7.   version: v1
  8.   metadata:
  9.   - name: bucket
  10.     value: "mybucket"
  11.   - name: type
  12.     value: "service_account"
  13.   - name: project_id
  14.     value: "project_111"
  15.   - name: private_key_id
  16.     value: "*************"
  17.   - name: client_email
  18.     value: "name@domain.com"
  19.   - name: client_id
  20.     value: "1111111111111111"
  21.   - name: auth_uri
  22.     value: "https://accounts.google.com/o/oauth2/auth"
  23.   - name: token_uri
  24.     value: "https://oauth2.googleapis.com/token"
  25.   - name: auth_provider_x509_cert_url
  26.     value: "https://www.googleapis.com/oauth2/v1/certs"
  27.   - name: client_x509_cert_url
  28.     value: "https://www.googleapis.com/robot/v1/metadata/x509/<project-name>.iam.gserviceaccount.com"
  29.   - name: private_key
  30.     value: "PRIVATE KEY"
  31.   - name: decodeBase64
  32.     value: "<bool>"
  33.   - name: encodeBase64
  34.     value: "<bool>"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

FieldRequiredBinding supportDetailsExample
bucketYOutputThe bucket name“mybucket”
typeYOutputTge GCP credentials type“service_account”
project_idYOutputGCP project idprojectId
private_key_idYOutputGCP private key id“privateKeyId”
private_keyYOutputGCP credentials private key. Replace with x509 cert12345-12345
client_emailYOutputGCP client email“client@email.com”
client_idYOutputGCP client id0123456789-0123456789
auth_uriYOutputGoogle account OAuth endpointhttps://accounts.google.com/o/oauth2/auth
token_uriYOutputGoogle account token urihttps://oauth2.googleapis.com/token
auth_provider_x509_cert_urlYOutputGCP credentials cert urlhttps://www.googleapis.com/oauth2/v1/certs
client_x509_cert_urlYOutputGCP credentials project x509 cert urlhttps://www.googleapis.com/robot/v1/metadata/x509/<PROJECT_NAME>.iam.gserviceaccount.com
decodeBase64NOutputConfiguration to decode base64 file content before saving to bucket storage. (In case of saving a file with binary content). true is the only allowed positive value. Other positive variations like “True”, “1” are not acceptable. Defaults to falsetrue, false
encodeBase64NOutputConfiguration to encode base64 file content before return the content. (In case of opening a file with binary content). true is the only allowed positive value. Other positive variations like “True”, “1” are not acceptable. Defaults to falsetrue, false

Binding support

This component supports output binding with the following operations:

Create file

To perform a create operation, invoke the GCP Storage Bucket binding with a POST method and the following JSON body:

Note: by default, a random UUID is generated. See below for Metadata support to set the name

  1. {
  2.   "operation": "create",
  3.   "data": "YOUR_CONTENT"
  4. }

The metadata parameters are:

  • key - (optional) the name of the object
  • decodeBase64 - (optional) configuration to decode base64 file content before saving to storage

示例

Save text to a random generated UUID file

On Windows, utilize cmd prompt (PowerShell has different escaping mechanism)

  1. curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\" }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "create", "data": "Hello World" }' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
Save text to a specific file
  1. curl -d "{ \"operation\": \"create\", \"data\": \"Hello World\", \"metadata\": { \"key\": \"my-test-file.txt\" } }" \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "create", "data": "Hello World", "metadata": { "key": "my-test-file.txt" } }' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
Upload a file

To upload a file, pass the file contents as the data payload; you may want to encode this in e.g. Base64 for binary content.

Then you can upload it as you would normally:

  1. curl -d "{ \"operation\": \"create\", \"data\": \"(YOUR_FILE_CONTENTS)\", \"metadata\": { \"key\": \"my-test-file.jpg\" } }" http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "create", "data": "$(cat my-test-file.jpg)", "metadata": { "key": "my-test-file.jpg" } }' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

The response body will contain the following JSON:

  1. {
  2.     "objectURL":"https://storage.googleapis.com/<your bucket>/<key>",
  3. }

Get object

To perform a get file operation, invoke the GCP bucket binding with a POST method and the following JSON body:

  1. {
  2.   "operation": "get",
  3.   "metadata": {
  4.     "key": "my-test-file.txt"
  5.   }
  6. }

The metadata parameters are:

  • key - the name of the object
  • encodeBase64 - (optional) configuration to encode base64 file content before return the content.

Example

  1. curl -d '{ \"operation\": \"get\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "get", "metadata": { "key": "my-test-file.txt" }}' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

The response body contains the value stored in the object.

Delete object

To perform a delete object operation, invoke the GCP bucket binding with a POST method and the following JSON body:

  1. {
  2.   "operation": "delete",
  3.   "metadata": {
  4.     "key": "my-test-file.txt"
  5.   }
  6. }

The metadata parameters are:

  • key - the name of the object

示例

Delete object
  1. curl -d '{ \"operation\": \"delete\", \"metadata\": { \"key\": \"my-test-file.txt\" }}' http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "delete", "metadata": { "key": "my-test-file.txt" }}' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Response

An HTTP 204 (No Content) and empty body will be retuned if successful.

List objects

To perform a list object operation, invoke the S3 binding with a POST method and the following JSON body:

  1. {
  2.   "operation": "list",
  3.   "data": {
  4.     "maxResults": 10,
  5.     "prefix": "file",
  6.     "delimiter": "i0FvxAn2EOEL6"
  7.   }
  8. }

The data parameters are:

  • maxResults - (optional) sets the maximum number of keys returned in the response. By default the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
  • prefix - (optional) it can be used to filter objects starting with prefix.
  • delimiter - (optional) it can be used to restrict the results to only the kobjects in the given “directory”. Without the delimiter, the entire tree under the prefix is returned

Response

The response body contains the list of found objects.

The list of objects will be returned as JSON array in the following form:

  1. [
  2.     {
  3.         "Bucket": "<your bucket>",
  4.         "Name": "02WGzEdsUWNlQ",
  5.         "ContentType": "image/png",
  6.         "ContentLanguage": "",
  7.         "CacheControl": "",
  8.         "EventBasedHold": false,
  9.         "TemporaryHold": false,
  10.         "RetentionExpirationTime": "0001-01-01T00:00:00Z",
  11.         "ACL": null,
  12.         "PredefinedACL": "",
  13.         "Owner": "",
  14.         "Size": 5187,
  15.         "ContentEncoding": "",
  16.         "ContentDisposition": "",
  17.         "MD5": "aQdLBCYV0BxA51jUaxc3pQ==",
  18.         "CRC32C": 1058633505,
  19.         "MediaLink": "https://storage.googleapis.com/download/storage/v1/b/<your bucket>/o/02WGzEdsUWNlQ?generation=1631553155678071&alt=media",
  20.         "Metadata": null,
  21.         "Generation": 1631553155678071,
  22.         "Metageneration": 1,
  23.         "StorageClass": "STANDARD",
  24.         "Created": "2021-09-13T17:12:35.679Z",
  25.         "Deleted": "0001-01-01T00:00:00Z",
  26.         "Updated": "2021-09-13T17:12:35.679Z",
  27.         "CustomerKeySHA256": "",
  28.         "KMSKeyName": "",
  29.         "Prefix": "",
  30.         "Etag": "CPf+mpK5/PICEAE="
  31.     }
  32. ]