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.
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
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 gsutil.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 added to the project that contains the bucket.
Enabling Requester Pays
To enable Requester Pays on a bucket:
Console
- In the Google Cloud Console, go to the Cloud Storage Browser page.
In the list of buckets, find the bucket you want to enable, and click the Off button in the Requester pays column.
In the window that appears, click Turn on.
Once enabled, a green bubble and On appear in the Requester pays column for the bucket.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the gsutil requesterpays set on
command:
gsutil requesterpays set on gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a
.json
file that contains the following information:{ "billing": { "requesterPays": true } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=billing"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create an
.xml
file that contains the following information:<BillingConfiguration> <RequesterPays>Enabled</RequesterPays> </BillingConfiguration>
Use
cURL
to call the XML API with aPUT
Bucket request andrequesterpays
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?billing"
Where:
XML_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Disabling Requester Pays
To disable Requester Pays on a bucket:
Console
- In the Google Cloud Console, go to the Cloud Storage Browser page.
In the list of buckets, find the bucket you want to disable, and click the On button in the Requester pays column.
In the window that appears, click Turn off.
Once disabled, a gray bubble and Off appear in the Requester pays column.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the gsutil requesterpays set off
command:
gsutil requesterpays set off gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a
.json
file that contains the following information:{ "billing": { "requesterPays": false } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=billing"
Where:
JSON_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create an
.xml
file that contains the following information:<BillingConfiguration> <RequesterPays>Disabled</RequesterPays> </BillingConfiguration>
Use
cURL
to call the XML API with aPUT
Bucket request andrequesterpays
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?billing"
Where:
XML_FILE_NAME
is the name of the file you created in Step 2.OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Checking 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 Browser 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.
gsutil
Use the gsutil requesterpays get
command:
gsutil requesterpays get gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
The response looks like the following if Requester Pays is enabled:
gs://my-bucket: Enabled
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aGET
Bucket request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=billing"
Where:
OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the XML API with aGET
Bucket request andbilling
query string parameter:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?billing"
Where:
OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
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
- In the Google Cloud Console, go to the Cloud Storage Browser page.
In the list of buckets, click on 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 operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the -u
flag in your request:
gsutil -u PROJECT_ID cp gs://BUCKET_NAME/OBJECT_NAME OBJECT_DESTINATION
Where:
PROJECT_ID
is the ID of the project to be billed. For example,my-project
.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.OBJECT_NAME
is the name of the object you want to download. For example,pets/dog.png
.OBJECT_DESTINATION
is the location where you want to save your object. For example,Desktop/dog.png
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
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 OAUTH2_TOKEN" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media&userProject=PROJECT_ID"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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 name of the object you want to download. For example,pets/dog.png
.PROJECT_ID
is the ID of the project to be billed. For example,my-project
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
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 OAUTH2_TOKEN" \ -H "x-goog-user-project: PROJECT_ID" \ -o "SAVE_TO_LOCATION" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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 name of the object you want to download. For example,pets/dog.png
.
What's next
- Learn more about Requester Pays.
- Make data publicly available.