Before you can make requests to Storage Transfer Service, you must make sure the Storage Transfer Service API is enabled for your project, and that your application is set up for authorization, using the OAuth 2.0 protocol. We recommend that you also implement Truncated exponential backoff to handle retry attempts in the event of request failures.
Enabling the service
Accessing Storage Transfer Service through a Google APIs Library, or directly using the Storage Transfer Service API, requires that you enable the Google Storage Transfer API.
Enable the Google Storage Transfer API.Authentication flow
Because all Storage Transfer Service operations occur without the need for human intervention or user consent, the best authentication flow for a Storage Transfer Service application is server-to-server, using a service account. App Engine and Compute Engine have built-in service accounts that you can use, or you can create a service credential in the Google Cloud Console.
When you use a service account, the Google APIs client libraries handle the authentication and authorization process for you in the following scenarios:
- App Engine application
If your application runs on App Engine, it authenticates with the default service account of your App Engine application.
The code also works with your App Engine local emulator as long as you're using Cloud SDK (
mvn gcloud:run
), by using a service account and setting theGOOGLE_APPLICATION_CREDENTIALS
environment variable.For more information, see Local or third-party host section.
- Compute Engine application
If your application runs on a Compute Engine instance, it authenticates using the default Compute Engine service account associated with the project.
Configure your instance to use service accounts and add the scope listed in the Authorization scope section.
For more information, see Setting the scope of service account access for instances in the Compute Engine documentation.
- Local or third-party host
If you're running a local client or if you're running your program in a non–Google Cloud environment, create a new service account, download its JSON key file, and then set the environment variable
GOOGLE_APPLICATION_CREDENTIALS
to point to the JSON key file.For more information, see Authenticating as a service account.
Authorization scope
Applications that access Storage Transfer Service using OAuth 2.0 must
specify the cloud-platform
authorization scope.
Scope | Meaning |
---|---|
https://www.googleapis.com/auth/cloud-platform |
Full access. |
Create a client
You can use the sample code below to create a Storage Transfer Service client in any of the environments discussed in Authentication Flow. Because the code uses Google Application Default Credentials, it selects the appropriate service account to use.
The service account must be assigned one of the following roles:
- roles/owner
- roles/editor
- roles/storagetransfer.admin
- roles/storagetransfer.user
A custom role that includes, at bare minimum, roles/storagetransfer.user permissions.
For more information about adding and viewing project-level permissions, see IAM permissions for Storage Transfer Service methods and Examples of IAM permissions and roles.
You can check by going to the permissions page for your project.
Java
This sample uses the
Google APIs Client Library for Java. The custom
RetryHttpInitializerWrapper
class is described in the
Retry Handling section.
Python
This sample uses the Google APIs Client Library for Python.
Retry handling
In this case of RPC failures, you should implement code to handle retry attempts with a Truncated exponential backoff strategy.
Java
This sample uses the
Google APIs Client Library for Java.The class
RetryHttpInitializerWrapper
handles retry attempts for you.
Python
You can pass the num_retries=n
argument to the library
execute
method to retry with exponential backoff upon
retryable failures.
resp = client.projects().subscriptions().pull(
subscription=subscription, body=body).execute(num_retries=3)