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.
Set 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
You should have the
storage.buckets.get
permission, which allows you to get the requester pays status for a bucket and is also required for enabling and disabling Requester Pays with the Google Cloud console or Google Cloud CLI.When enabling or disabling Requester Pays, you must have the
storage.buckets.update
permission.When disabling Requester Pays, you must either include a billing project in your request or else have the
resourcemanager.projects.createBillingAssignment
permission. See Requester Pays Use and access requirements for more information.
Permissions are given to users through roles. For example, users
granted the Storage Admin role have all of the above storage.buckets
permissions. Roles can be granted on the project that contains the bucket.
Set Requester Pays
To enable or disable Requester Pays on a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, find the bucket you want to set and locate the Requester pays column.
The value in the column indicates the current state of Requester Pays for that bucket.
Click the current state of Requester Pays for the desired bucket.
In the window that appears, click Turn on or Turn off, depending on the state you want to set for Requester Pays.
When enabled, a green bubble and On appear in the Requester pays column for the bucket. When disabled, a gray bubble and Off appear in the column.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
Use the gcloud storage buckets update
command with the
appropriate flag:
gcloud storage buckets update gs://BUCKET_NAME FLAG
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.FLAG
is either--requester-pays
to enable Requester Pays or `--no-requester-pays to disable it.
If successful, the response looks similar to the following example:
Updating gs://my-bucket/... Completed 1
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample enables Requester Pays on a bucket: The following sample disables Requester Pays on a bucket:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Create a JSON file that contains the following information:
{ "billing": { "requesterPays": STATE } }
Where STATE is either
true
orfalse
.Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=billing"
Where:
JSON_FILE_NAME
is the path for the JSON file that you created in Step 2.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Create an XML file that contains the following information:
<BillingConfiguration> <RequesterPays>STATE</RequesterPays> </BillingConfiguration>
Where STATE is either
Enabled
orDisabled
.Use
cURL
to call the XML API with aPUT
Bucket request andbilling
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?billing"
Where:
XML_FILE_NAME
is the path for the XML file that you created in Step 2.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Check whether Requester Pays is enabled
To check whether Requester Pays is enabled on a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
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.
Command line
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(requester_pays)"
Where BUCKET_NAME
is the name of the bucket
whose status you want to view. For example, my-bucket
.
If successful, the response looks similar to the following example:
requester_pays: true
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Use
cURL
to call the JSON API with aGET
Bucket request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=billing"
Where
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Use
cURL
to call the XML API with aGET
Bucket request andbilling
query string parameter:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?billing"
Where
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Access 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
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket that contains the object you want to download.
In the window that appears, use the dropdown menu to select a project for billing.
Check the checkbox to confirm you are authorized to use the selected project for billing purposes.
Click Save.
Download the object as you normally would.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
Use the --billing-project
flag in your request:
gcloud storage cp gs://BUCKET_NAME/OBJECT_NAME SAVE_TO_LOCATION --billing-project=PROJECT_IDENTIFIER
Where:
BUCKET_NAME
is the name of the bucket containing the object you are downloading. For example,my-bucket
.OBJECT_NAME
is the name of object you are downloading. For example,pets/dog.png
.SAVE_TO_LOCATION
is the local path where you are saving your object. For example,Desktop/Images
.PROJECT_IDENTIFIER
is the ID or number of the project to be billed. For example,my-project
.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.In your request, include the
userProject
query string parameter set to the ID of the project to be billed:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media&userProject=PROJECT_IDENTIFIER"
Where:
SAVE_TO_LOCATION
is the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the object you want to download. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.PROJECT_IDENTIFIER
is the ID or number of the project to be billed. For example,my-project
.
XML API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.In your request, include the
x-goog-user-project
header set to the ID of the project to be billed:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-user-project: PROJECT_ID" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
PROJECT_ID
is the ID of the project to be billed. For example,my-project
.SAVE_TO_LOCATION
is the location where you want to save your object. For example,Desktop/dog.png
.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the URL-encoded name of the object you want to download. For example,pets/dog.png
, URL-encoded aspets%2Fdog.png
.
What's next
- Learn more about Requester Pays.
- Make data publicly available.