Domain Name Service. API Reference. Issue 05 Date

Transcription

1 Issue 05 Date

2 Contents Contents 1 API Invoking Method Service Usage Request Methods Request Authentication Methods Token Authentication AK/SK Authentication AK and SK Generation Request Signing Procedure Sample Code Obtaining the Project ID or Tenant ID Common Message Headers Common Request Headers Common Response Headers Version Management Querying the DNS Version Zone Management Public Zone Creating a Public Zone Querying a Public Zone Querying Public Zones Querying Name Servers in a Public Zone Deleting a Public Zone Modifying a Public Zone Private Zone Creating a Private Zone Associating a Private Zone with a VPC Disassociating a VPC from a Private Zone Querying a Private Zone Querying Private Zones Querying Name Servers in a Private Zone Deleting a Private Zone Modifying a Private Zone...46 Issue 05 ( ) ii

3 Contents 5 Record Set Management Creating a Record Set Querying a Record Set Querying All Record Sets Querying Record Sets in a Zone Deleting a Record Set Modifying a Record Set PTR Record Management Configuring a PTR Record Querying a PTR Record Querying All PTR Records Unsetting a PTR Record Modifying a PTR Record Tag Management Adding Resource Tags Deleting a Resource Tag Adding or Deleting Resource Tags in Batches Querying Tags of a Resource Querying Tags of a Specified Resource Type...87 A Appendix...90 A.1 General Request Return Code A.2 Error Code B Change History Issue 05 ( ) iii

4 1 API Invoking Method 1 API Invoking Method 1.1 Service Usage Application programming interface (API) requests sent by third-party applications to public cloud services must be authenticated using signatures. This chapter describes the signature usage procedure, provides sample code to illustrate how to use the default signer to sign requests and how to use the HTTP client to send requests. Public cloud services provide RESTful APIs. Representational State Transfer (REST) allocates Uniform Resource Identifiers (URIs) to dispersed resources so that resources can be located. Applications on clients use Uniform Resource Locators (URLs) to obtain resources. The URL is in the following format: Table 1-1 describes the parameters in a URL. Table 1-1 Parameter description Parameter Endpoint URI Description Specifies the URL that is the entry point for a web service. Obtain the value from Regions and Endpoints. Specifies the API access path for performing a specified operation. Obtain the value from the URI of the API, for example, v3/auth/ tokens. 1.2 Request Methods The HTTP protocol defines request methods, such as GET, PUT, POST, DELETE, and PATCH, to indicate the desired action to be performed on the identified resource. The following table describes the HTTP methods supported by the RESTful APIs. Issue 05 ( ) 1

5 1 API Invoking Method Table 1-2 HTTPS methods Method GET PUT POST DELETE PATCH Description The GET method requests a representation of the specified resource. The PUT method requests that the enclosed entity be stored under the supplied URI. The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The DELETE method deletes the specified resource, for example, an object. The PATCH method applies partial modifications to a resource. If the resource does not exist, the PATCH method creates a resource. 1.3 Request Authentication Methods You can use either of the following two authentication methods to call APIs: Token authentication: Requests are authenticated using Tokens. AK/SK authentication: Requests are encrypted using the access key (AK) and secret key (SK) to provide higher security. 1.4 Token Authentication Scenarios Make an API Call If you use a token for authentication, you must obtain the user's token and add X-Auth-Token to the request header of the service API when making an API call. This section describes how to make an API call for token authentication. 1. Send POST of IAM/v3/auth/tokens to obtain the endpoint of IAM and the region name in the message body. See Regions and Endpoints. An example request message is as follows: NOTE Replace the items in italic in the following example with actual ones. For details, see the Identity and Access Management. "auth": "identity": "methods": [ "password" ], "password": "user": Issue 05 ( ) 2

6 1 API Invoking Method "name": "username", "password": "password", "domain": "name": "domainname", "scope": "project": "id": "0215ef11e49d4743be23dd97a1561e91" //This ID is used as an example. 2. Obtain the token. For details, see section "Obtaining the User Token" in the Identity and Access Management. 3. Make a call to a service API, add X-Auth-Token to the request header, and set the value of X-Auth-Token to the token obtained in step AK/SK Authentication When you use API Gateway to send requests to underlying services, the requests are signed using the AK and SK. NOTE AK: indicates the ID of the access key. AK is used together with SK to obtain an encrypted signature for a request. SK: indicates the secret access key together used with the access key ID to sign requests. AK and SK can be used together to identify a request sender to prevent the request from being modified AK and SK Generation 1. Log in to the management console. 2. Click the username and select My Credential from the drop-down list. 3. On the My Credential page, click Access Keys. 4. Click Add Access Key. 5. Enter the current login password. 6. Enter the authentication code received in the or mobile phone. 7. Click OK to download the access key. NOTE To prevent the access key from being leaked, keep it secure Request Signing Procedure Preparations 1. Download the API Gateway signature tool from the following link: 2. Extract the package. Issue 05 ( ) 3

7 1 API Invoking Method Sign a Request Sample Code 3. Create a Java project, and reference the extracted JAR to the dependency path. 1. Create a request com.cloud.sdk.defaultrequest (JAVA) used for signing. 2. Set the target API URL, HTTPS method, and content of request com.cloud.sdk.defaultrequest (JAVA). 3. Sign request com.cloud.sdk.defaultrequest (JAVA). a. Call SignerFactory.getSigner(String servicename, String regionname) to obtain a signing tool. b. Call Signer.sign(Request<?> request, Credentials credentials) to sign the request created in step 1. The following code shows the details: //Select an algorithm for request signing. Signer signer = SignerFactory.getSigner(serviceName, region); //Sign the request. The request will change after the signing. signer.sign(request, new BasicCredentials(this.ak, this.sk)); 4. Convert the request signed in the previous step to a new request that can be used to make an API call and copy the header of the signed request to the new request. For example, if Apache HttpClient is used, convert DefaultRequest to HttpRequestBase and copy the header of the signed DefaultRequest to HttpRequestBase. For details, see descriptions of AccessServiceImpl.java in section Sample Code. The following three types of code show how to sign a request and use an HTTP client to send an HTTPS request: AccessService: indicates the abstract class that converts the GET, POST, PUT, and DELETE methods in to the access method. Demo: indicates the execution entry used to simulate GET, POST, PUT, and DELETE request sending. AccessServiceImpl: indicates the implementation of the access method. Code required for API gateway communication is in the access method. For details about region and servicename in the following code, see Regions and Endpoints: AccessService.java: package com.cloud.apigateway.sdk.demo; import java.io.inputstream; import java.net.url; import java.util.map; import org.apache.http.httpresponse; import com.cloud.sdk.http.httpmethodname; public abstract class AccessService protected String servicename = null; protected String region = null; Issue 05 ( ) 4

8 1 API Invoking Method protected String ak = null; protected String sk = null; public AccessService(String servicename, String region, String ak, String sk) this.region = region; this.servicename = servicename; this.ak = ak; this.sk = sk; public abstract HttpResponse access(url url, Map<String, String> header, InputStream content, Long contentlength, HttpMethodName httpmethod) throws Exception; public HttpResponse access(url url, Map<String, String> header, HttpMethodName httpmethod) throws Exception return this.access(url, header, null, 0l, httpmethod); public HttpResponse access(url url, InputStream content, Long contentlength, HttpMethodName httpmethod) throws Exception return this.access(url, null, content, contentlength, httpmethod); public HttpResponse access(url url, HttpMethodName httpmethod) throws Exception return this.access(url, null, null, 0l, httpmethod); public abstract void close(); public String getservicename() return servicename; public void setservicename(string servicename) this.servicename = servicename; public String getregion() return region; public void setregion(string region) this.region = region; public String getak() return ak; public void setak(string ak) this.ak = ak; public String getsk() return sk; public void setsk(string sk) this.sk = sk; AccessServiceImpl.java: Issue 05 ( ) 5

9 1 API Invoking Method package com.cloud.apigateway.sdk.demo; import java.io.ioexception; import java.io.inputstream; import java.net.urisyntaxexception; import java.net.url; import java.util.hashmap; import java.util.map; import javax.net.ssl.sslcontext; import org.apache.http.header; import org.apache.http.httpheaders; import org.apache.http.httpresponse; import org.apache.http.client.methods.httpdelete; import org.apache.http.client.methods.httpget; import org.apache.http.client.methods.httphead; import org.apache.http.client.methods.httppatch; import org.apache.http.client.methods.httppost; import org.apache.http.client.methods.httpput; import org.apache.http.client.methods.httprequestbase; import org.apache.http.conn.ssl.allowallhostnameverifier; import org.apache.http.conn.ssl.sslconnectionsocketfactory; import org.apache.http.conn.ssl.sslcontexts; import org.apache.http.conn.ssl.trustselfsignedstrategy; import org.apache.http.entity.inputstreamentity; import org.apache.http.impl.client.closeablehttpclient; import org.apache.http.impl.client.httpclients; import com.cloud.sdk.defaultrequest; import com.cloud.sdk.request; import com.cloud.sdk.auth.credentials.basiccredentials; import com.cloud.sdk.auth.signer.signer; import com.cloud.sdk.auth.signer.signerfactory; import com.cloud.sdk.http.httpmethodname; public class AccessServiceImpl extends AccessService private CloseableHttpClient client = null; public AccessServiceImpl(String servicename, String region, String ak, String sk) super(servicename, region, ak, sk); */ public HttpResponse access(url url, Map<String, String> headers, InputStream content, Long contentlength, HttpMethodName httpmethod) throws Exception // Make a request for signing. Request request = new DefaultRequest(this.serviceName); try // Set the request address. request.setendpoint(url.touri()); String urlstring = url.tostring(); String parameters = null; if (urlstring.contains("?")) parameters = urlstring.substring(urlstring.indexof("?") + 1); Map parametersmap = new HashMap<String, String>(); if (null!= parameters &&!"".equals(parameters)) String[] parameterarray = parameters.split("&"); Issue 05 ( ) 6

10 1 API Invoking Method for (String p : parameterarray) String key = p.split("=")[0]; String value = p.split("=")[1]; parametersmap.put(key, value); request.setparameters(parametersmap); catch (URISyntaxException e) // It is recommended to add logs in this place. e.printstacktrace(); // Set the request method. request.sethttpmethod(httpmethod); if (headers!= null) // Add request header information if required. request.setheaders(headers); // Configure the request content. request.setcontent(content); // Select an algorithm for request signing. Signer signer = SignerFactory.getSigner(serviceName, region); // Sign the request, and the request will change after the signing. signer.sign(request, new BasicCredentials(this.ak, this.sk)); // Make a request that can be sent by the HTTP client. HttpRequestBase httprequestbase = createrequest(url, null, request.getcontent(), contentlength, httpmethod); Map<String, String> requestheaders = request.getheaders(); // Put the header of the signed request to the new request. for (String key : requestheaders.keyset()) if (key.equalsignorecase(httpheaders.content_length.tostring())) continue; httprequestbase.addheader(key, requestheaders.get(key)); HttpResponse response = null; SSLContext sslcontext = SSLContexts.custom().loadTrustMaterial(null, new TrustSelfSignedStrategy()).useTLS().build(); SSLConnectionSocketFactory sslsocketfactory = new SSLConnectionSocketFactory( sslcontext, new AllowAllHostnameVerifier()); client = HttpClients.custom().setSSLSocketFactory(sslSocketFactory).build(); // Send the request, and a response will be returned. response = client.execute(httprequestbase); return response; /** * Make a request that can be sent by the HTTP client. * url * specifies the API access path. header * specifies the header information to be added. content * specifies the body content to be sent in the API call. contentlength * specifies the length of the content. This parameter is optional. httpmethod * specifies the HTTP method to be used. specifies the request that can be sent by an HTTP client. */ private static HttpRequestBase createrequest(url url, Header header, Issue 05 ( ) 7

11 1 API Invoking Method InputStream content, Long contentlength, HttpMethodName httpmethod) HttpRequestBase httprequest; if (httpmethod == HttpMethodName.POST) HttpPost postmethod = new HttpPost(url.toString()); if (content!= null) InputStreamEntity entity = new InputStreamEntity(content, contentlength); postmethod.setentity(entity); httprequest = postmethod; else if (httpmethod == HttpMethodName.PUT) HttpPut putmethod = new HttpPut(url.toString()); httprequest = putmethod; if (content!= null) InputStreamEntity entity = new InputStreamEntity(content, contentlength); putmethod.setentity(entity); else if (httpmethod == HttpMethodName.PATCH) HttpPatch patchmethod = new HttpPatch(url.toString()); httprequest = patchmethod; if (content!= null) InputStreamEntity entity = new InputStreamEntity(content, contentlength); patchmethod.setentity(entity); else if (httpmethod == HttpMethodName.GET) httprequest = new HttpGet(url.toString()); else if (httpmethod == HttpMethodName.DELETE) httprequest = new HttpDelete(url.toString()); else if (httpmethod == HttpMethodName.HEAD) httprequest = new HttpHead(url.toString()); else throw new RuntimeException("Unknown HTTP method name: " + httpmethod); httprequest.addheader(header); return public void close() try if (client!= null) client.close(); catch (IOException e) // It is recommended to add logs in this place. e.printstacktrace(); Demo.java: package com.cloud.apigateway.sdk.demo; import java.io.bufferedreader; import java.io.bytearrayinputstream; import java.io.ioexception; import java.io.inputstream; import java.io.inputstreamreader; import java.net.malformedurlexception; Issue 05 ( ) 8

12 1 API Invoking Method import java.net.url; import org.apache.http.httpresponse; import com.cloud.sdk.http.httpmethodname; public class Demo //replace real region private static final String region = "regionname"; //replace real service name private static final String servicename = "servicename"; public static void main(string[] args) //replace real AK String ak = "akstring"; //replace real SK String sk = "skstring"; // get method //replace real url String url = "urlstring"; get(ak, sk, url); // post method //replace real url String posturl = "urlstring"; //replace real body String postbody = "bodystring"; post(ak, sk, posturl, postbody); // put method //replace real body String putbody = "bodystring"; //replace real url String puturl = "urlstring"; put(ak, sk, puturl, putbody); // delete method //replace real url String deleteurl = "urlstring"; delete(ak, sk, deleteurl); public static void put(string ak, String sk, String requesturl, String putbody) AccessService accessservice = null; try accessservice = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpmethod = HttpMethodName.PUT; InputStream content = new ByteArrayInputStream(putBody.getBytes()); HttpResponse response = accessservice.access(url, content, (long) putbody.getbytes().length, httpmethod); System.out.println(response.getStatusLine().getStatusCode()); catch (Exception e) e.printstacktrace(); finally accessservice.close(); Issue 05 ( ) 9

13 1 API Invoking Method public static void patch(string ak, String sk, String requesturl, String putbody) AccessService accessservice = null; try accessservice = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpmethod = HttpMethodName.PATCH; InputStream content = new ByteArrayInputStream(putBody.getBytes()); HttpResponse response = accessservice.access(url, content, (long) putbody.getbytes().length, httpmethod); System.out.println(convertStreamToString(response.getEntity().getContent())); catch (Exception e) e.printstacktrace(); finally accessservice.close(); public static void delete(string ak, String sk, String requesturl) AccessService accessservice = null; try accessservice = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpmethod = HttpMethodName.DELETE; HttpResponse response = accessservice.access(url, httpmethod); System.out.println(convertStreamToString(response.getEntity().getContent())); catch (Exception e) e.printstacktrace(); finally accessservice.close(); public static void get(string ak, String sk, String requesturl) AccessService accessservice = null; try accessservice = new AccessServiceImpl(serviceName, region, ak, sk); URL url = new URL(requestUrl); HttpMethodName httpmethod = HttpMethodName.GET; HttpResponse response; response = accessservice.access(url, httpmethod); System.out.println(convertStreamToString(response.getEntity().getContent())); catch (Exception e) e.printstacktrace(); finally accessservice.close(); public static void post(string ak, String sk, String requesturl, String postbody) AccessService accessservice = new AccessServiceImpl(serviceName, region, ak, sk); Issue 05 ( ) 10

14 1 API Invoking Method URL url = null; try url = new URL(requestUrl); catch (MalformedURLException e) e.printstacktrace(); InputStream content = new ByteArrayInputStream(postbody.getBytes()); HttpMethodName httpmethod = HttpMethodName.POST; HttpResponse response; try response = accessservice.access(url, content, (long) postbody.getbytes().length, httpmethod); System.out.println(convertStreamToString(response.getEntity().getContent())); catch (Exception e) e.printstacktrace(); finally accessservice.close(); private static String convertstreamtostring(inputstream is) BufferedReader reader = new BufferedReader(new InputStreamReader(is)); StringBuilder sb = new StringBuilder(); String line = null; try while ((line = reader.readline())!= null) sb.append(line + "\n"); catch (IOException e) e.printstacktrace(); finally try is.close(); catch (IOException e) e.printstacktrace(); return sb.tostring(); NOTE 1. Parameters URI, AK, SK, and HTTP METHOD are mandatory. 2. You can use the request.addheader() method to add header information. 1.6 Obtaining the Project ID or Tenant ID A project ID is required for some URLs when an API is called. It can be project_id or tenant_id because project_id has the same meaning as tenant_id in this document. Before calling an API, you need to obtain a project ID on the console. The steps are as follows: 1. Log in to the management console. 2. Click the username and select My Credential from the drop-down list. On the My Credential page, view the project ID in the project list. Issue 05 ( ) 11

15 1 API Invoking Method Figure 1-1 Viewing the project ID Issue 05 ( ) 12

16 2 Common Message Headers 2 Common Message Headers This chapter describes common request and response REST message headers. 2.1 Common Request Headers Table 2-1 Common request headers Parameter Description Mandatory Example Value x-sdk-date Specifies the time when the request is sent. The time is in YYYYMMDD'T'HHMMS S'Z' format. The value is the current GMT time of the system. No This field is mandatory for AK/SK authentication T101459Z Authorization Specifies the authentication information. The value can be obtained from the request signing result. For details, see section Request Signing Procedure. No This field is mandatory for AK/SK authentication. SDK-HMAC- SHA256 Credential=ZIRRK MTWPTQFQI1WK NKB/ //ec2/ sdk_request, SignedHeaders=cont ent-type;host;x-sdkdate, Signature=55741b61 0f3c9fa3ae40b5a802 1ebf7ebc2a28a603fc 62d25cb3bfe6608e1 994 Issue 05 ( ) 13

17 2 Common Message Headers Parameter Description Mandatory Example Value Host Specifies the server domain name and port number of the resources being requested. The value can be obtained from the URL of the service API. The value is hostname[:port]. If the port number is not specified, the default port is used. The default port number for https is 443. No This field is mandatory for AK/SK authentication. code.test.com or code.test.com:443 Content-Type Specifies the request body MIME type. You are advised to use the default value application/json. For interfaces 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 section 1.6 Obtaining the Project ID or Tenant ID. This parameter is mandatory for a request from a DeC or multi-project user. No This field is mandatory for requests that use AK/SK authentication in the Dedicated Cloud (DeC) scenario or multiproject scenario. e9993fc787d94b6c8 86cbaa340f9c0f4 X-Auth-Token Specifies the user token. For details about how to obtain the token, see section "Obtaining the User Token" in the Identity and Access Management. After the request is processed, the value of X- Subject-Token in the header is the token value. No This field is mandatory for token authentication. The following is part of an example token: MIIPAgYJKoZIhvc- NAQcCoIIO8zCCD u8caqexdtalbgl ghkgbzqmeagewg g1qbgkqhkig9w0b BwGggg1BBIINPXs idg9rz. NOTE For details about other parameters in the header, see the HTTP protocol documentation. Issue 05 ( ) 14

18 2 Common Message Headers 2.2 Common Response Headers Table 2-2 Common response headers Name Description Example Value Content-Length Date Specifies the length of the response body. The unit is byte. Specifies the GMT time when a request response is returned. - Wed, 27 Dec :49:46 GMT Content-Type Specifies the response body MIME type. application/json Issue 05 ( ) 15

19 3 Version Management 3 Version Management 3.1 Querying the DNS Version Function URI Request Query the available DNS API versions. To be interconnected with a third-party system, the current DNS version supports and 2048-bit DH key exchange algorithms, and the 2048-bit algorithm is recommended. URI format: GET / None Response Table 3-1 Parameters in the response versions object Version object Table 3-2 Description of the versions field values List object List of all versions Issue 05 ( ) 16

20 3 Version Management Table 3-3 Description of the values field status enum Whether the version is in-use or deprecated id string Version number The value can be DEPRECATED or CURRENT. Currently, only CURRENT is supported. links object Link of the current version Returned Value Example response "versions": "values": [ "status": "CURRENT", "id": "v2", "links": [ "href": " "rel": "self" ] ] See A.1 General Request Return Code. Issue 05 ( ) 17

21 4 Zone Management 4 Zone Management 4.1 Public Zone Creating a Public Zone Function URI Create a public zone. URI format: POST /v2/zones Request Issue 05 ( ) 18

22 4 Zone Management Table 4-1 Parameters in the request Parameter Mandatory Type Description name Yes string Domain name registered with the domain name registrar If a domain name is ended with a dot (.), it cannot exceed 254 characters. Otherwise, the domain name cannot exceed 253 characters. Labels of a domain name are separated by dot (.). Each label cannot exceed 63 characters. A domain name is case insensitive. Uppercase letters will also be converted into lowercase letters. description No string Description of the domain name, which cannot exceed 255 characters zone_type No string Zone type, the value of which can be public or private public: public zones accessible to hosts on the Internet private: private zones accessible only to hosts in specified VPCs If the value is left blank, a public zone will be created. For details about creating a private zone, see section Creating a Private Zone. No string address of the administrator managing the zone ttl No int Caching period of the SOA record set (in seconds) The default value is 300s. The value range is tags No List<tag > Resource tag. For details, see Table 4-2. Issue 05 ( ) 19

23 4 Zone Management Table 4-2 Description of the tag list Parameter Mandatory Type Description key Yes string Tag key. The key contains 36 Unicode characters at most and cannot be blank. It cannot contain the following characters: =*<>\, / nor start or end with a space. value Yes string Tag value. Each value contains 43 Unicode characters at most and can be an empty string. It cannot contain the following characters: =*<>\, / nor start or end with a space. Example request "name": "example.com.", "description": "This is an example zone.", "zone_type": "public", " ": "xx@example.org" Response Table 4-3 Parameters in the response id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system Issue 05 ( ) 20

24 4 Zone Management project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. masters enum Master DNS servers, from which the slave servers get DNS information Returned Value Example response "id": "2c9eb ec c9f90149", "name": "example.com.", "description": "This is an example zone.", " ": "xx@example.com", "ttl": 300, "serial": 1, "masters": [], "status": "PENDING_CREATE", "links": "self": " "pool_id": " e54ee01570e9939b20019", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "public", "created_at": " T11:56:03.439", "updated_at": null, "record_num": 0 See A.1 General Request Return Code Querying a Public Zone Function Query a public zone. URI URI format GET /v2/zones/zone_id Issue 05 ( ) 21

25 4 Zone Management Table 4-4 Parameter in the URI Paramete r Mandatory Type Description zone_id Yes string Zone ID Request None Response Table 4-5 Parameters in the response id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. Issue 05 ( ) 22

26 4 Zone Management masters enum Master DNS servers, from which the slave servers get DNS information Response example "id": "2c9eb ec c9f90149", "name": "example.com.", "description": "This is an example zone.", " ": "ttl": 300, "serial": 0, "masters": [], "status": "ACTIVE", "links": "self": " "pool_id": " e54ee01570e9939b20019", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "public", "created_at": " T11:56:03.439", "updated_at": " T11:56:05.528", "record_num": 2 Returned Value See A.1 General Request Return Code Querying Public Zones Function Query public zones in list. URI URI format GET /v2/zones? type=type&limit=limit&marker=marker&offset=offset&tags=tags Table 4-6 Parameters in the URI Parameter Mandatory Type Description type No string Zone type, which can be public or private public: Public zones are queried. private: Private zones are queried. If the value is left blank, public zones are queried by default. Issue 05 ( ) 23

27 4 Zone Management Parameter Mandatory Type Description marker No string Start resource ID of pagination query If the parameter is left blank, only resources on the first page are queried. limit No string Number of resources returned on each page Value range: Commonly used values are 10, 20, and 50. offset No int Start page of the list, which ranges from 0 to tags No string Resource tag When the value of marker is not blank, it determines the start of a page. The format is as follows: key1,value1 key2,value2. Multiple tags are separated by vertical bar ( ). The key and value of each tag are separated by comma (,). All tags listed will be queried. For details, see section 7 Tag Management. Request None Response Table 4-7 Parameters in the response zones List data structure Zone list object metadata object Number of resources that meet the filter condition Table 4-8 describes parameters under the zones field, and Table 4-9 describes the parameter under the metadata field. Issue 05 ( ) 24

28 4 Zone Management Table 4-8 Description of the zones field id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. masters enum Master DNS servers, from which the slave servers get DNS information Table 4-9 Description of the metadata field total_count int Total number of resources Example response "links": "self": " type=public&limit=11&marker=&name=&status=", "zones": [ Issue 05 ( ) 25

29 4 Zone Management "id": "2c9eb ec c9f90149", "name": "example.com.", "description": "This is an example zone.", " ": "ttl": 300, "serial": 0, "masters": [], "status": "ACTIVE", "links": "self": " 2c9eb ec c9f90149", "pool_id": " e54ee01570e9939b20019", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "public", "created_at": " T11:56:03.439", "updated_at": " T11:56:05.528", "record_num": 2, "id": "2c9eb c50001", "name": "example.org.", "description": "This is an example zone.", " ": "ttl": 300, "serial": 0, "masters": [], "status": "PENDING_CREATE", "links": "self": " 2c9eb c50001", "pool_id": " e54ee01570e9939b20019", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "public", "created_at": " T12:01:17.996", "updated_at": " T12:01:18.528", "record_num": 2 ], "metadata": "total_count": 2 Returned Value See A.1 General Request Return Code Querying Name Servers in a Public Zone Function Query name servers in a public zone. URI URI format GET /v2/zones/zone_id/nameservers Issue 05 ( ) 26

30 4 Zone Management Table 4-10 Parameter in the URI Parameter Mandatory Type Description zone_id Yes string Zone ID Request None Response Table 4-11 Parameter in the response nameservers List data structure Name server list object For details, see Table Table 4-12 Description of the nameservers field hostname string Host name of a name server priority int Priority of a name server For example, if the priority of a name server is 1, it is used to resolve domain names in first priority. Response example "nameservers": [ "hostname": "ns1.example.com.", "priority": 1, "hostname": "ns2.example.com.", "priority": 2 ] Returned Value See A.1 General Request Return Code. Issue 05 ( ) 27

31 4 Zone Management Deleting a Public Zone Function Delete a public zone. URI URI format DELETE /v2/zones/zone_id Table 4-13 Parameter in the URI Paramete r Mandatory Type Description zone_id Yes string Zone ID Request None Response Table 4-14 Parameters in the response id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone Issue 05 ( ) 28

32 4 Zone Management pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. masters enum Master DNS servers, from which the slave servers get DNS information Returned Value Response example "id": "2c9eb ec c9f90149", "name": "example.com.", "description": "This is an example zone.", " ": "xx@example.com", "ttl": 300, "serial": 1, "masters": [], "status": "PENDING_DELETE", "links": "self": " "pool_id": " e54ee01570e9939b20019", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "public", "created_at": " T11:56:03.439", "updated_at": " T11:56:05.057", "record_num": 0 See A.1 General Request Return Code Modifying a Public Zone Function Modify a public zone. URI URI format PATCH /v2/zones/zone_id Issue 05 ( ) 29

33 4 Zone Management Table 4-15 Parameter in the URI Parameter Mandatory Type Description zone_id Yes string ID of the zone to be modified Request Table 4-16 Parameters in the request Parameter Mandatory Type Description description No string Description of the domain name, which cannot exceed 255 characters No string address of the administrator managing the zone ttl No int Caching period of the SOA record set (in seconds) The default value is 300s. The value range is Request example "description": "This is an example zone.", " ": "ttl": 300 Response Table 4-17 Parameters in the response id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone Issue 05 ( ) 30

34 4 Zone Management serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. masters enum Master DNS servers, from which the slave servers get DNS information Returned Value Response example "id": "2c9eb ec c9f90149", "name": "example.com.", "description": "This is an example zone.", " ": "xx@example.com", "ttl": 300, "serial": 1, "masters": [], "status": "ACTIVE", "links": "self": " "pool_id": " e54ee01570e9939b20019", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "public", "created_at": " T11:56:03.439", "updated_at": " T11:56:05.749" "record_num": 2 See A.1 General Request Return Code. 4.2 Private Zone Issue 05 ( ) 31

35 4 Zone Management Creating a Private Zone Function Create a private zone. URI URI format: POST /v2/zones Request Table 4-18 Parameters in the request Parameter Mandatory Type Description name Yes string Domain name of the zone to be created If a domain name is ended with a dot (.), it cannot exceed 254 characters. Otherwise, the domain name cannot exceed 253 characters. Labels of a domain name are separated by dot (.). Each label cannot exceed 63 characters. A domain name is case insensitive. Uppercase letters will also be converted into lowercase letters. description No string Description of the domain name, which cannot exceed 255 characters zone_type Yes string Zone type The value must be private, indicating private zones accessible only to hosts in specified VPCs will be created. For details about creating a public zone, see section Creating a Public Zone. No string address of the administrator managing the zone ttl No int Caching period of the SOA record set (in seconds) The default value is 300s. The value range is Issue 05 ( ) 32

36 4 Zone Management Parameter Mandatory Type Description router Yes Router Router information (VPC associated with the private zone) For details, see Table tags No tag Resource tag. For details, see Table Table 4-19 Description of the router field Parameter Mandatory Type Description router_id Yes string Router ID (VPC ID) router_regio n No string Region of the router (VPC) If it is left blank, the region of the project in the token takes effect by default. Table 4-20 Description of the tag list Parameter Mandatory Type Description key Yes string Tag key. The key contains 36 Unicode characters at most and cannot be blank. It cannot contain the following characters: =*<>\, / nor start or end with a space. value Yes string Tag value. Each value contains 43 Unicode characters at most and can be an empty string. It cannot contain the following characters: =*<>\, / nor start or end with a space. Example request "name": "example.com.", "description": "This is an example zone.", "zone_type": "private", " ": "xx@example.org", "router": "router_id": " bf ad3a-94b8c79c6558", "router_region": "xx" Response Issue 05 ( ) 33

37 4 Zone Management Table 4-21 Parameters in the response id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. masters enum Master DNS servers, from which the slave servers get DNS information router Router Router information (VPC associated with the zone) Example response "id": "ff b8fc86c015b94bc6f8712c3", "name": "example.com.", "description": "This is an example zone.", " ": "xx@example.com", "ttl": 300, "serial": 1, "masters": [], "status": "PENDING_CREATE", "links": "self": " "pool_id": "ff ab738f4015ab e", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "private", "created_at": " T08:17:08.997", "updated_at": null, Issue 05 ( ) 34

38 4 Zone Management "record_num": 0, "router": "status": "PENDING_CREATE", "router_id": " bf ad3a-94b8c79c6558", "router_region": "xx" Returned Value See A.1 General Request Return Code Associating a Private Zone with a VPC Function Associate a private zone with a VPC. URI URI format POST /v2/zones/zone_id/associaterouter Table 4-22 Parameter in the URI Parameter Mandatory Type Description zone_id Yes string Zone ID Request Table 4-23 Parameters in the request Parameter Mandatory Type Description router Yes Router Router information (VPC associated with the zone) For details, see Table Table 4-24 Description of the router field Parameter Mandatory Type Description router_id Yes string Router ID (VPC ID) router_regio n No string Region of the router (VPC) If it is left blank, the region of the project in the token takes effect by default. Issue 05 ( ) 35

39 4 Zone Management Example request "router": "router_id": "f db8c-4a20-8a44-a06c6e24b15b", "router_region": "xx" Response Table 4-25 Parameters in the response router_id string Router ID (VPC ID) router_region string Region of the router (VPC) status string Task status The value can be PENDING_CREATE, PENDING_DELETE, ACTIVE, or ERROR. Returned Value Example response "status": "PENDING_CREATE", "router_id": "f db8c-4a20-8a44-a06c6e24b15b", "router_region": "xx" See A.1 General Request Return Code Disassociating a VPC from a Private Zone Function Disassociate a VPC from a private zone. When a private zone is associated with only one VPC, you cannot disassociate it. URI URI format POST /v2/zones/zone_id/disassociaterouter Table 4-26 Parameter in the URI Parameter Mandatory Type Description zone_id Yes string Zone ID Issue 05 ( ) 36

40 4 Zone Management Request Table 4-27 Parameter in the request Parameter Mandatory Type Description router Yes Router Router information (VPC associated with the zone) For details, see Table Table 4-28 Description of the router field Parameter Mandatory Type Description router_id Yes string Router ID (VPC ID) router_region No string Region of the router (VPC) If it is left blank, the region of the project in the token takes effect by default. Example request "router": "router_id": "f db8c-4a20-8a44-a06c6e24b15b", "router_region": "xx" Response Table 4-29 Parameters in the response router_id string Router ID (VPC ID) router_region string Region of the router (VPC) status string Task status The value can be PENDING_CREATE, PENDING_DELETE, ACTIVE, or ERROR. Example response "status": "PENDING_DELETE", "router_id": "f db8c-4a20-8a44-a06c6e24b15b", Issue 05 ( ) 37

41 4 Zone Management "router_region": "xx" Returned Value See A.1 General Request Return Code Querying a Private Zone Function Query a private zone. URI URI format GET /v2/zones/zone_id Table 4-30 Parameter in the URI Parameter Mandatory Type Description zone_id Yes string Zone ID Request None Response Table 4-31 Parameters in the response id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server Issue 05 ( ) 38

42 4 Zone Management status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated links object Link of the current resource or other related resources When a response is broken into pages, a next link is provided to retrieve all results. masters enum Master DNS servers, from which the slave servers get DNS information routers List<Router > Routers (VPCs associated with the zone) Example response "id": "ff b8fc86c015b94bc6f8712c3", "name": "example.com.", "description": "This is an example zone.", " ": "xx@example.com", "ttl": 300, "serial": 0, "masters": [], "status": "ACTIVE", "links": "self": " "pool_id": "ff ab738f4015ab e", "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c", "zone_type": "private", "created_at": " T08:17:08.997", "updated_at": " T08:17:09.997", "record_num": 2, "routers": [ "status": "ACTIVE", "router_id": " bf ad3a-94b8c79c6558", "router_region": "xx", "status": "ACTIVE", "router_id": "f db8c-4a20-8a44-a06c6e24b15b", "router_region": "xx" ] Issue 05 ( ) 39

43 4 Zone Management Returned Value See A.1 General Request Return Code Querying Private Zones Function Query private zones in list. URI URI format GET /v2/zones? type=type&limit=limit&marker=marker&offset=offset&tags=tags Table 4-32 Parameters in the URI Parameter Mandatory Type Description type Yes string Zone type The value is private, indicating that private zones are queried. marker No string Start resource ID of pagination query If the parameter is left blank, only resources on the first page are queried. limit No string Number of resources returned on each page Value range: Commonly used values are 10, 20, and 50. offset No int Start page of the list, which ranges from 0 to tags No string Resource tag When the value of marker is not blank, it determines the start of a page. The format is as follows: key1,value1 key2,value2. Multiple tags are separated by vertical bar ( ). The key and value of each tag are separated by comma (,). All tags listed will be queried. For details, see section 7 Tag Management. Issue 05 ( ) 40

44 4 Zone Management Request None Response Table 4-33 Parameters in the response zones List data structure Zone list object metadata object Number of resources that meet the filter condition Table 4-34 describes parameters under the zones field, and Table 4-35 describes the parameter under the metadata field. Table 4-34 Description of the zones field id string Zone ID, which is a UUID used to identify the zone name string Zone name description string Zone description string address of the administrator managing the zone zone_type string Zone type, which can be public or private ttl int TTL value of the SOA record set in the zone serial int Serial number in the SOA record set in the zone, which identifies the change on the primary DNS server status enum Resource status The value can be PENDING_CREATE, ACTIVE, PENDING_DELETE, or ERROR. record_num int Number of record sets in the zone pool_id string Pool ID of the zone, which is assigned by the system project_id string Project ID of the zone created_at string Time when the zone was created updated_at string Time when the zone was updated Issue 05 ( ) 41