GTM Instance API Configuration Reference - Alibaba Cloud DNS - Alibaba Cloud - Alibaba Cloud DNS

Retrieves instance configurations that match the specified parameters.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

alidns:SearchCloudGtmInstanceConfigs

list

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
AcceptLanguage	string	No	The language of the response. Valid values: `zh-CN`: Chinese `en-US` (default): English	zh-CN
ClientToken	string	No	A client-generated token to ensure the idempotence of the request. The token must be unique across requests and can contain up to 64 ASCII characters.	1ae05db4-10e7-11ef-b126-00163e24****
PageNumber	integer	No	The page number. Pages start from 1. The default value is 1.	1
PageSize	integer	No	The number of entries per page for a paged query. The maximum value is 100 and the default value is 20.	20
InstanceId	string	No	The ID of the Global Traffic Manager (GTM) 3.0 instance.	gtm-cn-wwo3a3h****
ScheduleZoneName	string	No	The primary domain name (for example, `example.com`) or subdomain name (for example, `a.example.com`) of the GTM access domain. This is typically a domain name managed by Alibaba Cloud DNS under the same account that owns the GTM instance.	example.com
ScheduleDomainName	string	No	The GTM access domain. It is formed by combining the host record (`ScheduleHostname`) with the primary or subdomain name (`ScheduleZoneName`).	www.example.com
EnableStatus	string	No	The status of the instance configuration. Valid values: `enable`: Enabled. The intelligent scheduling policy of the GTM instance is in effect. `disable`: Disabled. The intelligent scheduling policy of the GTM instance is unavailable.	enable
Remark	string	No	A note for the instance configuration.	test
HealthStatus	string	No	The health status of the instance configuration. Valid values: `ok`: Normal. All address pools referenced by the GTM access domain are available. `ok_alert`: Alert. Some address pools referenced by the GTM access domain are unavailable. In this state, DNS resolution continues for available address pools but stops for unavailable ones. `exceptional`: Exceptional. All address pools referenced by the GTM access domain are unavailable. In this case, failover resolution uses the addresses from the non-empty address pool with the smallest sequence number to ensure clients receive a resolution result.	ok
AvailableStatus	string	No	The service availability status of the instance configuration. Valid values: `available`: The service for the GTM access domain is available when the instance configuration is enabled and its health status is Normal or Alert. `unavailable`: The service for the GTM access domain is unavailable when the instance configuration is disabled or its health status is Exceptional.	available

Response elements

Element	Type	Description	Example
	object
RequestId	string	The unique request ID.	6AEC7A64-3CB1-4C49-8B35-0B901F1E26BF
PageNumber	integer	The page number. The start value is 1. Default value: 1.	1
PageSize	integer	The number of entries to return on each page. Maximum value: 100. Default value: 20.	20
TotalPages	integer	The total number of pages.	1
TotalItems	integer	The total number of instance configurations.	15
InstanceConfigs	object
InstanceConfig	array<object>	The list of instance configurations.
	array<object>	The instance configuration.
InstanceId	string	The ID of the Global Traffic Manager (GTM) 3.0 instance.	gtm-cn-x0r38e0****
ConfigId	string	The unique ID of the instance configuration. An access domain name can have both A and AAAA records on the same GTM instance, each with a separate configuration. This ID distinguishes between these configurations.	Config-000****
CreateTime	string	The time when the instance configuration was created.	2024-03-15T01:46Z
CreateTimestamp	integer	The timestamp when the instance configuration was created.	1527690629357
UpdateTime	string	The time when the instance configuration was last updated.	2024-03-15T01:46Z
UpdateTimestamp	integer	The timestamp when the instance configuration was last updated.	1527690629357
VersionCode	string	The edition of the GTM 3.0 instance. Valid values: `standard`: Standard Edition `ultimate`: Ultimate Edition	ultimate
CommodityCode	string	The commodity code. Valid values: `dns_gtm_public_cn`: The commodity code for the Alibaba Cloud China website. `dns_gtm_public_intl`: The commodity code for the Alibaba Cloud International website.	dns_gtm_public_cn
ScheduleZoneMode	string	The assignment mode for the access domain name. Valid values: `custom`: A custom access domain name. You generate it by customizing the host record and associating it with a domain managed by authoritative DNS in your GTM instance account. `sys_assign`: The system assigns a default access domain name. This mode is no longer supported. Do not use this mode.	custom
ScheduleZoneName	string	The root domain (for example, `example.com`) or subdomain (for example, `a.example.com`) of the GTM access domain name. This domain is typically managed by Alibaba Cloud DNS under the same account as the GTM instance.	example.com
ScheduleHostname	string	The host record of the GTM access domain name.	www
ScheduleDomainName	string	The GTM access domain name, formed by combining the host record (`ScheduleHostname`) and the root domain or subdomain (`ScheduleZoneName`).	www.example.com
ScheduleRrType	string	The record type of the access domain name. Valid values: `A`: IPv4 address `AAAA`: IPv6 address `CNAME`: CNAME record	A
Ttl	integer	The Time to Live (TTL) for the DNS record, in seconds. This value determines how long the record for the access domain name is cached by ISP DNS servers.	60
AddressPoolLbStrategy	string	The load balancing policy for address pools. Valid values: `round_robin`: Returns all address pools in a rotating order for each DNS request. `sequence`: Returns the available address pool with the smallest sequence number (highest priority). `weight`: GTM routes DNS requests to address pools based on their weight ratios. `source_nearest`: GTM returns an address pool based on the request's source to provide the nearest access for users.	round_robin
SequenceLbStrategyMode	string	When using the `sequence` load balancing policy, this parameter specifies how traffic is handled when a higher-priority address pool recovers. Valid values: `preemptive`: In preemptive mode, traffic is switched back to the higher-priority address pool. `non_preemptive`: In non-preemptive mode, traffic continues to be routed to the current address pool.	preemptive
AvailableStatus	string	The availability status of the instance configuration. Valid values: `available`: The instance configuration is enabled and its health status is normal. `unavailable`: The instance configuration is disabled or its health status is abnormal.	available
EnableStatus	string	The enabled status of the instance configuration. Valid values: `enable`: The scheduling policy is active. `disable`: The scheduling policy is inactive.	enable
HealthStatus	string	The health status of the instance configuration. Valid values: `ok`: All address pools referenced by the access domain name are healthy. `ok_alert`: Some referenced address pools are unhealthy, but the overall instance is still operational. DNS resolution continues for healthy pools while it stops for unhealthy ones. `exceptional`: All referenced address pools are unhealthy. GTM performs failover resolution by using an address from the failover address pool with the lowest sequence number.	ok
Remark	string	The remark for the instance configuration.	test
AddressPools	object
AddressPool	array<object>	The list of address pools.
	array<object>	The address pool.
CreateTime	string	The time when the address pool was created.	2024-03-15T01:46Z
CreateTimestamp	integer	The timestamp when the address pool was created.	1527690629357
UpdateTime	string	The time when the address pool was last updated.	2024-03-15T01:46Z
UpdateTimestamp	integer	The timestamp when the address pool was last updated.	1527690629357
AddressPoolId	string	The unique ID of the address pool.	pool-89564504435014**60
WeightValue	integer	The weight of the address pool. You can set a weight for each address pool to route DNS requests based on weight ratios. Valid values: integers from 1 to 100, inclusive.	1
SerialNumber	integer	The priority of the address pool, used for sequence-based load balancing. A smaller value indicates a higher priority, and the address pool with the highest priority is returned first.	1
RequestSource	object
RequestSource	array	The list of DNS request sources.
	string	The source of the DNS request. GTM routes traffic based on the egress IP address of the local DNS server that the client uses. If the local DNS server supports EDNS Client Subnet (ECS), GTM can perform more precise routing based on the client's IP address.	["default"]
AddressPoolName	string	The name of the address pool.	AddressPool-1
AddressPoolType	string	The type of the address pool. Valid values: `IPv4` `IPv6` `domain`	IPv4
AddressLbStrategy	string	The load balancing policy for addresses in the address pool. Valid values: `round_robin`: Returns all addresses in a rotating order for each DNS request. `sequence`: Returns the available address with the smallest sequence number (highest priority). `weight`: You can set a weight for each address. DNS requests are then routed to addresses based on their weight ratios. `source_nearest`: GTM returns an address based on the request's source to provide the nearest access for users.	round_robin
SequenceLbStrategyMode	string	If the load balancing policy for addresses is `sequence`, this parameter specifies the service recovery mode after a higher-priority address becomes available again. Valid values: `preemptive`: In preemptive mode, traffic is switched back to the higher-priority address. `non_preemptive`: In non-preemptive mode, traffic continues to be routed to the current address.	preemptive
EnableStatus	string	The enabled status of the address pool. Valid values: `enable`: Enabled `disable`: Disabled	enable
HealthJudgement	string	The condition for determining the health status of the address pool. Valid values: `any_ok`: The address pool is considered healthy if at least one address is available. `p30_ok`: The address pool is considered healthy if at least 30% of its addresses are available. `p50_ok`: The address pool is considered healthy if at least 50% of its addresses are available. `p70_ok`: The address pool is considered healthy if at least 70% of its addresses are available. `all_ok`: The address pool is considered healthy only if all of its addresses are available.	any_ok
HealthStatus	string	The health status of the address pool. Valid values: `ok`: All addresses in the address pool are available. `ok_alert`: Some addresses are unavailable, but the address pool is still considered healthy. In the warning state, DNS resolution continues for available addresses, but stops for unavailable addresses. `exceptional`: The address pool is considered unhealthy because some or all of its addresses are unavailable.	ok
AvailableStatus	string	The availability status of the address pool. Valid values: `available`: Available `unavailable`: Unavailable	available
SeqNonPreemptiveSchedule	boolean	Indicates whether non-preemptive sequential scheduling is used for this address pool. This mode is typically used in a multi-cloud management scenario. Valid values: `true`: Yes `false`: No	false
ConfigLoggingSwitchStatus	string		ENABLE

Examples

Success response

JSON format

{
  "RequestId": "6AEC7A64-3CB1-4C49-8B35-0B901F1E26BF",
  "PageNumber": 1,
  "PageSize": 20,
  "TotalPages": 1,
  "TotalItems": 15,
  "InstanceConfigs": {
    "InstanceConfig": [
      {
        "InstanceId": "gtm-cn-x0r38e0****",
        "ConfigId": "Config-000****\n",
        "CreateTime": "2024-03-15T01:46Z",
        "CreateTimestamp": 1527690629357,
        "UpdateTime": "2024-03-15T01:46Z",
        "UpdateTimestamp": 1527690629357,
        "VersionCode": "ultimate",
        "CommodityCode": "dns_gtm_public_cn",
        "ScheduleZoneMode": "custom",
        "ScheduleZoneName": "example.com",
        "ScheduleHostname": "www",
        "ScheduleDomainName": "www.example.com",
        "ScheduleRrType": "A",
        "Ttl": 60,
        "AddressPoolLbStrategy": "round_robin",
        "SequenceLbStrategyMode": "preemptive",
        "AvailableStatus": "available",
        "EnableStatus": "enable",
        "HealthStatus": "ok",
        "Remark": "test",
        "AddressPools": {
          "AddressPool": [
            {
              "CreateTime": "2024-03-15T01:46Z",
              "CreateTimestamp": 1527690629357,
              "UpdateTime": "2024-03-15T01:46Z",
              "UpdateTimestamp": 1527690629357,
              "AddressPoolId": "pool-89564504435014**60",
              "WeightValue": 1,
              "SerialNumber": 1,
              "RequestSource": {
                "RequestSource": [
                  "[\"default\"]"
                ]
              },
              "AddressPoolName": "AddressPool-1",
              "AddressPoolType": "IPv4",
              "AddressLbStrategy": "round_robin",
              "SequenceLbStrategyMode": "preemptive",
              "EnableStatus": "enable",
              "HealthJudgement": "any_ok",
              "HealthStatus": "ok",
              "AvailableStatus": " available",
              "SeqNonPreemptiveSchedule": false
            }
          ]
        },
        "ConfigLoggingSwitchStatus": "ENABLE"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.