This page describes how to use HTML forms, which allow your users to upload files to your bucket. When you create an HTML form, it's recommended that you create a [policy document](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt#policy-document), which defines conditions that upload requests must meet. HTML forms utilize the XML object `POST` API. The uploaded object replaces any existing object with the same name. For tips on uploading to Cloud Storage, see [best practices](https://docs.cloud.google.com/storage/docs/best-practices.md.txt#uploading). For information about `POST` object requests using the legacy signing process, see [POST Object with the V2 signing process](https://docs.cloud.google.com/storage/docs/xml-api/post-object-v2.md.txt). > [!NOTE] > **Note:** [Signatures](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt) are used in HTML forms that have an associated policy document. HTML forms do not support [signed URLs](https://docs.cloud.google.com/storage/docs/access-control/signed-urls.md.txt). ## Query string parameters This request does not include query string parameters. ## Form fields You can create an HTML form by defining the form fields described below. | Field | Description | Required | |---|---|---| | `acl` | The predefined ACL that you want to apply to the object that is being uploaded. If you do not specify this field the bucket's `default` ACL is applied. | No | | `bucket` | The name of the bucket that you want to upload to. If you include this field, it must match the bucket name you specify in the `action` attribute. | No | | [` Cache-Control`](https://docs.cloud.google.com/storage/docs/xml-api/reference-headers.md.txt#cachecontrol) | The cache control for the object. You can only set cache control for an object that is accessible to all users. For instance, an object's ACL must be `public-read` or `public-read-write` to be able to set the cache-control. | No | | [`Content-Disposition`](https://docs.cloud.google.com/storage/docs/xml-api/reference-headers.md.txt#contentdisposition) | Specifies how the object data should be transmitted. For example, a `Content-Disposition` value of `inline` means that the object should be displayed immediately. | No | | [`Content-Encoding`](https://docs.cloud.google.com/storage/docs/xml-api/reference-headers.md.txt#contentencoding) | The compression algorithm for the object, such as `gzip`. | No | | [`Content-Length`](https://docs.cloud.google.com/storage/docs/xml-api/reference-headers.md.txt#contentlength) | The size of the uploaded file, in bytes. | No | | [`Content-Type`](https://docs.cloud.google.com/storage/docs/xml-api/reference-headers.md.txt#contenttype) | The MIME type of the file you are uploading via the form. If you do not specify a content type, the Cloud Storage system defaults to [`application/octet-stream`](https://datatracker.ietf.org/doc/html/rfc2046#section-4.5.1) when it serves the content. | No | | `Expires` | An [ISO8601 timestamp](http://www.w3.org/TR/NOTE-datetime) that specifies the date and time before an object is considered stale by the browser. | No | | `file` | The file you are uploading. Must be the last field in the form. You can upload only one object per request. | Yes | | `key` | The [name of the object](https://docs.cloud.google.com/storage/docs/objects.md.txt#naming) that you are uploading. You can also use the ${filename} variable if a user is providing a file name. | Yes | | `policy` | The security policy that describes what can and cannot be uploaded in the form. The policy document must be Base64 encoded. See [policy documents](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt#policy-document) for more information. *If you do not provide a security policy, requests are considered to be anonymous and will only work with buckets that have granted `WRITE` or `FULL_CONTROL` permission to anonymous users.* | No | | `success_action_redirect` | A URL that users are redirected to when an upload is successful. If you do not provide a URL, Cloud Storage responds with the status code that you specified in `success_action_status`. | No | | `success_action_status` | The status code that you want Cloud Storage to respond with when an upload is successful. The default is 204, but you can change this to 200 or 201. If you choose 200 or 204, Cloud Storage returns an empty document with those status codes. If you choose 201, Cloud Storage returns an XML document with the elements that are described in Response Body Elements. | No | | `x-goog-algorithm` | The signing algorithm used to create the [signature](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt) associated with your policy document. Possible values are `GOOG4-HMAC-SHA256` and `GOOG4-RSA-SHA256` | Only if you specify a `policy` | | `x-goog-credential` | The credentials used to create the [signature](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt) associated with your policy document. `x-goog-credential` has the form `AccessKeyId/CredentialScope`, where: - `AccessKeyId` is the email address of the entity responsible for creating the signature. This entity is typically a [service account](https://docs.cloud.google.com/iam/docs/service-accounts), but may also be a user account. - `CredentialScope` is the [credential scope](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt#credential-scope) used in the signature. | Only if you specify a `policy` | | `x-goog-custom-time` | A user-specified date and time in the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format `YYYY-MM-DD'T'HH:MM:SS.SS'Z'`. | No | | `x-goog-date` | The current date, in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) basic format `YYYYMMDD'T'HHMMSS'Z'`. | Only if you specify a `policy` | | `x-goog-signature` | The [signature](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt) associated with your policy document. | Only if you specify a `policy` | | `x-goog-meta-*` | A field for custom metadata. You can use this to specify any additional metadata that is not provided by the other form fields. For example, `x-goog-meta-reviewer: jane` or `x-goog-meta-project-manager: john` is custom metadata. | No |
## Response body elements The following response body elements are returned in an XML document only if you set `success_action_status` to 201. | Element | Description | |---|---| | `Bucket` | Bucket in which the object was stored. | | `ETag` | [HTTP 1.1 entity tag](https://datatracker.ietf.org/doc/html/rfc7232#section-2.3) for the object. | | `Key` | The object's name. | | `Location` | The URI for the object. | ## Example of how to create an HTML form The following example shows you how to create an HTML form to upload an object, using a signature that's created with the V4 policy signing process. The form must be UTF-8 encoded. You can specify form encoding in the form's HTML `head` tag or by using the `Content-Type` request header. Your `form` tag must specify the following three items: - An action. The `action` attribute specifies an XML API [request endpoint](https://docs.cloud.google.com/storage/docs/request-endpoints.md.txt#xml-api). Valid endpoints include `https://BUCKET_NAME.storage.googleapis.com`, `https://storage.googleapis.com/BUCKET_NAME`, and [`CNAME` redirects](https://docs.cloud.google.com/storage/docs/request-endpoints.md.txt#cname). - A method. The `method` attribute specifies the method that you are using to submit the form. It must be `post`. - An enclosure type. The `enctype` attribute specifies the enclosure type you are using and must always be `multipart/form-data`. The following is an example HTML form, which uses a [policy document](https://docs.cloud.google.com/storage/docs/authentication/signatures.md.txt#policy-document) that's specified by the `policy` form field. ### HTML ```html
``` ### Client libraries ### C++ For more information, see the [Cloud Storage C++ API reference documentation](https://docs.cloud.google.com/cpp/docs/reference/storage/latest). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```c++ namespace gcs = ::google::cloud::storage; using ::google::cloud::StatusOr; [](gcs::Client client, std::string const& bucket_name, std::string const& object_name, std::string const& signing_account) { auto document = client.GenerateSignedPostPolicyV4( gcs::PolicyDocumentV4{ bucket_name, object_name, /*expiration=*/std::chrono::minutes(10), }, gcs::AddExtensionFieldOption("x-goog-meta-test", "data"), gcs::SigningAccount(signing_account)); if (!document) throw std::move(document).status(); // Create the HTML form for the computed policy. std::ostringstream os; os << "
\n"; for (auto const& field : document->required_form_fields) { os << " \n"; } os << "
\n" << "
\n" << "
"; std::cout << "A sample HTML form:\n" << os.str() << "\n"; } ``` ### C# For more information, see the [Cloud Storage C# API reference documentation](https://cloud.google.com/dotnet/docs/reference/Google.Cloud.Storage.V1/latest). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```c# // Create a signed post policy which can be used to upload a specific object and // expires in 1 hour after creation. UrlSigner urlSigner = UrlSigner.FromCredential(credential); UrlSigner.Options options = UrlSigner.Options .FromDuration(TimeSpan.FromHours(1)) .WithSigningVersion(SigningVersion.V4) .WithScheme("https"); UrlSigner.PostPolicy postPolicy = UrlSigner.PostPolicy.ForBucketAndKey(bucketName, objectName); postPolicy.SetCustomField(UrlSigner.PostPolicyCustomElement.GoogleMetadata, "x-goog-meta-test", "data"); UrlSigner.SignedPostPolicy signedPostPolicy = await urlSigner.SignAsync(postPolicy, options); // Create an HTML form including all the fields in the signed post policy. StringBuilder form = new StringBuilder(); form.AppendLine($"
"); foreach (var field in signedPostPolicy.Fields) { form.AppendLine($""); } // Include the file element. It should always be the last element in the form. form.AppendLine(""); form.AppendLine(""); form.AppendLine("
"); // You can now save the form to file and serve it as static content // or send it as the response to a request made to your application. File.WriteAllText("PostPolicySimple.html", form.ToString()); ``` ### Java For more information, see the [Cloud Storage Java API reference documentation](https://cloud.google.com/java/docs/reference/google-cloud-storage/latest/overview). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```java import com.google.cloud.storage.BlobInfo; import com.google.cloud.storage.PostPolicyV4; import com.google.cloud.storage.Storage; import com.google.cloud.storage.StorageOptions; import java.util.Map; import java.util.concurrent.TimeUnit; public class GenerateSignedPostPolicyV4 { /** * Generating a signed POST policy requires Credentials which implement ServiceAccountSigner. * These can be set explicitly using the Storage.PostPolicyV4Option.signWith(ServiceAccountSigner) * option. If you don't, you could also pass a service account signer to StorageOptions, i.e. * StorageOptions().newBuilder().setCredentials(ServiceAccountSignerCredentials). In this example, * neither of these options are used, which means the following code only works when the * credentials are defined via the environment variable GOOGLE_APPLICATION_CREDENTIALS, and those * credentials are authorized to sign a policy. See the documentation for * Storage.generateSignedPostPolicyV4 for more details. */ public static void generateSignedPostPolicyV4( String projectId, String bucketName, String blobName) { // The ID of your GCP project // String projectId = "your-project-id"; // The ID of the GCS bucket to upload to // String bucketName = "your-bucket-name" // The name to give the object uploaded to GCS // String blobName = "your-object-name" Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService(); PostPolicyV4.PostFieldsV4 fields = PostPolicyV4.PostFieldsV4.newBuilder().setCustomMetadataField("test", "data").build(); PostPolicyV4 policy = storage.generateSignedPostPolicyV4( BlobInfo.newBuilder(bucketName, blobName).build(), 10, TimeUnit.MINUTES, fields); StringBuilder htmlForm = new StringBuilder( "
\n"); for (Map.Entry entry : policy.getFields().entrySet()) { htmlForm.append( " \n"); } htmlForm.append("
\n"); htmlForm.append("
\n"); htmlForm.append("\n"); System.out.println( "You can use the following HTML form to upload an object to bucket " + bucketName + " for the next ten minutes:"); System.out.println(htmlForm.toString()); } } ``` ### Go For more information, see the [Cloud Storage Go API reference documentation](https://pkg.go.dev/cloud.google.com/go/storage). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```go import ( "context" "fmt" "html/template" "io" "time" "cloud.google.com/go/storage" ) // form is a template for an HTML form that will use the data from the signed // post policy. var form = `
{{- range $name, $value := .Fields }} {{- end }}

` var tmpl = template.Must(template.New("policyV4").Parse(form)) // generateSignedPostPolicyV4 generates a signed post policy. func generateSignedPostPolicyV4(w io.Writer, bucket, object string) (*storage.PostPolicyV4, error) { // bucket := "bucket-name" // object := "object-name" ctx := context.Background() client, err := storage.NewClient(ctx) if err != nil { return nil, fmt.Errorf("storage.NewClient: %w", err) } defer client.Close() metadata := map[string]string{ "x-goog-meta-test": "data", } // Generating a signed POST policy requires credentials authorized to sign a URL. // You can pass these in through PostPolicyV4Options with one of the following options: // a. a Google service account private key, obtainable from the Google Developers Console // b. a Google Access ID with iam.serviceAccounts.signBlob permissions // c. a SignBytes function implementing custom signing // In this example, none of these options are used, which means the // GenerateSignedPostPolicyV4 function attempts to use the same authentication // that was used to instantiate the Storage client. This authentication must // include a private key or have iam.serviceAccounts.signBlob permissions. opts := &storage.PostPolicyV4Options{ Expires: time.Now().Add(10 * time.Minute), Fields: &storage.PolicyV4Fields{ Metadata: metadata, }, } policy, err := client.Bucket(bucket).GenerateSignedPostPolicyV4(object, opts) if err != nil { return nil, fmt.Errorf("storage.GenerateSignedPostPolicyV4: %w", err) } // Generate the form, using the data from the policy. if err = tmpl.Execute(w, policy); err != nil { return policy, fmt.Errorf("executing template: %w", err) } return policy, nil } ``` ### Node.js For more information, see the [Cloud Storage Node.js API reference documentation](https://cloud.google.com/nodejs/docs/reference/storage/latest). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```javascript /** * TODO(developer): Uncomment the following lines before running the sample. */ // The ID of your GCS bucket // const bucketName = 'your-unique-bucket-name'; // The ID of your GCS file // const fileName = 'your-file-name'; // Imports the Google Cloud client library const {Storage} = require('@google-cloud/storage'); // Creates a client const storage = new Storage(); async function generateV4SignedPolicy() { const bucket = storage.bucket(bucketName); const file = bucket.file(fileName); // These options will allow temporary uploading of a file // through an HTML form. const expires = Date.now() + 10 * 60 * 1000; // 10 minutes const options = { expires, fields: {'x-goog-meta-test': 'data'}, }; // Get a v4 signed policy for uploading file const [response] = await file.generateSignedPostPolicyV4(options); // Create an HTML form with the provided policy let output = `
\n`; // Include all fields returned in the HTML form as they're required for (const name of Object.keys(response.fields)) { const value = response.fields[name]; output += ` \n`; } output += '
\n'; output += '
\n'; output += '
'; console.log(output); } generateV4SignedPolicy().catch(console.error); ``` ### PHP For more information, see the [Cloud Storage PHP API reference documentation](https://googleapis.github.io/google-cloud-php/#/docs/google-cloud/latest/storage/storageclient). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```php use Google\Cloud\Storage\StorageClient; /** * Generates a v4 POST Policy to be used in an HTML form and echo's form. * * @param string $bucketName The name of your Cloud Storage bucket. * (e.g. 'my-bucket') * @param string $objectName The name of your Cloud Storage object. * (e.g. 'my-object') */ function generate_v4_post_policy(string $bucketName, string $objectName): void { $storage = new StorageClient(); $bucket = $storage->bucket($bucketName); $response = $bucket->generateSignedPostPolicyV4( $objectName, new \DateTime('10 min'), [ 'fields' => [ 'x-goog-meta-test' => 'data' ] ] ); $url = $response['url']; $output = "
" . PHP_EOL; foreach ($response['fields'] as $name => $value) { $output .= " " . PHP_EOL; } $output .= "
" . PHP_EOL; $output .= "
" . PHP_EOL; $output .= '
' . PHP_EOL; echo $output; } ``` ### Python For more information, see the [Cloud Storage Python API reference documentation](https://cloud.google.com/python/docs/reference/storage/latest). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```python import datetime from google.cloud import storage def generate_signed_post_policy_v4(bucket_name, blob_name): """Generates a v4 POST Policy and prints an HTML form.""" # bucket_name = 'your-bucket-name' # blob_name = 'your-object-name' storage_client = storage.Client() policy = storage_client.generate_signed_post_policy_v4( bucket_name, blob_name, expiration=datetime.timedelta(minutes=10), fields={ 'x-goog-meta-test': 'data' } ) # Create an HTML form with the provided policy header = "
\n" form = header.format(policy["url"]) # Include all fields returned in the HTML form as they're required for key, value in policy["fields"].items(): form += f" \n" form += "
\n" form += "
\n" form += "
" print(form) return form ``` ### Ruby For more information, see the [Cloud Storage Ruby API reference documentation](https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage.html). To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see [Set up authentication for client libraries](https://docs.cloud.google.com/storage/docs/authentication.md.txt#client-libs). ```ruby def generate_signed_post_policy_v4 bucket_name:, file_name: # The ID of the GCS bucket to upload to # bucket_name = "your-unique-bucket-name" # The name to give the object uploaded to GCS # file_name = "your-file-name" require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket bucket_name post_object = bucket.generate_signed_post_policy_v4 file_name, expires: 600, fields: { "x-goog-meta-test" => "data" } html_form = "
\n" post_object.fields.each do |name, value| html_form += " \n" end html_form += "
\n" html_form += "
\n" html_form += "
\n" puts "You can use the following form to upload an object to bucket #{bucket_name} for the next 10 minutes:\n" puts html_form post_object end ``` ### Rust ```rust use google_cloud_storage::builder::storage::PostPolicyV4Builder; use std::time::Duration; pub async fn sample(bucket_name: &str, object_name: &str) -> anyhow::Result<()> { let signer = google_cloud_auth::credentials::Builder::default().build_signer()?; let policy = PostPolicyV4Builder::for_object(format!("projects/_/buckets/{bucket_name}"), object_name) .with_expiration(Duration::from_secs(30 * 60)) // 30 minutes .with_field("Content-Type", "text/plain") .with_field("x-goog-meta-test", "data") .with_starts_with("$key", "") .with_content_length_range(1, 10 * 1024 * 1024) // 1 byte to 10 MiB .sign_with(&signer) .await?; // Create an HTML form with the computed policy let mut form = format!( "
\n", policy.url ); for (key, value) in &policy.fields { form.push_str(&format!( " \n", key, value )); } form.push_str("
\n"); form.push_str("
\n"); form.push_str("
"); println!("Generated POST Policy HTML Form:"); println!("{form}"); Ok(()) } ```
As a best practice you should use the `Expect: 100-continue` header with `POST` requests. This lets you verify that the server will handle the request before you send the object. If you receive a status code `100 Continue` you should proceed with the request. If you receive a status code `417 Expectation Failed` then you shouldn't send the object.