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 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. To do so: 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. Google App Engine and Google Compute Engine have built-in service accounts that you can leverage, 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:
- Google App Engine application
-
If your application runs on App Engine, it authenticates with the default service account of your App Engine application.
Note: The code also works with your App Engine local emulator as long as you're using Google Cloud SDK (
mvn gcloud:run
), by using a service account and setting theGOOGLE_APPLICATION_CREDENTIALS
environment variable. See the Local or third-party host for more details. - Google Compute Engine application
-
If your application runs on a Google Compute Engine instance, it authenticates using the default Compute Engine service account associated with the project.
- 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 How the Application Default Credentials Work.
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 have 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 Using IAM permissions with projects.
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 an 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)