:original_name: gaussdb_06_0004.html
.. _gaussdb_06_0004:
Querying Backups
================
Function
--------
This API is used to query backups according to search criteria. Before using this API:
- Learn how to :ref:`authorize and authenticate ` it.
- Obtain the required :ref:`region and endpoint `.
URI
---
GET /v3/{project_id}/backups
.. table:: **Table 1** URI parameters
+-----------------+-----------------+-----------------+----------------------------------------------------------------------------+
| Parameter | Mandatory | Type | Description |
+=================+=================+=================+============================================================================+
| project_id | Yes | String | Project ID of a tenant in a region. |
| | | | |
| | | | To obtain this value, see :ref:`Obtaining a Project ID `. |
+-----------------+-----------------+-----------------+----------------------------------------------------------------------------+
.. table:: **Table 2** Query parameters
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter | Mandatory | Type | Description |
+=================+=================+=================+=======================================================================================================================================================================================================================================+
| instance_id | No | String | DB instance ID. |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| backup_id | No | String | Backup ID. |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| backup_type | No | String | Backup type. Value: |
| | | | |
| | | | **auto**: automated full backup |
| | | | |
| | | | **manual**: manual full backup |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| offset | No | String | Index offset. If **offset** is set to *N*, the resource query starts from the N+1 piece of data. The value is **0** by default, indicating that the query starts from the first piece of data. The value cannot be a negative number. |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| limit | No | String | Number of records to be queried. The default value is **100**. The value must be a positive integer. The minimum value is **1** and the maximum value is **100**. |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| begin_time | No | String | Query start time. The format is "yyyy-mm-ddThh:mm:ssZ". **T** is the separator between the calendar and the hourly notation of time. **Z** indicates the time zone offset. |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| end_time | No | String | Query end time. The format is "yyyy-mm-ddThh:mm:ssZ" and the end time must be later than the start time. **T** is the separator between the calendar and the hourly notation of time. **Z** indicates the time zone offset. |
+-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Request Parameters
------------------
.. table:: **Table 3** Request header parameters
============ ========= ====== ===========
Parameter Mandatory Type Description
============ ========= ====== ===========
X-Auth-Token Yes String User token.
X-Language No String Language.
============ ========= ====== ===========
Response Parameters
-------------------
**Status code: 200**
.. table:: **Table 4** Response body parameters
+-------------+---------------------------------------------------------------------+-------------------------------+
| Parameter | Type | Description |
+=============+=====================================================================+===============================+
| backups | Array of :ref:`backups ` objects | Backup information. |
+-------------+---------------------------------------------------------------------+-------------------------------+
| total_count | Long | Total number of backup files. |
+-------------+---------------------------------------------------------------------+-------------------------------+
.. _gaussdb_06_0004__response_backups:
.. table:: **Table 5** backups
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter | Type | Description |
+=======================+=========================================================================+============================================================================================================================================================================+
| id | String | Backup ID. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| name | String | Backup name. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| begin_time | String | Backup start time in the "yyyy-mm-ddThh:mm:ssZ" format. **T** is the separator between the calendar and the hourly notation of time. **Z** indicates the time zone offset. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| end_time | String | Backup end time in the "yyyy-mm-ddThh:mm:ssZ" format. **T** is the separator between the calendar and the hourly notation of time. **Z** indicates the time zone offset. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| status | String | Backup status. Value: |
| | | |
| | | - **BUILDING**: Backup in progress |
| | | - **COMPLETED**: Backup completed |
| | | - **FAILED**: Backup failed |
| | | - **AVAILABLE**: Backup available |
| | | |
| | | Valid value: |
| | | |
| | | - BUILDING |
| | | - COMPLETED |
| | | - FAILED |
| | | - AVAILABLE |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| take_up_time | Integer | Backup duration in minutes. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| type | String | Backup type. Value: |
| | | |
| | | - **auto**: automated full backup |
| | | - **manual**: manual full backup |
| | | |
| | | Valid value: |
| | | |
| | | - auto |
| | | - manual |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| size | Long | Backup size in MB. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| datastore | :ref:`MysqlDatastore ` object | Database information. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| instance_id | String | DB instance ID. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| description | String | Description of the backup file. |
+-----------------------+-------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. _gaussdb_06_0004__response_mysqldatastore:
.. table:: **Table 6** MysqlDatastore
+-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------+
| Parameter | Type | Description |
+=======================+=======================+=========================================================================================================+
| type | String | DB engine. Currently, only gaussdb-mysql is supported. |
+-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------+
| version | String | DB version. |
| | | |
| | | To obtain details about supported DB engine versions, call the API for querying the DB engine versions. |
+-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------+
**Status code: 400**
.. table:: **Table 7** Response body parameters
========== ====== ==============
Parameter Type Description
========== ====== ==============
error_code String Error code.
error_msg String Error message.
========== ====== ==============
**Status code: 500**
.. table:: **Table 8** Response body parameters
========== ====== ==============
Parameter Type Description
========== ====== ==============
error_code String Error code.
error_msg String Error message.
========== ====== ==============
Example Request
---------------
.. code-block:: text
GET https://gaussdb-mysql.eu-de.otc.t-systems.com/v3/97b026aa9cc4417888c14c84a1ad9860/backups?instance_id=43e4feaab48f11e89039fa163ebaa7e4br01&backup_id=c0c9f155c7b7423a9d30f0175998b63bbr01&backup_type=auto&offset=0&limit=10&begin_time=2020-07-06T10:41:14+0800&end_time=2020-07-16T10:41:14+0800
Example Response
----------------
**Status code: 200**
Success.
.. code-block::
{
"backups" : [ {
"id" : "c0c9f155c7b7423a9d30f0175998b63bbr01",
"name" : "GaussDBforMySQL-gauss-e747-20200705185048266",
"begin_time" : "2020-07-06T10:41:14+0800",
"end_time" : "2020-07-16T10:41:14+0800",
"take_up_time" : 2,
"status" : "COMPLETED",
"type" : "auto",
"size" : 2803,
"datastore" : {
"type" : "gaussdb-mysql",
"version" : "8.0"
},
"instance_id" : "c0c9f155c7b7423a9d30f0175998b63bbr01"
} ],
"total_count" : 1
}
Status Code
-----------
For details, see :ref:`Status Codes `.
Error Code
----------
For details, see :ref:`Error Codes `.