diff --git a/api-ref/source/_static/images/en-us_image_0000001372529646.png b/api-ref/source/_static/images/en-us_image_0000001372529646.png new file mode 100644 index 0000000..d4a37a9 Binary files /dev/null and b/api-ref/source/_static/images/en-us_image_0000001372529646.png differ diff --git a/api-ref/source/_static/images/en-us_image_0000001422968749.gif b/api-ref/source/_static/images/en-us_image_0000001422968749.gif new file mode 100644 index 0000000..493d448 Binary files /dev/null and b/api-ref/source/_static/images/en-us_image_0000001422968749.gif differ diff --git a/api-ref/source/_static/images/en-us_image_0000001423128721.jpg b/api-ref/source/_static/images/en-us_image_0000001423128721.jpg new file mode 100644 index 0000000..9a3a0c8 Binary files /dev/null and b/api-ref/source/_static/images/en-us_image_0000001423128721.jpg differ diff --git a/api-ref/source/api/index.rst b/api-ref/source/api/index.rst new file mode 100644 index 0000000..008af25 --- /dev/null +++ b/api-ref/source/api/index.rst @@ -0,0 +1,24 @@ +:original_name: gaussdb_04_0000.html + +.. _gaussdb_04_0000: + +API +=== + +- :ref:`Querying Version Information About a DB Engine ` +- :ref:`Querying Database Specifications ` +- :ref:`Managing DB Instances ` +- :ref:`Managing Parameter Templates ` +- :ref:`Managing Quotas ` +- :ref:`Obtaining Task Information ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + querying_version_information_about_a_db_engine + querying_database_specifications + managing_db_instances/index + managing_parameter_templates/index + managing_quotas/index + obtaining_task_information diff --git a/api-ref/source/api/managing_db_instances/creating_a_db_instance.rst b/api-ref/source/api/managing_db_instances/creating_a_db_instance.rst new file mode 100644 index 0000000..6553e62 --- /dev/null +++ b/api-ref/source/api/managing_db_instances/creating_a_db_instance.rst @@ -0,0 +1,332 @@ +:original_name: gaussdb_04_0004.html + +.. _gaussdb_04_0004: + +Creating a DB instance +====================== + +Function +-------- + +This API is used to create a GaussDB(for MySQL) DB instance + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + POST https://{*Endpoint*}/mysql/v3/{project_id}/instances + +- Example + + POST https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/instances + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+============================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + +Request +------- + +.. table:: **Table 2** Parameter description + + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Mandatory | Type | Description | + +==========================+=========================================================================================+=================+===========================================================================================================================================================================================================================================+ + | charge_info | No | Object | Billing mode. | + | | | | | + | | | | For details, see :ref:`Table 3 `. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | name | Yes | String | DB instance name. | + | | | | | + | | | | DB instances of the same type can have same names under the same tenant. | + | | | | | + | | | | The value must be 4 to 64 characters in length and start with a letter. It is case-sensitive and can contain only letters, digits, hyphens (-), and underscores (_). | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | datastore | Yes | Object | Database information. | + | | | | | + | | | | For details, see :ref:`Table 4 `. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | mode | Yes | String | DB instance type. Currently, only the cluster type is supported. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | flavor_ref | Yes | String | Specification code. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | vpc_id | Yes | String | VPC ID. To obtain this value, use either of the following methods: | + | | | | | + | | | | - Method 1: Log in to the VPC console and view the VPC ID on the VPC details page. | + | | | | - Method 2: See "Querying VPCs" in the *Virtual Private Cloud API Reference*. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | subnet_id | Yes | String | Network ID. To obtain this value, use either of the following methods: | + | | | | | + | | | | - Method 1: Log in to the VPC console and click the target subnet on the **Subnets** page. You can view the network ID on the displayed page. | + | | | | - Method 2: See "Querying Subnets" in the *Virtual Private Cloud API Reference*. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | security_group_id | No | String | Security group ID. | + | | | | | + | | | | If the network ACL is enabled for the subnet used by the created DB instance, this parameter is optional. If the network ACL is not enabled, this parameter is mandatory. | + | | | | | + | | | | - Method 1: Log in to VPC console. Choose **Access Control** > **Security Groups** in the navigation pane on the left. On the displayed page, click the target security group. You can view the security group ID on the displayed page. | + | | | | - Method 2: See "Querying Security Groups" in the *Virtual Private Cloud API Reference*. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | configuration_id | No | String | Parameter template ID. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | password | Yes | String | Database password. | + | | | | | + | | | | Valid value: | + | | | | | + | | | | The password is 8 to 32 characters long and must contain at least three types of the following: uppercase letters, lowercase letters, digits, and special characters (``~!@#%^*-_=+?``). | + | | | | | + | | | | You are advised to enter a strong password to improve security and prevent security risks such as brute force cracking. If you enter a weak password, the system automatically determines that the password is invalid. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | backup_strategy | No | Object | Automated backup policy. | + | | | | | + | | | | For details, see :ref:`Table 5 `. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | time_zone | No | String | UTC time zone. | + | | | | | + | | | | - If this parameter is not specified, UTC is used by default. | + | | | | - If this parameter is specified, the value ranges from UTC-12:00 to UTC+12:00 at the full hour. For example, the parameter can be **UTC+08:00** rather than **UTC+08:30**. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | availability_zone_mode | Yes | String | AZ type. The value can be **single** or **multi**. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | master_availability_zone | If **availability_zone_mode** is set to **multi**, this parameter is mandatory. | String | Primary AZ. | + | | | | | + | | If **availability_zone_mode** is set to **single**, this parameter cannot be specified. | | | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | slave_count | Yes | Integer | Number of read-only nodes from 1 to 9. A DB instance can have a maximum of 15 read-only nodes. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | region | Yes | String | Region ID. | + | | | | | + | | | | The value cannot be empty. To obtain this value, see `Regions and Endpoints `__. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | enterprise_project_id | No | String | Enterprise project ID. This parameter is mandatory only when the enterprise project is enabled. | + +--------------------------+-----------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. _gaussdb_04_0004__table1935491614524: + +.. table:: **Table 3** charge_info field data structure description + + +-----------------+-----------------+-----------------+---------------------+ + | Name | Mandatory | Type | Description | + +=================+=================+=================+=====================+ + | charge_mode | Yes | String | Billing mode. | + | | | | | + | | | | Value: **postPaid** | + +-----------------+-----------------+-----------------+---------------------+ + +.. _gaussdb_04_0004__table64243102: + +.. table:: **Table 4** datastore field data structure description + + +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------+ + | Name | Mandatory | Type | Description | + +=================+=================+=================+===============================================================================================================================+ + | type | Yes | String | DB engine. Currently, only gaussdb-mysql is supported. | + +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------+ + | version | Yes | String | DB version. | + | | | | | + | | | | For details about supported DB versions, see section :ref:`Querying Version Information About a DB Engine `. | + +-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------+ + +.. _gaussdb_04_0004__table0863181193416: + +.. table:: **Table 5** backup_strategy field data structure description + + +------------+-----------+--------+---------------------------------------------------------------------------------------------------------------------------------+ + | Name | Mandatory | Type | Description | + +============+===========+========+=================================================================================================================================+ + | start_time | Yes | String | Automated backup start time. The automatic backup will be triggered within one hour after the time specified by this parameter. | + +------------+-----------+--------+---------------------------------------------------------------------------------------------------------------------------------+ + +.. note:: + + The value of **region** in the following is used as an example. + +- Request example + + .. code-block:: text + + { + "charge_info":{ + "charge_mode":"postPaid" + }, + "region":"cn-north-4b", + "name":"gaussdb-2d34", + "datastore":{ + "type":"gaussdb-mysql", + "version":"8.0" + }, + "mode":"Cluster", + "flavor_ref":"gaussdb.mysql.large.4", + "vpc_id":"f7ee62e2-9705-4523-ba49-a85ea1a1fa87", + "subnet_id":"140af7bf-a9da-4dcf-8837-34199fd6d186", + "security_group_id":"c7f69884-fe2b-4630-8114-70a11499d902", + "configuration_id":"43570e0de32e40c5a15f831aa5ce4176pr07", + "password":"Gauss_234", + "backup_strategy":{ + "start_time":"17:00-18:00" + }, + "time_zone":"UTC+08:00", + "availability_zone_mode":"single", + "master_availability_zone":"az1pod1", + "slave_count":1, + "enterprise_project_id":"0" + } + +Response +-------- + +- Normal response + + .. table:: **Table 6** Parameter description + + +-----------------------+-----------------------+-----------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+=======================================================================+ + | instance | Object | DB instance information. | + | | | | + | | | For details, see :ref:`Table 7 `. | + +-----------------------+-----------------------+-----------------------------------------------------------------------+ + | job_id | String | DB instance creation task ID. | + +-----------------------+-----------------------+-----------------------------------------------------------------------+ + + .. _gaussdb_04_0004__table175305610274: + + .. table:: **Table 7** instance field data structure description + + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +============================+=======================+========================================================================================================================================================================+ + | id | String | DB instance ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | name | String | DB instance name. DB instances of the same type can have same names under the same tenant. | + | | | | + | | | The value must be 4 to 64 characters in length and start with a letter. It is case-insensitive and can contain only letters, digits, hyphens (-), and underscores (_). | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | status | String | DB instance status. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | datastore | Object | Database information. | + | | | | + | | | For details, see :ref:`Table 8 `. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | mode | String | DB instance type. Currently, only the cluster type is supported. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | configuration_id | String | Parameter template ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | port | String | Database port, which is the same as the request parameter. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | backup_strategy | Object | Automated backup policy. | + | | | | + | | | For details, see :ref:`Table 9 `. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | region | String | Region ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | availability_zone_mode | String | AZ ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | master\_ availability_zone | String | Primary AZ ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | vpc_id | String | VPC ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | security_group_id | String | Security group ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | subnet_id | String | Subnet ID. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | slave_count | Integer | Number of read-only nodes. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | charge_info | Object | Billing mode. | + | | | | + | | | For details, see :ref:`Table 10 `. | + +----------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0004__table766045720277: + + .. table:: **Table 8** datastore field data structure description + + ======= ====== ============= + Name Type Description + ======= ====== ============= + type String **DB Engine** + version String DB version. + ======= ====== ============= + + .. _gaussdb_04_0004__table81249589270: + + .. table:: **Table 9** backup_strategy field data structure description + + +------------+---------+----------------------------------------------------------------------------------------+ + | Name | Type | Description | + +============+=========+========================================================================================+ + | start_time | String | Backup time window. Automated backups will be triggered during the backup time window. | + +------------+---------+----------------------------------------------------------------------------------------+ + | keep_days | Integer | Backup retention days. | + +------------+---------+----------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0004__table207147873611: + + .. table:: **Table 10** charge_info field data structure description + + =========== ====== ============= + Name Type Description + =========== ====== ============= + charge_mode String Billing mode. + =========== ====== ============= + +.. note:: + + The values of **region** and **master_availability_zone** are used as examples. + +- Example normal response + + .. code-block:: text + + { + "instance":{ + "id":"5eebbb4c0f9f4a99b42ed1b6334569aain07", + "name":"gaussdb-2d34", + "status":"BUILD", + "datastore":{ + "type":"gaussdb-mysql", + "version":"8.0" + }, + "mode":"Cluster", + "configuration_id": "", + "port":null, + "backup_strategy":{ + "start_time":null, + "keep_days":"7" + }, + "enterprise_project_id": "0", + "region":"aaa", + "availability_zone_mode":"single", + "master_availability_zone":"aaa", + "vpc_id":"f7ee62e2-9705-4523-ba49-a85ea1a1fa87", + "security_group_id":"c7f69884-fe2b-4630-8114-70a11499d902", + "subnet_id":"140af7bf-a9da-4dcf-8837-34199fd6d186", + "slave_count":1, + "charge_info":{ + "charge_mode":"postPaid" + } + }, + "job_id":"43672fe5-56bd-47f1-8fd1-595cded08a7c" + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_db_instances/deleting_a_db_instance.rst b/api-ref/source/api/managing_db_instances/deleting_a_db_instance.rst new file mode 100644 index 0000000..caa7f8f --- /dev/null +++ b/api-ref/source/api/managing_db_instances/deleting_a_db_instance.rst @@ -0,0 +1,75 @@ +:original_name: gaussdb_04_0007.html + +.. _gaussdb_04_0007: + +Deleting a DB Instance +====================== + +Function +-------- + +This API is used to delete a DB instance. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + DELETE https://{*Endpoint*}/mysql/v3/{project_id}/instances/{instance_id} + +- Example + + DELETE https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/instances/dsfae23fsfdsae3435in01 + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+============================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | instance_id | Yes | DB instance ID, which is compliant with the UUID format. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + ====== ====== ==================================== + Name Type Description + ====== ====== ==================================== + job_id String ID of the DB instance deletion task. + ====== ====== ==================================== + +- Example normal response + + .. code-block:: text + + { + "job_id": "dff1d289-4d03-4942-8b9f-463ea07c000d" + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_db_instances/index.rst b/api-ref/source/api/managing_db_instances/index.rst new file mode 100644 index 0000000..9e1ac64 --- /dev/null +++ b/api-ref/source/api/managing_db_instances/index.rst @@ -0,0 +1,20 @@ +:original_name: gaussdb_04_0003.html + +.. _gaussdb_04_0003: + +Managing DB Instances +===================== + +- :ref:`Creating a DB instance ` +- :ref:`Querying a DB Instance List ` +- :ref:`Querying Details of a DB Instance ` +- :ref:`Deleting a DB Instance ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + creating_a_db_instance + querying_a_db_instance_list + querying_details_of_a_db_instance + deleting_a_db_instance diff --git a/api-ref/source/api/managing_db_instances/querying_a_db_instance_list.rst b/api-ref/source/api/managing_db_instances/querying_a_db_instance_list.rst new file mode 100644 index 0000000..464bdef --- /dev/null +++ b/api-ref/source/api/managing_db_instances/querying_a_db_instance_list.rst @@ -0,0 +1,240 @@ +:original_name: gaussdb_04_0005.html + +.. _gaussdb_04_0005: + +Querying a DB Instance List +=========================== + +Function +-------- + +This API is used to query a DB instance list according to search criteria. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{project_id}/instances?id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit} + +- Example + + GET https://{*Endpoint*}/mysql/v3/97b026aa9cc4417888c14c84a1ad9860/instances?id=ed7cc6166ec24360a5ed5c5c9c2ed726in01&name=hy&type=Cluster&datastore_type=gaussdb-mysql&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&offset=0&limit=10 + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Mandatory | Description | + +=================+=================+=================+=========================================================================================================================================================================================================================================+ + | project_id | String | Yes | Project ID of a tenant in a region. | + | | | | | + | | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | id | String | No | DB instance ID. | + | | | | | + | | | | The asterisk (``*``) is reserved for the system. If the instance ID starts with an asterisk (*), the value following asterisk (*) is used for fuzzy matching. Otherwise, the instance ID is used for exact matching. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | name | String | No | DB instance name. | + | | | | | + | | | | The asterisk (``*``) is reserved for the system. If the instance name starts with an asterisk (*), the value following asterisk (*) is used for fuzzy matching. Otherwise, the instance name is used for exact matching. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | type | String | No | DB instance type to be queried. Currently, only the cluster type is supported. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | datastore_type | String | No | Database type. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | vpc_id | String | No | VPC ID. | + | | | | | + | | | | - Method 1: Log in to VPC console and view the VPC ID in the VPC details. | + | | | | - Method 2: See the "Querying VPCs" section in the *Virtual Private Cloud API Reference*. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | subnet_id | String | No | Network ID of the subnet. | + | | | | | + | | | | - Method 1: Log in to VPC console and click the target subnet on the **Subnets** page. You can view the network ID on the displayed page. | + | | | | - Method 2: See the "Querying Subnets" section under "APIs" or the "Querying Networks" section under "OpenStack Neutron APIs" in the *Virtual Private Cloud API Reference*. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | offset | Integer | No | Index position. 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 | Integer | No | Number of records to be queried. The default value is **100**. The value cannot be a negative number. The minimum value is **1** and the maximum value is **100**. | + +-----------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + +-----------------------+-----------------------+------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+========================================================================+ + | instances | Array of objects | DB instance information. | + | | | | + | | | For details, see :ref:`Table 3 `. | + +-----------------------+-----------------------+------------------------------------------------------------------------+ + | total_count | Integer | Total number of records. | + +-----------------------+-----------------------+------------------------------------------------------------------------+ + + .. _gaussdb_04_0005__table2058713718267: + + .. table:: **Table 3** instances field data structure description + + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+====================================================================================================================+ + | id | String | DB instance ID. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | name | String | DB instance name. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | status | String | DB instance status. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | private_ips | List | Private IP address for write. It is a blank string until an ECS is created. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | public_ips | List | Public IP address list. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | port | Integer | Database port number. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | type | String | DB instance type. The value is **Cluster**. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | region | String | Region where the DB instance is deployed. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | datastore | Object | Database information. | + | | | | + | | | For details, see :ref:`Table 4 `. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | created | String | Creation 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. | + | | | | + | | | The value is empty unless the DB instance creation is complete. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | updated | String | Update time. The format is the same as that of the **created** field. | + | | | | + | | | The value is empty unless the DB instance creation is complete. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | db_user_name | String | Default username. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | vpc_id | String | VPC ID. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | subnet_id | String | Network ID of the subnet. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | security_group_id | String | Security group ID. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | flavor_ref | String | Specification code. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | flavor_info | Object | Specification description. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | volume | Object | Volume information. | + | | | | + | | | For details, see :ref:`Table 5 `. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | backup_strategy | Object | Backup policy. | + | | | | + | | | For details, see :ref:`Table 7 `. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | time_zone | String | Time zone. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0005__table187591675262: + + .. table:: **Table 4** datastore field data structure description + + ======= ====== =========== + Name Type Description + ======= ====== =========== + type String DB engine. + version String DB version. + ======= ====== =========== + + .. _gaussdb_04_0005__table14771167122611: + + .. table:: **Table 5** volume field data structure description + + ==== ====== =============== + Name Type Description + ==== ====== =============== + type String Disk type. + size String Used disk size. + ==== ====== =============== + + .. table:: **Table 6** flavor_ref field data structure description + + ===== ====== ================== + Name Type Description + ===== ====== ================== + vcpus String Number of vCPUs. + ram String Memory size in GB. + ===== ====== ================== + + .. _gaussdb_04_0005__table578797132615: + + .. table:: **Table 7** backup_strategy field data structure description + + +------------+--------+----------------------------------------------------------------------------------------+ + | Name | Type | Description | + +============+========+========================================================================================+ + | start_time | String | Backup time window. Automated backups will be triggered during the backup time window. | + +------------+--------+----------------------------------------------------------------------------------------+ + | keep_days | String | Backup retention days. | + +------------+--------+----------------------------------------------------------------------------------------+ + + .. note:: + + The value of **region** is used as an example in the following response. + +- Example normal response + + .. code-block:: text + + { + "total_count":6, + "instances":[ + { + "id":"d738399de028480fabb2b8120d4e01a4in07", + "status":"ACTIVE", + "name":"oMoS_001", + "port":3306, + "type":"Cluster", + "private_ips": ["192.168.0.142"], + "public_ips": ["10.154.219.187"], + "db_user_name": "root", + "region": "aaa", + "datastore": {"type": "gaussdb-mysql", "version":"8.0"}, + "created": "2018-08-20T02:33:49+0800", + "updated": "2018-08-20T02:33:50+0800", + "volume": { + "type": "POOL", + "used_size": 100 + }, + "vpc_id": "f7ee62e2-9705-4523-ba49-a85ea1a1fa87", + "subnet_id": "140af7bf-a9da-4dcf-8837-34199fd6d186", + "security_group_id":"c7f69884-fe2b-4630-8114-70a11499d902", + "flavor_ref":"gaussdb.mysql.c3.small.4", + "backup_strategy": {"start_time": "19:00-20:00", "keep_days": 7} + "charge_info": { + "charge_mode": "postPaid" + }, + "enterprise_project_id": "0", + "time_zone": "", + } + ] + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_db_instances/querying_details_of_a_db_instance.rst b/api-ref/source/api/managing_db_instances/querying_details_of_a_db_instance.rst new file mode 100644 index 0000000..2cdaa9c --- /dev/null +++ b/api-ref/source/api/managing_db_instances/querying_details_of_a_db_instance.rst @@ -0,0 +1,305 @@ +:original_name: gaussdb_04_0006.html + +.. _gaussdb_04_0006: + +Querying Details of a DB Instance +================================= + +Function +-------- + +This API is used to query the details of a specified DB instance. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{project_id}/instances/{instance_id} + +- Example + + GET https://{*Endpoint*}/mysql/v3/97b026aa9cc4417888c14c84a1ad9860/instances/436aaafb689c4250a9a5bb33cb271e8cin07 + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------+-----------------+-----------------+----------------------------------------------------------------------------+ + | Name | Type | Mandatory | Description | + +=================+=================+=================+============================================================================+ + | project_id | String | Yes | Project ID of a tenant in a region. | + | | | | | + | | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------+-----------------+-----------------+----------------------------------------------------------------------------+ + | instance_id | String | Yes | DB instance ID. | + +-----------------+-----------------+-----------------+----------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + +-----------------------+-----------------------+------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+========================================================================+ + | instance | Object | DB instance information. | + | | | | + | | | For details, see :ref:`Table 3 `. | + +-----------------------+-----------------------+------------------------------------------------------------------------+ + + .. _gaussdb_04_0006__table2058713718267: + + .. table:: **Table 3** instance field data structure description + + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+==================+=============================================================================================+ + | id | String | DB instance ID. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | name | String | DB instance name. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | project_id | String | Project ID of a tenant in a region. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | status | String | DB instance status. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | enterprise_project_id | String | Enterprise project ID. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | type | String | DB instance type. Currently, only the cluster type is supported. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | node_count | Integer | Number of nodes. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | datastore | Object | Database information. For details, see :ref:`Table 4 `. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | backup_used_space | Integer | Used backup space, in GB. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | created | String | DB instance creation time. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | updated | String | DB instance update time. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | public_ips | String | Public IP address of the DB instance. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | private_write_ips | Array of List | Private IP address for write. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | db_user_name | String | Default username. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | port | String | Database port number. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | vpc_id | String | VPC ID. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | subnet_id | String | Subnet ID. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | security_group_id | String | Security group ID. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | volume | Object | Disk information. For details, see :ref:`Table 8 `. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | backup_strategy | Object | Backup policy. For details, see :ref:`Table 6 `. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | nodes | Arrays of object | Node information. For details, see :ref:`Table 7 `. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | time_zone | String | Time zone. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | az_mode | String | AZ. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + | master_az_code | String | Primary AZ. | + +-----------------------+------------------+---------------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0006__table187591675262: + + .. table:: **Table 4** datastore field data structure description + + ======= ====== =========== + Name Type Description + ======= ====== =========== + type String DB engine. + version String DB version. + ======= ====== =========== + + .. table:: **Table 5** configurations field data structure description + + ==== ====== ======================== + Name Type Description + ==== ====== ======================== + id String Parameter template ID. + name String Parameter template name. + ==== ====== ======================== + + .. _gaussdb_04_0006__table37991653839: + + .. table:: **Table 6** backup_strategy field data structure description + + +------------+---------+----------------------------------------------------------------------------------------+ + | Name | Type | Description | + +============+=========+========================================================================================+ + | start_time | String | Backup time window. Automated backups will be triggered during the backup time window. | + +------------+---------+----------------------------------------------------------------------------------------+ + | keep_days | Integer | Backup retention days. | + +------------+---------+----------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0006__table5182635134511: + + .. table:: **Table 7** nodes field data structure description + + +------------------+-----------------+-------------------------------------------------------------------------+ + | Name | Type | Description | + +==================+=================+=========================================================================+ + | id | String | Node ID. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | name | Array of object | Node name. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | type | String | Node type, which can be **master** or **slave**. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | status | String | Node status. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | port | Integer | Database port number. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | private_read_ips | Array of String | Private IP address for read. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | volume | Object | Disk information. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | az_code | String | AZ. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | region_code | String | Region where the DB instance is deployed. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | created | String | DB instance creation time. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | updated | String | Update time. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | flavor_ref | String | Specification code. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | max_connections | String | Maximum number of connections. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | vcpus | String | Number of vCPUs. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | ram | String | Memory size in GB. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | need_restart | Boolean | Whether to reboot the DB instance for the modifications to take effect. | + +------------------+-----------------+-------------------------------------------------------------------------+ + | priority | String | Failover priority. | + +------------------+-----------------+-------------------------------------------------------------------------+ + + .. _gaussdb_04_0006__table14771167122611: + + .. table:: **Table 8** volume field data structure description + + ==== ====== ================================================ + Name Type Description + ==== ====== ================================================ + type String Storage type. Currently, only POOL is supported. + used String Used storage size, in GB. + ==== ====== ================================================ + + .. note:: + + The values of **region_code** and **az_code** are used as examples. + +- Example normal response + + .. code-block:: text + + { + "instance": { + "id": "d2cda7b97a39488e8b30e3cea4066204in07", + "name": "gauss-d616-lb07", + "status": "FAILED", + "project_id": "053f533ead80d5102f0cc012e8d468a4", + "enterprise_project_id": "0", + "type": "Cluster", + "charge_info": { + "charge_mode": "postPaid", + "order_id": "" + }, + "node_count": 2, + "datastore": { + "type": "GaussDB(for MySQL)", + "version": "8.0" + }, + "created": "2020-07-21T09:13:56+0800", + "updated": "2020-07-21T09:27:54+0800", + "public_ips": "", + "private_write_ips": [ + "192.168.0.235" + ], + "db_user_name": "root", + "port": "3306", + "vpc_id": "f7ee62e2-9705-4523-ba49-a85ea1a1fa87", + "subnet_id": "140af7bf-a9da-4dcf-8837-34199fd6d186", + "security_group_id": "c7f69884-fe2b-4630-8114-70a11499d902", + "backup_strategy": { + "start_time": "00:00-00:00", + "keep_days": "0" + }, + "nodes": [ + { + "id": "799a0f2fa49a4151bf9f7063c1fbba36no07", + "name": "gauss-d616-lb07_node01", + "type": "master", + "status": "FAILED", + "port": 3306, + "private_read_ips": [ + "192.168.0.163" + ], + "volume": { + "type": "POOL", + "used": "0.0" + }, + "az_code": "az1xahz", + "region_code": "cn-xianhz-1", + "flavor_id": "3169caaf-6c2f-41d5-aadd-c8fc3d83597e", + "flavor_ref": "taurus.large.4", + "max_connections": null, + "vcpus": "1", + "ram": "4", + "need_restart": false, + "priority": 1 + }, + { + "id": "816459d771c444db9fa4c1d5c173cb1cno07", + "name": "gauss-d616-lb07_node02", + "type": "slave", + "status": "FAILED", + "port": 3306, + "private_read_ips": [ + "192.168.0.160" + ], + "volume": { + "type": "POOL", + "used": "0.0" + }, + "az_code": "az1xahz", + "region_code": "cn-xianhz-1", + "flavor_id": "3169caaf-6c2f-41d5-aadd-c8fc3d83597e", + "flavor_ref": "taurus.large.4", + "max_connections": null, + "vcpus": "1", + "ram": "4", + "need_restart": false, + "priority": 1 + } + ], + "time_zone": "UTC+08:00", + "backup_used_space": 0, + "az_mode": "single", + "master_az_code": "az1xahz" + } + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_parameter_templates/index.rst b/api-ref/source/api/managing_parameter_templates/index.rst new file mode 100644 index 0000000..9288fcd --- /dev/null +++ b/api-ref/source/api/managing_parameter_templates/index.rst @@ -0,0 +1,14 @@ +:original_name: gaussdb_04_0008.html + +.. _gaussdb_04_0008: + +Managing Parameter Templates +============================ + +- :ref:`Querying a Parameter Template ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + querying_a_parameter_template diff --git a/api-ref/source/api/managing_parameter_templates/querying_a_parameter_template.rst b/api-ref/source/api/managing_parameter_templates/querying_a_parameter_template.rst new file mode 100644 index 0000000..fc25af0 --- /dev/null +++ b/api-ref/source/api/managing_parameter_templates/querying_a_parameter_template.rst @@ -0,0 +1,119 @@ +:original_name: gaussdb_04_0009.html + +.. _gaussdb_04_0009: + +Querying a Parameter Template +============================= + +Function +-------- + +This API is used to obtain a parameter template list, including all databases' default and custom parameter templates. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{*project_id*}/configurations + +- Example + + GET https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/configurations + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+============================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + +-----------------------+-----------------------+------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+========================================================================+ + | configurations | Array of objects | Parameter template list. | + | | | | + | | | For details, see :ref:`Table 3 `. | + +-----------------------+-----------------------+------------------------------------------------------------------------+ + | total_count | Integer | Total number of parameter templates. | + +-----------------------+-----------------------+------------------------------------------------------------------------+ + + .. _gaussdb_04_0009__table1324110018258: + + .. table:: **Table 3** configurations field data structure description + + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +========================+=======================+====================================================================================================================+ + | id | String | Parameter template ID. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | name | String | Parameter template name. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | description | String | Parameter template description. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | datastore_version_name | String | DB version name. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | datastore_name | String | DB name. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | created | String | Creation 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. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | updated | String | Update 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. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | user_defined | Boolean | Whether the parameter template is a custom template. | + | | | | + | | | - **false**: The parameter template is a default template. | + | | | - **true**: The parameter template is a custom template. | + +------------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + +- Example normal response + + .. code-block:: text + + { + "configurations":[ + { + "id":"1ad028f5f6b8482483948860feb33339pr07", + "name":"DBS_GaussDB_ParameterTemple_Apply_001", + "description":"GaussDB-Test", + "datastore_version_name":"8.0", + "datastore_name":"gaussdb-mysql", + "created":"2020-04-08 07:12:17", + "updated":"2020-04-08 07:12:17", + "user_defined":true, + } + ] + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_quotas/configuring_resource_quotas.rst b/api-ref/source/api/managing_quotas/configuring_resource_quotas.rst new file mode 100644 index 0000000..6ad80e9 --- /dev/null +++ b/api-ref/source/api/managing_quotas/configuring_resource_quotas.rst @@ -0,0 +1,130 @@ +:original_name: gaussdb_04_0012.html + +.. _gaussdb_04_0012: + +Configuring Resource Quotas +=========================== + +Function +-------- + +This API is used to set resource quotas for a specified enterprise project. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + POST https://{*Endpoint*}/mysql/v3/{project_id}/quotas + +- Example + + POST https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/quotas + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+============================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | quota_list | Yes | Quota details. A maximum of 10 quota records can be configured at a time. | + | | | | + | | | For details, see :ref:`Table 2 `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + +Request +------- + +- Parameter description + + .. _gaussdb_04_0012__table1453814912427: + + .. table:: **Table 2** quota_list field data structure description + + +-----------------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=========+==================================================================================================================================================================================================+ + | enterprise_project_id | String | Enterprise project ID. | + +-----------------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | instance_quota | Integer | DB instance quantity quota. The value ranges from **0** to **1000**. (If there are already DB instances created, this parameter value must be greater than the number of existing DB instances.) | + +-----------------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | vcpus_quota | Integer | vCPUs quota. The value ranges from **0** to **3600000**. (If there are already DB instances created, this parameter value must be greater than the number of used vCPUs.) | + +-----------------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ram_quota | Integer | Memory quota in GB. The value ranges from **0** to **19200000**. (If there are already DB instances created, this parameter value must be greater than the used memory size.) | + +-----------------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +- Request example + + .. code-block:: text + + { + "quota_list": [ + { + "enterprise_project_id": "0", + "instance_quota": 1, + "vcpus_quota": 4, + "ram_quota": 8 + } + ] + } + +Response +-------- + +- Parameter description + + .. table:: **Table 3** Parameter description + + +-----------------------+-----------------------+-------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+===================================================================+ + | quota_list | Array of objects | Configured quota information. | + | | | | + | | | For details, see :ref:`Table 4 `. | + +-----------------------+-----------------------+-------------------------------------------------------------------+ + + .. _gaussdb_04_0012__table66531170: + + .. table:: **Table 4** quota_list data structure description + + ===================== ======= ================================== + Name Type Description + ===================== ======= ================================== + enterprise_project_id String Enterprise project ID. + instance_quota Integer Quota of the DB instance quantity. + vcpus_quota Integer Quota of vCPUs. + ram_quota Integer Memory quota in GB. + ===================== ======= ================================== + +- Example response + + .. code-block:: text + + { + "quota_list": [ + { + "enterprise_project_id": "0", + "instance_quota": 1, + "vcpus_quota": 4, + "ram_quota": 8 + } + ] + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_quotas/index.rst b/api-ref/source/api/managing_quotas/index.rst new file mode 100644 index 0000000..1981941 --- /dev/null +++ b/api-ref/source/api/managing_quotas/index.rst @@ -0,0 +1,18 @@ +:original_name: gaussdb_04_0010.html + +.. _gaussdb_04_0010: + +Managing Quotas +=============== + +- :ref:`Querying Resource Quotas ` +- :ref:`Configuring Resource Quotas ` +- :ref:`Modifying Resource Quotas ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + querying_resource_quotas + configuring_resource_quotas + modifying_resource_quotas diff --git a/api-ref/source/api/managing_quotas/modifying_resource_quotas.rst b/api-ref/source/api/managing_quotas/modifying_resource_quotas.rst new file mode 100644 index 0000000..ea0afa0 --- /dev/null +++ b/api-ref/source/api/managing_quotas/modifying_resource_quotas.rst @@ -0,0 +1,132 @@ +:original_name: gaussdb_04_0013.html + +.. _gaussdb_04_0013: + +Modifying Resource Quotas +========================= + +Function +-------- + +This API is used to modify the resource quota of a specified enterprise project. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + PUT https://{*Endpoint*}/mysql/v3/{project_id}/quotas + +- Example + + PUT https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/quotas + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+----------------------------------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+====================================================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------------------------------+ + | quota_list | Yes | Enterprise project resource quotas to be updated. A maximum of 10 quotas can be updated at a time. | + | | | | + | | | For details, see :ref:`Table 2 `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------------------------------+ + +Request +------- + +- Parameter description + + .. _gaussdb_04_0013__table1252104315240: + + .. table:: **Table 2** quota_list field data structure description + + +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+=====================================================================================================================================================================================================================+ + | enterprise_project_id | String | Enterprise project ID. | + +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | instance_quota | Integer | Quota of the DB instance quantity. The value ranges from **0** to **1000**. (If there are already DB instances created, this parameter value must be greater than or equal to the number of existing DB instances.) | + +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | vcpus_quota | Integer | Quota of vCPUs. The value ranges from **0** to **3600000**. (If there are already DB instances created, this parameter value must be greater than or equal to the number of used vCPUs.) | + +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ram_quota | Integer | Memory quota in GB. | + | | | | + | | | Memory quota in GB. The value ranges from **0** to **19200000**. (If there are already DB instances created, this parameter value must be greater than or equal to the used memory size.) | + +-----------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +- Request example + + .. code-block:: text + + { + "quota_list": [ + { + "enterprise_project_id": "0", + "instance_quota": 1, + "vcpus_quota": 4, + "ram_quota": 8 + } + ] + } + +Response +-------- + +- Parameter description + + .. table:: **Table 3** Parameter description + + +-----------------------+-----------------------+-------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+===================================================================+ + | quota_list | Array of objects | Configured quota information. | + | | | | + | | | For details, see :ref:`Table 4 `. | + +-----------------------+-----------------------+-------------------------------------------------------------------+ + + .. _gaussdb_04_0013__table66531170: + + .. table:: **Table 4** quota_list field data structure description + + ===================== ======= ================================== + Name Type Description + ===================== ======= ================================== + enterprise_project_id String Enterprise project ID. + instance_quota Integer Quota of the DB instance quantity. + vcpus_quota Integer Quota of vCPUs. + ram_quota Integer Memory quota in GB. + ===================== ======= ================================== + +- Example response + + .. code-block:: text + + { + "quota_list": [ + { + "enterprise_project_id": "0", + "instance_quota": 1, + "vcpus_quota": 4, + "ram_quota": 8 + } + ] + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/managing_quotas/querying_resource_quotas.rst b/api-ref/source/api/managing_quotas/querying_resource_quotas.rst new file mode 100644 index 0000000..633fdbd --- /dev/null +++ b/api-ref/source/api/managing_quotas/querying_resource_quotas.rst @@ -0,0 +1,116 @@ +:original_name: gaussdb_04_0011.html + +.. _gaussdb_04_0011: + +Querying Resource Quotas +======================== + +Function +-------- + +This API is used to obtain the resource quota of a specified enterprise project. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{project_id}/quotas + +- Example + + GET https://{*Endpoint*}/mysql/v3/619d3e78f61b4be68bc5aa0b59edcf7b/quotas + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+=========================================================================================================================================================================================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | offset | No | Index position. 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 | Number of records to be queried. The default value is **10**. The value cannot be a negative number. The minimum value is **1** and the maximum value is **100**. | + +-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Request +------- + +None + +Response +-------- + +- Parameter description + + .. table:: **Table 2** Parameter description + + +-----------------------+-----------------------+-------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+===================================================================+ + | quota_list | Array of objects | Quota information list. | + | | | | + | | | For details, see :ref:`Table 3 `. | + +-----------------------+-----------------------+-------------------------------------------------------------------+ + | total_count | Integer | Number of quota records. | + +-----------------------+-----------------------+-------------------------------------------------------------------+ + + .. _gaussdb_04_0011__table66531170: + + .. table:: **Table 3** quota_list field data structure description + + =========================== ======= ================================== + Name Type Description + =========================== ======= ================================== + enterprise_project_id String Enterprise project ID. + instance_quota Integer Quota of the DB instance quantity. + vcpus_quota Integer Quota of vCPUs. + ram_quota Integer Memory quota in GB. + availability_instance_quota Integer Remaining quota of DB instances. + availability_vcpus_quota Integer Remaining quota of vCPU. + availability_ram_quota Integer Remaining memory quota. + =========================== ======= ================================== + +- Example response + + .. code-block:: text + + "quota_list": [ + { + "enterprise_project_id": "0", + "instance_quota": 20, + "vcpus_quota": 20, + "ram_quota": 40, + "availability_instance_quota": 1, + "availability_vcpus_quota ": 4, + "availability_ram_quota": 8 + }, + { + "enterprise_project_id": "d72ebb42-9110-464c-a8e2-f9b9f349f80f", + "instance_quota": 0, + "vcpus_quota": 0, + "ram_quota": 0, + "availability_instance_quota ": 1, + "availability_vcpus_quota ": 4, + "availability_ram_quota ": 8 + } + ], + "total_count": 2 + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/obtaining_task_information.rst b/api-ref/source/api/obtaining_task_information.rst new file mode 100644 index 0000000..0e4154e --- /dev/null +++ b/api-ref/source/api/obtaining_task_information.rst @@ -0,0 +1,186 @@ +:original_name: gaussdb_04_0014.html + +.. _gaussdb_04_0014: + +Obtaining Task Information +========================== + +Function +-------- + +This API is used to obtain task information from the task center. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{project_id}/jobs?id={id} + +- Example + + GET https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/jobs?id=a9767ede-fe0f-4888-9003-e843a4c90514 + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+============================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + | id | Yes | Task ID. | + +-----------------------+-----------------------+----------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + +------+--------+-------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +======+========+===========================================================================================+ + | job | Object | Task information. For details, see :ref:`Table 3 `. | + +------+--------+-------------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0014__table54571314103317: + + .. table:: **Table 3** job field data structure description + + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+====================================================================================================================+ + | id | String | Task ID. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | name | String | Task name. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | status | String | Task execution status. | + | | | | + | | | Valid value: | + | | | | + | | | - **Running**: The task is being executed. | + | | | - **Completed**: The task is successfully executed. | + | | | - **Failed**: The task fails to be executed. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | created | String | Creation 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. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | process | String | Task execution progress. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | instance | Object | DB instance on which the task is executed. | + | | | | + | | | For details, see :ref:`Table 4 `. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | entities | Object | Displayed information varies depending on tasks. | + | | | | + | | | For details, see :ref:`Table 5 `. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + | fail_reason | String | Task failure information. | + +-----------------------+-----------------------+--------------------------------------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0014__table4062895917262: + + .. table:: **Table 4** instances field data structure description + + ==== ====== ================= + Name Type Description + ==== ====== ================= + id String DB instance ID. + name String DB instance name. + ==== ====== ================= + + .. _gaussdb_04_0014__table1014617554138: + + .. table:: **Table 5** entities field data structure description + + +-----------------------+-----------------------+-----------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+=======================================================================+ + | instance | Object | DB instance queried in the task. | + | | | | + | | | For details, see :ref:`Table 6 `. | + +-----------------------+-----------------------+-----------------------------------------------------------------------+ + | resource_ids | List | Resource ID involved in a task. | + +-----------------------+-----------------------+-----------------------------------------------------------------------+ + + .. _gaussdb_04_0014__table975183423611: + + .. table:: **Table 6** entities.instance field data structure description + + +-----------+--------+---------------------------------------------------------------------------------------+ + | Name | Type | Description | + +===========+========+=======================================================================================+ + | endpoint | String | DB instance connection address. | + +-----------+--------+---------------------------------------------------------------------------------------+ + | type | String | DB instance type. | + +-----------+--------+---------------------------------------------------------------------------------------+ + | datastore | Object | DB information. For details, see :ref:`Table 7 `. | + +-----------+--------+---------------------------------------------------------------------------------------+ + + .. _gaussdb_04_0014__table173094268581: + + .. table:: **Table 7** datastore field data structure description + + ======= ====== =========== + Name Type Description + ======= ====== =========== + type String DB engine. + version String DB version. + ======= ====== =========== + + .. table:: **Table 8** entities field data structure description (binding or unbinding an EIP) + + ========= ====== ===================== + Name Type Description + ========= ====== ===================== + public_ip String EIP used in the task. + ========= ====== ===================== + + .. note:: + + In the response example, some tasks in the task center are used as examples. + +- Example normal response + + .. code-block:: text + + { + "job": { + "id": "31b8ae23-c687-4d80-b7b4-42a66c9bb886", + "name": " RestartGaussDBInstance", + "status": "Completed", + "created": "2018-08-06T10:41:14+0000", + "ended": "2018-08-06T16:41:14+0000", + "process": "", + "instance": { + "id": "a48e43ff268f4c0e879652d65e63d0fbin01", + "name": "DO-NOT-TOUCH-mgr2-gaussdb" + }, + "entities": {} + } + } + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/querying_database_specifications.rst b/api-ref/source/api/querying_database_specifications.rst new file mode 100644 index 0000000..1338106 --- /dev/null +++ b/api-ref/source/api/querying_database_specifications.rst @@ -0,0 +1,142 @@ +:original_name: gaussdb_04_0002.html + +.. _gaussdb_04_0002: + +Querying Database Specifications +================================ + +Function +-------- + +This API is used to query the database specifications of a specified DB engine version. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{project_id}/flavors/{database}?version_name={version_name}&spec_code={spec_code} + +- Example + + GET https://{*Endpoint*}/mysql/v3/0483b6b16e954cb88930a360d2c4e663/flavors/gaussdb-mysql?version_name=8.0&spec_code=gaussdb.mysql.xlarge.x86.4 + +- Parameter description + + .. table:: **Table 1** Parameter description + + +------------------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------+ + | Name | 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 `. | + +------------------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------+ + | database | Yes | String | DB engine. Its value can be any of the following and is case-insensitive: | + | | | | | + | | | | - gaussdb-mysql | + +------------------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------+ + | version_name | No | String | DB version number. To obtain this value, see :ref:`Querying Version Information About a DB Engine `. | + | | | | | + | | | | Currently, only MySQL 8.0 is supported. | + +------------------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------+ + | availability_zone_mode | Yes | String | AZ type of the specification. The value can be **single** or **multi**. | + +------------------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------+ + | spec_code | No | String | Specification code. | + +------------------------+-----------------+-----------------+-----------------------------------------------------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + +-----------------------+-----------------------+-------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+===================================================================+ + | flavors | Array of objects | DB instance specification list. | + | | | | + | | | For details, see :ref:`Table 3 `. | + +-----------------------+-----------------------+-------------------------------------------------------------------+ + + .. _gaussdb_04_0002__table66531170: + + .. table:: **Table 3** flavors field data structure description + + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+==========================================================================================+ + | vcpus | String | Number of vCPUs. For example, the value **1** indicates 1 vCPU. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | ram | Integer | Memory size in gigabyte (GB). | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | type | String | Specification type. The value can be **arm** or **x86**. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | id | String | Specification ID. The value must be unique. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | spec_code | String | Resource specification code. For example: gaussdb.mysql.xlarge.x86.4. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | version_name | String | DB version number. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | instance_mode | String | DB instance type. Currently, only the cluster type is supported. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + | az_status | Map | Status of the AZ where the specification belongs. Its value can be any of the following: | + | | | | + | | | - **normal**: on sale. | + | | | - **unsupported**: not supported. | + | | | - **sellout**: sold out. | + +-----------------------+-----------------------+------------------------------------------------------------------------------------------+ + +- Example normal response + + .. code-block:: text + + { + "flavors":[ + { + "vcpus":"1", + "ram":"4", + "type":"x86" + "id":"3169caaf-6c2f-41d5-aadd-c8fc3d83597e", + "spec_code":"gaussdb.xlarge.x86.4", + "instance_mode":"Cluster", + "version_name": "8.0", + "az_status":{ + "az1":"normal", + "az2":"normal" + } + }, + { + "vcpus":"2", + "ram":"4", + "type":"arm" + "id":"cefb8fab-c9f7-482f-a97c-e8a0c8abe35b", + "spec_code":"gaussdb.mysql.xlarge.x86.2", + "instance_mode":"Cluster", + "version_name": "8.0", + "az_status":{ + "az1":"normal", + "az2":"normal" + } + } + ] + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api/querying_version_information_about_a_db_engine.rst b/api-ref/source/api/querying_version_information_about_a_db_engine.rst new file mode 100644 index 0000000..042ece1 --- /dev/null +++ b/api-ref/source/api/querying_version_information_about_a_db_engine.rst @@ -0,0 +1,92 @@ +:original_name: gaussdb_04_0001.html + +.. _gaussdb_04_0001: + +Querying Version Information About a DB Engine +============================================== + +Function +-------- + +This API is used to query the DB version information of a specified DB engine. + +- Learn how to :ref:`authorize and authenticate ` this API before using it. +- Before calling this API, obtain the required :ref:`region and endpoint `. + +URI +--- + +- URI format + + GET https://{*Endpoint*}/mysql/v3/{project_id}/datastores/{database_name} + +- Example + + GET https://{*Endpoint*}/mysql/v3/619d3e78f61b4be68bc5aa0b59edcf7b/datastores/gaussdb-mysql + +- Parameter description + + .. table:: **Table 1** Parameter description + + +-----------------------+-----------------------+-----------------------------------------------------------------------------------+ + | Name | Mandatory | Description | + +=======================+=======================+===================================================================================+ + | project_id | Yes | Project ID of a tenant in a region. | + | | | | + | | | To obtain this value, see :ref:`Obtaining a Project ID `. | + +-----------------------+-----------------------+-----------------------------------------------------------------------------------+ + | database_name | Yes | DB engine. The following DB engine is supported (case-insensitive): gaussdb-mysql | + +-----------------------+-----------------------+-----------------------------------------------------------------------------------+ + +Request +------- + +None. + +Response +-------- + +- Normal response + + .. table:: **Table 2** Parameter description + + +-----------------------+-----------------------+-------------------------------------------------------------------+ + | Name | Type | Description | + +=======================+=======================+===================================================================+ + | datastores | Array of objects | DB version list. | + | | | | + | | | For details, see :ref:`Table 3 `. | + +-----------------------+-----------------------+-------------------------------------------------------------------+ + + .. _gaussdb_04_0001__table66531170: + + .. table:: **Table 3** datastores field data structure description + + +------+--------+-------------------------------------------------------------------------------+ + | Name | Type | Description | + +======+========+===============================================================================+ + | id | String | DB version ID. Its value is unique. | + +------+--------+-------------------------------------------------------------------------------+ + | name | String | DB version number. Only the major version number with two digits is returned. | + +------+--------+-------------------------------------------------------------------------------+ + +- Example normal response + + .. code-block:: text + + { + "datastores": [{ + "id": "87620726-6802-46c0-9028-a8785e1f1921", + "name": "8.0" + }] + } + +Status Code +----------- + +For details, see :ref:`Status Codes `. + +Error Code +---------- + +For details, see :ref:`Error Codes `. diff --git a/api-ref/source/api_overview.rst b/api-ref/source/api_overview.rst new file mode 100644 index 0000000..1c9e176 --- /dev/null +++ b/api-ref/source/api_overview.rst @@ -0,0 +1,24 @@ +:original_name: gaussdb_02_0000.html + +.. _gaussdb_02_0000: + +API Overview +============ + +With GaussDB(for MySQL) APIs, you can query, set, and modify resource quotas. + ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Type | Description | ++===============================+===============================================================================================================================================+ +| DB engine version query | Query the DB version information of a specified DB engine. | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| DB specifications query | Query the DB specifications of a specified DB engine version. | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| DB instance management | Create DB instances, query DB instance lists, query DB instance details, delete DB instances, create read replicas, and delete read replicas. | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Parameter template management | Query parameter templates. | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Quota management | Query, set, and modify resource quotas. | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Task information query | Obtain task information about the task center. | ++-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/appendix/abnormal_request_results.rst b/api-ref/source/appendix/abnormal_request_results.rst new file mode 100644 index 0000000..fc0d398 --- /dev/null +++ b/api-ref/source/appendix/abnormal_request_results.rst @@ -0,0 +1,27 @@ +:original_name: gaussdb_10_0001.html + +.. _gaussdb_10_0001: + +Abnormal Request Results +======================== + +- Abnormal response description + + .. table:: **Table 1** Abnormal response description + + +------------+--------+---------------------------------------------------------------------------------------------------------------------+ + | Name | Type | Description | + +============+========+=====================================================================================================================+ + | error_code | String | Returned error code when a task submission exception occurs. For details, see :ref:`Error Codes `. | + +------------+--------+---------------------------------------------------------------------------------------------------------------------+ + | error_msg | String | Returned error description when a task submission exception occurs. | + +------------+--------+---------------------------------------------------------------------------------------------------------------------+ + +- Example response + + .. code-block:: text + + { + "error_code": "DBS.280234", + "error_msg": "Invalid DB instance name." + } diff --git a/api-ref/source/appendix/error_codes.rst b/api-ref/source/appendix/error_codes.rst new file mode 100644 index 0000000..dfa5a25 --- /dev/null +++ b/api-ref/source/appendix/error_codes.rst @@ -0,0 +1,90 @@ +:original_name: gaussdb_10_0003.html + +.. _gaussdb_10_0003: + +Error Codes +=========== + +The following table describes error codes. + +.. table:: **Table 1** Error codes + + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | Error Code | Response Code | Description | + +============+===============+=================================================================================================+ + | DBS.200040 | 400 | The DB engine type must be specified. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.200041 | 400 | Invalid DB engine type. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.200051 | 500 | Invalid deployment mode. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.200910 | 400 | The maximum number of read replicas has been reached. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280203 | 400 | This is a weak password. Please enter a strong password. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280216 | 400 | Invalid backup start time. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280227 | 400 | The new storage space must be greater than the current storage and must be a multiple of 10 GB. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280234 | 400 | Invalid DB instance name. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280235 | 400 | Invalid database type. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280236 | 400 | Invalid database version. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280237 | 400 | DB engine information must be specified. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280238 | 400 | The DB engine or version is not supported. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280242 | 400 | Storage space is out of range. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280243 | 400 | Invalid region. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280247 | 400 | Invalid VPC ID. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280248 | 400 | Invalid subnet ID. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280260 | 400 | Invalid AZ. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280266 | 400 | Storage space must be a multiple of 10. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280288 | 400 | Invalid specification code. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280305 | 400 | Invalid security group. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280311 | 400 | Storage space must be specified. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280342 | 400 | Invalid cluster mode. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280365 | 400 | Invalid billing mode. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280431 | 400 | Invalid billing period. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280433 | 400 | Invalid enterprise project ID. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280434 | 400 | Invalid specification code | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280447 | 400 | Invalid time zone. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280448 | 400 | The storage type is sold out. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280450 | 400 | The DB instance specifications are sold out. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280462 | 400 | Invalid auto renewal parameter. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280463 | 400 | Invalid auto payment parameter. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280464 | 400 | Primary AZ cannot be defined in a single AZ. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280465 | 400 | Invalid password. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280466 | 400 | Invalid read replica quantity. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280467 | 400 | Invalid read replica failover priority. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280468 | 400 | Invalid DB instance type. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280470 | 400 | The primary node and read replicas must be located in different AZs. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ + | DBS.280471 | 500 | CBC error. | + +------------+---------------+-------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/appendix/gaussdbfor_mysql_monitoring_metrics.rst b/api-ref/source/appendix/gaussdbfor_mysql_monitoring_metrics.rst new file mode 100644 index 0000000..c83fa50 --- /dev/null +++ b/api-ref/source/appendix/gaussdbfor_mysql_monitoring_metrics.rst @@ -0,0 +1,187 @@ +:original_name: gaussdb_10_0006.html + +.. _gaussdb_10_0006: + +GaussDB(for MySQL) Monitoring Metrics +===================================== + +Function Description +-------------------- + +This section describes namespaces, descriptions, and dimensions of monitoring metrics to be reported to Cloud Eye. You can use APIs provided by Cloud Eye to retrieve monitoring metrics and alarm information generated for GaussDB(for MySQL). + +Namespace +--------- + +SYS.GAUSSDB + +Monitoring Metrics +------------------ + +.. table:: **Table 1** Monitoring metrics + + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | Metric | Name | Description | Value Range | Remarks | + +================================================+================================================+===================================================================================================+====================+======================================================+ + | gaussdb_mysql001_cpu_util | CPU Usage | CPU usage of the monitored object | 0-100% | Monitored object: ECS | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql002_mem_util | Memory Usage | Memory usage of the monitored object | 0-100% | Monitored object: ECS | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql004_bytes_in | Network Input Throughput | Incoming traffic in bytes per second | >=0 Bytes/s | Monitored object: ECS | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql005_bytes_out | Network Output Throughput | Outgoing traffic in bytes per second | >=0 Bytes/s | Monitored object: ECS | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql006_conn_count | Total Connections | Total number of connections that attempt to connect to the MySQL server | >=0 Counts | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql007_conn_active_count | Current Active Connections | Number of current active connections | >=0 Counts | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql008_qps | QPS | Query times of SQL statements (including storage procedures) per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql009_tps | TPS | Execution times of submitted and rollback transactions per second | >=0 Transactions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql010_innodb_buf_usage | Buffer Pool Usage | Ratio of dirty data to all data in the InnoDB buffer | 0-1 | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql011_innodb_buf_hit | Buffer Pool Hit Ratio | Ratio of read hits to read requests in the InnoDB buffer | 0-100% | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql012_innodb_buf_dirty | Buffer Pool Dirty Block Ratio | Ratio of used pages to total pages in the InnoDB buffer | 0-1 | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql013_innodb_reads | InnoDB Read Throughput | Number of read bytes per second in the InnoDB buffer | >=0 Bytes/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql014_innodb_writes | InnoDB Write Throughput | Number of write bytes per second in the InnoDB buffer | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql017_innodb_log_write_req_count | InnoDB Log Write Requests per Second | Number of InnoDB log write requests per second | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql020_temp_tbl_count | Temporary Tables | Number of temporary tables automatically created on hard disks when MySQL statements are executed | >=0 Counts | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql028_comdml_del_count | DELETE Statements per Second | Number of DELETE statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql029_comdml_ins_count | INSERT Statements per Second | Number of INSERT statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql030_comdml_ins_sel_count | INSERT_SELECT Statements per Second | Number of INSERT_SELECT statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql031_comdml_rep_count | REPLACE Statements per Second | Number of REPLACE statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql032_comdml_rep_sel_count | REPLACE_SELECTION Statements per Second | Number of REPLACE_SELECTION statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql033_comdml_sel_count | SELECT Statements per Second | Number of SELECT statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql034_comdml_upd_count | UPDATE Statements per Second | Number of UPDATE statements executed per second | >=0 Executions/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql035_innodb_del_row_count | Row Delete Frequency | Number of rows deleted from the InnoDB table per second | >=0 Rows/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql036_innodb_ins_row_count | Row Insert Frequency | Number of rows inserted into the InnoDB table per second | >=0 Rows/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql037_innodb_read_row_count | Row Read Frequency | Number of rows read from the InnoDB table per second | >=0 Rows/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql038_innodb_upd_row_count | Row Update Frequency | Number of rows updated into the InnoDB table per second | >=0 Rows/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql048_disk_used_size | Used Storage Space | Used storage space of the monitored object | 0-4000 GB | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql072_conn_usage | Connection Usage | Percent of used MySQL connections to the total number of connections | 0~100% | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql074_slow_queries | Slow Query Logs | Number of MySQL slow query logs generated per minute | >=0 Counts/Minute | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql077_replication_delay | Replication Delay | Data replication delay between the primary node and read replicas | >=0 s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql104_dfv_write_delay | Storage Write Latency | Average latency of writing data to the storage layer in a specified period | >=0 ms | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql105_dfv_read_delay | Storage Read Latency | Average latency of reading data from the storage layer in a specified period | >=0 ms | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql106_innodb_row_lock_current_waits | InnoDB Row Locks | Number of row locks being waited by operations on the InnoDB table | >=0 Counts | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql107_comdml_ins_and_ins_sel_count | INSERT and INSERT_SELECT Statements per Second | Number of INSERT and INSERT_SELECT statements executed per second | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql108_com_commit_count | COMMIT Statements per Second | Number of COMMIT statements executed per second | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql109_com_rollback_count | ROLLBACK Statements per Second | Number of ROLLBACK statements executed per second | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql110_innodb_bufpool_reads | InnoDB Storage Layer Read Requests per Second | Number of times that InnoDB reads data from the storage layer per second | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + | gaussdb_mysql111_innodb_bufpool_read_requests | InnoDB Read Requests per Second | Number of InnoDB read requests per second | >=0 Counts/s | Monitored object: database | + | | | | | | + | | | | | Monitored instance type: GaussDB(for MySQL) instance | + +------------------------------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------+--------------------+------------------------------------------------------+ + +Dimension +--------- + +========================= ============================================ +Key Value +========================= ============================================ +gaussdb_mysql_instance_id GaussDB (for MySQL) instance ID. +gaussdb_mysql_node_id Node ID of the GaussDB (for MySQL) instance. +========================= ============================================ diff --git a/api-ref/source/appendix/index.rst b/api-ref/source/appendix/index.rst new file mode 100644 index 0000000..414b142 --- /dev/null +++ b/api-ref/source/appendix/index.rst @@ -0,0 +1,22 @@ +:original_name: gaussdb_10_0000.html + +.. _gaussdb_10_0000: + +Appendix +======== + +- :ref:`Abnormal Request Results ` +- :ref:`Status Codes ` +- :ref:`Error Codes ` +- :ref:`Obtaining a Project ID ` +- :ref:`GaussDB(for MySQL) Monitoring Metrics ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + abnormal_request_results + status_codes + error_codes + obtaining_a_project_id + gaussdbfor_mysql_monitoring_metrics diff --git a/api-ref/source/appendix/obtaining_a_project_id.rst b/api-ref/source/appendix/obtaining_a_project_id.rst new file mode 100644 index 0000000..c03b2d1 --- /dev/null +++ b/api-ref/source/appendix/obtaining_a_project_id.rst @@ -0,0 +1,66 @@ +:original_name: gaussdb_10_0004.html + +.. _gaussdb_10_0004: + +Obtaining a Project ID +====================== + +Scenarios +--------- + +When calling APIs, you need to specify the project ID in some URLs. To do so, you need to obtain the project ID first. Two methods are available: + +- :ref:`Obtaining the Project ID by Calling an API ` +- :ref:`Obtain a Project ID from the Console ` + +.. _gaussdb_10_0004__section85791974381: + +Obtaining the Project ID by Calling an API +------------------------------------------ + +The API used to obtain a project ID is **GET https://{Endpoint}/v3/projects**. **{Endpoint}** is the IAM endpoint and can be obtained from `Regions and Endpoints `__. For details about API authentication, see :ref:`Authentication `. + +The following is an example response. The value of **id** is the project ID. + +.. code-block:: + + { + "projects": [ + { + "domain_id": "65382450e8f64ac0870cd180d14e684b", + "is_domain": false, + "parent_id": "65382450e8f64ac0870cd180d14e684b", + "name": "project_name", + "description": "", + "links": { + "next": null, + "previous": null, + "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22cd05f897d6b99" + }, + "id": "a4a5d4098fb4474fa22cd05f897d6b99", + "enabled": true + } + ], + "links": { + "next": null, + "previous": null, + "self": "https://www.example.com/v3/projects" + } + } + +.. _gaussdb_10_0004__section196091152113715: + +Obtain a Project ID from the Console +------------------------------------ + +#. Register yourself on the management console and log in to it. + +#. Move your pointer over the username and select My Credentials in the displayed drop-down list. + + On the **My Credentials** page, view project IDs in the project list. + + + .. figure:: /_static/images/en-us_image_0000001423128721.jpg + :alt: **Figure 1** Viewing project IDs + + **Figure 1** Viewing project IDs diff --git a/api-ref/source/appendix/status_codes.rst b/api-ref/source/appendix/status_codes.rst new file mode 100644 index 0000000..727eb55 --- /dev/null +++ b/api-ref/source/appendix/status_codes.rst @@ -0,0 +1,120 @@ +:original_name: gaussdb_10_0002.html + +.. _gaussdb_10_0002: + +Status Codes +============ + +Status code list: + +.. table:: **Table 1** Status Code + + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Status Code | Message | Description | + +=======================+===============================+=====================================================================================================================================================================================================================================================================================================================================================+ + | 100 | Continue | The client should continue with its request. | + | | | | + | | | This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 101 | Switching Protocols | The protocol should be switched. The protocol can only be switched to a more advanced protocol. | + | | | | + | | | For example, the current HTTP protocol is switched to a later version. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 200 | OK | Request succeeded. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 201 | Created | The request for creating a resource or task has been fulfilled. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 202 | Accepted | The request has been accepted, but the processing has not been completed. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 203 | Non-Authoritative Information | Unauthorized information. The request is successful. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 204 | NoContent | The server has successfully processed the request, but has not returned any content. | + | | | | + | | | The status code is returned in response to an HTTP OPTIONS request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 205 | Reset Content | The server has fulfilled the request, but the requester is required to reset the content. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 206 | Partial Content | The server has processed certain GET requests. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 300 | Multiple Choices | There are multiple options for the location of the requested resource. The response contains a list of resource characteristics and addresses from which the user or user agent (such as a browser) can choose the most appropriate one. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 301 | Moved Permanently | The requested resource has been assigned a new permanent URI, and the new URI is contained in the response. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 302 | Found | The requested resource was temporarily moved. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 303 | See Other | The response to the request can be found under a different URI and should be retrieved using a GET or POST method. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 304 | Not Modified | The requested resource has not been modified. In such a case, there is no need to retransmit the resource since the client still has a previously-downloaded copy. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 305 | Use Proxy | The requested resource must be accessed through a proxy. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 306 | Unused | The HTTP status code is no longer used. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 400 | BadRequest | Invalid request. | + | | | | + | | | The client should not repeat the request without modifications. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 401 | Unauthorized | The status code is returned after the client provides the authentication information, indicating that the authentication information is incorrect or invalid. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 402 | Payment Required | This status code is reserved for future use. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 403 | Forbidden | The server understood the request, but is refusing to fulfill it. | + | | | | + | | | The client should not repeat the request without modifications. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 404 | NotFound | The requested resource cannot be found. | + | | | | + | | | The client should not repeat the request without modifications. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 405 | MethodNotAllowed | The method specified in the request is not supported for the requested resource. | + | | | | + | | | The client should not repeat the request without modifications. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 406 | Not Acceptable | The server cannot fulfill the request according to the content characteristics of the request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 407 | Proxy Authentication Required | This status code is similar to 401, but indicates that the client must first authenticate itself with the proxy. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 408 | Request Time-out | The server timed out waiting for the request. | + | | | | + | | | The client may repeat the request without modifications at any later time. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 409 | Conflict | The request could not be processed due to a conflict. | + | | | | + | | | This status code indicates that the resource that the client attempts to create already exits, or the request fails to be processed because of the update of the conflict request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 410 | Gone | The requested resource is no longer available. | + | | | | + | | | The requested resource has been deleted permanently. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 411 | Length Required | The server refuses to process the request without a defined Content-Length. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 412 | Precondition Failed | The server does not meet one of the preconditions that the requester puts on the request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 413 | Request Entity Too Large | The request is larger than that a server is able to process. The server may close the connection to prevent the client from continuing the request. If the server temporarily cannot process the request, the response will contain a Retry-After header field. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 414 | Request-URI Too Large | The URI provided was too long for the server to process. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 415 | Unsupported Media Type | The server is unable to process the media format in the request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 416 | Requested range not satisfied | The requested range is invalid. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 417 | Expectation Failed | The server fails to meet the requirements of the Expect request-header field. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 422 | UnprocessableEntity | The request is well-formed but is unable to be processed due to semantic errors. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 429 | TooManyRequests | The client has sent more requests than its rate limit is allowed within a given amount of time, or the server has received more requests than it is able to process within a given amount of time. In this case, it is advisable for the client to re-initiate requests after the time specified in the Retry-After header of the response expires. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 500 | InternalServerError | The server is able to receive the request but it could not understand the request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 501 | Not Implemented | The server does not support the requested function. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 502 | Bad Gateway | The server acting as a gateway or proxy receives an invalid response from a remote server. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 503 | ServiceUnavailable | The requested service is invalid. | + | | | | + | | | The client should not repeat the request without modifications. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 504 | ServerTimeout | The request cannot be fulfilled within a given time. The response will reach the client only if the request carries a timeout parameter. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | 505 | HTTP Version not supported | The server does not support the HTTP protocol version used in the request. | + +-----------------------+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/api-ref/source/before_you_start/api_calling.rst b/api-ref/source/before_you_start/api_calling.rst new file mode 100644 index 0000000..d5add04 --- /dev/null +++ b/api-ref/source/before_you_start/api_calling.rst @@ -0,0 +1,8 @@ +:original_name: gaussdb_00_0002.html + +.. _gaussdb_00_0002: + +API Calling +=========== + +GaussDB(for MySQL) supports Representational State Transfer (REST) APIs, allowing you to call APIs using HTTPS. For details about API calling, see :ref:`Calling APIs `. diff --git a/api-ref/source/before_you_start/concepts.rst b/api-ref/source/before_you_start/concepts.rst new file mode 100644 index 0000000..edf7788 --- /dev/null +++ b/api-ref/source/before_you_start/concepts.rst @@ -0,0 +1,34 @@ +:original_name: gaussdb_00_0005.html + +.. _gaussdb_00_0005: + +Concepts +======== + +- Domain + + A domain is created upon successful registration. The domain has full access permissions for all of its cloud services and resources. It can be used to reset user passwords and grant user permissions. The domain is a payment entity and should not be used directly to perform routine management. For security purposes, create users and grant them permissions for routine management. + +- IAM User + + An IAM user is created using an account to use cloud services. Each IAM user has its own identity credentials (password and access keys). + + API authentication requires information such as the account name, username, and password. + +- Region + + A region is a geographic area in which cloud resources are deployed. Availability zones (AZs) in the same region can communicate with each other over an intranet, while AZs in different regions are isolated from each other. Deploying cloud resources in different regions can better suit certain user requirements or comply with local laws or regulations. + +- AZ + + An AZ contains one or more physical data centers. Each AZ has independent cooling, fire extinguishing, moisture-proof, and electricity facilities. Within an AZ, computing, network, storage, and other resources are logically divided into multiple clusters. AZs within a region are interconnected using high-speed optical fibers to support cross-AZ high-availability systems. + +- Project + + Projects group and isolate resources (including compute, storage, and network resources) across physical regions. A default project is provided for each region, and subprojects can be created under each default project. Users can be granted permissions to access all resources in a specific project. For more refined access control, create subprojects under a project and purchase resources in the subprojects. Users can then be assigned permissions to access only specific resources in the subprojects. + + + .. figure:: /_static/images/en-us_image_0000001422968749.gif + :alt: **Figure 1** Project isolating model + + **Figure 1** Project isolating model diff --git a/api-ref/source/before_you_start/constraints.rst b/api-ref/source/before_you_start/constraints.rst new file mode 100644 index 0000000..84936e1 --- /dev/null +++ b/api-ref/source/before_you_start/constraints.rst @@ -0,0 +1,9 @@ +:original_name: gaussdb_00_0004.html + +.. _gaussdb_00_0004: + +Constraints +=========== + +- The number of DB instances that you can create is determined by your quota. To view or increase the quota, see "Managing Quotas" in the *GaussDB(for MySQL) User Guide*. +- For more constraints, see API description. diff --git a/api-ref/source/before_you_start/endpoints.rst b/api-ref/source/before_you_start/endpoints.rst new file mode 100644 index 0000000..e8b9513 --- /dev/null +++ b/api-ref/source/before_you_start/endpoints.rst @@ -0,0 +1,8 @@ +:original_name: gaussdb_00_0003.html + +.. _gaussdb_00_0003: + +Endpoints +========= + +An endpoint is the **request address** for calling an API. Endpoints vary depending on services and regions. For the endpoints of all services, see `Regions and Endpoints `__. diff --git a/api-ref/source/before_you_start/index.rst b/api-ref/source/before_you_start/index.rst new file mode 100644 index 0000000..e10b14a --- /dev/null +++ b/api-ref/source/before_you_start/index.rst @@ -0,0 +1,22 @@ +:original_name: gaussdb_00_0011.html + +.. _gaussdb_00_0011: + +Before You Start +================ + +- :ref:`Overview ` +- :ref:`API Calling ` +- :ref:`Endpoints ` +- :ref:`Constraints ` +- :ref:`Concepts ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + overview + api_calling + endpoints + constraints + concepts diff --git a/api-ref/source/before_you_start/overview.rst b/api-ref/source/before_you_start/overview.rst new file mode 100644 index 0000000..5ace8db --- /dev/null +++ b/api-ref/source/before_you_start/overview.rst @@ -0,0 +1,10 @@ +:original_name: gaussdb_00_0001.html + +.. _gaussdb_00_0001: + +Overview +======== + +This document describes how to use application programming interfaces (APIs) to perform operations on DB instances. For details about all supported operations, see :ref:`API Overview `. + +If you plan to access GaussDB(for MySQL) through an API, ensure that you are familiar with GaussDB(for MySQL) concepts. For details, see "What Is GaussDB(for MySQL)?" in the *GaussDB(for MySQL) User Guide*. diff --git a/api-ref/source/calling_apis/authentication.rst b/api-ref/source/calling_apis/authentication.rst new file mode 100644 index 0000000..0a507ac --- /dev/null +++ b/api-ref/source/calling_apis/authentication.rst @@ -0,0 +1,28 @@ +:original_name: gaussdb_03_0001.html + +.. _gaussdb_03_0001: + +Authentication +============== + +Token authentication must be performed to call APIs. + +Authentication using tokens: General requests are authenticated using tokens. + +Token-based Authentication +-------------------------- + +.. note:: + + The validity period of a token is 24 hours. When using a token for authentication, cache it to prevent frequently calling the IAM API used to obtain a user token. + +A token specifies temporary permissions in a computer system. During API authentication using a token, the token is added to requests to get permissions for calling the API. + +In :ref:`Making an API Request `, the process of calling the API used to `obtain a user token `__ is described. + +After a token is obtained, add the **X-Auth-Token** header field must be added to requests to specify the token when calling other APIs. For example, if the token is **ABCDEFJ....**, **X-Auth-Token: ABCDEFJ....** can be added to a request as follows: + +:: + + Content-Type: application/json + X-Auth-Token: ABCDEFJ.... diff --git a/api-ref/source/calling_apis/index.rst b/api-ref/source/calling_apis/index.rst new file mode 100644 index 0000000..308827b --- /dev/null +++ b/api-ref/source/calling_apis/index.rst @@ -0,0 +1,18 @@ +:original_name: gaussdb_03_0000.html + +.. _gaussdb_03_0000: + +Calling APIs +============ + +- :ref:`Making an API Request ` +- :ref:`Authentication ` +- :ref:`Response ` + +.. toctree:: + :maxdepth: 1 + :hidden: + + making_an_api_request + authentication + response diff --git a/api-ref/source/calling_apis/making_an_api_request.rst b/api-ref/source/calling_apis/making_an_api_request.rst new file mode 100644 index 0000000..ecdf93a --- /dev/null +++ b/api-ref/source/calling_apis/making_an_api_request.rst @@ -0,0 +1,132 @@ +:original_name: gaussdb_03_0005.html + +.. _gaussdb_03_0005: + +Making an API Request +===================== + +This section describes the structure of a REST API, and uses the IAM API for `obtaining a user token `__ as an example to describe how to call an API. The obtained token is used to authenticate the calling of other APIs. + +Request URI +----------- + +A request URI consists of the following: + +**{URI-scheme}://{Endpoint}/{resource-path}?{query-string}** + +Although a request URI is included in a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message. + +.. table:: **Table 1** Parameters in a URI + + +---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Parameter | Description | + +===============+===================================================================================================================================================================================================================================================================+ + | URI-scheme | Protocol used to transmit requests. All APIs use HTTPS. | + +---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Endpoint | Domain name or IP address of the server bearing the REST service. The endpoint varies between services in different regions. It can be obtained from `Regions and Endpoints `__. | + +---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | resource-path | Access path of an API for performing a specified operation. Obtain the path from the URI of an API. For example, the **resource-path** of the API used to obtain a user token is **/v3/auth/tokens**. | + +---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | query-string | Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "Parameter name=Parameter value". For example, **? limit=10** indicates that a maximum of 10 data records will be displayed. | + +---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. note:: + + To simplify the URI display in this document, each API is provided only with a resource-path and a request method. The **URI-scheme** of all APIs is **HTTPS**, and the endpoints of all APIs in the same region are identical. + +Request Methods +--------------- + +The HTTP protocol defines the following request methods that can be used to send a request to the server: + +.. table:: **Table 2** HTTP methods + + +--------+---------------------------------------------------------------------+ + | Method | Description | + +========+=====================================================================+ + | GET | Requests the server to return specified resources. | + +--------+---------------------------------------------------------------------+ + | PUT | Requests the server to update specified resources. | + +--------+---------------------------------------------------------------------+ + | POST | Requests the server to add resources or perform special operations. | + +--------+---------------------------------------------------------------------+ + +For example, in the case of the API used to `obtain a user token `__, the request method is POST. The request is as follows: + +Request Header +-------------- + +You can also add additional fields to a request, such as the fields required by a specified URI or an HTTP method. For example, to request for the authentication information, add **Content-Type**, which specifies the request body type. + +:ref:`Table 3 ` lists common request header fields. + +.. _gaussdb_03_0005__table1986821153312: + +.. table:: **Table 3** Common request headers + + +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------+ + | Name | Description | Mandatory | Example | + +=================+===================================================================================================================================================================================================================================================================+=======================================================+============================================+ + | Host | Specifies the requested server information, which can be obtained from the URL of the service API. The value is in the *hostname[:port]* format. If the port number is not specified, the default port is used. The default port number for **https** is **443**. | No | code.test.com | + | | | | | + | | | This parameter is mandatory for AK/SK authentication. | or | + | | | | | + | | | | code.test.com:443 | + +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------+ + | Content-Type | Specifies the MIME type of the request body. You are advised to use the default value **application/json**. For APIs used to upload objects or images, the value can vary depending on the flow type. | Yes | application/json | + +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------+ + | Content-Length | Specifies the length of the request body. The unit is byte. | No | 3495 | + +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------+ + | X-Project-Id | Specifies the project ID. Obtain the project ID by following the instructions in :ref:`Obtaining a Project ID `. | No | e9993fc787d94b6c886cbaa340f9c0f4 | + +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------+ + | X-Auth-Token | Specifies the user token. | No | The following is part of an example token: | + | | | | | + | | The user token is a response to the API used to `obtain a user token `__. This API is the only one that does not require authentication. | This parameter is mandatory for token authentication. | MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ | + | | | | | + | | After the request is processed, the value of **X-Subject-Token** in the message header is the token value. | | | + +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------+ + +The API used to `obtain a user token `__ does not require authentication. Therefore, only the **Content-Type** field needs to be added to requests for calling the API. An example of such requests is as follows: + +(Optional) Request Body +----------------------- + +This part is optional. The body of a request is often sent in a structured format (for example, JSON or XML) as specified in the **Content-Type** header field. If the request body contains full-width characters, these characters must be coded in UTF-8. + +The request body varies between APIs. Some APIs do not require the request body, such as the APIs requested using the GET and DELETE methods. + +In the case of the API used to `obtain a user token `__, the request parameters and parameter description can be obtained from the API request. The following provides an example request with a body included. Replace **username**, **domainname**, **\*******\*** (login password), and **xxxxxxxxxxxxxxxxxx** (project name) with actual values. You can obtain the values from `Regions and Endpoints `__. + +.. note:: + + The **scope** parameter specifies where a token takes effect. You can set **scope** to an account or a project under an account. In the following example, the token takes effect only for the resources in a specified project. For more information about this API, see `Obtaining a User Token `__. + +.. code-block:: + + Content-Type: application/json + + { + "auth": { + "identity": { + "methods": [ + "password" + ], + "password": { + "user": { + "name": "username", + "password": "********", + "domain": { + "name": "domainname" + } + } + } + }, + "scope": { + "project": { + "name": "xxxxxxxxxxxxxxxxxx" + } + } + } + } + +If all data required for the API request is available, you can send the request to call the API through `curl `__, `Postman `__, or coding. In the response to the API used to obtain a user token, **x-subject-token** is the desired user token. This token can then be used to authenticate the calling of other APIs. diff --git a/api-ref/source/calling_apis/response.rst b/api-ref/source/calling_apis/response.rst new file mode 100644 index 0000000..81d86b9 --- /dev/null +++ b/api-ref/source/calling_apis/response.rst @@ -0,0 +1,62 @@ +:original_name: gaussdb_03_0006.html + +.. _gaussdb_03_0006: + +Response +======== + +Status Code +----------- + +After sending a request, you will receive a response, including the status code, response header, and response body. + +A status code is a group of digits ranging from 1xx to 5xx. It indicates the status of a response. For more information, see :ref:`Status Codes `. + +For example, if status code **201** is returned for calling the API used to `obtain a user token `__, the request is successful. + +Response Header +--------------- + +Similar to a request, a response also has a header, for example, **Content-Type**. + +:ref:`Figure 1 ` shows the response header for the API used to `obtain a user token `__. The **x-subject-token** header field is the desired user token. This token can then be used to authenticate the calling of other APIs. + +.. _gaussdb_03_0006__fig4865141011511: + +.. figure:: /_static/images/en-us_image_0000001372529646.png + :alt: **Figure 1** Header fields of the response to the request for obtaining a user token + + **Figure 1** Header fields of the response to the request for obtaining a user token + +(Optional) Response Body +------------------------ + +This part is optional. The body of a response is often returned in structured format as specified in the **Content-Type** header field. The response body transfers content except the response header. + +The following is part of the response body for the API used to `obtain a user token `__. + +.. code-block:: + + { + "token": { + "expires_at": "2019-02-13T06:52:13.855000Z", + "methods": [ + "password" + ], + "catalog": [ + { + "endpoints": [ + { + "region_id": "az-01", + ...... + +If an error occurs during API calling, an error code and a message will be displayed. The following shows an error response body. + +.. code-block:: + + { + "error_code": "AS.0001", + "error_msg": "The format of message is error" + } + +In the response body, **error_code** is an error code, and **error_msg** provides information about the error. diff --git a/api-ref/source/change_history.rst b/api-ref/source/change_history.rst new file mode 100644 index 0000000..75d9734 --- /dev/null +++ b/api-ref/source/change_history.rst @@ -0,0 +1,17 @@ +:original_name: changeHistory.html + +.. _changeHistory: + +Change History +============== + ++-----------------------------------+-------------------------------------------------------------------------------------+ +| Released On | Description | ++===================================+=====================================================================================+ +| 2022-10-30 | This issue is the second official release. | +| | | +| | - Optimized the content in :ref:`Querying a Parameter Template `. | +| | - Optimized the content in :ref:`Querying a DB Instance List `. | ++-----------------------------------+-------------------------------------------------------------------------------------+ +| 2020-05-30 | This issue is the first official release. | ++-----------------------------------+-------------------------------------------------------------------------------------+ diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py index d67562c..9c66273 100644 --- a/api-ref/source/conf.py +++ b/api-ref/source/conf.py @@ -24,7 +24,7 @@ extensions = [ otcdocs_auto_name = False otcdocs_auto_version = False -project = 'GaussDB Enterprise-class Distributed Database compatible with MySQL' +project = 'GaussDB (for MySQL)' otcdocs_repo_name = 'docs/gaussdb-mysql' # Those variables are required for edit/bug links otcdocs_git_fqdn = 'gitea.eco.tsi-dev.otc-service.com' @@ -86,7 +86,7 @@ html_theme_options = { # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = "GaussDB Enterprise-class Distributed Database compatible with MySQL - API Reference" +html_title = "GaussDB (for MySQL) - API Reference" # Add any paths that contain custom static files (such as style sheets) here, @@ -98,6 +98,6 @@ html_static_path = ['_static'] latex_documents = [ ('index', 'gaussdb_mysql-api-ref.tex', - u'GaussDB Enterprise-class Distributed Database compatible with MySQL - API Reference', + u'GaussDB (for MySQL) - API Reference', u'OpenTelekomCloud', 'manual'), ] diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index d7ffd75..c42ed2e 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -1,4 +1,13 @@ -=================================================================================== -GaussDB Enterprise-class Distributed Database compatible with MySQL - API Reference -=================================================================================== +=================================== +GaussDB (for MySQL) - API Reference +=================================== +.. toctree:: + :maxdepth: 1 + + before_you_start/index + api_overview + calling_apis/index + api/index + appendix/index + change_history