Using Requester Pays

This page describes how to set up the Requester Pays feature and gives an example of making a request on a bucket that has enabled the Requester Pays feature. For a description of this feature, see Requester Pays.

Setting up Requester Pays

The following sections show how to turn Requester Pays on and off, as well as how to check to see if Requester Pays is enabled on a bucket.

Prerequisites

  1. To enable and disable requester pays, you must have the storage.buckets.update permission. When using gsutil, you must also have the storage.buckets.setIamPolicy permission.

  2. To get the requester pays status for a bucket, you must have the storage.buckets.get permission.

Permissions are granted to users through roles. For example, users with the roles/storage.admin role hold all of the above permissions. Roles can be either added to the desired bucket or added to the project that contains the bucket.

Enabling Requester Pays

To enable Requester Pays on a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the list of buckets, find the bucket you want to enable, and click the Off button in the Requester pays column.

  3. In the window that appears, click Enable.

Once enabled, a green bubble and On appear in the Requester pays column for the bucket.

gsutil

Use the gsutil requesterpays set on command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil requesterpays set on gs://[BUCKET_NAME]

Code samples

C#

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

void EnableRequesterPays(string bucketName)
{
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName);
    bucket.Billing = bucket.Billing ?? new Bucket.BillingData();
    bucket.Billing.RequesterPays = true;
    bucket = storage.UpdateBucket(bucket, new UpdateBucketOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = bucket.Metageneration
    });
}

Go

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

bucket := c.Bucket(bucketName)
if _, err := bucket.Update(ctx, storage.BucketAttrsToUpdate{
	RequesterPays: true,
}); err != nil {
	return err
}

Java

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of the existing bucket to enable requester-paying for, e.g. "my-bucket"
// String bucketName = "my-bucket"
BucketInfo bucketInfo = BucketInfo.newBuilder(bucketName)
    .setRequesterPays(true)
    .build();

// Update the bucket, throws StorageException on failure
Bucket bucket = storage.update(bucketInfo);

System.out.println("Requester pay status for " + bucketName +": " + bucket.requesterPays());

Node.js

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Imports the Google Cloud client library
const Storage = require(`@google-cloud/storage`);

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Enables requester-pays requests
storage
  .bucket(bucketName)
  .enableRequesterPays()
  .then(() => {
    console.log(
      `Requester-pays requests have been enabled for bucket ${bucketName}.`
    );
  })
  .catch(err => {
    console.error(`ERROR:`, err);
  });

PHP

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

use Google\Cloud\Storage\StorageClient;

/**
 * Enable a bucket's requesterpays metadata.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName Name of your Google Cloud Storage bucket.
 *
 * @return void
 */
function enable_requester_pays($projectId, $bucketName)
{
    $storage = new StorageClient([
        'projectId' => $projectId
    ]);
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'billing' => [
            'requesterPays' => true
        ]
    ]);
    printf('Requester pays has been enabled for %s' . PHP_EOL, $bucketName);
}

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

def enable_requester_pays(bucket_name):
    """Enable a bucket's requesterpays metadata"""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)
    bucket.requester_pays = True
    bucket.patch()
    print('Requester Pays has been enabled for {}'.format(bucket_name))

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project: project_id
bucket  = storage.bucket bucket_name

bucket.requester_pays = true

puts "Requester pays has been enabled for #{bucket_name}"

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information:
  3. {
      "billing": {
        "requesterPays": true
      }
    }
  4. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=billing"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create an .xml file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    <BillingConfiguration>
      <RequesterPays>Enabled</RequesterPays>
    </BillingConfiguration>
  3. Use cURL to call the XML API, with a PUT Bucket request and requesterpays query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?billing"

Disabling Requester Pays

To disable Requester Pays on a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the list of buckets, find the bucket you want to disable, and click the On button in the Requester pays column.

  3. In the window that appears, click Disable.

Once disabled, a gray bubble and Off appear in the Requester pays column.

gsutil

Use the gsutil requesterpays set off command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil requesterpays set off gs://[BUCKET_NAME]

Code samples

C#

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

void DisableRequesterPays(string bucketName)
{
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName);
    bucket.Billing = bucket.Billing ?? new Bucket.BillingData();
    bucket.Billing.RequesterPays = false;
    bucket = storage.UpdateBucket(bucket, new UpdateBucketOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = bucket.Metageneration
    });
}

Go

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

bucket := c.Bucket(bucketName)
if _, err := bucket.Update(ctx, storage.BucketAttrsToUpdate{
	RequesterPays: false,
}); err != nil {
	return err
}

Java

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of the bucket to disable requester-paying for, e.g. "my-bucket"
// String bucketName = "my-bucket"
BucketInfo bucketInfo = BucketInfo.newBuilder(bucketName)
    .setRequesterPays(false)
    .build();

// Update the bucket, throws StorageException on failure
Bucket bucket = storage.update(bucketInfo);

System.out.println("Requester pays status for " + bucketName +": " + bucket.requesterPays());

Node.js

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Imports the Google Cloud client library
const Storage = require(`@google-cloud/storage`);

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Disables requester-pays requests
storage
  .bucket(bucketName)
  .disableRequesterPays()
  .then(() => {
    console.log(
      `Requester-pays requests have been disabled for bucket ${bucketName}.`
    );
  })
  .catch(err => {
    console.error(`ERROR:`, err);
  });

PHP

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

use Google\Cloud\Storage\StorageClient;

/**
 * Disable a bucket's requesterpays metadata.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName Name of your Google Cloud Storage bucket.
 *
 * @return void
 */
function disable_requester_pays($projectId, $bucketName)
{
    $storage = new StorageClient([
        'projectId' => $projectId
    ]);
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'billing' => [
            'requesterPays' => false
        ]
    ]);
    printf('Requester pays has been disabled for %s' . PHP_EOL, $bucketName);
}

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

def disable_requester_pays(bucket_name):
    """Disable a bucket's requesterpays metadata"""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)
    bucket.requester_pays = False
    bucket.patch()
    print('Requester Pays has been disabled for {}'.format(bucket_name))

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project: project_id
bucket  = storage.bucket bucket_name

bucket.requester_pays = false

puts "Requester pays has been disabled for #{bucket_name}"

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information:
  3. {
      "billing": {
        "requesterPays": false
      }
    }
  4. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=billing"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create an .xml file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    <BillingConfiguration>
      <RequesterPays>Disabled</RequesterPays>
    </BillingConfiguration>
  3. Use cURL to call the XML API, with a PUT Bucket request and requesterpays query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?billing"

Checking whether Requester Pays is enabled

To check whether Requester Pays is enabled on a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the list of buckets, the Requester Pays status of each bucket is found in the Requester Pays column.

If enabled, the status is green and the word On appears.

gsutil

Use the gsutil requesterpays get command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil requesterpays get gs://[BUCKET_NAME]

The response looks like the following if Requester Pays is enabled:

gs://[BUCKET_NAME]: Enabled

Code samples

C#

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

bool GetRequesterPays(string bucketName)
{
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName);
    bool? requesterPaysOrNull = bucket.Billing?.RequesterPays;
    bool requesterPays =
        requesterPaysOrNull.HasValue ? requesterPaysOrNull.Value : false;
    Console.WriteLine("RequesterPays: {0}", requesterPays);
    return requesterPays;
}

Go

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

attrs, err := c.Bucket(bucketName).Attrs(ctx)
if err != nil {
	return err
}
fmt.Printf("Is requester pays enabled? %v\n", attrs.RequesterPays)

Java

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of the bucket to retrieve requester-pays status, eg. "my-bucket"
// String bucketName = "my-bucket"
// Retrieve the bucket, throws StorageException on failure
Bucket bucket = storage.get(bucketName,
    Storage.BucketGetOption.fields(BucketField.BILLING));

System.out.println("Requester pays status : " + bucket.requesterPays());

Node.js

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Imports the Google Cloud client library
const Storage = require(`@google-cloud/storage`);

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Gets the requester-pays status of a bucket
storage
  .bucket(bucketName)
  .getMetadata()
  .then(data => {
    let status;
    const metadata = data[0];
    if (metadata && metadata.billing && metadata.billing.requesterPays) {
      status = `enabled`;
    } else {
      status = `disabled`;
    }
    console.log(
      `Requester-pays requests are ${status} for bucket ${bucketName}.`
    );
  })
  .catch(err => {
    console.error(`ERROR:`, err);
  });

PHP

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

use Google\Cloud\Storage\StorageClient;

/**
 * Get a bucket's requesterpays metadata.
 *
 * @param string $projectId Your Google Cloud project ID.
 * @param string $bucketName Name of your Google Cloud Storage bucket.
 *
 * @return void
 */
function get_requester_pays_status($projectId, $bucketName)
{
    $storage = new StorageClient([
        'projectId' => $projectId
    ]);
    $bucket = $storage->bucket($bucketName);
    $bucketInformation = $bucket->info();
    $requesterPaysStatus = $bucketInformation['billing']['requesterPays'];
    if ($requesterPaysStatus) {
        printf('Requester Pays is enabled for %s' . PHP_EOL, $bucketName);
    } else {
        printf('Requester Pays is disabled for %s' . PHP_EOL, $bucketName);
    }
}

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

def get_requester_pays_status(bucket_name):
    """Get a bucket's requester pays metadata"""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)
    requester_pays_status = bucket.requester_pays
    if requester_pays_status:
        print('Requester Pays is enabled for {}'.format(bucket_name))
    else:
        print('Requester Pays is disabled for {}'.format(bucket_name))

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project: project_id
bucket  = storage.bucket bucket_name

if bucket.requester_pays
  puts "Requester Pays is enabled for #{bucket_name}"
else
  puts "Requester Pays is disabled for #{bucket_name}"
end

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the JSON API with a GET Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=billing"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the XML API with a GET Bucket request and billing query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?billing"

Accessing Requester Pays buckets

The following example shows how to include a billing project so that you can download an object stored in a Requester Pays bucket. Use a similar procedure to perform other requests on the Requester Pays bucket or on objects within it. See Requester Pays access requirements for prerequisite considerations.

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the list of buckets, click on the bucket that contains the object you want to download.

  3. In the window that appears, use the dropdown menu to select a project for billing.

  4. Check the checkbox to confirm you are authorized to use the selected project for billing purposes.

  5. Click Save.

  6. Download the object as you normally would.

gsutil

Use the -u flag in your request along with the ID of the project to be billed, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil -u [PROJECT_ID] cp gs://[BUCKET_NAME]/[OBJECT_NAME] [OBJECT_DESTINATION]

Code samples

C#

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

private void DownloadObjectRequesterPays(string bucketName, string objectName,
    string localPath = null)
{
    var storage = StorageClient.Create();
    localPath = localPath ?? Path.GetFileName(objectName);
    using (var outputFile = File.OpenWrite(localPath))
    {
        storage.DownloadObject(bucketName, objectName, outputFile, new DownloadObjectOptions()
        {
            UserProject = s_projectId
        });
    }
    Console.WriteLine(
        $"downloaded {objectName} to {localPath} paid by {s_projectId}.");
}

Go

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

bucket := client.Bucket(bucketName).UserProject(billingProjectID)
src := bucket.Object(object)

f, err := os.OpenFile(localpath, os.O_RDWR|os.O_CREATE, 0755)
if err != nil {
	return err
}
rc, err := src.NewReader(ctx)
if err != nil {
	return err
}
if _, err := io.Copy(f, rc); err != nil {
	return err
}
if err := rc.Close(); err != nil {
	return err
}
fmt.Printf("Downloaded using %v as billing project.\n", billingProjectID)

Java

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// The project ID to bill
// String projectId = "my-billable-project-id";

// The name of the bucket to access
// String bucketName = "my-bucket";

// The name of the remote file to download
// String srcFilename = "file.txt";

// The path to which the file should be downloaded
// Path destFilePath = Paths.get("/local/path/to/file.txt");

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// Get specific file from specified bucket
Blob blob = storage.get(BlobId.of(bucketName, srcFilename));

// Download file to specified path
blob.downloadTo(destFilePath, Blob.BlobSourceOption.userProject(projectId));

Node.js

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

// Imports the Google Cloud client library
const Storage = require(`@google-cloud/storage`);

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'The project ID to bill from, e.g. some-project-id';
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const srcFilename = 'Name of file to download, e.g. file.txt';
// const destFilename = 'Local destination of file, e.g. ./local/path/to/file.txt';

const options = {
  // The path to which the file should be downloaded, e.g. "./file.txt"
  destination: destFilename,

  // The project to bill from, if requester-pays requests are enabled
  userProject: projectId,
};

// Downloads the file
storage
  .bucket(bucketName)
  .file(srcFilename)
  .download(options)
  .then(() => {
    console.log(
      `gs://${bucketName}/${srcFilename} downloaded to ${destFilename} using requester-pays requests.`
    );
  })
  .catch(err => {
    console.error(`ERROR:`, err);
  });

PHP

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

use Google\Cloud\Storage\StorageClient;

/**
 * Download file using specified project as requester
 *
 * @param string $projectId Your Google Cloud billable project ID.
 * @param string $bucketName A Google Cloud Storage bucket name.
 * @param string $objectName Name of object in Google Cloud Storage to download locally.
 * @param string $destination Path to local file to save.
 *
 * @return void
 */
function download_file_requester_pays($projectId, $bucketName, $objectName, $destination)
{
    $storage = new StorageClient([
        'projectId' => $projectId
    ]);
    $userProject = true;
    $bucket = $storage->bucket($bucketName, $userProject);
    $object = $bucket->object($objectName);
    $object->downloadToFile($destination);
    printf('Downloaded gs://%s/%s to %s using requester-pays requests.' . PHP_EOL,
        $bucketName, $objectName, basename($destination));
}

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

def download_file_requester_pays(
        bucket_name, project_id, source_blob_name, destination_file_name):
    """Download file using specified project as the requester"""
    storage_client = storage.Client()
    user_project = project_id
    bucket = storage_client.bucket(bucket_name, user_project)
    blob = bucket.blob(source_blob_name)
    blob.download_to_filename(destination_file_name)

    print('Blob {} downloaded to {} using a requester-pays request.'.format(
        source_blob_name,
        destination_file_name))

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

# project_id  = "Your Google Cloud billable project ID"
# bucket_name = "A Google Cloud Storage bucket name"
# file_name   = "Name of file in Google Cloud Storage to download locally"
# local_path  = "Destination path for downloaded file"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project: project_id
bucket  = storage.bucket bucket_name, skip_lookup: true, user_project: true
file    = bucket.file file_name

file.download local_path

puts "Downloaded #{file.name} using billing project #{project_id}"

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. In your request, include the userProject query string parameter set to the ID of the project to be billed, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -o "[SAVE_TO_LOCATION]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?alt=media&userProject=[PROJECT_ID]"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. In your request, include the x-goog-user-project header set to the ID of the project to be billed, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X GET \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "x-goog-user-project: [PROJECT_ID]" \
        -o "[SAVE_TO_LOCATION]" \
        "https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]"

Enviar comentarios sobre…

Cloud Storage Documentation