The following topics will instruct you how to connect to the REST API and authorize your access, and how to control and sort the data that the REST API returns.

Each Veeam Backup for Google Cloud REST API-exposed entity has a resource representing it. To get a resource representation, request its URL.

Veeam Backup for Google Cloud REST API requests use the following base URL format:

https://<hostname>:<port>/api/<version>

where:

• <hostname> is a public IPv4 address or DNS hostname of the VM instance where Veeam Backup for Google Cloud is installed.

• <port> is the number of a port used to communicate with the REST API service running on the backup appliance.

  The default port number is 13140.

• <version> is an API version.

  The current version is v1.

To get a collection of Veeam Backup for Google Cloud REST API resources, request the base URL followed by a resource collection endpoint. For example:

https://123.123.123.123:13140/api/v1/vmInstances

To get a representation of an individual resource, enter a resource identifier after the resource collection endpoint. For example:

https://123.123.123.123:13140/api/v1/vmInstances/7876786467083982093

The resource identifier is represented by the id property of the resource from the collection. For example:

[
   {
      "id": "7876786467083982093",
      "resourceId": "dept-gc475akr1",
      "name": "dept-gc475akr1",
      "locationId": "1587a0d3-f27a-436e-b0cb-fe2d82a85767",
      "locationName": "asia-northeast3-a",
      "projectId": "project-backup-252812",
      "instanceType": "e2-medium"
   },
   ...
]

The Veeam Backup for Google Cloud REST API is available in multiple versions. All existing Veeam Backup for Google Cloud REST API versions are supported.

To work with resources available in a particular version of the REST API specification, you must specify the version in the x-api-version header. For example, to obtain information on VM backup policies using the latest Veeam Backup for Google Cloud REST API specification, send the following HTTP request to the backup appliance:

Request:
GET https://123.123.123.123:13140/api/v1/vmInstance/policies

Request Header:
x-api-version:1.3-rev0

The Veeam Backup for Google Cloud REST API is backward-compatible with client applications that were created using earlier versions of the REST API specification. This means that you can use any of the supported REST API specifications to perform operations with Veeam Backup for Google Cloud resources if the specification version has been released earlier or with the product version installed on the backup appliance:

Veeam Backup for Google Cloud 6.0, 7.0

• v1 (1.4-rev0)
• v1 (1.3-rev0)
• v1 (1.2-rev0)
• v1 (1.1-rev0)

Veeam Backup for Google Cloud 5.0

• v1 (1.3-rev0)
• v1 (1.2-rev0)
• v1 (1.1-rev0)

Veeam Backup for Google Cloud 4.0

• v1 (1.2-rev0)
• v1 (1.1-rev0)
• v1 (1.0-rev0)

Veeam Backup for Google Cloud 3.0

• v1 (1.1-rev0)
• v1 (1.0-rev0)

Veeam Backup for Google Cloud 2.0

• v1 (1.0-rev0)

To start working with the Veeam Backup for Google Cloud REST API, users must first authenticate themselves and get authorization to make requests. Veeam Backup for Google Cloud REST API authorization process is based on the OAuth 2.0 Authorization Framework and involves obtaining an access token and a refresh token.

• Access token is a string that represents authorization issued to the client and that must be used in all requests during the current logon session.
• Refresh token is a string that represents authorization granted to the client and that can be used to obtain a new access token if the current access token expires or becomes lost.

By default, the Veeam Backup for Google Cloud REST API access token expires in 15 minutes, refresh token expires in 2 weeks. You can change the expiration period of the refresh token to 60 minutes. For more information, see Requesting Authorization.

For increased security, Veeam Backup for Google Cloud allows you to use multi-factor authentication (MFA) to verify user identity. It is recommended to enable MFA for Veeam Backup for Google Cloud users. For more information, see Multi-Factor Authentication or the Veeam Backup for Google Cloud User Guide, section Enabling Multi-Factor Authentication.

Veeam Backup for Google Cloud follows OAuth 2.0 protocol for authenticating and authorizing users in the REST API. The authorization process involves the following procedures:

1. Requesting authorization.
2. Using the refresh token.
3. Performing logout.

The Veeam Backup for Google Cloud REST API accepts the following grant types to authenticate a Veeam Backup for Google Cloud user:

• Password
• MFA
• Authorization Code

To obtain authorization tokens, a user sends the HTTP POST request to the api/v1/token endpoint.

The request body must contain the grant_type parameter with the specified password value and the credentials of a user created in Veeam Backup for Google Cloud. For more information on how to create users, see User Accounts or the Veeam Backup for Google Cloud User Guide, section Adding User Accounts.

A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the Veeam Backup for Google Cloud REST API. The refresh token must be saved locally.

To learn how to authorize your access using the Password grant type, see Example [Password]. Alternatively, you can use the Swagger UI.

If multi-factor authentication (MFA) is enabled for a user, the user must first obtain an mfa token, and then get authorization tokens.

1. To obtain an mfa token, the user sends the HTTP POST request to the api/v1/token endpoint. The request body must contain the grant_type parameter with the specified password value and the credentials of the user.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns an mfa token.

2. To obtain an access token and a refresh token, the user must send another HTTP POST request to the api/v1/token endpoint. The request body must contain the grant_type parameter with the specified mfa value, the mfa token previously received from the authorization server, and the verification code generated by the authentication application running on the trusted device.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the Veeam Backup for Google Cloud REST API. The refresh token must be saved locally.

To learn how to authorize your access using the MFA grant type, see Example [MFA]. Alternatively, you can use the Swagger UI.

To get authorization using the Authorization Code grant type, a user must first obtain an authorization code, and then get authorization tokens.

1. To obtain the authorization code, an authorized user sends the HTTP POST request to the api/v1/authorization_code endpoint.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns an authorization code, which can be used by another user or client application to get authorization in the Veeam Backup for Google Cloud REST API.

   NOTE
   

   By default, the Veeam Backup for Google Cloud authorization code expires in 60 seconds.

2. To obtain an access token and a refresh token, a user or client application sends the HTTP POST request to the api/v1/token endpoint. The request body must contain the grant_type parameter with the specified authorization_code value and the authorization code previously issued by the authorization server.

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns an access token, its expiration time (in seconds) and a refresh token. The user inserts the access token in headers of further requests to the Veeam Backup for Google Cloud REST API. The refresh token must be saved locally.

To learn how to authorize your access using the Authorization Code grant type, see Example [Authorization Code]. Alternatively, you can use the Swagger UI.

Example [Password]

To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for Google Cloud REST API.

In the request body, the user specifies the following parameters:

• grant_type — the password value must be specified for this parameter.
• username and password — credentials used to access the server; in this example, administrator and Password1 are used.

Request:
POST https://123.123.123.123:13140/api/v1/token

Request Header:
x-api-version:1.3-rev0

Request Body:
grant_type=password&username=administrator&password=Password1

The server sends a response in the following format.

Response:
200

Response Body:
{
   "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkQzMjUyMThDOUMwMTYxODU1MzkxMjk1RTlDODQ4MTFGODZEODIwRTYiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJuYmYiOjE2MTY0NDU2OTEsImV4...",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkQzMjUyMThDOUMwMTYxODU1MzkxMjk1RTlDODQ4MTFGODZEODIwRTYiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJ0b2tlbl9pZCI6IjYxMzBjMmM0L...",
   "expires_in": 900,
   ".issued": "2021-03-22T20:41:31",
   ".expires": "2021-03-22T20:56:31"
}

Example [MFA]

To access the REST API when MFA is enabled, a user must do the following:

1. To obtain an mfa token, the user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for Google Cloud REST API.

   In the request body, the user specifies the following parameters:

   • grant_type — the password value must be specified for this parameter.
   • username and password — credentials used to access the server; in this example, administrator and Password1 are used.

   Request:
   POST https://123.123.123.123:13140/api/v1/token
   
   Request Header:
   x-api-version:1.3-rev0
   
   Request Body:
   grant_type=password&username=administrator&password=Password1
   

   The server sends a response in the following format.

   Response:
   202
   
   Response Body:
   {
      "mfa_token": "NzMxODI0QjQ4MjY5NTVCMUExNkU0NDc5QUFBRThEN0EwRjEyQ0M3RTk3QzkwNjU4NTgxQzg4MUNCMDQxRTYxQg==",
      "description": "mfa required"
   }
   

2. To obtain an access token and a refresh token, the user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for Google Cloud REST API.

   In the request body, the user specifies the following parameters:

   • grant_type — the mfa value must be specified for this parameter.
   • mfa_token — the mfa token previously received from the authorization server.
   • mfa_code — the six-digit verification code generated by the authentication application running on the trusted device.

   Request:
   POST https://123.123.123.123:13140/api/v1/token/
   
   Request Header:
   x-api-version:1.3-rev0
   
   Request Body:
   grant_type=mfa&mfa_token=RUI3Q0VCMUU3RTAzMTk5RUVCRjk3RjVGMDhCNzQ2MkU0QTgzMzRGQkFBMzJGM0YyNzQwQ0QxMzU1REMwOUEzMw%3D%3D&mfa_code=962724
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InR3X3Rlc3QiLCJuYmYiOjE2MTY3NzQ0MDYsImV4...",
      "token_type": "bearer",
      "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InR3X3Rlc3QiLCJ0b2tlbl9pZCI6IjczYjZiMWEy...",
      "expires_in": 900,
      ".issued": "2021-03-26T16:00:06",
      ".expires": "2021-03-26T16:15:06"
   }
   

Example [Authorization Code]

To access the REST API using an authorization code, a user must do the following:

1. To obtain an authorization code, an authorized user sends the HTTP POST request to the api/v1/authorization_code endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for Google Cloud REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

   Request:
   POST https://123.123.123.123:13140/api/v1/authorization_code
   
   Request Header:
   x-api-version:1.3-rev0
   Authorization:Bearer eyJhbGciOiJSUzUxMiIsImtpZCI6IjQ2MDU0QjExNTE3Njk0QzAxN0IyRTE2MTQyNURCRDM1QkNGNzY3NkQi-LCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InVzZXIiLCJuYmYiOjE1ODYyNTUzNzksImV4cCI6MTU...
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "code": "AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80r..."
   }
   

2. To obtain an access token and a refresh token, the user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the current revision of the Veeam Backup for Google Cloud REST API must be specified.

   In the request body, the user specifies the following parameters:

   • grant_type — the authorization_code value must be specified for this parameter.
   • code — the authorization code previously issued by the authorization server.

   Request:
   POST https://123.123.123.123:13140/api/v1/token
   
   Request Header:
   x-api-version:1.3-rev0
   
   Request Body:
   grant_type=authorization_code&code=AAEAAJO1R+DANfH7JDlyUzDVYGDw+77dyaa0mFu8nozvbOreW31Uu1X+mejLUilSp6nBrhcmv9/LTjAjMz3P+grbg1OATjZN7kZ5XbhenJG7DrVUtvpA6h5aDmma8INsMv6xW7+TmcOUNlK65n2J2/rQCjg80r...
   

   The server sends a response in the following format.

   Response:
   200
   
   Response Body:
   {
      "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJuYmYiOjE2MTY3NzUyMzQsImV4cCI6...",
      "token_type": "bearer",
      "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJ0b2tlbl9pZCI6IjE5Nzg2MDg4LTQzO...",
      "expires_in": 900,
      ".issued": "2021-03-26T16:13:54",
      ".expires": "2021-03-26T16:28:54"
   }
   

To obtain a new pair of tokens in case the access token expires or becomes lost, a user sends the HTTP POST request to the api/v1/token endpoint. The request body must contain the grant_type parameter with the specified refresh_token value and the refresh token saved locally. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

Example

To obtain an access token and a refresh token, a user sends the HTTP POST request to the api/v1/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for Google Cloud REST API.

In the body of the request, the user specifies the following parameters:

• grant_type — to refresh the token, it is required that the refresh_token value must be specified for this parameter.
• refresh_token — the previously saved refresh token.

Request:
POST https://123.123.123.123:13140/api/v1/token

Request Header:
x-api-version:1.3-rev0

Request Body:
grant_type=refresh_token&refresh_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJ0b2tlbl9pZCI6IjE5Nzg2MDg4LTQzO...

The server sends a response in the following format.

Response:
200
Response Body:
{
   "access_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJuYmYiOjE2MTY3NzU0OTYsImV4cCI6MTYx...",
   "token_type": "bearer",
   "refresh_token": "eyJhbGciOiJSUzUxMiIsImtpZCI6IkVDQTM3OTczM0U5MzhDMjRBMjQzMkE4MTJBNzAwNEYzMzdBRTAyQjgiLCJ0eXAiOiJKV1QifQ.eyJ1bmlxdWVfbmFtZSI6InJvb3QiLCJ0b2tlbl9pZCI6IjYxMzQ5ZWY3LTU5MmYt...",
   "expires_in": 900,
   ".issued": "2021-03-26T16:18:16",
   ".expires": "2021-03-26T16:33:16"
}

To log out, a user sends the HTTP DELETE request to the api/v1/token endpoint. A successfully completed operation returns the 204 response code.

Example

To log out, a user sends the HTTP DELETE request to the api/oauth2/token endpoint. In the x-api-version header, the user specifies the current revision of the Veeam Backup for Google Cloud REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

Request:
DELETE https://123.123.123.123:13140/api/oauth2/token

Request Header:
x-api-version:1.3-rev0
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISk...

The server sends a response in the following format.

Response:
204

Veeam Backup for Google Cloud multi-factor authentication (MFA) is based on the Time-based One-Time Password (TOTP) method. This method requires a user to install an authentication application on the trusted device. The authentication application will generate temporary six-digit codes used to verify the user identity.

To enable MFA for a specific user, do the following:

1. To obtain a secret key and a token, send the HTTP POST request to the /api/v1/accounts/users/{name}/mfaEnable endpoint, where {name} is a name of the user for which you want to enable MFA.

   In the x-api-version header, specify the current revision of the Veeam Backup for Google Cloud REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

   In the request body, specify the recreate parameter. The parameter indicates whether you want to re-create the existing MFA secret key (true) or to enable MFA for the user (false). Specify the false value for the parameter.

   Request:
   POST https://123.123.123.123:13140/api/v1/accounts/users/administrator/mfaEnable
   
   Request Header:
   x-api-version:1.3-rev0
   Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmy...
   
   Request Body:
   {
      "recreate": "false"
   }
   

   A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns the secret key, token, recovery scratch codes and the qrString link. The recovery codes must be saved locally.

   Response:
   200
   
   Response Body:
   {
      "response": {
         "qrString": "otpauth://totp/administrator@ap-ubuntu-2?secret=P6JV3GGODIMXHOUZ2OAXN3S2LQ&issuer=ap-ubuntu-2",
         "secretKey": "P6JV3GGODIMXHOUZ2OAXN3S2LQ",
         "scratchCodes": [
            "13433973",
            "96799468",
            "19712857",
            "22056331",
            "90916425"
         ],
         "token": "NEQ0RTY2RUNFNzAxQjdCMjE0MjVEOTRDOTMwRTlDNEY3RThDRkZBODM3MTY1N0E2NUUyQkYxNjAwQTYyNDlGNA=="
      },
      "issues": []
   }
   

2. Install a supported authentication application on the trusted device.

3. Open the authentication application, create an account and enter the secret key manually.

   The authentication application will generate a six-digit verification code.

   TIP
   

   You can use a QR code to create an account in the authentication application:

   1. On another device, open a QR code generator in a web browser.

   2. In the QR code generator, insert the qrString link returned by Veeam Backup for Google Cloud. The QR code generator will display a QR code.

   3. On your trusted device, open a supported authentication application and choose Scan barcode option.

   4. Scan the displayed QR code using the device camera.

      The authentication application will automatically create an account and generate a six-digit verification code.

4. To associate the authentication application with the authorization server, send the HTTP POST request to the /api/v1/accounts/users/{name}/mfaAccepted endpoint.

   In the x-api-version header, specify the current revision of the Veeam Backup for Google Cloud REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

   In the request body, specify the following parameters

   • code — the six-digit verification code generated by the authentication application on the trusted device.
   • token — the token previously received from the authorization server.

   Request:
   POST https://123.123.123.123:13140/api/v1/accounts/users/administrator/mfaAccepted
   
   Request Header:
   x-api-version:1.3-rev0
   Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQczIHVuSqbnVb00m-yOihPZZHQ48aP1VcgUtgnYTvtAO3WRJ1cJ8VaIXzsVYKIGrLa1Lm41LsjpMiiPZytkqIUUiphhlXn7Vm10xlTzQUe0TU3HmXK-KD2MiB6qBImaISkEjgCmy...
   
   Request Body:
   {
      "code": "475112",
      "token": "NEQ0RTY2RUNFNzAxQjdCMjE0MjVEOTRDOTMwRTlDNEY3RThDRkZBODM3MTY1N0E2NUUyQkYxNjAwQTYyNDlGNA=="
   }
   

   A successfully completed operation returns the 200 response code.

   Response:
   {
      "success": true,
      "issues": []
   }
   

   NOTE
   

   In case of losing access to the authentication application:

   • To get authorization in Veeam Backup for Google Cloud, the user can use a recovery scratch code saved locally instead of a verification code. Each recovery code can be used only once.
   • To re-create the MFA secret key for a new device if the trusted device is lost or broken, repeat step 1 (specify the true value for the recreate parameter), and then repeat steps 2, 3 and 4.

To disable MFA for a specific user, send the HTTP POST request to the /api/v1/accounts/users/{name}/mfaDisable endpoint, where {name} is a name of the user for which you want to disable MFA.

In the x-api-version header, specify the current revision of the Veeam Backup for Google Cloud REST API, in the Authorization header — currently valid access token in the Bearer <access_token> format.

Request:
POST https://123.123.123.123:13140/api/v1/accounts/users/administrator/mfaDisable

Request Header:
x-api-version:1.3-rev0
Authorization: Bearer YSEoaL6H9EEyJpnrJ9WhLtzbrrBBYWqMQFDBQuLnp13qGQX6MjNfZ_wriPIRHQrbY-8dYtsWcRZQcz...

A successfully completed operation returns the 200 response code.

Response:
{
   "success": true,
   "issues": []
}

To perform operations with Veeam Backup for Google Cloud entities using the REST API, you can use the following standard HTTP methods:

• GET — retrieves information about a resource or collection.
• POST — creates a new resource in a collection or activates a resource action.
• PUT — makes changes to a resource.
• DELETE — removes a resource from a collection.

To control the amount and order of data that the Veeam Backup for Google Cloud REST API returns for a resource or collection, you can use the following query parameters:

• Offset Parameter
• Limit Parameter
• Orderby Parameter
• Filter Parameters

Query parameters are part of a URL. The question mark ? separates query parameters from a resource collection endpoint.

The Offset query parameter is used to exclude from a response the first N items of a resource collection.

For example, to return a list of regions starting from the third one in the /regions collection, send the following request:

GET https://123.123.123.123:13140/api/v1/regions?Offset=2

You can combine the Limit and the Offset query parameters to request a particular set of items. Note that the Offset parameter is applied before the Limit parameter, regardless of the parameter position in the request. That is, top results are selected from a collection where a set of items is already excluded.

The Veeam Backup for Google Cloud REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the orderby or one of the filter query parameters. Note that the orderby and filter parameters are applied before the Offset parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are excluded.

The Limit query parameter is used to specify the maximum number of items of a resource collection to return in a response.

For example, to return only the first 3 VM instances in the /vmInstances collection, send the following request:

GET https://123.123.123.123:13140/api/v1/vmInstances?Limit=3

The Veeam Backup for Google Cloud REST API returns resources in the default order based on its own semantics. To sort or filter a collection before excluding results, use the orderby or one of the filter query parameters. Note that the orderby and filter parameters are applied before the Limit parameter, regardless of their position in the request. That is, a collection is first filtered or sorted, and then the top results are selected.

The orderby query parameter is used to sort items in a resource collection to be returned in a response.

The parameter accepts the array data type. To sort a resource collection use the orderby query parameter in the following format:

GET https://<hostname>:<port>/api/<version>/Endpoint?orderby=[{"property":"<property>","direction":"<direction>"}]

where:

• <property> is a resource property name.
• <direction> is a direction specifier.

The Veeam Backup for Google Cloud REST API accepts the following direction specifiers:

Direction Specifier	Description
ASC	Defines the ascending order of the resource collection representation.
DESC	Defines the descending order of the resource collection representation.

Examples

• To sort plans by their state, send the following request:

  GET https://123.123.123.123:13140/api/5.0/Plans?orderby=[{"property":"state","direction":"ASC"}]
  

• To sort recovery locations by their type and name, send the following request:

  GET https://123.123.123.123:13140/api/5.0/RecoveryLocations?orderby=[{"property":"type","direction":"ASC"},{"property":"name","direction":"ASC"}]
  

The filter query parameter is used to filter items in a resource collection to return a subset of resources in a response. The subset includes only those resources that satisfy parameter value specified in the query.

To filter a resource collection use the filter query parameter in the following format:

GET https://hostname>:<port>/api/<version>/<endpoint>?filter=[{"property":"<property>","operator":"<operator>","ignorecase":"<boolean>","value":"<value>"}]

where:

• <endpoint> is the resource collection endpoint.
• <property> is the resource property name.
• <operator> is a relational or logical operator.
• <ignorecase> defines whether to ignore letter case in the value parameter.
• <value> is a resource property value.

Veeam Backup for Google Cloud REST API supports the following operators:

Operator	Description
equals	Returns resources that match the specified property value.
contains	Returns resources that contain the value specified for a property.
exclusiveOr	Returns resources that match one of the filter expressions.
notEquals	Returns resources that do not match the specified property value.
greaterThan	Returns resources with the property value that is greater than the specified value.
greaterThanOrEqual	Returns resources with the property value that is greater than or equal to the specified value.
lessThan	Returns resources with the property value that is less than the specified value.
lessThanOrEqual	Returns resources with the property value that is less than or equal to the specified value.
in	Returns resources that match at least one of the values specified for a property.
and	Returns resources that match all the specified property values.
andAlso	Returns resources that match all the specified property values.
or	Returns resources that match at least one of the specified property values.
orElse	Returns resources that match at least one of the specified property values.
like	[Applies only to properties with the string data type] Returns resources that match a specified pattern in the property value.

To group multiple filter expressions, you can include them into the <items> parameter in the following format:

GET https://<hostname>:<port>/api/<version>/<endpoint>?filter=[{"items":[{"property":"<property>","operator":"<operator>","ignorecase":<boolean>,"value":"<value>"},{"property":"<property>","operator":"<operator>","ignorecase":<boolean>,"value":"<value>"}],"operator":"<operator>"}]

Examples

To get all VM instances with the vm-gc name pattern, send the following request:

GET https://123.123.123.123:13140/api/v1/vmInstances?filter=[{"property":"name","operator":"like","ignorecase":true,"value":"vm-gc"}]

To get all VM instances with the vm-gc name pattern and e2-medium instance type, send the following request:

GET https://123.123.123.123:13140/api/v1/vmInstances?filter=[{"items":[{"property":"instanceType","operator":"equals","ignorecase":true,"value":"e2-medium"},{"property":"name","operator":"like","ignorecase":true,"value":"vm-gc"}],"operator":"and"}]

To increase readability and optimize network traffic, Veeam Backup for Google Cloud REST API applies pagination to a number of responses that contain array of values.

Pagination data is returned in the meta section of a response and includes the following properties:

• offset — number of resources skipped. You can skip resources using the $offset parameter.
• limit — number of resources on the current page. The default value is 100. You can modify this number using the $limit parameter.
• totalCount — total number of resources returned.

To start working with the Veeam Backup for Google Cloud REST API, you can use any client application that supports the HTTPS protocol.

The Veeam Backup for Google Cloud REST API is additionally available through the Swagger UI, a tool that you can use to evaluate and explore capabilities of the REST API. The Swagger UI visually presents API specification files and allows you to work with resources.

All resources and methods are expandable. When you expand a method, you get a full description of available parameters and an automatically generated example. You can also send requests and see response messages.

To access the Swagger UI for the Veeam Backup for Google Cloud REST API, in a web browser, navigate to the following URL:

https://<hostname>:<port>/swagger/index.html

where:

• <hostname> is a public IPv4 address or DNS hostname of the VM instance on which Veeam Backup for Google Cloud is installed.

• <port> is the REST API port number set during Veeam Backup for Google Cloud installation.

  The default port number is 13140.

In the Select a definition field, select the version and revision of the Veeam Backup for Google Cloud REST API.

Veeam Backup for Google Cloud REST API authorization with the Swagger UI involves the following procedures:

1. Obtain an access token and a refresh token:

   1. On the Veeam Backup for Google Cloud public API 1.0 page, expand the Token resource and click POST api/v1/token.

   2. In the expanded method window, click Try it out.

      

   3. From the grant_type drop-down list, select password.

   4. In the username and password fields, specify the credentials of a user created in Veeam Backup for Google Cloud.

   5. Click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code. In the response body, Veeam Backup for Google Cloud returns an access token, its expiration time and a refresh token.

      NOTE
      

      If MFA is enabled for the user, Veeam Backup for Google Cloud returns an mfa token in the response body. To learn how to obtain an access token and a refresh token when MFA is enabled, see Requesting Authorization.

      

   6. Save the access and refresh token locally for further use.

      TIP
      

      You can download a server response in the JSON format. To do that, in the expanded method window, click Download at the lower right corner of the Response body field.

2. Authorize your access in the Swagger UI:

   1. At the top right corner of the Veeam Backup for Google Cloud public API 1.0 page, click Authorize.

      

   2. In the Available authorizations window, insert the access token saved locally in the Value field. Use the Bearer <access_token> format.

      

   3. Click Authorize.

3. When the access token expires, use the refresh token:

   1. On the Veeam Backup for Google Cloud public API 1.0 page, expand the Token resource and click POST api/v1/token.

   2. In the expanded method window, click Try it out.

   3. From the grant_type drop-down list, select refresh_token.

   4. In the refresh_token field, insert the refresh token saved locally, and click Execute.

      

      Wait for the response from the server. A successfully completed operation returns the 200 response code and a new pair of tokens in the response body.

      

   5. Save the access and refresh token locally for further use. To authorize your access in the Swagger UI, repeat step 2.

4. When you finish working with the Swagger UI:

   1. At the top right corner of the Veeam Backup for Google Cloud public API 1.0 page, click Authorize.

   2. In the Available authorizations window, click Logout.

      

After you get authorization, you can send HTTP requests to Veeam Backup for Google Cloud REST API collections and resources in the Swagger UI.

To send a request:

1. On the Veeam Backup for Google Cloud public API 1.0 page, expand a resource to which you want to perform an operation.

2. In the list of request methods, click the required method.

3. In the expanded method window, click Try it out.

4. Enter parameter values if required.

5. Click Execute.

   

   The Swagger UI returns a response body as well as a response code and response headers. Additionally the Swagger UI generates a curl command and a URL for your request.

   TIP
   

   You can download a server response in the JSON format. To do that, in the expanded method window, click Download at the lower right corner of the Response body field.