Back to top

API v2.0 Authentication Overview

Summary

API v2身份验证使用与CenturyLink Cloud控制门户相同的登录信息。 The username and password are provided to the API and in return, the user gets back a credentials object that contains a valid bearer token. This token -- which can be reused for up to 2 weeks -- must be provided on each subsequent API request.

Walkthrough

.NET Framework Example

Below is a brief demonstration of using the .NET framework to retrieve a valid token from the API authentication service.

  1. Reference the assemblies needed to make HTTP requests.
using System.Net.Http;
using System.Net.Http.Headers;
  1. Create an instance of the HttpClient object.
HttpClient authClient = new HttpClient();
  1. Add an Accept header to indicate that returning JSON as a response is ok.
authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
  1. Create an HttpContent object to hold the JSON payload ({"username": "[username]", "password": "[password]"}) sent to the API. Also, note that the content type application/json is set.
HttpContent content =
   new StringContent("{ \"username\":\"[username]\", \"password\":\"[password]\" }", null, "application/json");
  1. Invoke the API and send the HTTP content using a POST command.
HttpResponseMessage message =
    await authClient.PostAsync("https://api.ctl.io/v2/authentication/login", content);
  1. Load the response into a string for parsing.
string responseString = await message.Content.ReadAsStringAsync();

If valid credentials are provided, an HTTP 200 status is returned along with the following JSON payload:

  {
     "userName":"user@company.com",
     "accountAlias":"RLS1",
     "locationAlias":"WA1",
     "roles":[
        "ServerAdmin",
        "AccountAdmin"
     ],
     "bearerToken":"[LONG TOKEN VALUE]"
  }

这些结果显示了用户的父账户、默认数据中心位置以及被分配的平台角色。 The bearerToken is the value that must be added to the HTTP Authorization header when calling any other API service.该令牌可识别用户身份及其在API中的权限。

如果您提供的登录信息无效,您将收到HTTP 400(请求无效)和以下响应消息:

{"message":"We didn't recognize the username or password you entered. Please try again."}
  1. Submit a request: the following .NET code demonstrates how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".
  HttpClient authClient = new HttpClient();

  authClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

  // Add bearer token to the header
  authClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "Bearer [LONG TOKEN VALUE]");

  HttpResponseMessage message = await authClient.GetAsync("https://api.ctl.io/v2/datacenters/DEMO/CA1");

  string responseString = await message.Content.ReadAsStringAsync();

PowerShell Example

Below is a brief demonstration of how PowerShell can be used to retrieve a valid token from the API authentication service.

  1. Log into the API.
$Body = @{ 
Username = 'CONTROL_USERNAME' 
Password = 'CONTROL_PASSWORD' 
}
  1. Log in to the Platform and get back a bearerToken.
$LogonUri = 'https://api.ctl.io/v2/authentication/login' 
$LogonResponse = Invoke-RestMethod -Method Post -Uri $LogonUri -Body $Body -SessionVariable WebSession
  1. Pull the BearerToken out of the response and format it correctly. Note that a prefix of "Bearer " is required.
$Bearer = 'Bearer ' + $LogonResponse.bearerToken
  1. Add Accept and Authorization headers to the session variable to be used on future requests.
$WebSession.Headers.Add('Accept', 'application/json') 
$WebSession.Headers.Add('Authorization', $Bearer)

You can now use the session variable for authenticating further API calls. Example:

Here's an example of pulling server credentials:

  $AccountAlias = 'ACCOUNT_ALIAS' 
  $ServerName = 'SERVER_NAME' 
  $ServercredsURL = "https://api.ctl.io/v2/servers/$AccountAlias/$ServerName/credentials" 
  $ServerCreds = Invoke-RestMethod -Uri $servercredsURL -WebSession $WebSession 
  $ServerCreds

Raw HTTP Example

下方为在API身份验证服务中检索有效令牌时原始HTTP请求和响应消息的示例。

请求

POST https://api.ctl.io/v2/authentication/login HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Content-Length: 54

{
  "username": "[username]",
  "password": "[password]"
}

响应

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Fri, 03 Jan 2015 21:23:45 GMT
Content-Length: 149

{
  "userName": "user@company.com",
  "accountAlias": "RLS1",
  "locationAlias": "WA1",
  "roles": [
    "ServerAdmin",
    "AccountAdmin"
  ],
  "bearerToken": "[LONG TOKEN VALUE]"
}

这些结果显示了用户的父账户、默认数据中心位置以及被分配的平台角色。调用任何其他API服务时,bearerToken值必须添加至HTTP 身份验证标头中。该令牌可识别用户身份及其在API中的权限。

如果您提供的登录信息无效,您将收到HTTP 400(请求无效)和以下响应消息:

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Fri, 03 Jan 2015 21:26:45 GMT
Content-Length: 89

{"message":"We didn't recognize the username or password you entered. Please try again."}

The following raw HTTP request message shows how a user can make a secure API request to retrieve the root Group in a particular data center. Note that the bearerToken is added to the header of the request, with a prefix of "Bearer ".

GET https://api.ctl.io/v2/datacenters/RLS1/WA1 HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Content-Length: 0
Authorization: Bearer [LONG TOKEN VALUE]

API v2.0 Links Framework

概览

The CenturyLink Cloud v2 REST API utilizes the concept of "linking" to reference other related entities from within JSON response payloads. Many of the JSON response entities include a links attribute which contains an array of link entities for resources that are related the object that was just acted upon.

This link model helps with both discoverability as well as use-case scalability. In addition, it provides a mechanism for exposing only those endpoints that are available to a user based on their role. In other words, a user will only see links and associated actions that they have access to. Each link entity contains a URL in the href attribute so the API user may simply follow the link to perform a followup action.

Link Entity

Each link entity defines the following properties. For more details about each specific link type, see the Link Definitions for each resource type.

Name Type 描述 Req.
rel 字符串 The link type, as described in the table below.
href 字符串 Address of the resource.
id 字符串 Unique ID of the resource.
用户名 字符串 Friendly name of the resource.
verbs array Valid HTTP verbs that can act on this resource. If none are explicitly listed, GET is assumed to be the only one.

API v2.0 Overview

The CenturyLink Cloud has a new, improved API for performing the same actions programmatically as you can with the Control Portal. The API is RESTful and works with JSON messages over HTTP. It relies on the standard HTTP verbs including GET, POST, PUT, DELETE, and PATCH.

The URL format of the service is: https://api.ctl.io/v2/{resource}/{account alias}. As an example, to retrieve the top level Group for a given data center, you would issue a GET request to https://api.ctl.io/v2/datacenters/ALIAS/WA1. The HTTP request must include Content-Type and Accepts headers set to application/json.

验证

Service authentication is done via bearer tokens and is outlined in the Authentication Overview and also the Login API description.

Links Framework

The CenturyLink Cloud v2 REST API utilizes the concept of "linking" to reference other related entities from within JSON response payloads. See more information in our overview of the Links Framework.

HTTP Response Codes

The service responds to requests using standard HTTP codes, and if applicable, a JSON payload.

HTTP Code 描述
200 OK. Sent when requests are immediately successful and did NOT create a new URL-addressable resource.
201 CREATED. Sent when requests are immediately successful and DID create a new URL-addressable resource.
202 ACCEPTED. Sent when requests result in a scheduled activity. Response body will include a URL for them to get the status of the activity.
204 NO CONTENT. Sent when requests are immediately successful but return no additional information about the resource.
400 BAD REQUEST. Sent when something is wrong with the query string or message body.
401 UNAUTHORIZED. Sent when a bearer token is not provided.
403 FORBIDDEN. Sent if the request violates the security demands of the service.
404 NOT FOUND. Sent if the URL points to a non-existent resource.
500 INTERNAL SERVER ERROR. Sent if the service experiences an error through no fault of the user.

Create Alert Policy

Creates an alert policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new alert policy within a given account.

URL

Structure

POST https://api.ctl.io/v2/alertPolicies/{accountAlias}

Example

POST https://api.ctl.io/v2/alertPolicies/ALIAS

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.

Actions Entity

Name Type 描述
action 字符串 The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type 描述
metric 字符串 The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration 字符串 The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold 数字 The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "name":"Disk Above 80%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "user@company.com"
        ]
      }
    }
  ],
  "triggers":[
    {
      "metric":"disk",
      "duration":"00:05:00",
      "threshold":80.0
    }
  ]
}

响应

Entity Definition

Name Type 描述
id 字符串 ID of the alert policy.
用户名 字符串 Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id" : "6fbe6ba659424b738e1134ab3be7b4b4",
  "name" : "Disk Above 80%",
  "actions" : [
    {
      "action" : "email",
      "settings" : {
        "recipients" : [
          "user@company.com"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 80.0
    }
  ]
}

Delete Alert Policy

Deletes a given alert policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific alert policy within a given account.

URL

Structure

DELETE https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

DELETE https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
PolicyId 字符串 ID of the alert policy being queried.

响应

The response will not contain JSON content, but should return a standard HTTP 200 OK response upon deletion of the policy.

Get Alert Policies

Gets a list of alert policies within a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of alert policies within a given account and what servers are part of these policies. You can also use the IDs provided in this list to add a server to that alert policy using the API.

URL

Structure

GET https://api.ctl.io/v2/alertPolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/alertPolicies/ALIAS

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

响应

The response will be an items objects referencing an array containing one entity for each alert policy in the given account.

Entity Definition

Name Type 描述
id 字符串 ID of the alert policy.
用户名 字符串 Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Actions Entity

Name Type 描述
action 字符串 The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type 描述
metric 字符串 The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration 字符串 The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold 数字 The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "items":[
    {
      "id":"999de90f25ab4308a6c346cd03602fef",
      "name":"Memory Above 90%",
      "actions":[
        {
          "action":"email",
          "settings":{
            "recipients":[
              "user@company.com"
            ]
          }
        }
      ],
      "links":[
        {
          "rel":"self",
          "href":"/v2/alertPolicies/ALIAS/999de90f25ab4308a6c346cd03602fef",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ],
      "triggers":[
        {
          "metric":"memory",
          "duration":"00:10:00",
          "threshold":90.0
        }
      ]
    },
    {
      "id":"175c3b5743d64cea952a5cca03bdb2da",
      "name":"CPU Above 75%",
      "actions":[
        {
          "action":"email",
          "settings":{
            "recipients":[
              "user@company.com"
            ]
          }
        }
      ],
      "links":[
        {
          "rel":"self",
          "href":"/v2/alertPolicies/ALIAS/175c3b5743d64cea952a5cca03bdb2da",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ],
      "triggers":[
        {
          "metric":"cpu",
          "duration":"00:05:00",
          "threshold":75.0
        }
      ]
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/alertPolicies/ALIAS",
      "verbs":[
        "GET",
        "POST"
      ]
    }
  ]
}

Get Alert Policy

Gets a given alert policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a specific alert policy within a given account.

URL

Structure

GET https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
PolicyId 字符串 ID of the alert policy being queried.

响应

Entity Definition

Name Type 描述
id 字符串 ID of the alert policy.
用户名 字符串 Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Actions Entity

Name Type 描述
action 字符串 The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type 描述
metric 字符串 The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration 字符串 The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold 数字 The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "id":"999de90f25ab4308a6c346cd03602fef",
  "name":"Memory Above 90%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "user@company.com"
        ]
      }
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/alertPolicies/ALIAS/999de90f25ab4308a6c346cd03602fef",
      "verbs":[
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers":[
    {
      "metric":"memory",
      "duration":"00:10:00",
      "threshold":90.0
    }
  ]
}

Update Alert Policy

Updates the name of an alert policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name of an existing alert policy within a given account.

URL

Structure

PUT https://api.ctl.io/v2/alertPolicies/{accountAlias}/{policyId}

Example

PUT https://api.ctl.io/v2/alertPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
PolicyId 字符串 ID of the alert policy being updated.

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.

Actions Entity

Name Type 描述
action 字符串 The only action currently supported by alerts is email.
settings complex The only setting currently supported is the recipients list, which is an array of email addresses to be notified when the alert is triggered.

Triggers Entity

Name Type 描述
metric 字符串 The metric on which to measure the condition that will trigger the alert: cpu, memory, or disk.
duration 字符串 The length of time in minutes that the condition must exceed the threshold: 00:05:00, 00:10:00, 00:15:00.
threshold 数字 The threshold that will trigger the alert when the metric equals or exceeds it. This number represents a percentage and must be a value between 5.0 - 95.0 that is a multiple of 5.0.

Examples

JSON

{
  "name":"Disk Above 90%",
  "actions":[
    {
      "action":"email",
      "settings":{
        "recipients":[
          "user@company.com"
        ]
      }
    }
  ],
  "triggers":[
    {
      "metric":"disk",
      "duration":"00:05:00",
      "threshold":90.0
    }
  ]
}

响应

Entity Definition

Name Type 描述
id 字符串 ID of the alert policy.
用户名 字符串 Name of the alert policy.
actions array The actions to perform when the alert is triggered.
triggers array The definition of the triggers that fire the alert.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id" : "6fbe6ba659424b738e1134ab3be7b4b4",
  "name" : "Disk Above 90%",
  "actions" : [
    {
      "action" : "email",
      "settings" : {
        "recipients" : [
          "user@company.com"
        ]
      }
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/alertPolicies/ALIAS/6fbe6ba659424b738e1134ab3be7b4b4",
      "verbs" : [
        "GET",
        "DELETE",
        "PUT"
      ]
    }
  ],
  "triggers" : [
    {
      "metric" : "disk",
      "duration" : "00:05:00",
      "threshold" : 90.0
    }
  ]
}

Create Anti-Affinity Policy

Creates an anti-affinity policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new anti-affinity policy within a given account.

URL

Structure

POST https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}

Example

POST https://api.ctl.io/v2/antiAffinityPolicies/ALIAS

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the anti-affinity policy.
地点 字符串 Data center location of the anti-affinity policy.

Examples

JSON

{
  "name":"New Anti-Affinity Policy",
  "location":"VA1"
}

响应

Entity Definition

Name Type 描述
id 字符串 ID of the anti-affinity policy.
用户名 字符串 Name of the anti-affinity policy.
地点 字符串 Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{

  "id":"80a7bf90b459454b859399aef54f4173",
  "name":"New Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b459454b859399aef54f4173"
    }
  ]
}

Delete Anti-Affinity Policy

Deletes a given anti-affinity policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific anti-affinity policy within a given account.

URL

Structure

DELETE https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

DELETE https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
PolicyId 字符串 ID of the anti-affinity policy being queried.

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the policy.

Get Anti-Affinity Policies

Gets a list of anti-affinity policies within a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of anti-affinity policies within a given account and what servers are part of these policies. You can also use the IDs provided in this list to add a server to that anti-affinity policy using the API.

URL

Structure

GET https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/antiAffinityPolicies/ALIAS

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

响应

The response will be an items objects referencing an array containing one entity for each anti-affinity policy in the given account.

Entity Definition

Name Type 描述
id 字符串 ID of the anti-affinity policy.
用户名 字符串 Name of the anti-affinity policy.
地点 字符串 Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "items":[
    {
      "id":"80a7bf90b199454b859399bff54f4173",
      "name":"My Anti-Affinity Policy",
      "location":"VA1",
      "links":[
        {
          "rel":"self",
          "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        },
        {
          "rel":"server",
          "href":"/v2/servers/alias/va1aliashypsc01",
          "id":"va1aliashypsc01",
          "name":"VA1ALIASHYPSC01"
        }
      ]
    },
    {
      "id":"ca8b07035cf844f3b4f953074c2630eb",
      "name":"My Other Anti-Affinity Policy",
      "location":"WA1",
      "links":[
        {
          "rel":"self",
          "href":"/v2/antiAffinityPolicies/alias/ca8b07035cf844f3b4f953074c2630eb",
          "verbs":[
            "GET",
            "DELETE",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias",
      "verbs":[
        "GET",
        "POST"
      ]
    }
  ]
}

Get Anti-Affinity Policy

Gets a given anti-affinity policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a specific anti-affinity policy within a given account.

URL

Structure

GET https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
PolicyId 字符串 ID of the anti-affinity policy being queried.

响应

Entity Definition

Name Type 描述
id 字符串 ID of the anti-affinity policy.
用户名 字符串 Name of the anti-affinity policy.
地点 字符串 Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id":"80a7bf90b199454b859399bff54f4173",
  "name":"My Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173",
      "verbs":[
        "GET",
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel":"server",
      "href":"/v2/servers/alias/va1aliashypsc01",
      "id":"va1aliashypsc01",
      "name":"VA1ALIASHYPSC01"
    }
  ]
}

Update Anti-Affinity Policy

Updates the name of an anti-affinity policy in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name of an existing anti-affinity policy within a given account.

URL

Structure

PUT https://api.ctl.io/v2/antiAffinityPolicies/{accountAlias}/{policyId}

Example

PUT https://api.ctl.io/v2/antiAffinityPolicies/ALIAS/80a7bf90b199454b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
PolicyId 字符串 ID of the anti-affinity policy being updated.

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the anti-affinity policy.

Examples

JSON

{
  "name":"Changed Name of Anti-Affinity Policy",
}

响应

Entity Definition

Name Type 描述
id 字符串 ID of the anti-affinity policy.
用户名 字符串 New name of the anti-affinity policy.
地点 字符串 Data center location of the anti-affinity policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON

{
  "id":"80a7bf90b199454b859399bff54f4173",
  "name":"My Anti-Affinity Policy",
  "location":"VA1",
  "links":[
    {
      "rel":"self",
      "href":"/v2/antiAffinityPolicies/alias/80a7bf90b199454b859399bff54f4173"
    },
    {
      "rel":"server",
      "href":"/v2/servers/alias/va1aliashypsc01",
      "id":"va1aliashypsc01",
      "name":"VA1ALIASHYPSC01"
    }
  ]
}

Acquires an authentication token used for subsequent queries to the API.

When to Use It

Use this API operation before you call any other API operation. It shows a user's roles, primary data center, and a valid bearer token.

URL

Structure

POST https://api.ctl.io/v2/authentication/login

请求

Content Properties

Name Type 描述 Req.
username 字符串 Control Portal user name value
password 字符串 Control Portal password value.

Examples

JSON

{
   "username":"demouser1",
   "password":"mypassword"
}

响应

Entity Definition

Name Type 描述
userName 字符串 Control Portal user name value
accountAlias 字符串 Account that contains this user record
locationAlias 字符串 Default data center of the user
roles array Permission roles associated with this user
bearerToken 字符串 Security token for this user that is included in the Authorization header for all other API requests as "Bearer [LONG TOKEN VALUE]".

Examples

JSON

{
    "userName": "user@email.com",
    "accountAlias": "ALIAS",
    "locationAlias": "DC1",
    "roles": [
        "AccountAdmin",
        "ServerAdmin"
    ],
    "bearerToken": "[LONG TOKEN VALUE]"
}

Get Vertical Autoscale Policies

Gets a list of vertical autoscale policies for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of vertical autoscale policies for a given account, and to see what servers are associated with these policies. You can also use the IDs provided in this list to add a server to that autoscale policy using Set Vertical Autoscale Policy On Server API method.

URL

Structure

GET https://api.ctl.io/v2/autoscalePolicies/{accountAlias}

Example

GET https://api.ctl.io/v2/autoscalePolicies/ALIAS

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account

响应

The response will be an array containing one entity for each autoscale policy in the given account.

Entity Definition

Name Type 描述
id 字符串 ID of the vertical autoscale policy
用户名 字符串 Name of the vertical autoscale policy
resourceType 字符串 The resource type to autoscale; only cpu is supported at this time
thresholdPeriodMinutes integer Duration the resource must be at min/max in order to autoscale (5, 10, 15, or 30 minutes)
scaleUpIncrement integer Number of CPU to increase on a scale up event (1, 2, or 4)
range complex The range defining the minimum and maximum number of CPU to allow (between 1-16)
scaleUpThreshold integer Will scale up when resource it at this setting for at least the threshold period (between 1-100)
scaleDownThreshold integer Will scale down when resource it at this setting for at least the threshold period (between 1-100)
scaleDownWindow complex A server reboot is required for all resource scale downs; this is the scale down window during which the resource will be set to the policy's minimum value.
links array Collection of entity links that point to resources related to this policy

Range Definition

Name Type 描述
min integer Maximum number of CPU
max integer Minimum number of CPU

ScaleDownWindow Definition

Name Type 描述
start 字符串 Start time of window in UTC
end 字符串 End time of window in UTC

Examples

JSON

      {
        "id": "3b6f26003c224596bc7e748a0adc97d5",
        "name": "Production Database Scale Policy",
        "resourceType": "cpu",
        "thresholdPeriodMinutes": 5,
        "scaleUpIncrement": 1,
        "range": {
          "max": 6,
          "min": 2
        },
        "scaleUpThreshold": 85,
        "scaleDownThreshold": 15,
        "scaleDownWindow": {
          "start": "02:00",
          "end": "04:00"
        },
        "links": [
          {
            "rel": "self",
            "href": "/v2/autoscalePolicies/ALIAS/3b6f26003c224596bc7e748a0adc97d5"
          }
        ]
      },
      {
        "id": "23a68b22e35b4983abd1051fae10ee7b",
        "name": "Another CPU Autoscale Policy",
        "resourceType": "cpu",
        "thresholdPeriodMinutes": 5,
        "scaleUpIncrement": 1,
        "range": {
          "max": 4,
          "min": 1
        },
        "scaleUpThreshold": 85,
        "scaleDownThreshold": 15,
        "scaleDownWindow": {
          "start": "00:00",
          "end": "23:00"
        },
        "links": [
          {
            "rel": "self",
            "href": "/v2/autoscalePolicies/ALIAS/23a68b22e35b4983abd1051fae10ee7b"
          }
        ]
      }

Get Vertical Autoscale Policy

Gets a given vertical autoscale policy by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the details of a vertical autoscale policy for a given account.

URL

Structure

GET https://api.ctl.io/v2/autoscalePolicies/{accountAlias}/{policyId}

Example

GET https://api.ctl.io/v2/autoscalePolicies/ALIAS/80a7bf90b199464b859399bff54f4173

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
policyId 字符串 ID of the autoscale policy being queried

响应

Entity Definition

Name Type 描述
id 字符串 ID of the vertical autoscale policy
用户名 字符串 Name of the vertical autoscale policy
resourceType 字符串 The resource type to autoscale; only cpu is supported at this time
thresholdPeriodMinutes integer Duration the resource must be at min/max in order to autoscale (5, 10, 15, or 30 minutes)
scaleUpIncrement integer Number of CPU to increase on a scale up event (1, 2, or 4)
range complex The range defining the minimum and maximum number of CPU to allow (between 1-16)
scaleUpThreshold integer Will scale up when resource it at this setting for at least the threshold period (between 1-100)
scaleDownThreshold integer Will scale down when resource it at this setting for at least the threshold period (between 1-100)
scaleDownWindow complex A server reboot is required for all resource scale downs. This is the scale down window during which the resource will be set to the policy's minimum value.
links array Collection of entity links that point to resources related to this policy

Range Definition

Name Type 描述
min integer Maximum number of CPU
max integer Minimum number of CPU

ScaleDownWindow Definition

Name Type 描述
start 字符串 Start time of window in UTC
end 字符串 End time of window in UTC

Examples

JSON

    {
      "id": "9d14822c1e8541cea11703cf2b078c9d",
      "name": "Production Database Scale Policy",
      "resourceType": "cpu",
      "thresholdPeriodMinutes": 5,
      "scaleUpIncrement": 1,
      "range": {
        "max": 6,
        "min": 2
      },
      "scaleUpThreshold": 85,
      "scaleDownThreshold": 15,
      "scaleDownWindow": {
        "start": "02:00",
        "end": "04:00"
      },
      "links": [
        {
          "rel": "self",
          "href": "/v2/autoscalePolicies/ALIAS/9d14822c1e8541cea11703cf2b078c9d"
        }
      ]
    }

Remove Vertical Autoscale Policy from Server

Removes the autoscale policy from a given server, if the policy has first been applied to the server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to remove the autoscale policy from a server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverId 字符串 ID of the server. Retrieved from query to containing a group, or by looking at the URL when viewing a server in the Control Portal.

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the policy from the server.

Set Vertical Autoscale Policy on Server

Sets the autoscale policy for a specified server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set the autoscale policy of a server.

URL

Structure

PUT https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

PUT https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverId 字符串 ID of the server. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
id 字符串 The unique identifier of the autoscale policy to apply to the server. Can be retrieved by calling Get Vertical Autoscale Policies.

Examples

JSON

    {
      "id": "3440b69f139c435b8f9462b0661014fc"
    }

响应

Entity Definition

Name Type Value 描述
id 字符串 ID of the autoscale policy.
links array Collection of entity links that point to resources related to this policy.

Examples

JSON


  {
    "id": "3440b69f139c435b8f9462b0661014fc",
    "links": [
      {
        "rel": "self",
        "href": "/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy"
      }
    ]
  }

View Vertical Autoscale Policy on Server

Gets the autoscale policy of a given server, if a policy has been applied on the server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the autoscale policy of a given server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/cpuAutoscalePolicy

Example

GET https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverId 字符串 ID of the server. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

响应

Entity Definition

Name Type Value 描述
id 字符串 ID of the autoscale policy
links array Collection of entity links that point to resources related to this policy

Examples

JSON

  {
    "id": "6c8d7b5349054fe6a532539ff066b53b",
    "links": [
      {
        "rel": "self",
        "href": "/v2/servers/ALIAS/WA1ALIASSERV0101/cpuAutoscalePolicy"
      }
    ]
  }

Get Invoice Data for an Account Alias

Gets a list of invoicing data for a given account alias for a given month. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

NOTE: THE DATA RETURNED IN THIS API ARE USAGE ESTIMATES ONLY, AND DOES NOT REPRESENT AN ACTUAL BILL.

When to Use It

Use this API operation when you want to get invoicing data for a given account for a given month.

URL

Structure

GET https://api.ctl.io/v2/invoice/{accountAlias}/{year}/{month}

Example

GET https://api.ctl.io/v2/invoice/ALIAS/2015/7/?pricingAccount=PALIAS

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
year integer Year of usage, in YYYY format.
month integer Monthly period of usage, in M format.
pricingAccountAlias 字符串 Short code of the account that sends the invoice for the accountAlias

响应

The response includes a JSON object containing an array with invoicing data.

Entity Definition

Name Type 描述
id 字符串 ID of the account alias being queried
terms 字符串 payment terms associated with the account
companyName 字符串 Description of the account name
accountAlias 字符串 Short code for a particular account
pricingAccountAlias 字符串 Short code for a particular account that receives the bill for the accountAlias usage
parentAccountAlias 字符串 Short code for the parent account alias associated with the account alias being queried
address1 字符串 First line of the address associated with accountAlias
address2 字符串 Second line of the address associated with accountAlias
city 字符串 City associated with the accountAlias
stateProvince 字符串 State or province associated with the accountAlias
postalCode 字符串 Postal code associated with the accountAlias
billingContactEmail 字符串 Billing email address associated with the accountAlias
invoiceCCEmail 字符串 Additional billing email address associated with the accountAlias
totalAmount decimal Invoice amount in dollars
invoiceDate 字符串 Date the invoice is finalized
poNumber 字符串 Purchase Order associated with the Invoice
lineItems array Usage details of a resource or collection of similar resources

Line Items Definition

Name Type 描述
quantity integer Quantity of the line item
描述 字符串 Text description of the line item
unitCost decimal Unit cost of the line item
itemTotal decimal Total cost of the line item
serviceLocation 字符串 Location of the line item
itemDetails complex Details about the line item

Examples

JSON

{
    "id": "ALIAS69849A66",
    "terms": "Net 15",
    "companyName": "CTL Cloud Solutions",
    "accountAlias": "ALIAS",
    "pricingAccountAlias": "ALIAS",
    "parentAccountAlias": "PALIAS",
    "address1": "1100 112th Ave NE",
    "address2": "Suite 400",
    "city": "Bellevue",
    "stateProvince": "WA",
    "postalCode": "98004",
    "billingContactEmail": "billing@domain.com",
    "invoiceCCEmail": "",
    "totalAmount": 0,
    "invoiceDate": "2015-08-01T00:00:00Z",
    "poNumber": "",
    "lineItems": [
        {
            "quantity": 1,
            "description": "Server Group: DEMO - VA1",
            "unitCost": 153.93,
            "itemTotal": 153.93,
            "serviceLocation": "VA1",
            "itemDetails": [
                {
                    "description": "VA1ALIASJMB01",
                    "cost": 153.93
                }
            ]
        },
        {
            "quantity": 1,
            "description": "Shared Load Balancer - CA1",
            "unitCost": 29.76,
            "itemTotal": 29.76,
            "serviceLocation": "CA1",
            "itemDetails": []
        },
        {
            "quantity": 1,
            "description": "Additional Networks - GB3",
            "unitCost": 45,
            "itemTotal": 45,
            "serviceLocation": "GB3",
            "itemDetails": []
        },
    ]
}

Get Custom Fields

Retrieves the custom fields defined for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to find out the details of what custom fields are defined for an account.

URL

Structure

GET https://api.ctl.io/v2/accounts/{accountAlias}/customFields

Example

GET https://api.ctl.io/v2/accounts/ACCT/customFields

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

响应

The response will be an array containing one entity for each custom field defined in the given account.

Entity Definition

Name Type 描述
id 字符串 Unique identifier of the custom field.
用户名 字符串 Friendly name of the custom field as it appears in the UI.
isRequired boolean Boolean value representing whether or not a value is required for this custom field.
类型 字符串 The type of custom field defined. Will be either "text" (free-form text field), "checkbox" (boolean value), or "option" (dropdown list).
options array Array of name-value pairs corresponding to the options defined for this field. (Empty for "text" or "checkbox" field types.)

Examples

JSON

[
  {
    "id":"dba67b156f77123fb413ddfa3dc4ac1d",
    "name":"Cost Center",
    "isRequired":false,
    "type":"text",
    "options":[]
  },
  {
    "id":"58f83af6123846769ee6cb091ce3561e",
    "name":"Production",
    "isRequired":true,
    "type":"checkbox",
    "options":[]
  },
  {
    "id":"22f002123e3b46d9a8b38ecd4c6df7f9",
    "name":"Color",
    "isRequired":true,
    "type":"option",
    "options":[
      {
        "name":"red",
        "value":"Red"
      },
      {
        "name":"blue",
        "value":"Blue"
      }
    ]
  }
]

Get Data Center Bare Metal Capabilities

Gets the list of bare metal capabilities that a specific data center supports for a given account, including the list of configuration types and the list of supported operating systems. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the available capabilities of related to provisioning bare metal servers in a data center for your account. Specifically, this operation is helpful for retrieving the list of configuration identifiers and OS types to use when creating a bare metal server.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}/bareMetalCapabilities

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/VA1/bareMetalCapabilities

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.

响应

Entity Definition

Name Type 描述
skus array Collection of available bare metal configuration types to pass in to configurationId when creating a bare metal server
operatingSystems array Collection of available operating systems when creating a bare metal server

SKUs Definition

Name Type 描述
id 字符串 The configurationId to pass to the Create Server API operation when creating a bare metal server.
hourlyRate 数字 Price per hour for the given configuration.
availability 字符串 The level of availability for the given configuration: either high, low, or none.
memory array Information about the memory on the server.
processor complex Information about the physical processors on the server.
存储 array Collection of disk information, each item representing one physical disk on the server.

Memory Definition

Name Type 描述
capacityGB 数字 Memory capacity in gigabytes

Processor Definition

Name Type 描述
coresPerSocket 数字 Number of cores for each processor socket
描述 字符串 Description of the processor including model and clock speed
sockets 数字 Number of sockets

Storage Definition

Name Type 描述
capacityGB 数字 Drive capacity in gigabytes
speedRpm 数字 RPM (revolutions per minutes) speed of the disk
类型 字符串 Disk type. Only Hdd currently supported.

OperatingSystems Definition

Name Type 描述
类型 字符串 Underlying unique name for the OS type
描述 字符串 Friendly description for the OS type
hourlyRatePerSocket 数字 Price per hour per socket for the OS type.

Examples

JSON

{
  "skus": [
    {
      "id": "529e2592a3e640a7c2617b5e8bc8feaed95eab22",
      "hourlyRate": 0.56,
      "availability": "high",
      "memory": [
        {
          "capacityGB": 16
        }
      ],
      "processor": {
        "coresPerSocket": 4,
        "description": "Intel(R) Xeon(R) CPU E3-1271 v3 @ 3.60GHz",
        "sockets": 1
      },
      "storage": [
        {
          "capacityGB": 1000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 1000,
          "speedRpm": 7200,
          "type": "Hdd"
        }
      ]
    },
    {
      "id": "f24b18ba2ce23657657444601649c7b8b7f9b60c",
      "hourlyRate": 1.65,
      "availability": "none",
      "memory": [
        {
          "capacityGB": 64
        }
      ],
      "processor": {
        "coresPerSocket": 6,
        "description": "Intel(R) Xeon(R) CPU E5-2620 v3 @ 2.40GHz",
        "sockets": 2
      },
      "storage": [
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        },
        {
          "capacityGB": 2000,
          "speedRpm": 7200,
          "type": "Hdd"
        }
      ]
    }
  ],
  "operatingSystems": [
    {
      "type": "centOS6_64Bit",
      "description": "CentOS 6 64-bit",
      "hourlyRatePerSocket": 0
    },
    {
      "type": "redHat6_64Bit",
      "description": "RedHat Enterprise Linux 6 64-bit",
      "hourlyRatePerSocket": 0.075
    },
    {
      "type": "ubuntu14_64Bit",
      "description": "Ubuntu 14 64-bit",
      "hourlyRatePerSocket": 0
    },
    {
      "type": "windows2012R2Standard_64bit",
      "description": "Windows 2012 R2 Standard 64-bit",
      "hourlyRatePerSocket": 0.04
    },
    {
      "type": "windows2012R2Datacenter_64bit",
      "description": "Windows 2012 R2 Datacenter 64-bit",
      "hourlyRatePerSocket": 0.279
    }
  ]
}

Get Data Center Deployment Capabilities

Gets the list of capabilities that a specific data center supports for a given account, including the deployable networks, OS templates, and whether features like shared load balancer configuration are available. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the available capabilities of a data center for your account. Specifically, this operation is helpful for retrieving network identifiers and OS template names to use when creating a server.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}/deploymentCapabilities

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/UC1/deploymentCapabilities

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.

响应

Entity Definition

Name Type 描述
supportsSharedLoadBalancer boolean Whether or not this data center provides support for shared load balancer configuration
supportsBareMetalServers boolean Whether or not this data center provides support for provisioning bare metal servers
deployableNetworks array Collection of networks that can be used for deploying servers
templates array Collection of available templates in the data center that can be used to create servers
importableOSTypes array Collection of available OS types that can be imported as virtual machines.

DeployableNetworks Definition

Name Type 描述
用户名 字符串 User-defined name of the network
networkId 字符串 Unique identifier of the network
类型 字符串 Network type, usually "private" for networks created by the user
accountID 字符串 Account alias for the account in which the network exists

Templates Definition

Name Type 描述
用户名 字符串 Underlying unique name for the template
描述 字符串 Description of the template at it appears in the Control Portal UI
storageSizeGB integer The amount of storage allocated for the primary OS root drive
capabilities array List of capabilities supported by this specific OS template (example: whether adding CPU or memory requires a reboot or not)
reservedDrivePaths array List of drive path names reserved by the OS that can't be used to name user-defined drives
drivePathLength integer Length of the string for naming a drive path, if applicable

Examples

JSON

{
  "supportsBareMetalServers":false,
  "supportsSharedLoadBalancer":true,
  "deployableNetworks":[
    {
      "name":"My Network",
      "networkId":"a933432bd8894e84b6c4fb123e48cb8b",
      "type":"private",
      "accountID":"ACCT"
    }
  ],
  "templates":[
    {
      "name":"UBUNTU-14-64-TEMPLATE",
      "description":"Ubuntu 14 | 64-bit",
      "storageSizeGB":17,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "bin",
        "boot",
        "build",
        "cdrom",
        "compat",
        "dist",
        "dev",
        "entropy",
        "etc",
        "home",
        "initrd.img",
        "lib",
        "lib64",
        "libexec",
        "lost+found",
        "media",
        "mnt",
        "opt",
        "proc",
        "root",
        "sbin",
        "selinux",
        "srv",
        "sys",
        "tmp",
        "usr",
        "var",
        "vmlinuz"
      ]
    },
    {
      "name":"WIN2012R2DTC-64",
      "description":"Windows 2012 R2 Datacenter Edition | 64-bit",
      "storageSizeGB":60,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "a",
        "b",
        "c",
        "d"
      ],
      "drivePathLength":1
    },
    {
      "name":"WA1ACCTCUST01",
      "description":"My Custom Template",
      "storageSizeGB":16,
      "capabilities":[
        "cpuAutoscale"
      ],
      "reservedDrivePaths":[
        "bin",
        "boot",
        "build",
        "cdrom",
        "compat",
        "dist",
        "dev",
        "entropy",
        "etc",
        "home",
        "initrd.img",
        "lib",
        "lib64",
        "libexec",
        "lost+found",
        "media",
        "mnt",
        "opt",
        "proc",
        "root",
        "sbin",
        "selinux",
        "srv",
        "sys",
        "tmp",
        "usr",
        "var",
        "vmlinuz"
      ]
    }
  ]
}

Get Data Center List

Gets the list of data centers that a given account has access to. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of data center names and codes that you have access to. Using that list of data centers, you can then query for the root group, and all the child groups in an entire data center.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}

Example

GET https://api.ctl.io/v2/datacenters/ALIAS

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

响应

Entity Definition

Name Type 描述
id 字符串 Short value representing the data center code
用户名 字符串 Full, friendly name of the data center
links array Collection of entity links that point to resources related to this data center

Examples

JSON

[
  {
    "id": "DC1",
    "name": "DC FRIENDLY NAME",
    "links": [
      {
        "rel": "self",
        "href": "/v2/datacenters/ALIAS/DC1"
      }
    ]
  },
  {
    "id": "DC2",
    "name": "DC2 FRIENDLY NAME",
    "links": [
      {
        "rel": "self",
        "href": "/v2/datacenters/ALIAS/DC2"
      }
    ]
  }
]

Get Data Center

Gets the details of a specific data center the account has access to. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover the name of the root hardware group for a data center. Once you have that group alias, you can issue a secondary query to retrieve the entire group hierarchy for a given data center.

URL

Structure

GET https://api.ctl.io/v2/datacenters/{accountAlias}/{dataCenter}?groupLinks=true|false

Example

GET https://api.ctl.io/v2/datacenters/ALIAS/UC1?groupLinks=true

请求

URI and Querystring Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
GroupLinks boolean Determine whether link collections are returned for each group

响应

Entity Definition

Name Type 描述
id 字符串 Short value representing the data center code
用户名 字符串 Full, friendly name of the data center
links array Collection of entity links that point to resources related to this data center

Examples

JSON

{
  "id": "DC1",
  "name": "DC FRIENDLY NAME",
  "links": [
    {
      "rel": "self",
      "href": "/v2/datacenters/ALIAS/DC1"
    },
    {
      "rel":"group",
      "href":"/v2/groups/ALIAS/54faef9c2bfd41d6b30f787567f9b0d4",
      "id":"54faef9c2bfd41d6b30f787567f9b0d4",
      "name":"DC1 Hardware"
    }
  ]
}

Add Public IP Address

Claims a public IP address and associates it with a server, allowing access to it on a given set of protocols and ports. It may also be set to restrict access based on a source IP range. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to add a public IP address to an existing server. The public IP can be exposed on multiple protocols and ports and also be set to restrict access based on source IP ranges.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses

Example

POST https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
internalIPAddress 字符串 The internal (private) IP address to map to the new public IP address. If not provided, one will be assigned for you.
ports array The set of ports and protocols to allow access to for the new public IP address. Only these specified ports on the respective protocols will be accessible when accessing the server using the public IP address claimed here.
sourceRestrictions array The source IP address range allowed to access the new public IP address. Used to restrict access to only the specified range of source IPs.

Ports Definition

Name Type 描述
protocol 字符串 The specific protocol to support for the given port(s). Should be one of the following: "tcp", "udp", or "icmp".
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type 描述
cidr 字符串 The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "ports":[
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will be available for use as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Create a Cross Data Center Firewall Policy

Creates a firewall policy for a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a firewall policy between networks in different data centers for a given account.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation.

Content Properties

Name Type 描述 Req.
destinationAccountId 字符串 Short code for a particular account
destinationLocationId 字符串 Short code for a particular location
destinationCidr 字符串 Destination address for traffic on the terminating firewall, specified using CIDR notation
启用 字符串 Indicates if the policy is enabled (true) or disabled (false)
sourceCidr 字符串 Source address for traffic on the originating firewall, specified using CIDR notation, on the originating firewall

Example

JSON

{
    "destinationAccountId" : "dest",
    "destinationLocationId" : "UC1",
    "destinationCidr" : "10.1.1.0/24",
    "enabled" : true,
    "sourceCidr" : "10.2.2.0/24"
}

响应

The response will be an entity representing the new firewall policy that was created.

Example

JSON

{
    "id": "921670344d781378a8df6159c00bddea",
    "status": "pending",
    "enabled": true,
    "sourceCidr": "10.2.2.0/24",
    "sourceAccount": "src",
    "sourceLocation": "va1",
    "destinationCidr": "10.1.1.0/24",
    "destinationAccount": "dest",
    "destinationLocation": "uc1",
    "links": [
        {
            "rel": "self",
            "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Create an Intra Data Center Firewall Policy

Creates a firewall policy for a given account in a given data center ("intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation.

Content Properties

Name Type 描述 Req.
destinationAccount 字符串 Short code for a particular account
source 字符串 Source addresses for traffic on the originating firewall, specified using CIDR notation, on the originating firewall
destination 字符串 Destination addresses for traffic on the terminating firewall, specified using CIDR notation
ports 字符串 Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).

Examples

JSON

{
    "destinationAccount": "DEST_ALIAS",
    "source":["123.45.223.1/32", "123.45.223.2/32", "123.45.223.3/32"],
    "destination":["123.45.223.1/32", "123.45.223.2/32"],
    "ports":["tcp/1-600"]
}

响应

The response will be an entity representing the new firewall policy that was created.

Entity Definition

Name Type 描述
links array Collection of entity links that point to resources related to this firewall policy

Examples

JSON

{
    "links": [
        {
            "rel": "self",
            "href": "https://api.ctl.io/v2-experimental/firewallPolicies/DEST_ALIAS/WA1/71f912d00e1c11e5b9390800200c9a66",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Delete a Cross Data Center Firewall Policy

Deletes a firewall policy for a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

DELETE https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}

Example

DELETE https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation.
policyId 字符串 ID of the firewall policy

响应

There is no response upon the successful removal of the firewall policy.

Delete an Intra Data Center Firewall Policy

Deletes a firewall policy for a given account in a given data center ("intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

DELETE https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

DELETE https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a66

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation.
firewallPolicy 字符串 ID of the firewall policy

响应

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful removal of the firewall policy.

Get Cross Data Center Firewall Policy List

Gets the list of firewall policies associated with a given account, between networks in different data centers ("cross data center firewall policies"). Users can optionally filter results by requesting policies associated with a second "destination" account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available firewall policies between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountId}/{dataCenter}?destinationAccountId={destinationAccountId}

Example

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1?destinationAccountId=DEST_ALIAS

请求

URI Parameters

Name Type 描述 Req.
sourceAccountId 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the target data center for the new policy. Valid codes can be retrieved from the Get Data Center List API operation.
destinationAccountId 字符串 Short code for another account

响应

Example

JSON

[
 {
   "id": "921670344d781378a8df6159c00bddea",
   "status": "pending",
   "enabled": true,
   "sourceCidr": "10.2.2.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.1.1.0/24",
   "destinationAccount": "dest",
   "destinationLocation": "uc1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 },
 {
   "id": "1a4b72963130e7a4d1a3343299f84edc",
   "status": "active",
   "enabled": true,
   "sourceCidr": "10.5.5.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.1.1.0/24",
   "destinationAccount": "dest1",
   "destinationLocation": "uc1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src5/wa1/1a4b72963130e7a4d1a3343299f84edc",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 },
 {
   "id": "372d37109487b0584db2c87b16f654b1",
   "status": "active",
   "enabled": true,
   "sourceCidr": "10.7.7.0/24",
   "sourceAccount": "src",
   "sourceLocation": "va1",
   "destinationCidr": "10.9.9.0/24",
   "destinationAccount": "dest2",
   "destinationLocation": "il1",
   "links": [
     {
       "rel": "self",
       "href": "/v2-experimental/crossDcFirewallPolicies/src7/gb3/372d37109487b0584db2c87b16f654b1",
       "verbs": [
         "GET",
         "PUT",
         "DELETE"
       ]
     }
   ]
 }
]

Get Cross Data Center Firewall Policy

Gets the details of a specific firewall policy associated with a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the details of a specific firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
policyId 字符串 ID of the firewall policy

响应

Example

JSON

{
    "id": "921670344d781378a8df6159c00bddea",
    "status": "active",
    "enabled": true,
    "sourceCidr": "10.2.2.0/24",
    "sourceAccount": "src",
    "sourceLocation": "va1",
    "destinationCidr": "10.1.1.0/24",
    "destinationAccount": "dest",
    "destinationLocation": "uc1",
    "links": [
        {
            "rel": "self",
            "href": "/v2-experimental/crossDcFirewallPolicies/src/va1/921670344d781378a8df6159c00bddea",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Get Intra Data Center Firewall Policy List

Gets the list of firewall policies associated with a given account in a given data center ("intra data center firewall policies"). Users can optionally filter results by requesting policies associated with a second "destination" account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available firewall policies in a given data center for a given account. Using that list of firewall policies, you can then query for a specific policy in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}?destinationAccount={destinationAccountAlias}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1?destinationAccount=DEST_ALIAS

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
destinationAccountAlias 字符串 Short code for a particular account

响应

Entity Definition

Name Type 描述
id 字符串 ID of the firewall policy
status 字符串 The state of the policy: either active (policy is available and working as expected), error (policy creation did not complete as expected) or pending (the policy is in the process of being created)
启用 boolean Indicates if the policy is enabled (true) or disabled (false)
source 字符串 Source addresses for traffic on the originating firewall, specified using CIDR notation
destination 字符串 Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount 字符串 Short code for a particular account
ports 字符串 Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).
links array Collection of entity links that point to resources related to this list of firewall policies

Examples

JSON

[
    {
        "id": "c59b96600e0d11e5b9390800200c9a66",
        "status": "active",
        "enabled": true,
        "source": [
            "123.45.678.1/32",
            "123.45.678.2/32",
            "123.45.678.3/32"
        ],
        "destination": [
            "234.56.789.1/32",
            "234.56.789.2/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "any"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/c59b96600e0d11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
    {
        "id": "bbb377290e0e11e5b9390800200c9a66",
        "status": "active",
        "enabled": false,
        "source": [
            "145.67.890.1/32",
            "145.67.890.2/32",
            "145.67.890.3/32"
        ],
        "destination": [
            "156.78.901.1/32",
            "156.78.901.2/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "any"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/bbb377290e0e11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
    {
        "id": "d56587800e0e11e5b9390800200c9a66",
        "status": "active",
        "enabled": true,
        "source": [
            "123.45.678.1/32"
        ],
        "destination": [
            "234.23.435.200/32"
        ],
        "destinationAccount": "DEST_ALIAS",
        "ports": [
            "tcp/8080",
            "tcp/1-8000"
        ],
        "links": [
            {
                "rel": "self",
                "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/d56587800e0e11e5b9390800200c9a66",
                "verbs": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        ]
    },
]

Get Intra Data Center Firewall Policy

Gets the details of a specific firewall policy associated with a given account in a given data center (an "intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the details of a specific firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

GET https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a66

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
firewallPolicy 字符串 ID of the firewall policy

响应

Entity Definition

Name Type 描述
id 字符串 ID of the firewall policy
status 字符串 The state of the policy; either active (policy is available and working as expected), error (policy creation did not complete as expected) or pending (the policy is in the process of being created)
启用 boolean Indicates if the policy is enabled (true) or disabled (false)
source 字符串 Source addresses for traffic on the originating firewall, specified using CIDR notation
destination 字符串 Destination addresses for traffic on the terminating firewall, specified using CIDR notation
destinationAccount 字符串 Short code for a particular account
ports 字符串 Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).
links array Collection of entity links that point to resources related to this list of firewall policies

Examples

JSON

{
    "id": "1ac853b00e1011e5b9390800200c9a6",
    "status": "active",
    "enabled": true,
    "source": [
        "123.45.678.1/32",
        "123.45.678.2/32",
        "123.45.678.3/32"
    ],
    "destination": [
        "245.21.223.1/32",
        "245.21.223.2/32"
    ],
    "destinationAccount": "DEST_ALIAS",
    "ports": [
        "any"
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/1ac853b00e1011e5b9390800200c9a6",
            "verbs": [
                "GET",
                "PUT",
                "DELETE"
            ]
        }
    ]
}

Get Public IP Address

Gets the details for the public IP address of a server, including the specific set of protocols and ports allowed and any source IP restrictions. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out information about a specific public IP address for an existing server. This operation is linked to from the Get Server response that lists all public IPs assigned to a server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

GET https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.
PublicIP 字符串 The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server.

响应

Entity Definition

Name Type 描述
internalIPAddress 字符串 The internal (private) IP address mapped to the public IP address.
ports array The set of accessible ports and protocols for the public IP address.
sourceRestrictions array The source IP address range allowed to access the new public IP address. Only traffic from this range will have access to the public IP on the specified ports.

Ports Definition

Name Type 描述
protocol 字符串 The specific protocol to support for the given port(s). Should be either "tcp", "udp", or "icmp" (which is enabled by default).
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type 描述
cidr 字符串 The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "internalIPAddress":"10.11.12.13",
  "ports":[
    {
      "protocol":"ICMP",
      "port":0
    },
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

Remove Public IP Address

Releases the given public IP address of a server so that it is no longer associated with the server and available to be claimed again by another server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to stop using a specific public IP address on an existing server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

DELETE https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.
PublicIP 字符串 The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server.

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will no longer be associated with the server.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Update Cross Data Center Firewall Policy

Updates a given firewall policy associated with a given account, between networks in different data centers ("cross data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a firewall policy between networks in different data centers.

NOTE: This API operation is experimental only, and subject to change without notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/{sourceAccountAlias}/{dataCenter}/{policyId}?enabled=true/false

Example

PUT https://api.ctl.io/v2-experimental/crossDcFirewallPolicies/SRC_ALIAS/VA1/921670344d781378a8df6159c00bddea?enabled=false

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center associated with the policy of interest. Valid codes can be retrieved from the Get Data Center List API operation.
启用 字符串 true or false

响应

There is no response upon the successful update of the firewall policy.

Update Intra Data Center Firewall Policy

Updates a given firewall policy associated with a given account in a given data center (an "intra data center firewall policy"). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a firewall policy in a given data center for a given account.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/firewallPolicies/{sourceAccountAlias}/{dataCenter}/{firewallPolicy}

Example

PUT https://api.ctl.io/v2-experimental/firewallPolicies/SRC_ALIAS/WA1/e46ef2500e1011e5b9390800200c9a66

请求

URI Parameters

Name Type 描述 Req.
sourceAccountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center associated with the policy of interest. Valid codes can be retrieved from the Get Data Center List API operation.
destinationAccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
启用 boolean Indicates if the policy is enabled (true) or disabled (false)
source 字符串 Source addresses for traffic on the originating firewall, specified using CIDR notation
destination 字符串 Destination addresses for traffic on the terminating firewall, specified using CIDR notation
ports 字符串 Type of ports associated with the policy. Supported ports include: any, icmp, TCP and UDP with single ports (tcp/123, udp/123) and port ranges (tcp/123-456, udp/123-456). Some common ports include: tcp/21 (for FTP), tcp/990 (FTPS), tcp/80 (HTTP 80), tcp/8080 (HTTP 8080), tcp/443 (HTTPS 443), icmp (PING), tcp/3389 (RDP), and tcp/22 (SSH/SFTP).

Examples

JSON

{
    "enabled":false,
    "source":["123.45.678.1/32"],
    "destination":["234.4.678.2/32"],
    "ports":["udp/8080"]
}

响应

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful update of firewall policy attributes.

Update Public IP Address

Updates a public IP address on an existing server, allowing access to it on a given set of protocols and ports as well as restricting access based on a source IP range. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to update the ports and protocols or source IP restrictions for a public IP address on an existing server.

URL

Structure

PUT https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/publicIPAddresses/{publicIP}

Example

PUT https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/publicIPAddresses/12.34.56.78

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.
PublicIP 字符串 The specific public IP to return details about. A server may have more than one public IP, and the list of available ones can be retrieved from the call to Get Server.

Content Properties

Name Type 描述 Req.
ports array The set of ports and protocols to allow access to for the public IP address. Only these specified ports on the respective protocols will be accessible when accessing the server using the public IP address specified here.
sourceRestrictions array The source IP address range allowed to access the public IP address. Used to restrict access to only the specified range of source IPs.

Ports Definition

Name Type 描述
protocol 字符串 The specific protocol to support for the given port(s). Should be one of the following: "tcp", "udp", or "icmp".
port integer The port to open for the given protocol. If defining a range of ports, this represents the first port in the range.
portTo integer If defining a range of ports, optionally provide the last number of the range.

SourceRestrictions Definition

Name Type 描述
cidr 字符串 The IP range allowed to access the public IP, specified using CIDR notation.

Examples

JSON

{
  "ports":[
    {
      "protocol":"TCP",
      "port":80
    },
    {
      "protocol":"TCP",
      "port":443
    },
    {
      "protocol":"TCP",
      "port":8080,
      "portTo":8081
    },
    {
      "protocol":"UDP",
      "port":123
    }
  ],
  "sourceRestrictions":[
    {
      "cidr":"70.100.60.140/32"
    },
    {
      "cidr":"71.100.60.0/24"
    }
  ]
}

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the public IP address will be available for use as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Create Group

Creates a new group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}

Example

POST https://api.ctl.io/v2/groups/ALIAS/

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the group to create.
描述 字符串 User-defined description of this group
parentGroupId 字符串 ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal.
customFields complex Collection of custom field ID-value pairs to set for the server.

CustomFields Definition

Name Type 描述
id 字符串 ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value 字符串 Value to set the custom field to for this server.

Examples

JSON

{
  "name": "New Group",
  "description": "A new group.",
  "parentGroupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "customFields": [
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "value": "1100003"
    }
  ]
}

响应

Group Entity Definition

Name Type 描述
id 字符串 ID of the group being queried
用户名 字符串 User-defined name of the group
描述 字符串 User-defined description of this group
locationId 字符串 Data center location identifier
类型 字符串 Group type which could include system types like "archive"
status 字符串 Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of entity links that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type 描述
createdDate dateTime Date/time that the group was created
createdBy 字符串 Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy 字符串 Who modified the group last

CustomFields Definition

Name Type 描述
id 字符串 Unique ID of the custom field
用户名 字符串 Friendly name of the custom field
value 字符串 Underlying value of the field
displayValue 字符串 Shown value of the field

Examples

JSON

{
  "id": "56b789a2a72f43a98ae2227061e8f8f8",
  "name": "New Group",
  "description": "A new group.",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "groups": [
    {
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
      "name": "Parent Group Name",
      "description": "The parent group.",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
          "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities",
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/56b789a2a72f43a98ae2227061e8f8f8/scheduledActivities"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

Delete Group

Sends the delete operation to a given group and adds operation to queue. This operation will delete the group and all servers and groups underneath it. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a group and all objects underneath it.

URL

Structure

DELETE https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

DELETE https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupId 字符串 ID of the group to be deleted. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal.

响应

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Get Group Billing Details

Gets the current and estimated charges for each server in a designated group hierarchy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out the charges associated with a specific group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/billing

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/billing

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal

响应

Group Entity Definition

Name Type 描述
date datetime Date that this billing information applies to
groups array List of groups (with the first being the queried group) in the requested hierarchy. Group ID listed before each group entity description

Groups Definition

Name Type 描述
用户名 字符串 User-defined name of the group
servers array Collection of servers in this group, each with billing information. Server ID listed before each entity description

Servers Definition

Name Type 描述
templateCost float Cost of templates stored in the group
archiveCost float Cost of archived servers in this group
monthlyEstimate float Projected charges for the servers given current usage
monthToDate float Charges up until the requested time
currentHour float Charges for the most recent hour

Examples

JSON

{
  "date": "2014-04-07T21:33:51.9743015Z",
  "groups": {
    "8c95fbaf74b7497fb671235aa318b44c": {
      "name": "Web Applications",
      "servers": {
        "wa1acctserv7101": {
          "templateCost": 0.0,
          "archiveCost": 0.0,
          "monthlyEstimate": 77.76,
          "monthToDate": 17.93,
          "currentHour": 0.108
        },
        "wa1acctserv7202": {
          "templateCost": 0.0,
          "archiveCost": 0.0,
          "monthlyEstimate": 156.96,
          "monthToDate": 36.19,
          "currentHour": 0.218
        }
      }
    },
    "4bca7bf6ead14cd59053e1eb1cd2d01f": {
      "name": "Training Environment",
      "servers": {}
    }
  }
}

Get Group Horizontal Autoscale Policy

Retrieves the details of a horizontal autoscale policy associated with a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a horizontal autoscale policy associated to a Group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/horizontalAutoscalePolicy/

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI.

响应

Name Type 描述
groupId 字符串 ID of the group
policyId 字符串 The unique identifier of the autoscale policy
locationId 字符串 Data center location identifier
用户名 字符串 Name of the Policy
availableServers int The number of servers available for scaling
targetSize int Number of servers to scale to
scaleDirection 字符串 Direction to Scale (In or Out )
scaleResourceReason 字符串 Reason for scaling, either: CPU, Memory, MinimumResourceCount, or None
loadBalancer complex Information about the load balancer associated with the policy
links array Collection of entity links that point to resources related to this data center

Load Balancer Definition

Name Type 描述
id 字符串 ID of the load balancer
用户名 字符串 Friendly name of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server
publicIP 字符串 The external (public) IP address of the load balancer
links array Collection of entity links that point to resources related to this data center

Examples

JSON

{
  "groupId": "fc06fd421e2ee41190460050568600e8",
  "policyId": "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "locationId": "WA1",
  "availableServers": 2,
  "targetSize": 1,
  "scaleDirection": "Up",
  "scaleResourceReason": "MinimumResourceCount",
  "loadBalancer": {
    "id": "bf82320cc96d42048fc7d5e41b0cdada",
    "name": "hotfix111314",
    "publicPort": 443,
    "privatePort": 300,
    "publicIP": "1.1.1.1",
    "links": [
      {
        "rel": "self",
        "href": "/v2/sharedLoadBalancers/ALIAS/WA1/bf82320cc96d42048fc7d5e41b0cdada"
      }
    ]
  },
  "timestamp": "2015-10-20T21:20:02Z",
  "links": [
    {
      "rel": "self",
      "href": "/v2/groups/WHIM/fc06fd421e2ee41190460050568600e8/horizontalAutoscalePolicy"
    },
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8"
    },
    {
      "rel": "horizontalAutoscalePolicy",
      "href": "/v2/horizontalAutoscalePolicies/ALIAS/6cf7f7d139ee4d4f98a09bd0400b1a56"
    }
  ]
}

Get Group Monitoring Statistics

Gets the resource consumption details for whatever window specified in the request. Data can be retrieve for a variety of time windows and intervals. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to track the resource usage of servers within a group hierarchy. It can be used to populate a local data mart or chart the results on a dashboard.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/statistics?type=hourly&start={datetime}&end={datetime}&sampleInterval={dd:hh:mm:ss}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/statistics?type=hourly&start=2014-04-05T07:52:47.302Z&end=2014-04-07T07:52:47.302Z&sampleInterval=01:00:00

请求

URI and Querystring Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal.
类型 字符串 Valid values are latest, hourly, or realtime.

latest will return a single data point that reflects the last monitoring data collected. No start, end, or sampleInterval values are required for this type.

hourly returns data points for each sampleInterval value between the start and end times provided. The start and sampleInterval parameters are both required for this type.

realtime will return data from the last 4 hours, available in smaller increments. To use realtime type, start parameter must be within the last 4 hours. The start and sampleInterval parameters are both required for this type.
start datetime DateTime (UTC) of the query window. Note that statistics are only held for 14 days. Start date (and optional end date) must be within the past 14 days. Value is not required if choosing the latest query type. Yes, except for latest type
end datetime DateTime (UTC) of the query window. Default is the current time in UTC. End date (and start date) must be within the past 14 days. Not a required value if results should be up to the current time.
sampleInterval timespan Result interval. For the default hourly type, the minimum value is 1 hour (01:00:00) and maximum is the full window size of 14 days. Note that interval must fit within start/end window, or you will get an exception that states: "The 'end' parameter must represent a time that occurs at least one 'sampleInterval' before 'start.'" If realtime type is specified, interval can be as small as 5 minutes (05:00). Yes, except for latest type

响应

Entity Definition

Name Type 描述
用户名 字符串 Name of the server
stats array Collection of stats for the server for the interval chosen

Stats Definition

Name Type 描述
timestamp datetime Timestamp of the monitoring results
cpu float CPU allocation during the interval
cpuPercent float CPU consumption (out of 100%) during the interval
memoryMB float Memory allocation during the interval
memoryPercent float Memory consumption (out of 100%) during the interval
networkReceivedKbps float Public network consumption in during the interval
networkTransmittedKbps float Public network consumption out during the interval
diskUsageTotalCapacityMB float Total disk allocation during the interval
diskUsage array List of physical disks attached to the virtual machine
guestDiskUsage array List of partitions used inside the guest OS

Disk Usage Definition

Name Type 描述
id 字符串 Disk identifier
capacityMB integer Capacity (in MB) allocated for this disk

Guest Usage Definition

Name Type 描述
path 字符串 Path of this partition
capacityMB integer Total capacity available to this partition
consumedMB integer Amount of capacity in use by this partition

Examples

JSON

(/v2/groups/ALIAS/GROUP/statistics?start=2014-04-09T20:00:00&sampleInterval=01:00:00)

[
  {
    "name": "wa1acctser7101",
    "stats": [
      {
        "timestamp": "2014-04-09T20:00:00Z",
        "cpu": 2.0,
        "cpuPercent": 5.0,
        "memoryMB": 3072.0,
        "memoryPercent": 0.0,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": []
      },
      {
        "timestamp": "2014-04-09T21:00:00Z",
        "cpu": 2.0,
        "cpuPercent": 2.0,
        "memoryMB": 3072.0,
        "memoryPercent": 0.0,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": []
      }
    ]
  },
  {
    "name": "wa1acctser7202",
    "stats": [
      {
        "timestamp": "2014-04-09T20:00:00Z",
        "cpu": 1.0,
        "cpuPercent": 1.14,
        "memoryMB": 2048.0,
        "memoryPercent": 9.24,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": [
          {
            "path": "C:\\",
            "capacityMB": 40607,
            "consumedMB": 16619
          }
        ]
      },
      {
        "timestamp": "2014-04-09T21:00:00Z",
        "cpu": 1.0,
        "cpuPercent": 1.02,
        "memoryMB": 2048.0,
        "memoryPercent": 2.32,
        "networkReceivedKBps": 0.0,
        "networkTransmittedKBps": 0.0,
        "diskUsageTotalCapacityMB": 40960.0,
        "diskUsage": [
          {
            "id": "0:0",
            "capacityMB": 40960
          }
        ],
        "guestDiskUsage": [
          {
            "path": "C:\\",
            "capacityMB": 40607,
            "consumedMB": 16619
          }
        ]
      }
    ]
  }
]

Get Group Scheduled Activities

Gets the scheduled activities associated with a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the scheduled activities for a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/ScheduledActivities/

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/ScheduledActivities

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI.

响应

Name Type 描述
id 字符串 ID of the group
locationId 字符串 Data center location identifier
changeInfo complex Change history
links array Collection of entity links that point to resources related to this data center
status 字符串 State of scheduled activity: on or off
类型 字符串 Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUtc datetime Time when scheduled activity should start
repeat 字符串 How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire 字符串 When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUtc datetime When the scheduled activity should expire
timeZoneOffset 字符串 To display in local time
isExpired bool True: scheduled activity has expired. False: scheduled activity is active
lastOccurrenceDateUtc datetime Last time scheduled activity was run
occurrenceCount int How many times scheduled activity has been run
nextOccurrenceDateUtc datetime When the next scheduled activty will be run

Examples

JSON

[
  {
    "id": "95715f96f8a145d68ace797fe542c9ae",
    "locationId": "WA1",
    "changeInfo": {
      "createdBy": "john.doe",
      "createdDate": "2015-03-16T18:12:02Z",
      "modifiedBy": "john.doe",
      "modifiedDate": "2015-10-20T22:20:25Z"
    },
    "links": [
      {
        "rel": "group",
        "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8",
        "id": "fc06fd421e2ee41190460050568600e8",
        "name": "Default Group"
      },
      {
        "rel": "self",
        "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8/scheduledActivities/95715f96f8a145d68ace797fe542c9ae",
        "verbs": [
          "GET",
          "PUT",
          "DELETE"
        ]
      }
    ],
    "status": "on",
    "type": "shutdown",
    "beginDateUTC": "2015-03-16T18:11:00Z",
    "repeat": "customWeekly",
    "customWeeklyDays": [
      "tue",
      "thu"
    ],
    "expire": "never",
    "timeZoneOffset": "-07:00:00",
    "isExpired": false,
    "occurrenceCount": 0,
    "nextOccurrenceDateUTC": "2015-10-22T18:11:00Z"
  }
]

Get Group

Gets the details for a individual server group and any sub-groups and servers that it contains. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to identify the servers in a particular group, retrieve a group hierarchy, or get links to information (e.g. billing, monitoring, scheduled activities) about a group.

URL

Structure

GET https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

GET https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal.

响应

Group Entity Definition

Name Type 描述
id 字符串 ID of the group being queried
用户名 字符串 User-defined name of the group
描述 字符串 User-defined description of this group
locationId 字符串 Data center location identifier
类型 字符串 Group type which could include system types like "archive"
status 字符串 Describes if group is online or not
serversCount integer Number of servers this group contains
groups array Refers to this same entity type for each sub-group
links array Collection of entity links that point to resources related to this group
changeInfo complex Describes "created" and "modified" details
customFields complex Details about any custom fields and their values

ChangeInfo Definition

Name Type 描述
createdDate dateTime Date/time that the group was created
createdBy 字符串 Who created the group
modifiedDate dateTime Date/time that the group was last updated
modifiedBy 字符串 Who modified the group last

CustomFields Definition

Name Type 描述
id 字符串 Unique ID of the custom field
用户名 字符串 Friendly name of the custom field
value 字符串 Underlying value of the field
displayValue 字符串 Shown value of the field

Examples

JSON

{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "name": "Web Applications",
  "description": "public facing web apps",
  "locationId": "WA1",
  "type": "default",
  "status": "active",
  "serversCount": 2,
  "groups": [
    {
      "id": "31d13f501459411ba59304f3d47486eb",
      "name": "Training Environment",
      "description": "Temporary servers",
      "locationId": "WA1",
      "type": "default",
      "status": "active",
      "serversCount": 0,
      "groups": [],
      "links": [
        {
          "rel":"createGroup",
          "href":"/v2/groups/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel":"createServer",
          "href":"/v2/servers/acct",
          "verbs":[
            "POST"
          ]
        },
        {
          "rel": "self",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb",
          "verbs":[
            "GET",
            "PATCH",
            "DELETE"
          ]
        },
        {
          "rel": "parentGroup",
          "href": "/v2/groups/acct/231c3f3fec0e46499290b351199d555f",
          "id": "231c3f3fec0e46499290b351199d555f"
        },
        {
          "rel": "defaults",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/defaults",
          "verbs":[
            "GET",
            "POST"
          ]
        },  
        {
          "rel": "billing",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/billing"
        },
        {
          "rel": "archiveGroupAction",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/archive"
        },
        {
          "rel": "statistics",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/statistics"
        },
        {
          "rel":"upcomingScheduledActivities",
          "href":"/v2/groups/acct/8a03fcae8dd65411b05f00505682315a/upcomingScheduledActivities"
        },
        {
          "rel":"horizontalAutoscalePolicyMapping",
          "href":"/v2/groups/acct/31d13f501459411ba59304f3d47486eb/horizontalAutoscalePolicy",
          "verbs":[
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel": "scheduledActivities",
          "href": "/v2/groups/acct/31d13f501459411ba59304f3d47486eb/scheduledActivities"
          "verbs":[
            "GET",
            "POST"
          ]
        }
      ]
    }
  ],
  "links":[
    {
      "rel": "self",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "parentGroup",
      "href": "/v2/groups/acct/540494152d0c4a9ab61869562b4c1471",
      "id": "540494152d0c4a9ab61869562b4c1471"
    },
    {
      "rel": "billing",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/billing"
    },
    {
      "rel": "archiveGroupAction",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/archive"
    },
    {
      "rel": "statistics",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/groups/acct/2a5c0b9662cf4fc8bf6180f139facdc0/scheduledActivities"
    },
    {
      "rel": "server",
      "href": "/v2/servers/acct/wa1acctpre7101",
      "id": "WA1ACCTPRE7101"
    },
    {
      "rel": "server",
      "href": "/v2/servers/btdi/wa1acctpre7202",
      "id": "WA1ACCTPRE7202"
    }
  ],
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "customFields": [
    {
      "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
      "name": "Cost Center",
      "value": "IT-DEV",
      "displayValue": "IT-DEV"
    },
    {
      "id": "58f83af6123846769ee6cb091ce3561e",
      "name": "CMDB ID",
      "value": "1100003",
      "displayValue": "1100003"
    }
  ]
}

Set Group Custom Fields

Changes the custom field values for an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the custom field values for a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupId 字符串 ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the group. In this case, the value must be "set" for setting the custom field values.
member 字符串 The property of the group to perform the operation on. In this case, the value will be "customFields".
value array A list of id-value pairs for all custom fields including all required values and other custom field values that you wish to set.

Note: You must specify the complete list of custom field values to set on the group. If you want to change only one value, specify all existing field values along with the new value for the field you wish to change. To unset the value for an unrequired field, you may leave the field id-value pairing out, however all required fields must be included. (You can get existing custom field value info by using the Get Group call to see all the details of the group or the Get Custom Fields call to see available custom fields for a given account.)

Examples

JSON

[
   {
      "op":"set",
      "member":"customFields",
      "value":[
         {
            "id":"dba67b154f774a1fb413ddfa3dc4ac1d",
            "value":"Required Value 1"
         },
         {
            "id":"58f83bf6675846769ee6cb091ce3561e",
            "value":"Optional Value 1"
         },
         {
            "id":"22f002e08f3b46d9a8b38ecd4c6df7f9",
            "value":"Required Value 2"
         }
      ]
   }
]

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Defaults

Sets the defaults for a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set defaults for a group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/defaults

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/defaults

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI.

Content Properties

Name Type 描述 Req.
cpu integer Number of processors to configure the server with (1-16) (ignored for bare metal servers)
memoryGB integer Number of GB of memory to configure the server with (1-128) (ignored for bare metal servers)
networkId 字符串 ID of the Network. This can be retrieved from the Get Network List API operation.
primaryDns 字符串 Primary DNS to set on the server. If not supplied the default value set on the account will be used.
secondaryDns 字符串 Secondary DNS to set on the server. If not supplied the default value set on the account will be used.
templateName 字符串 Name of the template to use as the source. The list of available templates for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. (Ignored for bare metal servers.)

Examples

JSON

{
  "cpu": "1",
  "memoryGB": "2",
  "networkId": "fb46f06f8278421d8e94d78cf6409ba5",
  "primaryDns": "8.8.8.8",
  "secondaryDns": "8.8.4.4",
  "templateName": "UBUNTU-10-64-TEMPLATE"
}

响应

Cpu Definition

Name Type 描述
value int How many vCPUs are allocated to the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Memory Definition

Name Type 描述
value int How many GB of memory are allocated to the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Network Definition

Name Type 描述
value 字符串 ID of the Network
inherited bool Whether the value is set explicitly (false) or by its parent (true)

PrimaryDNS Definition

Name Type 描述
value 字符串 Primary DNS set on the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

SecondaryDNS Definition

Name Type 描述
value 字符串 Secondary DNS set on the server
inherited bool Whether the value is set explicitly (false) or by its parent (true)

TemplateName Definition

Name Type 描述
value 字符串 爱达荷州
inherited bool Whether the value is set explicitly (false) or by its parent (true)

Examples

JSON

{
  "cpu": {
    "value": 1,
    "inherited": false
  },
  "memoryGB": {
    "value": 2,
    "inherited": false
  },
  "networkId": {
    "value": "ee600a2b4b734aac8ab0de2642597433",
    "inherited": true
  },
  "primaryDns": {
    "value": "8.8.8.8",
    "inherited": false
  },
  "secondaryDns": {
    "value": "8.8.4.4",
    "inherited": false
  },
  "templateName": {
    "value": "UBUNTU-10-64-TEMPLATE",
    "inherited": false
  }
}

Set Group Horizontal Autoscale Policy

Applies a horizontal autoscale policy to a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to apply a horizontal autoscale policy to a group.

URL

Structure

PUT https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/horizontalAutoscalePolicy/

Example

PUT https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/horizontalAutoscalePolicy

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI.

Content Properties

Name Type 描述 Req.
policyId 字符串 The unique identifier of the autoscale policy
loadBalancerPool complex Information about the load balancer

Load Balancer Pool

Name Type 描述 Req.
id 字符串 ID of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server

Example

{
  "policyId" : "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "loadBalancerPool" :  
  {
    "id" : "bf82320cc96d42048fc7d5e41b0cdada",
    "privatePort" : 80,
    "publicPort" : 80
  }
}

响应

Name Type 描述
groupId 字符串 ID of the group
policyId 字符串 The unique identifier of the autoscale policy
locationId 字符串 Data center location identifier
availableServers int The number of servers available for scaling
targetSize int Number of servers to scale to
scaleDirection 字符串 Direction to Scale (In or Out )
scaleResourceReason 字符串 Reason for scaling, either: CPU, Memory, MinimumResourceCount, or None
loadBalancer complex
links array Collection of entity links that point to resources related to this data center

Load Balancer Definition

Name Type 描述
id 字符串 ID of the load balancer
用户名 字符串 Friendly name of the load balancer
publicPort int Port configured on the public-facing side of the load balancer pool.
privatePort int The internal (private) port of the node server
publicIP 字符串 The external (public) IP address of the load balancer
links array Collection of entity links that point to resources related to this data center

Example

{
  "groupId": "fc06fd421e2ee41190460050568600e8",
  "policyId": "6cf7f7d139ee4d4f98a09bd0400b1a56",
  "locationId": "WA1",
  "availableServers": 2,
  "targetSize": 1,
  "scaleDirection": "None",
  "scaleResourceReason": "Cpu",
  "loadBalancer": {
    "id": "bf82320cc96d42048fc7d5e41b0cdada",
    "name": "hotfix111314",
    "publicPort": 80,
    "privatePort": 80,
    "publicIP": "63.251.170.219",
    "links": [
      {
        "rel": "self",
        "href": "/v2/sharedLoadBalancers/ALIAS/WA1/bf82320cc96d42048fc7d5e41b0cdada"
      }
    ]
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8/horizontalAutoscalePolicy"
    },
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/fc06fd421e2ee41190460050568600e8"
    },
    {
      "rel": "horizontalAutoscalePolicy",
      "href": "/v2/horizontalAutoscalePolicies/ALIAS/6cf7f7d139ee4d4f98a09bd0400b1a56"
    }
  ]
}

Set Group Name/Description

Changes the name and description of an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the name or description of a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupId 字符串 ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the group. In this case, the value must be "set" for setting the name and description.
member 字符串 The property of the group to perform the operation on. In this case, the value will be either "name" or "description".
value 字符串 The value to set for the given member. This is the name or description to set for the group.

Examples

JSON

[
   {
      "op":"set",
      "member":"name",
      "value":"New Name"
   },
   {
      "op":"set",
      "member":"description",
      "value":"New Description"
   }
]

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Parent

Changes the parent group of an existing group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the parent of a given group.

URL

Structure

PATCH https://api.ctl.io/v2/groups/{accountAlias}/{groupId}

Example

PATCH https://api.ctl.io/v2/groups/ACCT/2a5c0b9662cf4fc8bf6180f139facdc0

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
GroupId 字符串 ID of the group to update. Retrieved from query to containing group, or by looking at the URL when viewing a group in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the group.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the group. In this case, the value must be "set" for setting the parent group.
member 字符串 The property of the group to perform the operation on. In this case, the value will be "parentGroupId".
value 字符串 The value to set for the given member. This is the group identifier for the new parent group.

Examples

JSON

[
   {
      "op":"set",
      "member":"parentGroupId",
      "value":"af7552c50e1b40b28d8023ed5eeaa74c"
   }
]

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Group Scheduled Activities

Sets scheduled activities for a group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to set scheduled activities for a group.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/ScheduledActivities/

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/ScheduledActivities

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
GroupID 字符串 ID of the group being queried. Retrieved from query to parent group, or by looking at the URL of the Group in the Control Portal UI.

Content Properties

Name Type 描述 Req.
status 字符串 State of scheduled activity: on or off
类型 字符串 Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUTC datetime Time when scheduled activity should start
repeat 字符串 How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire 字符串 When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUTC datetime When the scheduled activity should expire
timeZoneOffset 字符串 To display in local time

Examples

JSON

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T19:41:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "weekly",
  "expire": "never"
}

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T19:40:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "customWeekly",
  "expire": "never",
  "customWeeklyDays": [
    "mon",
    "wed",
    "fri"
  ]
}

{
  "status": "on",
  "type": "reboot",
  "beginDateUTC": "2015-11-23T21:27:00.000Z",
  "timeZoneOffset": "-08:00",
  "repeat": "daily",
  "expire": "afterCount",
  "expireCount": "10"
}

响应

Name Type 描述
id 字符串 ID of the group
locationId 字符串 Data center location identifier
changeInfo complex Change history
links array Collection of entity links that point to resources related to this data center
status 字符串 State of scheduled activity: on or off
类型 字符串 Type of activity: archive, createsnapshot, delete, deletesnapshot, pause, poweron, reboot, shutdown
beginDateUTC datetime Time when scheduled activity should start
repeat 字符串 How often to repeat: never, daily, weekly, monthly, customWeekly
customWeeklyDays array An array of strings for the days of the week: sun, mon, tue, wed, thu, fri, sat
expire 字符串 When the scheduled activities are set to expire: never, afterDate, afterCount
expireCount int Number of times scheduled activity should run before expiring
expireDateUTC datetime When the scheduled activity should expire
timeZoneOffset 字符串 To display in local time
isExpired bool True: scheduled activity has expired. False: scheduled activity is active
lastOccurrenceDateUtc datetime Last time scheduled activity was run
occurrenceCount int How many times scheduled activity has been run
nextOccurrenceDateUtc datetime When the next scheduled activty will be run
{
  "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "locationId": "WA1",
  "changeInfo": {
    "createdBy": "user@user.com",
    "createdDate": "2015-11-23T21:17:16Z",
    "modifiedBy": "user@user.com",
    "modifiedDate": "2015-11-23T21:17:16Z"
  },
  "links": [
    {
      "rel": "group",
      "href": "/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0",
      "name": "Default Group Name"
    },
    {
      "rel": "self",
      "href": "/v2/groups/ALIAS/5b824632e319e411929e00505682315a/scheduledActivities/2a5c0b9662cf4fc8bf6180f139facdc0",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ],
  "status": "on",
  "type": "pause",
  "beginDateUTC": "2015-11-23T19:41:00Z",
  "repeat": "daily",
  "customWeeklyDays": [],
  "expire": "never",
  "timeZoneOffset": "-08:00:00",
  "isExpired": false,
  "occurrenceCount": 0,
  "nextOccurrenceDateUTC": "2015-11-24T19:41:00Z"
}

Archive Group

Sends the archive operation to a group. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to archive an entire group and its groups and servers.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/archive

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/archive

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.
GroupID 字符串 ID of the group to archive. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal.

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the group will be archived as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Restore Group

Sends the restore operation to an archived group. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore an archived group and its groups and servers.

URL

Structure

POST https://api.ctl.io/v2/groups/{accountAlias}/{groupId}/restore

Example

POST https://api.ctl.io/v2/groups/ALIAS/2a5c0b9662cf4fc8bf6180f139facdc0/restore

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.
GroupID 字符串 ID of the group to restore. Retrieved from query to parent group, or by looking at the URL on the new UI pages in the Control Portal.

Content Properties

Name Type 描述 Req.
targetGroupId 字符串 The unique identifier of the target group to restore the group to.

响应

Entity Definition

Name Type 描述
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this group operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "isQueued":true,
  "links":[
    {
      "rel":"self",
      "href":"/v2/groups/bryf/2a5c0b9662cf4fc8bf6180f139facdc0?AccountAlias=ALIAS&identifier=2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel":"status",
      "href":"/v2/operations/bryf/status/wa1-12345",
      "id":"wa1-12345"
    }
  ]
}

Configure Intrusion Protection Service Notifications

Configures notifications associated with an IPS agent running on a designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to configure the notifications of an installed IPS agent on CenturyLink Cloud servers.

The calls below will perform all of the operations for configuring, retrieving, updating, and deleting a notification destination.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

Create and Update

PUT https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Retrieve

GET https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

删除

DELETE https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Example

PUT https://api.client-security.ctl.io/ips/api/notifications/ALIAS/VA1ALIASTEST04

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverName 字符串 The name of the server that has the agent already installed

Content Properties

Name Type 描述 Req.
notificationDestinations array List of Notification Destinations

Notification Destination Definition

Name Type 描述 Req.
url 字符串 The URL endpoint for WEBHOOK or SLACK notification
typeCode 字符串 This is the type of destination (either SYSLOG, EMAIL, or WEBHOOK)
sysLogSettings array This contains all of the options for SYSLOG
emailAddress 字符串 This object will contain options for an EMAIL notification

SysLogSettings Definition

Name Type 描述 Req.
ipAddress 字符串 The IP address of customers syslog server
udpPort integer The port the syslog is listening on
facility integer This is an Integer, 16-23, to set the type of program logging messages.

Example

PUT http://api.client-security.ctl.io/ips/api/notification/ALIAS/VA1ALIASMYSVR01

{
    "url": "http://my.slack.webhook",
    "typeCode": "SLACK"
},
{
    "url": "http://my.generic.webhook",
    "typeCode": "WEBHOOK"
},
{
    "typeCode": "SYSLOG",
    "sysLogSettings":
        {
            "ipAddress": "12345",
            "udpPort": "8081",
            "facility": "16"
        }
},
{
    "typeCode": "EMAIL",
    "emailAddress": "youremail@site.com"
}

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response. For details on what's included in each alert, please refer to this knowledge base article.

Install Intrusion Protection Service Agent

Installs an IPS agent on the designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to install an IPS agent on CenturyLink Cloud servers.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

POST https://api.client-security.ctl.io/ips/api/app/

Example

POST https://api.client-security.ctl.io/ips/api/app/

请求

Content Properties

Name Type 描述 Req.
hostName 字符串 The name of the server that will ha Data center location of the anti-affinity policy.
accountAlias 字符串 Short code for a particular account

Example

JSON

{
    "hostName":"VA1ALIASTEST04",
    "accountAlias":"ALIAS"
}

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the install of the agent.

Uninstall Intrusion Protection Service Agent

Uninstalls an IPS agent on the designated host. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to uninstall an IPS agent on CenturyLink Cloud servers.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

URL

Structure

DELETE https://api.client-security.ctl.io/ips/api/app/

Example

DELETE https://api.client-security.ctl.io/ips/api/app/

请求

URI Parameters

Name Type 描述 Req.
hostName 字符串 The name of the server that is the target destination for the agent uninstall
accountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
hostName 字符串 The name of the server that will ha Data center location of the anti-affinity policy.
accountAlias 字符串 Short code for a particular account

Example

JSON

{
    "hostName":"VA1ALIASTEST04",
    "accountAlias":"ALIAS"
}

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the uninstall of the agent.

Claim Network

Claims a network for a given account in a given data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to claim a network in a given data center you are able to access. Once you have a network, you can then perform various actions like getting IP addresses and updating its name.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/claim

Example

POST https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/claim

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.

Response [UPDATED JANUARY 19 2016]

Entity Definition

Name Type 描述
operationId 字符串 Unique identifier for network claim operation
uri 字符串 URI to check status of operation

Examples

The initial response from the Claim Network API provides the unique identifier for the asynchronous operation to claim the network and a URI to check the status of that operation.

{
  "operationId": "c387aa9873ab4f7399ea8964dd61510d",
  "uri": "/v2-experimental/operations/{accountAlias}/status/{operationId}"
}

While the operation is executing, the response from the operation URI will provide a summary of the operation.

{
  "requestType": "blueprintOperation",
  "status": "running",
  "summary": {
    "blueprintId": 92121,
    "locationId": "{locationAlias}"
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:39:07Z"
  }
}

When the operation completes successfully the response will provide a status property as "succeeded" and a link to the claimed network.

{
  "requestType": "blueprintOperation",
  "status": "succeeded",
  "summary": {
    "blueprintId": 92121,
    "locationId": "{locationAlias}",
    "links": [
      {
        "rel": "network",
        "href": "/v2-experimental/networks/{accountAlias}/{locationAlias}/{networkId}",
        "id": "{networkId}"
      }
    ]
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:39:07Z"
  }
}

If the operation to claim a network were to fail, the response will come back with status "failed" along with the operation summary information.

{
  "requestType": "blueprintOperation",
  "status": "failed",
  "summary": {
    "blueprintId": 92123,
    "locationId": "{locationId}"
  },
  "source": {
    "userName": "{requestedUser}",
    "requestedAt": "2016-01-11T18:43:42Z"
  }
}

Get IP Address List

Gets the list of IP addresses for a network in a given data center for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of IP Addresses associated with a given network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}/ipAddresses?type=claimed|free|all

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses?type=claimed

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
网络 字符串 ID of the Network. These can be retrieved from the Get Network List API operation
类型 字符串 Optional component of the query to request details of IP Addresses in a certain state. Should be one of the following: "claimed" (returns details of the network as well as information about claimed IP addresses), "free" (returns details of the network as well as information about free IP addresses) or "all" (returns details of the network as well as information about all IP addresses)

响应

Entity Definition

Name Type 描述
address 字符串 An IP Address on the Network
claimed boolean Indicates claimed status of the address, either true or false
服务器 字符串 ID of the server associated with the IP address, if claimed
类型 字符串 Indicates if the IP address is private, publicMapped, or virtual

Examples

JSON

[
    {
        "address": "11.22.33.12",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "private"
    },
    {
        "address": "11.22.33.13",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "private"
    },
    {
        "address": "11.22.33.14",
        "claimed": false,
        "type": "private"
    },
    {
        "address": "65.43.210.123",
        "claimed": true,
        "server": "WA1ALIASAPI01",
        "type": "publicMapped"
    }
]

Get Network List

Gets the list of networks available for a given account in a given data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need the list of available networks in a given data center you are able to access. Using that list of networks, you can then query for a specific network in a given data center.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.

响应

Entity Definition

Name Type 描述
id 字符串 ID of the network
cidr 字符串 The network address, specified using CIDR notation
描述 字符串 Description of VLAN, a free text field that defaults to the VLAN number combined with the network address
gateway 字符串 Gateway IP address of the network
用户名 字符串 User-defined name of the network; the default is the VLAN number combined with the network address
netmask 字符串 A screen of numbers used for routing traffic within a subnet
类型 字符串 Network type, usually private for networks created by the user
vlan integer Unique number assigned to the VLAN
links array Collection of entity links that point to resources related to this list of networks

Examples

JSON

[
    {
        "id": "711725920a1f4002ac49e634e1789206",
        "cidr": "12.34.0.0/24",
        "description": "vlan_9998_12.34.0",
        "gateway": "12.34.0.1",
        "name": "vlan_9998_12.34.0",
        "netmask": "255.255.255.0",
        "type": "private",
        "vlan": 9998,
        "links": [
            {
                "rel": "self",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206",
                "verbs": [
                    "GET",
                    "PUT"
                ]
            },
            {
                "rel": "ipAddresses",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206/ipAddresses",
                "verbs": [
                    "GET"
                ]
            },
            {
                "rel": "release",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/711725920a1f4002ac49e634e1789206/release",
                "verbs": [
                    "POST"
                ]
            }
        ]
    },
    {
        "id": "ec6ff75a0ffd4504840dab343fe41077",
        "cidr": "11.22.33.0/24",
        "description": "vlan_9999_11.22.33",
        "gateway": "11.22.33.1",
        "name": "vlan_9999_11.22.33",
        "netmask": "255.255.255.0",
        "type": "private",
        "vlan": 9999,
        "links": [
            {
                "rel": "self",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077",
                "verbs": [
                    "GET",
                    "PUT"
                ]
            },
            {
                "rel": "ipAddresses",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses",
                "verbs": [
                    "GET"
                ]
            },
            {
                "rel": "release",
                "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release",
                "verbs": [
                    "POST"
                ]
            }
        ]
    }
]

Get Network

Gets the details of a specific network in a given data center for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover properties of a network in a data center. You may optionally query details of IP Addresses on this network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

GET https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}?ipAddresses=none|claimed|free|all

Example

GET https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077?ipAddresses=claimed

请求

URI and Querystring Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
网络 字符串 ID of the Network. This can be retrieved from the Get Network List API operation.
ipAddresses 字符串 Optional component of the query to request details of IP Addresses in a certain state. Should be one of the following: "none" (returns details of the network only), "claimed" (returns details of the network as well as information about claimed IP addresses), "free" (returns details of the network as well as information about free IP addresses) or "all" (returns details of the network as well as information about all IP addresses). Refer to Get IP Address List for the data shape of returned IP addresses.

响应

Entity Definition

Name Type 描述
id 字符串 ID of the network
cidr 字符串 The network address, specified using CIDR notation
描述 字符串 Description of VLAN, a free text field that defaults to the VLAN number combined with the network address
gateway 字符串 Gateway IP address of the network
用户名 字符串 User-defined name of the network; the default is the VLAN number combined with the network address
netmask 字符串 A screen of numbers used for routing traffic within a subnet
类型 boolean Network type, usually private for networks created by the user
vlan integer Unique number assigned to the VLAN
links array Collection of entity links that point to resources related to this list of networks

Examples

JSON

{
    "id": "ec6ff75a0ffd4504840dab343fe41077",
    "cidr": "11.22.33.0/24",
    "description": "vlan_9999_11.22.33",
    "gateway": "11.22.33.1",
    "name": "vlan_9999_11.22.33",
    "netmask": "255.255.255.0",
    "type": "private",
    "vlan": 9999,
    "ipAddresses": [
        {
            "address": "11.22.33.12",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "private"
        },
        {
            "address": "11.22.33.13",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "private"
        },
        {
            "address": "65.43.210.123",
            "claimed": true,
            "server": "WA1ALIASAPI01",
            "type": "publicMapped"
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077",
            "verbs": [
                "GET",
                "PUT"
            ]
        },
        {
            "rel": "ipAddresses",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/ipAddresses",
            "verbs": [
                "GET"
            ]
        },
        {
            "rel": "release",
            "href": "http://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release",
            "verbs": [
                "POST"
            ]
        }
    ]
}

Release Network

Releases a network from a given account in a given data center to a pool for another user to claim. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you no longer need a network, and wish to to release it back a given data center. Before you can release a network, there must be no IP addresses claimed by servers.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

POST https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}/release

Example

POST https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077/release

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
网络 字符串 ID of the Network. This can be retrieved from the Get Network List API operation

响应

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful release of the network.

Create a Site to Site VPN

Creates a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to create a Site to Site VPN for a given account.

URL

Structure

POST https://api.ctl.io/v2/siteToSiteVpn?account={accountId}

Example

POST https://api.ctl.io/v2/siteToSiteVpn?account=ACCT

请求

URI Parameters

Name Type 描述 Req.
accountId 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
local 字符串 Local site properties
remote 字符串 Remote site properties
ike 字符串 IKE properties
ipsec 字符串 IPSec properties

Local Entity

Name Type 描述 Req.
locationAlias 字符串 Short code for a particular location
subnets 字符串 Local address for Site to Site VPN, specified using CIDR notation

Remote Entity

Name Type 描述 Req.
siteName 字符串 Friendly name of the site
deviceType 字符串 Friendly name of the device type
address 字符串 Remote address for Site to Site VPN, specified using CIDR notation
subnets 字符串 Remote network address for Site to Site VPN, specified using CIDR notation

IKE Entity

Name Type 描述 Option Req.
encryption 字符串 Encryption algorithm aes128, aes192, aes256, tripleDES
hashing 字符串 Hashing algorithm sha1_96, sha1_256, md5
diffieHellmanGroup 字符串 Group 1 (legacy), Group 2 or Group 5. If using AES with a cipher strength greater than 128-bit, or SHA2 for hashing, we recommend Group 5, otherwise Group 2 is sufficient group1, group2, group5
preSharedKey 字符串 The pre-shared key is a shared secret that secures the VPN tunnel. This value must be identical on both ends of the connection
lifetime 字符串 Lifetime is set to 8 hours for IKE. This is not required to match, as the negotiation will choose the shortest value supplied by either peer 3600, 28800, 86400
mode 字符串 Protocol mode main, aggressive
deadPeerDetection boolean Specify if you wish this enabled or disabled. Check your device defaults; for example, Cisco ASA defaults to 'on', while Netscreen/Juniper SSG or Juniper SRX default to 'off'. Our default is 'off'. true/false
natTraversal boolean NAT-Traversal: Allows connections to VPN end-points behind a NAT device. Defaults to 'off'. If you require NAT-T, you also need to provide the private IP address that your VPN endpoint will use to identify itself. true/false
remoteIdentity 字符串 The private IP address that your VPN endpoint will use to identify itself. Required only when NAT-T state is on a valid IPv4 address

IPSec Entity

Name Type 描述 Option Req.
encryption 字符串 Encryption algorithm aes128, aes192, aes256, tripleDES
hashing 字符串 Hashing algorithm sha1_96, sha1_256, md5
protocol 字符串 IPSec protocol esp, ah
pfs 字符串 PFS enabled or disabled (we suggest enabled, using Group 2, though Group 5 is recommended with SHA2 hashing or AES-192 or AES-256) disabled, group1, group2, group5
lifetime 字符串 Lifetime is set to 1 hour (and unlimited KB). This setting is not required to match, as the negotiation process will choose the shortest value supplied by either peer. 3600, 28800, 86400

Example

JSON

{
  "local": {
    "locationAlias": "WA1",            	  
    "subnets": [                          
      "10.10.10.0/24"
    ]
  },
  "remote": {
    "siteName": "API test",                
    "deviceType": "SRX and stuff",        
    "address": "1.2.3.4",
    "subnets": [                          
      "10.1.1.0/24"
    ]
  },
  "ike": {
    "encryption": "aes128",               
    "hashing": "sha1_96",                 
    "diffieHelmanGroup": "group2",        
    "preSharedKey": "Password123",
    "lifetime": 28800,                    
    "mode": "main",                       
    "deadPeerDetection": false,
    "natTraversal": false,
    "remoteIdentity": null                
  },
  "ipsec": {
    "encryption": "aes128",               
    "hashing": "sha1_96",                 
    "protocol": "esp",                    
    "pfs": "group2",                      
    "lifetime": 3600                      
  }
}

响应

The response will be an entity representing the new Site to Site VPN that was created.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "pendingTaskId": "",
    "accountAlias": "ACCT",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
 "local": {
   "locationAlias": "WA1",               
   "subnets": [                          
     "10.10.10.0/24"
   ]
 },
 "remote": {
   "siteName": "Montreal Office",                
   "deviceType": "Cisco ASA5520 v8.3",        
   "address": "1.2.3.4",
   "subnets": [                          
     "10.1.1.0/24"
   ]
 },
 "ike": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "diffieHelmanGroup": "group2",        
   "preSharedKey": "Password123",
   "lifetime": 28800,                    
   "mode": "main",                       
   "deadPeerDetection": false,
   "natTraversal": false,
   "remoteIdentity": null                
 },
 "ipsec": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "protocol": "esp",                    
   "pfs": "group2",                      
   "lifetime": 3600                      
 }
}

Delete a Site to Site VPN

Deletes a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to delete a Site to Site VPN for a given account.

URL

Structure

DELETE https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

DELETE https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

请求

URI Parameters

Name Type 描述 Req.
accountId 字符串 Short code for a particular account
vpnId 字符串 ID of the VPN

响应

The response will be the job ID in the Queue, for the Site to Site VPN that is to be deleted.

Example

JSON

"54851"

Get Details for a Site to Site VPN

Gets Details for a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to get details for a Site to Site VPN for a given account.

URL

Structure

GET https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

GET https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

请求

URI Parameters

Name Type 描述 Req.
accountId 字符串 Short code for a particular account
vpnId 字符串 ID of the VPN

响应

The response will be an entity representing the details for a Site to Site VPN for a given account.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
    "accountAlias": "ACCT",
    "local": {
        "address": "4.3.2.1",
        "locationAlias": "WA1",
        "locationDescription": "WA1 - US West (Seattle)",
        "subnets": [
            "10.10.10.0/24"
        ]
    },
    "remote": {
        "siteName": "Montreal Office",                
        "deviceType": "Cisco ASA5520 v8.3",
        "address": "1.2.3.4",
        "subnets": [
            "10.1.1.0/24"
        ]
    },
    "ike": {
        "encryption": "aes128",
        "hashing": "sha1_96",
        "diffieHellmanGroup": "group2",
        "lifetime": 28800,
        "mode": "main",
        "deadPeerDetection": false,
        "natTraversal": false,
        "remoteIdentity": null
    },
    "ipsec": {
        "encryption": "aes128",
        "hashing": "sha1_96",
        "protocol": "esp",
        "pfs": "group2",
        "lifetime": 3600
    },
    "links": [
        {
            "rel": "self",
            "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"
        }
    ]
}

Get Site to Site VPNs

Gets all Site to Site VPNs for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to get a list Site to Site VPNs for a given account.

URL

Structure

GET https://api.ctl.io/v2/siteToSiteVpn?account={accountId}

Example

GET https://api.ctl.io/v2/siteToSiteVpn?account=ACCT

请求

URI Parameters

Name Type 描述 Req.
accountId 字符串 Short code for a particular account

响应

The response will be an entity representing the Site to Site VPNs for a given account.

Example

JSON

[
    {
        "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
        "changeInfo": {
            "createdBy": "username",
            "createdDate": "2016-06-14T16:22:51Z",
            "modifiedBy": "username",
            "modifiedDate": "2016-06-14T17:53:12Z"
        },
        "accountAlias": "ACCT",
        "local": {
            "address": "4.3.2.1",
            "locationAlias": "WA1",
            "locationDescription": "WA1 - US West (Seattle)",
            "subnets": [
                "10.10.10.0/24"
            ]
        },
        "remote": {
            "siteName": "Montreal Office",                
            "deviceType": "Cisco ASA5520 v8.3",
            "address": "1.2.3.4",
            "subnets": [
                "10.1.1.0/24"
            ]
        },
        "ike": {
            "encryption": "aes128",
            "hashing": "sha1_96",
            "diffieHellmanGroup": "group2",
            "lifetime": 28800,
            "mode": "main",
            "deadPeerDetection": false,
            "natTraversal": false,
            "remoteIdentity": null
        },
        "ipsec": {
            "encryption": "aes128",
            "hashing": "sha1_96",
            "protocol": "esp",
            "pfs": "group2",
            "lifetime": 3600
        },
        "links": [
            {
                "rel": "self",
                "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"
            }
        ]
    }
]

Update a Site to Site VPN

Updates a Site to Site VPN for a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to update a Site to Site VPN for a given account.

URL

Structure

PUT https://api.ctl.io/v2/siteToSiteVpn/{vpnId}?account={accountId}

Example

PUT https://api.ctl.io/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT

请求

URI Parameters

Name Type 描述 Req.
accountId 字符串 Short code for a particular account
vpnId 字符串 ID of the VPN

Content Properties

Name Type 描述 Req.
local 字符串 Local site properties
remote 字符串 Remote site properties
ike 字符串 IKE properties
ipsec 字符串 IPSec properties

Local Entity

Name Type 描述 Req.
subnets 字符串 Local address for Site to Site VPN, specified using CIDR notation

Remote Entity

Name Type 描述 Req.
siteName 字符串 Friendly name of the site
deviceType 字符串 Friendly name of the device type
address 字符串 Remote address for Site to Site VPN, specified using CIDR notation
subnets 字符串 Remote network address for Site to Site VPN, specified using CIDR notation

IKE Entity

Name Type 描述 Option Req.
encryption 字符串 Encryption algorithm aes128, aes192, aes256, tripleDES
hashing 字符串 Hashing algorithm sha1_96, sha1_256, md5
diffieHelmanGroup 字符串 Group 1 (legacy), Group 2 or Group 5. If using AES with a cipher strength greater than 128-bit, or SHA2 for hashing, we recommend Group 5, otherwise Group 2 is sufficient group1, group2, group5
preSharedKey 字符串 The pre-shared key is a shared secret that secures the VPN tunnel. This value must be identical on both ends of the connection
lifetime 字符串 Lifetime is set to 8 hours for IKE. This is not required to match, as the negotiation will choose the shortest value supplied by either peer 3600, 28800, 86400
mode 字符串 Protocol mode main, aggressive
deadPeerDetection boolean Specify if you wish this enabled or disabled. Check your device defaults; for example, Cisco ASA defaults to 'on', while Netscreen/Juniper SSG or Juniper SRX default to 'off'. Our default is 'off'. true/false
natTraversal boolean NAT-Traversal: Allows connections to VPN end-points behind a NAT device. Defaults to 'off'. If you require NAT-T, you also need to provide the private IP address that your VPN endpoint will use to identify itself. true/false
remoteIdentity 字符串 The private IP address that your VPN endpoint will use to identify itself. Required only when NAT-T state is on a valid IPv4 address

IPSec Entity

Name Type 描述 Option Req.
encryption 字符串 Encryption algorithm aes128, aes192, aes256, tripleDES
hashing 字符串 Hashing algorithm sha1_96, sha1_256, md5
protocol 字符串 IPSec protocol esp, ah
pfs 字符串 PFS enabled or disabled (we suggest enabled, using Group 2, though Group 5 is recommended with SHA2 hashing or AES-192 or AES-256) disabled, group1, group2, group5
lifetime 字符串 Lifetime is set to 1 hour (and unlimited KB). This setting is not required to match, as the negotiation process will choose the shortest value supplied by either peer. 3600, 28800, 86400

Example

JSON

{
  "ike": {
    "preSharedKey": "321drowssaP"
  }
}

响应

The response will be an entity representing the Site to Site VPN that was updated.

Example

JSON

{
    "id": "4FA8D6C83271CA53F9ABA815D7F4A0DD",
    "changeInfo": {
      "createdBy": "username",
      "createdDate": "2016-06-14T16:22:51Z",
      "modifiedBy": "username",
      "modifiedDate": "2016-06-14T17:53:12Z"
    },
 "pendingTaskId": "54847",
 "accountAlias": "ACCT",
 "local": {
   "address": "4.3.2.1",
   "locationAlias": "WA1",
   "locationDescription": "WA1 - US West (Seattle)"               
   "subnets": [                          
     "10.10.10.0/24"
   ]
 },
 "remote": {
   "siteName": "Montreal Office",                
   "deviceType": "Cisco ASA5520 v8.3",        
   "address": "1.2.3.4",
   "subnets": [                          
     "10.1.1.0/24"
   ]
 },
 "ike": {
   "encryption": "aes128",               
   "hashing": "sha1_96",                 
   "diffieHelmanGroup": "group2",        
   "preSharedKey": "321drowssaP",
   "lifetime": 28800,                    
   "mode": "main",                       
   "deadPeerDetection": false,
   "natTraversal": false,
   "remoteIdentity": null                
 },
 "ipsec": {
     "encryption": "aes128",
     "hashing": "sha1_96",
     "protocol": "esp",
     "pfs": "group2",
     "lifetime": 3600
 },
 "links": [
     {
         "rel": "self",
         "href": "/v2/siteToSiteVpn/4FA8D6C83271CA53F9ABA815D7F4A0DD?account=ACCT"                      
 }
}

Update Network

Updates the attributes of a given Network via PUT. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the name and description of a network.

NOTE: This API operation is experimental only, and subject to change with no notice. Please plan accordingly.

URL

Structure

PUT https://api.ctl.io/v2-experimental/networks/{accountAlias}/{dataCenter}/{Network}

Example

PUT https://api.ctl.io/v2-experimental/networks/ALIAS/WA1/ec6ff75a0ffd4504840dab343fe41077

请求

URI and Querystring Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
dataCenter 字符串 Short string representing the data center you are querying. Valid codes can be retrieved from the Get Data Center List API operation.
网络 字符串 ID of the Network. These can be retrieved from the Get Network List API operation

Content Properties

Name Type 描述 Req.
用户名 字符串 User-defined name of the network; the default is the VLAN number combined with the network address
描述 字符串 Description of VLAN, a free text field that defaults to the VLAN number combined with the network address

Examples

JSON

{
    "name": "VLAN for Development Servers",
    "description": "Development Servers on 11.22.33.0/24"
}

响应

Entity Definition

The response will not contain JSON content, but should return the HTTP 204 No Content response upon the successful update of network attributes.

Applying Patches to Operating Systems

This service allows the user to patch virtual machines to the latest available patches provided by the OS vendor, using the Execute Package API. It does not discriminate patches based on patch severity or any other vendor categorization. The package will kick off one or multiple attempts to apply patches, including a series of reboots. Reboots will cease and the execution will complete when there are no more patches to apply. Additional information on this capability is in this knowledge base article.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to patch operating systems with updates from OS vendors.

NOTE: Servers require Internet access to be patched. It is also recommended to place servers in Maintenance Mode before patching. Further, an API request can deploy against all VMs a user is authorized to administer under a single alias.

支持的操作系统

Currently, the Operating Systems that may be updated with this service are show below:

  • CentOS 5
  • CentOS 6
  • Red Hat Enterprise Linux 6
  • Red Hat Enterprise Linux 5
  • Red Hat Enterprise Linux 7
  • Windows 2012
  • Windows 2012R2

Exceptions

  • Red Hat Enterprise Linux and CentOS: This service will exclude some updates. It will exclude kernel patches and nss packages.

Package Details

操作系统 Blueprint Name Script Package Name Package ID
Windows 2012 and 2012R2 Auto Patching Windows 2012 Auto Patching Windows 2012 b229535c-a313-4a31-baf8-6aa71ff4b9ed
Red Hat Enterprise Linux 5, 6, and 7 OR CentOS 5 and 6 Yum Update Script Yum Update c3c6642e-24e1-4c37-b56a-1cf1476ee360

Example

JSON

{
    "servers": [
        "WA1ALIASSERV0101"
    ],
    "package": {
        "packageId": "c3c6642e-24e1-4c37-b56a-1cf1476ee360",
        "parameters": {"patch.debug.mode": "false"

        }
    }
}

响应

The response will be an array containing one entity for each server that the operation was performed on.

In addition, you will receive an email confirming that the patch was requested. A second email will be sent upon the successful application of the auto-patch capability.

Get Details of Patches Applied to a Server During a Single Execution

This services returns details on all attempted patches for a single execution against a server.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of the patches applied for a given execution to a server using the Patching-as-a-Service feature.

The response will contain information from the vendor about the patch and the status of the attempt.

URL

Structure

GET https://patching.useast.appfog.ctl.io/rest/servers/{alias}/server/{serverID}/patch/{execution_id}

Example

GET https://patching.useast.appfog.ctl.io/rest/servers/OSD/server/VA1OSDPATCH33/patch/VA1-132457

请求

URI

Name Type 描述
accountAlias 字符串 Short code for a particular account
serverID 字符串 ID of the server
execution_id 字符串 Correlation ID for all the patches included with a single update execution, obtained from the Patch Summary response or emails regarding a patch request. The execution ID format will be aa#-######

响应

Name Type 描述
execution_id 字符串 The execution ID associated with a particular patch
status 字符串 Either pending or completed
start_time dateTime When this value is superior to patches, indicates the start time of the entire execution (which contains all initiations). When this value is inferior to patches, indicates the start time of the patch.
end_time dateTime When this value is superior to patches, indicates the end time of the entire execution (which contains all initiations). When this value is inferior to patches, indicates the end time of the patch.
duration 字符串 The minutes and seconds between the start and end time
begin_message 字符串 "Update Process BEGIN"
end_message 字符串 "Updating Complete"
patches Number Quantity of patches installed
patch_begin_message 字符串 Identifies the Software or OS updated and the reference number (if Windows, KB#######) for that particular update
patch_end_message 字符串 Result code established by Microsoft, defining the possible results of an install. These same codes will be used for other Operating Systems as well. https://msdn.microsoft.com/en-us/library/windows/desktop/aa387095(v=vs.85).aspx
status 字符串 Status of an individual patch, either pending, completed, or failed

Get a Summary of All Patches Deployed to a Server

This service shows a history of all the patches deployed to a given server.

Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of the patches applied to a server using the Patching-as-a-Service feature.

The response will contain a high-level overview of all the patches installed for each execution and when they were applied.

URL

Structure

GET https://patching.useast.appfog.ctl.io/rest/servers/{accountAlias}/server/{serverID}/patch

Example

GET https://patching.useast.appfog.ctl.io/rest/servers/ALIAS/server/WA1ALIASSERV0101/patch

请求

URI

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverId 字符串 ID of the server

响应

Name Type 描述
execution_id 字符串 The execution ID associated with a particular patch
status 字符串 Either pending or completed
start_time date/Time Either the start time of the entire execution (which contains all initiations) or a particular initiation
end_time date/Time Either the end time of the entire execution (which contains all initiations) or a particular initiation
init_messages complex Shows the quantity of initiations
init_begin_message 字符串 "Invoking SUS API" or "Invoking yum check-update"
init_end_mesasge 字符串 identifies how many updates were installed and the URLS (for Windows) or names of the patches/updates

Pause Server

Sends the pause operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to pause a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the pause command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/pause

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/pause

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform pause operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Power Off Server

Sends the power off operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to power off a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the power off command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/powerOff

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/powerOff

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform power off operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Power On Server

Sends the power on operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to power on a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the power on command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/powerOn

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/powerOn

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform power on operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
array complex Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Reboot Server

Sends the reboot operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to reboot a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the reboot command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/reboot

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/reboot

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform reboot operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Reset Server

Sends the reset operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to reset a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the reset command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/reset

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/reset

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform reset operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Set Maintenance Mode

Sends a specified setting for maintenance mode per server to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly turn on or off maintenance mode on multiple servers. Specifically, this call can be used if you want set some servers to have maintenance mode on and others to have it off. If you want to set maintenance mode for servers to all on or all off, you can use the respective methods for starting maintenance mode or stopping maintenance mode for multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/setMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/setMaintenance

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
servers array List of server ID and maintenance mode pairs to set.

Servers Definition

Name Type 描述
id 字符串 ID of server to set maintenance mode on or off
inMaintenanceMode boolean Indicator of whether to place server in maintenance mode or not

Examples

JSON

{
  "servers":[
    {
      "id": "wa1aliaswb01",
      "inMaintenanceMode": "true"
    },
    {
      "id": "wa1aliaswb02",
      "inMaintenanceMode": "false"
    }
  ]
}

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Shut Down Server

Sends the shut down operation to a list of servers and adds operation to queue. (See Description of Server Group Power Commands for details on how the power off operation is used.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to shut down a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the shut down command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/shutDown

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/shutDown

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform shut down operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Start Maintenance Mode

Sends a the start maintenance mode operation to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly start maintenance mode on multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/startMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/startMaintenance

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to start maintenance mode on.

Request Example

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Stop Maintenance Mode

Sends a the stop maintenance mode operation to a list of servers and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to explicitly stop maintenance mode on multiple servers.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/stopMaintenance

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/stopMaintenance

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to stop maintenance mode on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

Public IP: See Firewall

APIs for Public IP are located within the Firewall section.

Get Status

Gets the status of a particular job in the queue, which keeps track of any long-running asynchronous requests (such as server power operations or provisioning tasks). Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to check the status of a specific job in the queue. It is usually called after running a batch job and receiving the job identifier from the status link (e.g. Power On Server, Create Server, etc.) and will typically continue to get called until a "succeeded" or "failed" response is returned.

URL

Structure

GET https://api.ctl.io/v2/operations/{accountAlias}/status/{statusId}

Example

GET https://api.ctl.io/v2/operations/ALIAS/status/wa1-12345

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.
Status ID 字符串 ID of the job to query. Retrieved from the status link in the response to a batch job request.

响应

Entity Definition

Name Type 描述
状态 字符串 The status of the operation. Will be one of the following: "notStarted", "executing", "succeeded", "failed", "resumed" or "unknown".

Examples

JSON

{
  "status":"succeeded"
}

Create Subscription Backup Operation

Initiation a subscription backup's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore a subscription's backup. You may restore a backup to the subscription it was created from, or to another subscription with equal or greater storage. Backup restore is an asynchronous process; valid requests will be accepted and the restore request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups/{backupId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups/2957/operations

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.
backupId 数字 Backup id.

Content Properties

Name Type 描述 Req.
类型 字符串 'restore'
toSubscriptionId 数字 The id of the subscription you want to restore this backup to. The target subscription may be any subscription in your account that has equal or greater storage.

Create Subscription Backup

Create a subscription backup. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to initiate a subscription backup. Backup creation is an asynchronous process; valid requests will be accepted and the create request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

Create Subscription Notification Operation

Initiate a subscription notification's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to verify a subscription notification. You must provide the token sent in the notification verification email.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19/operations

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.
notificationId 数字 Notification id.

Content Properties

Name Type 描述 Req.
类型 字符串 'verify'
token 字符串 Token included in the notification verification email.

Create Subscription Notification

Create a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a subscription's notification. Subscriptions can be configured to notify users of high CPU or Storage use through Notifications. When a new notification is created, the recipient must validate their email through a url provided in a notification verification email before they begin to receive email notifications.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

Content Properties

Name Type 描述 Req.
destinationType 字符串 EMAIL.
recipient 字符串 Email address to send notificaitons to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.

响应

Entity Definition

Name Type 描述
id 数字 Notification id.
destinationType 字符串 EMAIL
recipient 字符串 Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "wilfred@example.com",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]```

Create Subscription Operation

Initiate a subscription's operation. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to failover a replicated subscription. Subscription failover is an asynchronous process; valid requests will be accepted and the failover request queued for further processing.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/operations

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/operations

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

Content Properties

Name Type 描述 Req.
类型 字符串 'failover'

Create Subscription

Create a new subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new subscription.

URL

Structure

POST https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions

Example

POST https://api.rdbs.ctl.io/v1/ALIAS/subscriptions

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
instanceType 字符串 One of MYSQL, MySQL_REPLICATION
地点 字符串 Datacenter id. Available datacenters are listed in Get Datacenters method
externalId 字符串 The hostname part of the connection string
machineConfig 对象 Server provisioning information for cpu, memory, and storage
backupRetentionDays 数字 Number of days to retain database backups
destinations array Server capacity notification destinations
users array Initial database user account.
backupTime 对象 Time of day to run backups (UTC)

MachineConfig Definition

Name Type 描述 Req.
cpu 数字 Number of CPUs to allocate to server
memory 数字 Amount of RAM to allocate to server (GB)
存储 数字 Amount of disk storage to allocate to server (GB)

Destination Definition

Name Type 描述 Req.
destinationType 字符串 EMAIL
地点 字符串 Where to send notifications. For EMAIL, this is an email address.
notifications array A list of notifications to receive.

User Definition

Name Type 描述 Req.
用户名 字符串 User name.
password 字符串 User password. The password must pass our minimum requirements: at least 9 characters and contain at least 3 of the following: uppercase letters, lowercase letters, numbers, symbols

BackupTime Definition

Name Type 描述 Req.
hour 数字 Hour of day to start backup (UTC).
minute 数字 Minute of minute to start backup (UTC).

Example

{
  "instanceType": "MySQL",
  "location": "VA1",
  "externalId": "st-api-test",
  "machineConfig": {
    "cpu": 1,
    "memory": 1,
    "storage": 1
  },
  "backupRetentionDays": 7,
  "destinations": [
    {
      "destinationType": "EMAIL",
      "location": "foo@bar.com",
      "notifications": [
        "CPU_UTILIZATION",
        "MEMORY_UTILIZATION"
      ]
    }
  ],
  "users": [
   {
     "name": "admin",
     "password": "AstrongPW!"
   }
  ],
  "backupTime": {
    "hour": 9,
    "minute": 15
  }
}

响应

Entity Definition

Name Type 描述
id 数字 Subscription id
地点 字符串 Datacenter id
instanceType 字符串 Type of relational database.
externalId 字符串 External id used in connection strings, etc.
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown
backupTime 字符串 Scheduled backup time in "hour:minute"
backupRetentionDays 字符串 Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host 字符串 Host DNS name used in connection strings.
port 字符串 Host port used in connection strings.
certificate 字符串 TLS certificate used to secure subscription connections.

Server Entity Definition

Name Type 描述
id 数字 Server id
alias 字符串 Server alias (hostname)
地点 字符串 Datacenter id where server is located
cpu 数字 Number of CPUs allocated to the server
memory 数字 Amount of RAM allocated to the server (GB)
存储 数字 Amount of disk storage allocated to the server (GB)
attributes 对象 Misc attributes for the server
connections 数字 Estimated number of concurrent connections possible given the server's RAM and CPU.

JSON

{
  "id": 894,
  "location": "VA1",
  "instanceType": "MySQL",
  "externalId": "st-api-test",
  "status": "Configuring",
  "backupTime": "9:15",
  "backupRetentionDays": 6,
  "servers": [
    {
      "id": 1025,
      "alias": "VA1DBDVMYSQL2130",
      "location": "va1",
      "cpu": 1,
      "memory": 1,
      "storage": 1,
      "attributes": {
        "INTERNAL_IP": "10.126.63.89"
      },
      "connections": 89
    }
  ],
  "host": "10.126.63.31",
  "port": 49562,
  "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----"
}}

Delete Subscription Backup

Delete a subscription backup. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription backup. Backup deletion is an asynchronous process; valid requests will be accepted and the delete request queued for further processing.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups/{backupId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups/2957

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.
backupId 数字 Backup id.

Delete Subscription Notification

Delete a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription notification.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.
notificationId 数字 Notification id.

Delete Subscription

Delete an existing subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a subscription.

URL

Structure

DELETE https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

DELETE https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
subscriptionId 数字 Subscription id

Get Billing

Returns current RDBS billing for an entire account or individual subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see current billing for the entire account or a single subscription.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/billing?subscriptionId={subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/billing?subscriptionId=744

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Query Parameters

Name Type 描述
subscriptionId 数字 Subscription id to narrow billing focus to a single subscription. You can get a list of all subscriptions with Get Subscriptions API operation.

响应

Entity Definition

Name Type 描述
productCode future future
metadata 对象 future
monthlyEstimate 字符串 Estimate of monthly charge for this account or subscription.
monthToDate 字符串 Monthly charges to date for this account or subscription.
currentHour 字符串 Hourly charges for this account or subscription.

JSON

{
  "productCode": null,
  "metadata": {},
  "monthlyEstimate": "446.83美元",
  "monthToDate": "85.52美元",
  "currentHour": "0.60美元"
}

Get Datacenters

Get a list of datacenters providing RDBS subscriptions. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to identify datacenters that you may create subscriptions in. You will use the dataCenter response attribute in create subscription requests.

URL

Example

GET https://api.rdbs.ctl.io/v1/datacenters

响应

Entity Definition

Name Type 描述
dataCenter 字符串 Short string representing the data center.
friendlyName 字符串 Name of the datacenter.
active boolean Is the datacenter accepting new subscriptions.

JSON

[
  {
    "dataCenter": "UC1",
    "friendlyName": "UC1 - US West (Santa Clara)",
    "active": true
  },
  {
    "dataCenter": "VA1",
    "friendlyName": "VA1 - US East (Sterling)",
    "active": true
  }
]

Get History

Returns an ordered history of actions performed on all account subscriptions, or a single subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see actions performed on all subscriptions on an account, or actions performed on a single subscription.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/history?subscriptionId={subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/history
GET https://api.rdbs.ctl.io/v1/ALIAS/history?subscriptionId=744

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.

Query Parameters

Name Type 描述
subscriptionId 数字 Subscription id to narrow focus to a single subscription. Subscription Ids are listed in the Get Subscriptions API operation.

响应

Entity Definition

Name Type 描述
timestamp 数字 Unix style timestamp; milliseconds since epoch.
消息 字符串 Summary message of form "subscription name: message".
details 字符串 Additional details, if available.
user 字符串 User initiating the action. An RDBS service account is listed when the action is provided by the service, like automated failover to replicated instances.

JSON

[
  {
    "timestamp": 1459878501968,
    "message": "demo-dev: created.",
    "details": "1 CPU, 1GB RAM, 1GB storage",
    "user": "user1"
  },
  {
    "timestamp": 1459878122697,
    "message": "poc1-test: deleted.",
    "details": null,
    "user": "user2"
  },
  {
    "timestamp": 1459455272384,
    "message": "config-db: failed over (automatic).",
    "details": "Primary server became active.",
    "user": "dbaas_service"
  },
  ...
]

Get Promotions

Returns all promotions applied to this account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see all promotions applied to an account.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/promotions

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/promotions

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.

响应

Entity Definition

Name Type 描述
code 字符串 Promotion code.

JSON

{
  "code": "PROMO_2016"
}

Get Subscription Backups

Returns details of subscription backups. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a subscription's backups.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/backups

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/backups

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

响应

Entity Definition

Name Type 描述
id 数字 Backup id.
fileName 字符串 Backup file name.
backupTime 数字 Unix timestamp of milliseconds since epoch.
backupType 字符串 One of Automated, Manual .
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size 数字 Size of the compressed backup.

JSON

[
  {
    "id": 2656,
    "fileName": "UC1DBDVMYSQL566-2016-04-06_23-00-01.tar.gz",
    "backupTime": 1459983603000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2842348
  },
  {
    "id": 2674,
    "fileName": "UC1DBDVMYSQL566-2016-04-07_23-00-01.tar.gz",
    "backupTime": 1460070003000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2842335
  },
  ...
}

Get Subscription Certificate

Returns the subscription TLS certificate as a stream. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to download a subscription certificate. Subscription certificates are included in the Get Subscription API operation; this API operation downloads the certificate as a file.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/certificate

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/certificate

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

响应

Entity Definition

Name Type 描述
N/A octet stream The certificate is returned as application/octet-stream with a default name of <subscription.externalId>.pem

Get Subscription Notifications

Returns all subscription notifications. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a subscription's notifications.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

响应

Entity Definition

Name Type 描述
id 数字 Notification id.
destinationType 字符串 EMAIL
recipient 字符串 Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "wilfred@example.com",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]```

Get Subscription

Returns details of a single subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see a single subscription's details.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

响应

Entity Definition

Name Type 描述
id 数字 Subscription id.
地点 字符串 Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType 字符串 Type of relational database.
externalId 字符串 External id used in connection strings, etc.
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime 字符串 Scheduled backup time in "hour:minute".
backupRetentionDays 字符串 Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host 字符串 Host DNS name used in connection strings.
port 字符串 Host port used in connection strings.
certificate 字符串 TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type 描述
id 数字 Server id.
alias 字符串 Server alias (hostname).
地点 字符串 Datacenter id where server is located.
cpu 数字 Number of CPUs allocated to the server.
memory 数字 Amount of RAM allocated to the server (GB).
存储 数字 Amount of disk storage allocated to the server (GB).
attributes 对象 Misc attributes for the server.
connections 数字 Estimated number of concurrent connections possible given the server's RAM and CPU.

Backup Entity Definition

Name Type 描述
id 数字 Backup id.
fileName 字符串 Backup file name.
backupTime 数字 Unix timestamp of milliseconds since epoch.
backupType 字符串 One of Automated, Manual .
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size 数字 Size of the compressed backup.

JSON

{
"id": 2957,
"location": "IL1",
"instanceType": "MySQL",
"externalId": "config-db",
"status": "Active",
"backupTime": "0:0",
"backupRetentionDays": 7,
"servers": [
  {
    "id": 2917,
    "alias": "IL1DBPDMYSQLXXXX",
    "location": "IL1",
    "cpu": 1,
    "memory": 1,
    "storage": 1,
    "attributes": {
      "INTERNAL_IP": "10.90.85.43"
    },
    "connections": 89
  }
],
"host": "config-db.il1.rdbs.ctl.io",
"port": 49929,
"certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----",
"backups": [
  {
    "id": 27538,
    "fileName": "IL1DBPDMYSQLXXXX-2016-03-30_00-00-02.tar.gz",
    "backupTime": 1459296004000,
    "backupType": "Automated",
    "status": "SUCCESS",
    "size": 2841295
  },
  ...
}

Get Subscriptions

Returns a list of all subscriptions and details. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to see all subscriptions and their details. You can narrow focus to a single datacenter and/or subscription status.

URL

Structure

GET https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions?dataCenter={dataCenterId}&status={status}

Example

GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?dataCenter=UC1
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?staus=ACTIVE
GET https://api.rdbs.ctl.io/v1/ALIAS/subscriptions?dataCenter=UC1&staus=PENDING

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account.

Query Parameters

Name Type 描述
dataCenter 字符串 Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation
status 字符串 One of: ACTIVE, BACKING_UP, CONFIGURING, DELETED, FAILED, PENDING, READY, RESTORING, SUCCESS, TERMINATED, UNKNOWN

响应

Entity Definition

Name Type 描述
id 数字 Subscription id.
地点 字符串 Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType 字符串 Type of relational database.
externalId 字符串 External id used in connection strings, etc.
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime 字符串 Scheduled backup time in "hour:minute".
backupRetentionDays 字符串 Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host 字符串 Host DNS name used in connection strings.
port 字符串 Host port used in connection strings.
certificate 字符串 TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type 描述
id 数字 Server id.
alias 字符串 Server alias (hostname).
地点 字符串 Datacenter id where server is located.
cpu 数字 Number of CPUs allocated to the server.
memory 数字 Amount of RAM allocated to the server (GB).
存储 数字 Amount of disk storage allocated to the server (GB).
attributes 对象 Misc attributes for the server.
connections 数字 Estimated number of concurrent connections possible given the server's RAM and CPU.

Backup Entity Definition

Name Type 描述
id 数字 Backup id.
fileName 字符串 Backup file name.
backupTime 数字 Unix timestamp of milliseconds since epoch.
backupType 字符串 One of Automated, Manual.
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
size 数字 Size of the compressed backup.

JSON

[
  {
    "id": 2957,
    "location": "IL1",
    "instanceType": "MySQL",
    "externalId": "config-db",
    "status": "Active",
    "backupTime": "0:0",
    "backupRetentionDays": 7,
    "servers": [
      {
        "id": 2917,
        "alias": "IL1DBPDMYSQLXXXX",
        "location": "IL1",
        "cpu": 1,
        "memory": 1,
        "storage": 1,
        "attributes": {
          "INTERNAL_IP": "10.90.85.43"
        },
        "connections": 89
      }
    ],
    "host": "config-db.il1.rdbs.ctl.io",
    "port": 49929,
    "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----",
    "backups": [
      {
        "id": 27538,
        "fileName": "IL1DBPDMYSQLXXXX-2016-03-30_00-00-02.tar.gz",
        "backupTime": 1459296004000,
        "backupType": "Automated",
        "status": "SUCCESS",
        "size": 2841295
      },
      ...
    ]
  },
  ...

Patch Subscription

Modify an existing subscription. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to resize a subscription server(s), change the number of days to keep backups, or the backup time.

NOTE: A subscription storage allocation cannot be reduced.

URL

Structure

PATCH https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}

Example

PATCH https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.

Content Properties

Name Type 描述 Req.
machineConfig 对象 Server provisioning information for cpu, memory, and storage.
backupRetentionDays 数字 Number of days to retain database backups.
backupTime 对象 Time of day to run backups (UTC).

MachineConfig Definition

Name Type 描述 Req.
cpu 数字 Number of CPUs to allocate to server.
memory 数字 Amount of RAM to allocate to server (GB).
存储 数字 Amount of disk storage to allocate to server (GB).

BackupTime Definition

Name Type 描述 Req.
hour 数字 Hour of day to start backup (UTC).
minute 数字 Minute of minute to start backup (UTC).

Example

{
  "machineConfig": {
    "cpu": 2,
    "memory": 1,
    "storage": 1
  },
  "backupRetentionDays": 6,
  "backupTime": {
    "hour": 1,
    "minute": 15
  }
}

响应

Entity Definition

Name Type 描述
id 数字 Subscription id.
地点 字符串 Short string representing the data center. Datacenters are listed in the dataCenter attribute in the RDBS Get Datacenters API operation.
instanceType 字符串 Type of relational database.
externalId 字符串 External id used in connection strings, etc.
status 字符串 One of: Active, Backing Up, Configuring, Deleted, Failed, Pending, Ready, Restoring, Success, Terminated, Unknown.
backupTime 字符串 Scheduled backup time in "hour:minute".
backupRetentionDays 字符串 Number of days to retain backups.
servers array Servers implementing the subscription. Replicated subscriptions will have two servers.
host 字符串 Host DNS name used in connection strings.
port 字符串 Host port used in connection strings.
certificate 字符串 TLS certificate used to secure subscription connections.
backups array Database backups available for restore.

Server Entity Definition

Name Type 描述
id 数字 Server id.
alias 字符串 Server alias (hostname).
地点 字符串 Datacenter id where server is located.
cpu 数字 Number of CPUs allocated to the server.
memory 数字 Amount of RAM allocated to the server (GB).
存储 数字 Amount of disk storage allocated to the server (GB).
attributes 对象 Misc attributes for the server.
connections 数字 Estimated number of concurrent connections possible given the server's RAM and CPU.

JSON

{
  "id": 894,
  "location": "VA1",
  "instanceType": "MySQL",
  "externalId": "st-api-test",
  "status": "Configuring",
  "backupTime": "1:15",
  "backupRetentionDays": 6,
  "servers": [
    {
      "id": 1025,
      "alias": "VA1DBDVMYSQL2130",
      "location": "va1",
      "cpu": 2,
      "memory": 1,
      "storage": 1,
      "attributes": {
        "INTERNAL_IP": "10.126.63.89"
      },
      "connections": 89
    }
  ],
  "host": "10.126.63.31",
  "port": 49562,
  "certificate": "-----BEGIN CERTIFICATE-----....-----END CERTIFICATE-----"
}}

入门指南

The Relational DataBase Services (RDBS) API focuses on manipulating Subscriptions to the RDBS service. A Subscription includes the backing database server(s), certificates, database backups, and notifications.

You can also view RDBS billing, action history, and promotions applied to your account.

The RDBS api is a satellite of the platform API and offered on a separate URL.

Base URL: https://api.rdbs.ctl.io/v1/

Update Subscription Notification

Update a subscription notification. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change a subscription notification.

URL

Structure

PUT https://api.rdbs.ctl.io/v1/{accountAlias}/subscriptions/{subscriptionId}/notifications/{notificationId}

Example

PUT https://api.rdbs.ctl.io/v1/ALIAS/subscriptions/744/notifications/19

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account.
subscriptionId 数字 Subscription id.
notificationId 数字 Notification id.

Content Properties

Name Type 描述 Req.
destinationType 字符串 EMAIL.
recipient 字符串 Email address to send notificaitons to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.

响应

Entity Definition

Name Type 描述
id 数字 Notification id.
destinationType 字符串 EMAIL
recipient 字符串 Email address the notification is delivered to.
notificationTypes array One of more of CPU_UTILIZATION, STORAGE_UTILIZATION.
verified boolean True if the recipient has verified their email address through the notification verification email.

JSON

[
  {
    "id": 19,
    "destinationType": "EMAIL",
    "recipient": "wilfred@example.com",
    "notificationTypes": [
      "CPU_UTILIZATION",
      "STORAGE_UTILIZATION"
    ],
    "verified": false
  }
]```

Add Secondary Network

Adds a secondary network adapter to a given server in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to add a secondary network adapter to a server. You will need a NetworkId to associate with the server. Users have the option to specify an IP address to assign to the server; otherwise the first available IP address in the network will be assigned. Up to four total network adapters can be attached to a server (i.e. a total of 3 secondary adapters). In addition, only one IP address per secondary network can be associated with a server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/networks

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/networks

请求

URI Parameters

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverId 字符串 ID of the server

Content Properties

Name Type 描述 Req.
networkId 字符串 ID of the network. These can be retrieved from the Get Network List API operation
ipAddress 字符串 Optional IP address for the networkId

Examples

JSON

{
      "networkId": "61a7e67908ce4bedabfdaf694a1360fe",
      "ipAddress": "123.456.1.1"
}

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the secondary network will be available on the server.

Entity Definition

Name Type 描述
operationId 字符串 GUID for the item in the queue for completion
uri 字符串 Link to review status of the operation

Examples

JSON

  {
    "operationId": "2b70710dba4142dcaf3ab2de68e4f40c",
    "uri": "http://api.ctl.io/v2-experimental/operations/RSDA/status/2b70710dba4142dcaf3ab2de68e4f40c"
  }

Clone Server

Creates a new server as a clone of an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new server from a standard or custom template, or clone an existing server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}

Example

POST https://api.ctl.io/v2/servers/ALIAS/

请求

The request parameters are the same as defined for Create Server with the addition of the sourceServerPassword parameter being required when cloning a server. Also, note that the sourceServerId parameter should be the name of the server that is being cloned rather than a template name.

Examples

JSON

{
  "name": "web",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "sourceServerId": "WA1ALIASWEB01",
  "sourceServerPassword": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard"
}

响应

The response will be the same as specified in Create Server.

Create Server

Creates a new server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new server from a standard or custom template, or clone an existing server.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}

Example

POST https://api.ctl.io/v2/servers/ALIAS/

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the server to create. Alphanumeric characters and dashes only. Must be between 1-8 characters depending on the length of the account alias. The combination of account alias and server name here must be no more than 10 characters in length. (This name will be appended with a two digit number and prepended with the datacenter code and account alias to make up the final server name.)
描述 字符串 User-defined description of this server
groupId 字符串 ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal.
sourceServerId 字符串 ID of the server to use a source. May be the ID of a template, or when cloning, an existing server ID. The list of available templates for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation. (Ignored for bare metal servers.)
isManagedOS bool Whether to create the server as managed or not. Default is false. (Ignored for bare metal servers.)
isManagedBackup bool Whether to add managed backup to the server. Must be a managed OS server. (Ignored for bare metal servers.)
primaryDns 字符串 Primary DNS to set on the server. If not supplied the default value set on the account will be used.
secondaryDns 字符串 Secondary DNS to set on the server. If not supplied the default value set on the account will be used.
networkId 字符串 ID of the network to which to deploy the server. If not provided, a network will be chosen automatically. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. The list of available networks for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation.
ipAddress 字符串 IP address to assign to the server. If not provided, one will be assigned automatically. (Ignored for bare metal servers.)
password 字符串 Password of administrator or root user on server. If not provided, one will be generated automatically.
sourceServerPassword 字符串 Password of the source server, used only when creating a clone from an existing server. (Ignored for bare metal servers.)
cpu integer Number of processors to configure the server with (1-16) (ignored for bare metal servers)
cpuAutoscalePolicyId 字符串 ID of the vertical CPU Autoscale policy to associate the server with. Available IDs can be retrieved from the Get Autoscale Policies API operation. (Ignored for bare metal servers.)
memoryGB integer Number of GB of memory to configure the server with (1-128) (ignored for bare metal servers)
类型 字符串 Whether to create a standard, hyperscale, or bareMetal server
antiAffinityPolicyId 字符串 ID of the Anti-Affinity policy to associate the server with. Only valid for hyperscale servers. Available IDs can be retrieved from the Get Anti-Affinity Policies API operation.
customFields complex Collection of custom field ID-value pairs to set for the server.
additionalDisks complex Collection of disk parameters (ignored for bare metal servers)
ttl dateTime Date/time that the server should be deleted (ignored for bare metal servers)
packages complex Collection of packages to run on the server after it has been built (ignored for bare metal servers)
configurationId 字符串 Only required for bare metal servers. Specifies the identifier for the specific configuration type of bare metal server to deploy. A list of possible configs can be retrieved from the Get Data Center Bare Metal Capabilities API operation. (Ignored for standard and hyperscale servers.)
osType 字符串 Only required for bare metal servers. Specifies the OS to provision with the bare metal server. Currently, the only supported OS types are redHat6_64Bit, centOS6_64Bit, windows2012R2Standard_64Bit, windows2012R2Datacenter_64Bit, ubuntu14_64Bit. A list of importable OS types for a given data center can be retrieved from the Get Data Center Bare Metal Capabilities API operation. (Ignored for standard and hyperscale servers.)

CustomFields Definition

Name Type 描述
id 字符串 ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value 字符串 Value to set the custom field to for this server.

AdditionalDisks Definition

Name Type 描述
path 字符串 File system path for disk (Windows drive letter or Linux mount point). Must not be one of reserved names.
sizeGB integer Amount in GB to allocate for disk, up to 1024 GB per.
类型 字符串 Whether the disk should be raw or partitioned

Packages Definition

Name Type 描述
packageId 字符串 ID of the package to run on the server after it builds. Available package IDs can be retrieved from the Get Packages API operation.
parameters complex Collection of name-value pairs to specify package-specific parameters.

Examples

JSON

{
  "name": "web",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "sourceServerId": "RHEL-6-64-TEMPLATE",
  "isManagedOS": false,
  "primaryDns": "172.17.1.26",
  "secondaryDns": "172.17.1.27",
  "networkId": "d51ef9f58f244205922eab9d240b126f",
  "ipAddress": "10.123.456.12",
  "password": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard",
  "customFields":[
    {
      "id": "90b3c5e28162456781d36ee42c5771a3",
      "value": "custom value"
    }
  ],
  "additionalDisks":[
    {
      "path": "data",
      "sizeGB": 10,
      "type": "partitioned"
    }
  ],
  "ttl": "2014-12-17T01:17:17Z"
}

响应

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"web",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    },
    {
      "rel":"self",  "href":"/v2/servers/alias/8134c91a66784c6dada651eba90a5123?uuid=True",
      "id":"8134c91a66784c6dada651eba90a5123",
      "verbs":[
        "GET"
      ]
    }
  ]
}

Delete Server

Sends the delete operation to a given server and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a server that is no longer being used.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

DELETE https://api.ctl.io/v2/servers/ACCT/WA1ACCTWB01

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server to be deleted. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

响应

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that is being deleted.
isQueued boolean Boolean indicating whether the delete operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"wa1acctwb01",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    }
  ]
}

Get Available Server Imports

Gets the list of available servers that can be imported. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the list of available OVFs that can be imported with the Import Server API. These OVFs are ones that have been uploaded to your FTP server as described in Using Self-Service VM Import.

URL

Structure

GET https://api.ctl.io/v2/vmImport/{accountAlias}/{locationId}/available

Example

GET https://api.ctl.io/v2/vmImport/ALIAS/WA1/available

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
LocationId 字符串 Data center location identifier

响应

The response is an array of available servers for import. The list of available servers is dependent upon what OVFs have been uploaded to your FTP server as described in Using Self-Service VM Import.

Entity Definition

Name Type 描述
id 字符串 ID of the OVF.
用户名 字符串 Name of the OVF.
storageSizeGB integer Number of GB of storage the server is configured with.
cpuCount integer Number of processors the server is configured with.
memorySizeMB integer Number of MB of memory the server is configured with.

Examples

JSON

[
  {
    "id":"ALIAS/CUSTOM-OVF-IMPORT",
    "name":"CUSTOM-OVF-IMPORT-RHEL-6-64",
    "storageSizeGB":16,
    "cpuCount":1,
    "memorySizeMB":1024
  },
  {
    "id":"ALIAS/CUSTOM-OVF-IMPORT-2",
    "name":"CUSTOM-OVF-IMPORT-2",
    "storageSizeGB":60,
    "cpuCount":2,
    "memorySizeMB":4096
  }
]

Get Server Credentials

Retrieves the administrator/root password on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get the administrator/root password for an existing server.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/credentials

Example

GET https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/credentials

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server with the credentials to return. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

响应

Entity Definition

Name Type 描述
userName 字符串 The username of root/administrator on the server. Typically "root" for Linux machines and "Administrator" for Windows.
password 字符串 The administrator/root password used to login.

Examples

JSON

{
  "userName":"root",
  "password":"P@ssw0rd1"
}

Get Server

Gets the details for a individual server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to find out all the details for a server. It can be used to look for changes, its status, or to retrieve links to associated resources.

URL

Structure

GET https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

GET https://api.ctl.io/v2/servers/ALIAS/WA1ACCTSERV0101

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server being queried. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

响应

Server Entity Definition

Name Type 描述
id 字符串 ID of the server being queried
用户名 字符串 Name of the server
displayName 字符串 Friendly display name for the server (can be the same as the name)
描述 字符串 User-defined description of this server
groupId 字符串 ID of the parent group
isTemplate boolean Boolean indicating whether this is a custom template or running server
locationId 字符串 Data center that this server resides in
osType 字符串 Friendly name of the Operating System the server is running
isManagedOS boolean Describes whether the server is managed or not. Only appears when the server is managed.
isManagedBackup boolean Describes whether the server has Managed Backup or not. Only appears when the server has both Managed OS and Managed Backup.
status 字符串 Describes whether the server is active or not
details complex Managed applications, resource allocations, alert policies, snapshots and more.
类型 字符串 Whether a standard or premium server
storageType 字符串 Whether it uses standard or premium storage
changeInfo complex Describes "created" and "modified" details
links array Collection of entity links that point to resources related to this server

Details Definition

Name Type 描述
ipAddresses complex Details about IP addresses associated with the server
alertPolicies complex Describe each alert policy applied to the server
cpu integer How many vCPUs are allocated to the server
diskCount integer How many disks are attached to the server
hostName 字符串 Fully qualified name of the server
inMaintenanceMode boolean Indicator of whether server has been placed in maintenance mode
memoryMB integer How many MB of memory are allocated to the server
powerState 字符串 Whether the server is running or not
storageGB integer How many total GB of storage are allocated to the server
disks complex The disks attached to the server
partitions complex The partitions defined for the server
截图 complex Details about any snapshot associated with the server
customFields complex Details about any custom fields and their values
processorDescription 字符串 Processor configuration description (for bare metal servers only)
storageDescription 字符串 Storage configuration description (for bare metal servers only)

IPAddresses Definition

Name Type 描述
public 字符串 If applicable, the public IP
internal 字符串 Private IP address. If associated with a public IP address, then the "public" value is populated

AlertPolicies Definition

Name Type 描述
id 字符串 Unique identifier of the policy
用户名 字符串 User-defined name of the alert policy
links array Collection of entity links that point to resources related to this policy

Disks Definition

Name Type 描述
id 字符串 Unique identifier of the disk
sizeGB integer Size of the disk in GB
partitionPaths array List of partition paths on the disk

Partitions Definition

Name Type 描述
sizeGB 数字 Size of the partition in GB
path 字符串 File system location path of the partition

Snapshots Definition

Name Type 描述
用户名 字符串 Timestamp of the snapshot
links array Collection of entity links that point to resources related to this snapshot

CustomFields Definition

Name Type 描述
id 字符串 Unique ID of the custom field
用户名 字符串 Friendly name of the custom field
value 字符串 Underlying value of the field
displayValue 字符串 Shown value of the field

ChangeInfo Definition

Name Type 描述
createdDate dateTime Date/time that the server was created
createdBy 字符串 Who created the server
modifiedDate dateTime Date/time that the server was last updated
modifiedBy 字符串 Who modified the server last

Examples

JSON

{
  "id": "WA1ALIASWB01",
  "name": "WA1ALIASWB01",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "isTemplate": false,
  "locationId": "WA1",
  "osType": "Windows 2008 64-bit",
  "status": "active",
  "details": {
    "ipAddresses": [
      {
        "internal": "10.82.131.44"
      },
      {
        "public": "91.14.111.101",
        "internal": "10.82.131.45"
      }
    ],
    "alertPolicies": [
      {
        "id": "15836e6219e84ac736d01d4e571bb950",
        "name": "Production Web Servers - RAM",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/alias/15836e6219e84ac736d01d4e571bb950"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies/15836e6219e84ac736d01d4e571bb950",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      },
      {
        "id": "2bec81dd90aa4217887548c3c20d7421",
        "name": "Production Web Servers - Disk",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/alias/2bec81dd90aa4217887548c3c20d7421"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies/2bec81dd90aa4217887548c3c20d7421",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      }
    ],
    "cpu": 2,
    "diskCount": 1,
    "hostName": "WA1ALIASWB01.customdomain.com",
    "inMaintenanceMode": false,
    "memoryMB": 4096,
    "powerState": "started",
    "storageGB": 60,
    "disks":[
      {
        "id":"0:0",
        "sizeGB":60,
        "partitionPaths":[]
      }
    ],
    "partitions":[
      {
        "sizeGB":59.654,
        "path":"C:\\"
      }
    ],
    "snapshots": [
      {
        "name": "2014-05-16.23:45:52",
        "links": [
          {
            "rel": "self",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40"
          },
          {
            "rel": "delete",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40"
          },
          {
            "rel": "restore",
            "href": "/v2/servers/alias/WA1ALIASWB01/snapshots/40/restore"
          }
        ]
      }
    ],
    "customFields": [
      {
        "id": "22f002123e3b46d9a8b38ecd4c6df7f9",
        "name": "Cost Center",
        "value": "IT-DEV",
        "displayValue": "IT-DEV"
      },
      {
        "id": "58f83af6123846769ee6cb091ce3561e",
        "name": "CMDB ID",
        "value": "1100003",
        "displayValue": "1100003"
      }
    ]
  },
  "type": "standard",
  "storageType": "standard",
  "changeInfo": {
    "createdDate": "2012-12-17T01:17:17Z",
    "createdBy": "user@domain.com",
    "modifiedDate": "2014-05-16T23:49:25Z",
    "modifiedBy": "user@domain.com"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/servers/alias/WA1ALIASWB01",
      "id": "WA1ALIASWB01",
      "verbs": [
        "GET",
        "PATCH",
        "DELETE"
      ]
    },
    {
      "rel": "group",
      "href": "/v2/groups/alias/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "account",
      "href": "/v2/accounts/alias",
      "id": "alias"
    },
    {
      "rel": "billing",
      "href": "/v2/billing/alias/estimate-server/WA1ALIASWB01"
    },
    {
      "rel": "statistics",
      "href": "/v2/servers/alias/WA1ALIASWB01/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/servers/alias/WA1ALIASWB01/scheduledActivities"
    },
    {
      "rel": "publicIPAddresses",
      "href": "/v2/servers/alias/WA1ALIASWB01/publicIPAddresses",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "alertPolicyMappings",
      "href": "/v2/servers/alias/WA1ALIASWB01/alertPolicies",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "antiAffinityPolicyMapping",
      "href": "/v2/servers/alias/WA1ALIASWB01/antiAffinityPolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "cpuAutoscalePolicyMapping",
      "href": "/v2/servers/alias/WA1ALIASWB01/cpuAutoscalePolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "capabilities",
      "href": "/v2/servers/alias/WA1ALIASWB01/capabilities"
    },
    {
      "rel": "credentials",
      "href": "/v2/servers/alias/WA1ALIASWB01/credentials"
    },
    {
      "rel": "publicIPAddress",
      "href": "/v2/servers/alias/WA1ALIASWB01/publicIPAddresses/91.14.111.101",
      "id": "91.14.111.101",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

Import Server

Imports a new server from an uploaded OVF. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to import a new server from an OVF that has been uploaded to your FTP server. For more information about uploading an OVF for import, see Using Self-Service VM Import and make sure the OVF meets these requirements before attempting to import it.

URL

Structure

POST https://api.ctl.io/v2/vmImport/{accountAlias}

Example

POST https://api.ctl.io/v2/vmImport/ALIAS/

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
用户名 字符串 Name of the server to create. Alphanumeric characters and dashes only. Must be between 1-7 characters depending on the length of the account alias. (This name will be appended with a two digit number and prepended with the datacenter code and account alias to make up the final server name.)
描述 字符串 User-defined description of this server
groupId 字符串 ID of the parent group. Retrieved from query to parent group, or by looking at the URL on the UI pages in the Control Portal.
primaryDns 字符串 Primary DNS to set on the server. If not supplied the default value set on the account will be used.
secondaryDns 字符串 Secondary DNS to set on the server. If not supplied the default value set on the account will be used.
networkId 字符串 ID of the network to which to deploy the server. If not provided, a network will be chosen automatically. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. The list of available networks for a given account in a data center can be retrieved from the Get Data Center Deployment Capabilities API operation.
password 字符串 Password of administrator or root user on server. This password must match the one set on the server being imported or the import will fail.
cpu integer Number of processors to configure the server with (1-16). If this value is different from the one specified in the OVF, the import process will resize the server according to the value specified here.
memoryGB integer Number of GB of memory to configure the server with (1-128). If this value is different from the one specified in the OVF, the import process will resize the server according to the value specified here.
类型 字符串 Whether to create standard or hyperscale server
customFields complex Collection of custom field ID-value pairs to set for the server.
ovfId 字符串 The identifier of the OVF that defines the server to import. This can be retrieved from the Get Available Server Imports API operation.
ovfOsType 字符串 The OS type of the server being imported. Currently, the only supported OS types are redHat6_64Bit, windows2008R2DataCenter_64bit, and windows2012R2DataCenter_64Bit. A list of importable OS types for a given data center can be retrieved from the Get Data Center Deployment Capabilities API operation.

CustomFields Definition

Name Type 描述
id 字符串 ID of the custom field to set. Available custom field IDs can be retrieved from the Get Custom Fields API operation.
value 字符串 Value to set the custom field to for this server.

Examples

JSON

{
  "name": "import",
  "description": "Custom Import Server",
  "groupId": "3d30a6bc6b5443388b7bc966d073e353",
  "primaryDns": "172.17.1.26",
  "secondaryDns": "172.17.1.27",
  "networkId": "d51ef9f58f244205922eab9d240b126f",
  "password": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard",
  "customFields":[
    {
      "id": "90b3c5e28162456781d36ee42c5771a3",
      "value": "custom value"
    }
  ],
  "ovfId": "ALIAS/CUSTOM-OVF-IMPORT",
  "ovfOsType": "redHat6_64Bit"
}

响应

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

{
  "server":"import",
  "isQueued":true,
  "links":[
    {
      "rel":"status",
      "href":"/v2/operations/alias/status/wa1-12345",
      "id":"wa1-12345"
    },
    {
      "rel":"self",  "href":"/v2/servers/alias/8134c91a66784c6dada651eba90a5123?uuid=True",
      "id":"8134c91a66784c6dada651eba90a5123",
      "verbs":[
        "GET"
      ]
    }
  ]
}

Remove Secondary Network

Removes a secondary network adapter from a given server in a given account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you need to remove a secondary network adapter from a server. You will need a NetworkId to de-associate with the server.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/networks/{networkId}

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/networks/f49875b17cee4b8c99bf1ab75aa286d6

请求

URI Properties

Name Type 描述 Req.
accountAlias 字符串 Short code for a particular account
serverId 字符串 ID of the server
networkId 字符串 ID of the network. These can be retrieved from the Get Network List API operation

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the secondary network will be removed from the server.

Entity Definition

Name Type 描述
operationId 字符串 GUID for the item in the queue for completion
uri 字符串 Link to review status of the operation

Examples

JSON

  {
    "operationId": "6c8d7b5349054fe6a532539ff066b53b",
    "uri": "http://api.ctl.io/v2-experimental/operations/ALIAS/status/6c8d7b5349054fe6a532539ff066b53b"
  }

Set Server CPU/Memory

Changes the amount of CPU cores and memory (in GB) on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the number of CPU cores or the amount of memory for a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server with the CPU or memory configuration to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the server. In this case, the value must be "set" for setting the CPU or memory amount.
member 字符串 The property of the server to perform the operation on. In this case, the value will be either "cpu" or "memory".
value integer The integer value to set for the given member. For CPU this represents the number of cores; for memory it is in GB.

Examples

JSON

[
   {
      "op":"set",
      "member":"cpu",
      "value":"4"
   },
   {
      "op":"set",
      "member":"memory",
      "value":"8"
   }
]

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server configuration will be changed as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Set Server Credentials

Changes the administrator/root password on an existing server given the current administrator/root password. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the administrator/root password on an existing server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server with the credentials to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the server. In this case, the value must be "set" for setting the credentials.
member 字符串 The property of the server to perform the operation on. In this case, the value must be "password" for setting the credentials.
value complex The current and new administrator/root password values.

Value Definition

Name Type 描述
current 字符串 The current administrator/root password used to login.
password 字符串 The new administrator/root password to change to.

Examples

JSON

[
   {
      "op":"set",
      "member":"password",
      "value":
      {
         "current":"OldP@ssw0rd1",
         "password":"NewP@ssw0rd2"
      }
   }
]

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the password will be changed as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Set Server Custom Fields

Changes the custom field values for an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the custom field values for a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the server. In this case, the value must be "set" for setting the custom field values.
member 字符串 The property of the server to perform the operation on. In this case, the value will be "customFields".
value array A list of id-value pairs for all custom fields including all required values and other custom field values that you wish to set.

Note: You must specify the complete list of custom field values to set on the server. If you want to change only one value, specify all existing field values along with the new value for the field you wish to change. To unset the value for an unrequired field, you may leave the field id-value pairing out, however all required fields must be included. (You can get existing custom field value info by using the Get Server call to see all the details of the server or the Get Custom Fields call to see available custom fields for a given account.)

Examples

JSON

[
   {
      "op":"set",
      "member":"customFields",
      "value":[
         {
            "id":"dba67b154f774a1fb413ddfa3dc4ac1d",
            "value":"Required Value 1"
         },
         {
            "id":"58f83bf6675846769ee6cb091ce3561e",
            "value":"Optional Value 1"
         },
         {
            "id":"22f002e08f3b46d9a8b38ecd4c6df7f9",
            "value":"Required Value 2"
         }
      ]
   }
]

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Server Description/Group

Changes the description and parent group of an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the description or the parent group of a given server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the server. In this case, the value must be "set" for setting the description and parent group.
member 字符串 The property of the server to perform the operation on. In this case, the value will be either "description" or "groupId".
value 字符串 The value to set for the given member. This is either the description of the server to set, or the unique identifier of the group to set as the parent.

Examples

JSON

[
   {
      "op":"set",
      "member":"description",
      "value":"New Description"
   },
   {
      "op":"set",
      "member":"groupId",
      "value":"2a5c0b9662cf4fc8bf6180f139facdc0"
   }
]

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Set Server Disks

Changes (adds or removes) disks on an existing server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the disks on an existing server.

URL

Structure

PATCH https://api.ctl.io/v2/servers/{accountAlias}/{serverId}

Example

PATCH https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server with the disk configuration to update. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
patchOperation array A list of properties, values, and the operations to perform with them for the server.

PatchOperation Definition

Name Type 描述
op 字符串 The operation to perform on a given property of the server. In this case, the value must be "set" for setting the disk configuration.
member 字符串 The property of the server to perform the operation on. In this case, the value must be "disks" for setting the disks.
value array A list of information for all disks to be on the server including type (raw or partition), size, and path.

Note: You must specify the complete list of disks to be on the server. If you want to add or resize a disk, specify all existing disks/sizes along with a new entry for the disk to add or the new size of an existing disk. To delete a disk, just specify all the disks that should remain. (You can get existing disk info by using the Get Server call to see all the details of the server.)

Examples

JSON

[
  {
    "op":"set",
    "member":"disks",
    "value":[
      {
        "diskId":"0:0",
        "sizeGB":"1",
        "type":"raw"
      },
      {
        "diskId":"0:1",
        "sizeGB":"2",
        "type":"raw"
      },
      {
        "diskId":"0:2",
        "sizeGB":"16",
        "type":"raw"
      },
      {
        "path":"/extra",
        "sizeGB":"20",
        "type":"partitioned"
      }
    ]  
  }
]

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server configuration will be changed as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Archive Server

Sends the archive operation to a list of servers and adds operation to queue. (See Understanding VM Deployment Options and Power States for details on the archive operation.) Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to archive a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the archive command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/archive

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/archive

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
serverIds array List of server IDs to perform archive operation on.

Examples

JSON

[
   "WA1ALIASWB01",
   "WA1ALIASWB02"
]

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

创建截图

Sends the create snapshot operation to a list of servers (along with the number of days to keep the snapshot for) and adds operation to queue. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a snapshot of a single server or group of servers. It should be used in conjunction with the Get Status operation to check the result of the create snapshot command.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/createSnapshot

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/createSnapshot

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
snapshotExpirationDays integer Number of days to keep the snapshot for (must be between 1 and 10).
serverIds array List of server names to perform create snapshot operation on.

Examples

JSON

{
  "snapshotExpirationDays":"7",
  "serverIds":[
      "WA1ALIASWB01",
      "WA1ALIASWB02"
    ]
}

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  },
  {
    "server":"wa1aliaswb02",
    "isQueued":false,
    "errorMessage":"The operation cannot be queued because the server cannot be found or it is not in a valid state."
  }
]

删除截图

Deletes a given server snapshot. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete an existing server snapshot.

URL

Structure

DELETE https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/snapshots/{snapshotId}

Example

DELETE https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/snapshots/10

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server with the snapshot to delete. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.
SnapshotId 字符串 ID of the snapshot to delete. Retrieved from the links in the snapshots section of the Get Server response.

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server snapshot will be deleted as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Execute Package

Executes a single package on one or more servers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to execute a Blueprint package that is available from within a given account on one or more servers. The list of available packages can be retrieved from the Get Packages API operation.

URL

Structure

POST https://api.ctl.io/v2/operations/{accountAlias}/servers/executePackage

Example

POST https://api.ctl.io/v2/operations/ALIAS/servers/executePackage

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

Content Properties

Name Type 描述 Req.
servers array List of server IDs to run the package on.
package complex The package entity describing which package to run on the specified servers.

Package Definition

Name Type 描述
packageId 字符串 Unique identifier of the package to execute.
parameters complex Set of key-value pairs for setting the package-specific parameters defined.

Examples

JSON

{
    "servers": [
        "wa1aliaswb01"
    ],
    "package": {
        "packageId": "86567681-c79c-1234-a530-850708435c23",
        "parameters": {
            "AB.HelloWorld.Variable": "someValue"
        }
    }
}

响应

The response will be an array containing one entity for each server that the operation was performed on.

Entity Definition

Name Type 描述
服务器 字符串 ID of the server that the operation was performed on.
isQueued boolean Boolean indicating whether the operation was successfully added to the queue.
links array Collection of entity links that point to resources related to this server operation.
errorMessage 字符串 If something goes wrong or the request is not queued, this is the message that contains the details about what happened.

Examples

JSON

[
  {
    "server":"wa1aliaswb01",
    "isQueued":true,
    "links":[
      {
        "rel":"status",
        "href":"/v2/operations/alias/status/wa1-12345",
        "id":"wa1-12345"
      }
    ]
  }
]

Restore Server

Restores a given archived server to a specified group. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to restore a server that has been archived.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/restore

Example

POST https://api.ctl.io/v2/servers/ACCT/WA1ACCTSERV0101/restore

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the archived server to restore. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.

Content Properties

Name Type 描述 Req.
targetGroupId 字符串 The unique identifier of the target group to restore the server to.

Examples

JSON

{
  "targetGroupId": "2a5c0b9662cf4fc8bf6180f139facdc0"
}

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server will be restored as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Revert to Snapshot

Reverts a server to a snapshot. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to revert a server to the state it was in when the given snapshot was taken.

URL

Structure

POST https://api.ctl.io/v2/servers/{accountAlias}/{serverId}/snapshots/{snapshotId}/restore

Example

POST https://api.ctl.io/v2/servers/ALIAS/WA1ALIASSERV0101/snapshots/10/restore

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
ServerId 字符串 ID of the server with the snapshot to restore. Retrieved from query to containing group, or by looking at the URL when viewing a server in the Control Portal.
SnapshotId 字符串 ID of the snapshot to restore. Retrieved from the links in the snapshots section of the Get Server response.

响应

The response is a link to the Get Status operation so the asynchronous job can be tracked. Once successfully completed, the server snapshot will be deleted as specified.

Entity Definition

Name Type Value 描述
rel 字符串 status The link type
href 字符串 /v2/operations/[ALIAS]/status/[ID] Address of the job in the queue
id 字符串 [ID] The identifier of the job in queue. Can be passed to Get Status call to retrieve status of job.

Examples

JSON

{
  "rel":"status",
  "href":"/v2/operations/alias/status/wa1-12345",
  "id":"wa1-12345"
}

Create Load Balancer Pool

Creates a new shared load balancer configuration for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to create a new shared load balancers in a given account and data center.

URL

Structure

POST https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools

Example

POST https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer

Content Properties

Name Type 描述 Req.
port integer Port to configure on the public-facing side of the load balancer pool. Must be either 80 (HTTP) or 443 (HTTPS).
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. Default is roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. Default is standard. See Shared Load Balancer Overview for more information about these options.

Examples

JSON

{
	"port": 80,
	"method": "leastConnection",
  "persistence": "sticky"
}

响应

The response will be an entity representing the new load balancer pool that was created.

Entity Definition

Name Type 描述
id 字符串 ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Empty array since no nodes will be configured yet for the new pool
links array Collection of entity links that point to resources related to this load balancer pool

Examples

JSON

{
  "id" : "40150dde098640e8b993de0e7417afc4",
  "port" : 80,
  "method" : "leastConnection",
  "persistence" : "sticky",
  "nodes" : [],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "nodes",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4/nodes",
      "verbs" : [
        "GET",
        "PUT"
      ]
    }
  ]
}

Create Shared Load Balancer

Creates a new shared load balancer configuration for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to create a new shared load balancer in a given account and data center.

URL

Structure

POST https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}

Example

POST https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.

Content Properties

Name Type 描述 Req.
用户名 字符串 Friendly name for new the load balancer
描述 字符串 Description for new the load balancer
status 字符串 Status to create the load balancer with: enabled or disabled

Examples

JSON

{
	"name":"New Load Balancer",
	"description":"A brand new load balancer"
}

响应

The response will be an entity representing the new load balancer that was created.

Entity Definition

Name Type 描述
id 字符串 ID of the load balancer
用户名 字符串 Friendly name of the load balancer
描述 字符串 Description for the load balancer
ipAddress 字符串 The external (public) IP address of the load balancer
status 字符串 Status of the load balancer: enabled, disabled or deleted
pools array Empty array since no pools will be configured yet for the new shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Examples

JSON

{
  "id" : "6b66b474fce940b8b581242709b5b2f0",
  "name" : "New Load Balancer",
  "description" : "A brand new load balancer",
  "ipAddress" : "98.76.54.32",
  "status" : "enabled",
  "pools" : [],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "pools",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools",
      "verbs" : [
        "GET",
        "POST"
      ]
    }
  ],
}

Delete Load Balancer Pool

Deletes a given pool of a shared load balancer by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific pool from a given load balancer.

URL

Structure

DELETE https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

DELETE https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is located. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer with the pool to delete.
PoolId 字符串 ID of the pool to delete.

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the load balancer.

Delete Shared Load Balancer

Deletes a given shared load balancer by ID. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a specific load balancer within a given account and data center.

URL

Structure

DELETE https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

DELETE https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is located. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer to delete.

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon deletion of the load balancer.

Get Load Balancer Nodes

Gets the list of nodes configured behind a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of nodes configured behind a given shared load balancer pool.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}/nodes

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer
PoolId 字符串 ID of the pool containing the nodes

响应

Entity Definition

The response will be an array containing one entity for each node configured.

Name Type 描述
status 字符串 Status of the node: enabled, disabled or deleted.
ipAddress 字符串 The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "status" : "enabled",
    "ipAddress" : "10.11.12.13",
    "privatePort" : 80
  },
  {
    "status" : "enabled",
    "ipAddress" : "10.11.12.14",
    "privatePort" : 80
  }
]

Get Load Balancer Pool

Gets a specified pool configured for the given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get the details for a given shared load balancer pool.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer
PoolId 字符串 ID of the pool

响应

Entity Definition

Name Type 描述
id 字符串 ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type 描述
用户名 字符串 Name of the node (generally the IP address)
status 字符串 Status of the node: enabled, disabled or deleted.
ipAddress 字符串 The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

{
  "id" : "2fa937bd20dd47c9b856376e9499c0c1",
  "port" : 80,
  "method" : "roundRobin",
  "persistence" : "standard",
  "nodes" : [
    {
      "status" : "enabled",
      "ipAddress" : "10.11.12.13",
      "privatePort" : 80,
      "name" : "10.11.12.13"
    },
    {
      "status" : "enabled",
      "ipAddress" : "10.11.12.14",
      "privatePort" : 80,
      "name" : "10.11.12.14"
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "nodes",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
      "verbs" : [
        "GET",
        "PUT"
      ]
    }
  ]
}

Get Load Balancer Pools

Gets the list of pools configured for a given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a list of pools configured for a given shared load balancer.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer

响应

Entity Definition

The response will be an array containing one entity for each pool configured on the given load balancer.

Name Type 描述
id 字符串 ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type 描述
用户名 字符串 Name of the node (generally the IP address)
status 字符串 Status of the node: enabled, disabled or deleted.
ipAddress 字符串 The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "id" : "2fa937bd20dd47c9b856376e9499c0c1",
    "port" : 80,
    "method" : "roundRobin",
    "persistence" : "standard",
    "nodes" : [
      {
        "status" : "enabled",
        "ipAddress" : "10.11.12.13",
        "privatePort" : 80,
        "name" : "10.11.12.13"
      },
      {
        "status" : "enabled",
        "ipAddress" : "10.11.12.14",
        "privatePort" : 80,
        "name" : "10.11.12.14"
      }
    ],
    "links" : [
      {
        "rel" : "self",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
        "verbs" : [
          "GET",
          "PUT",
          "DELETE"
        ]
      },
      {
        "rel" : "nodes",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
        "verbs" : [
          "GET",
          "PUT"
        ]
      }
    ]
  }
]

Get Shared Load Balancer

Gets the specified shared load balancer for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get a specific shared load balancer configured for a given account and data center.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer

响应

Entity Definition

Name Type 描述
id 字符串 ID of the load balancer
用户名 字符串 Friendly name of the load balancer
描述 字符串 Description for the load balancer
ipAddress 字符串 The external (public) IP address of the load balancer
status 字符串 Status of the load balancer: enabled, disabled or deleted
pools array Collection of pools configured for this shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Pools Definition

Name Type 描述
id 字符串 ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type 描述
用户名 字符串 Name of the node (generally the IP address)
status 字符串 Status of the node: enabled, disabled or deleted.
ipAddress 字符串 The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

{
  "id" : "ae3bbac5d9694c70ad7de062476ccb70",
  "name" : "My Load Balancer",
  "description" : "My Load Balancer",
  "ipAddress" : "12.34.56.78",
  "status" : "disabled",
  "pools" : [
    {
      "id" : "2fa937bd20dd47c9b856376e9499c0c1",
      "port" : 80,
      "method" : "roundRobin",
      "persistence" : "standard",
      "nodes" : [
        {
          "status" : "enabled",
          "ipAddress" : "10.11.12.13",
          "privatePort" : 80,
          "name" : "10.11.12.13"
        },
        {
          "status" : "enabled",
          "ipAddress" : "10.11.12.14",
          "privatePort" : 80,
          "name" : "10.11.12.14"
        }
      ],
      "links" : [
        {
          "rel" : "self",
          "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
          "verbs" : [
            "GET",
            "PUT",
            "DELETE"
          ]
        },
        {
          "rel" : "nodes",
          "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
          "verbs" : [
            "GET",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70",
      "verbs" : [
        "GET",
        "PUT",
        "DELETE"
      ]
    },
    {
      "rel" : "pools",
      "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools",
      "verbs" : [
        "GET",
        "POST"
      ]
    }
  ]
}

Get Shared Load Balancers

Gets the list of shared load balancers that exist for a given account and data center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to get the list of shared load balancers configured for a given account and data center.

URL

Structure

GET https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}

Example

GET https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.

响应

The response will be an array containing one entity for each load balancer in the given account and data center.

Entity Definition

Name Type 描述
id 字符串 ID of the load balancer
用户名 字符串 Friendly name of the load balancer
描述 字符串 Description for the load balancer
ipAddress 字符串 The external (public) IP address of the load balancer
status 字符串 Status of the load balancer: enabled, disabled or deleted
pools array Collection of pools configured for this shared load balancer
links array Collection of entity links that point to resources related to this load balancer

Pools Definition

Name Type 描述
id 字符串 ID of the load balancer pool
port integer Port configured on the public-facing side of the load balancer pool.
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.
nodes array Collection of nodes configured behind this shared load balancer
links array Collection of entity links that point to resources related to this load balancer pool

Nodes Definition

Name Type 描述
用户名 字符串 Name of the node (generally the IP address)
status 字符串 Status of the node: enabled, disabled or deleted.
ipAddress 字符串 The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server
links array Collection of entity links that point to resources related to this node

Examples

JSON

[
  {
    "id" : "ae3bbac5d9694c70ad7de062476ccb70",
    "name" : "My Load Balancer",
    "description" : "My Load Balancer",
    "ipAddress" : "12.34.56.78",
    "status" : "disabled",
    "pools" : [
      {
        "id" : "2fa937bd20dd47c9b856376e9499c0c1",
        "port" : 80,
        "method" : "roundRobin",
        "persistence" : "standard",
        "nodes" : [
          {
            "status" : "enabled",
            "ipAddress" : "10.11.12.13",
            "privatePort" : 80,
            "name" : "10.11.12.13"
          },
          {
            "status" : "enabled",
            "ipAddress" : "10.11.12.14",
            "privatePort" : 80,
            "name" : "10.11.12.14"
          }
        ],
        "links" : [
          {
            "rel" : "self",
            "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1",
            "verbs" : [
              "GET",
              "PUT",
              "DELETE"
            ]
          },
          {
            "rel" : "nodes",
            "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools/2fa937bd20dd47c9b856376e9499c0c1/nodes",
            "verbs" : [
              "GET",
              "PUT"
            ]
          }
        ]
      }
    ],
    "links" : [
      {
        "rel" : "self",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70",
        "verbs" : [
          "GET",
          "PUT",
          "DELETE"
        ]
      },
      {
        "rel" : "pools",
        "href" : "/v2/sharedLoadBalancers/ALIAS/WA1/ae3bbac5d9694c70ad7de062476ccb70/pools",
        "verbs" : [
          "GET",
          "POST"
        ]
      }
    ]
  }
]

Shared Load Balancers Overview

负载平衡器

A shared load balancer is made up of a VIP (virtual IP) and a set of servers grouped by pools (i.e. access ports). The load balancer entity is merely a named container with an IP address that can further be configured to include multiple pools of servers behind the same IP.

Load Balancer Pool

Within a shared load balancer definition, multiple pools can be configured. Each pool defines the port that will respond to and redirect traffic to the server nodes in the pool. The pool is also where the load balancing method and persistence types are set.

The method can either be set to "round robin" or "least connection." For the round robin option, the load balancer cycles through a list of all the servers bound to it. It does not take into account server workload or latency and simply distributes traffic evenly across servers. The least connection option routes traffic to the server with the fewest active connections. An "active" connection is considered one where the HTTP request has not yet received a response. This is considered the best performing of the two algorithms.

The persistence type can be either "standard" or "sticky." The standard option employs no persistence and is best for stateless web applications. If an application does require server-based state, then choose the sticky option. The sticky choice uses source IP + destination IP address-based persistence to tie users to the target server.

If you choose round robin or least connection along with standard persistence, then requests are routed without any concern for where the last user's request came from. If you choose round robin or least connection along with sticky persistence, then the FIRST request will be routed based on either round robin or least connection, and each subsequent request from that source IP address will return to the server that responded to the initial request.

Load Balancer Node

For each pool, one or more nodes are configured corresponding to a server that is included in the load balancing pool. The node definition includes the server's private IP address and the port that is serving the content.

Update Load Balancer Nodes

Updates the nodes behind a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the list of nodes in a given load balancer pool.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}/nodes

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4/nodes

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer
PoolId 字符串 ID of the pool to update

Content Properties

The body of the request is an array of node entities.

Name Type 描述 Req.
status 字符串 Status of the node: enabled, disabled or deleted.
ipAddress 字符串 The internal (private) IP address of the node server
privatePort integer The internal (private) port of the node server. Must be a value between 1 and 65535.

Examples

JSON

[
  {
    "ipAddress" : "10.11.12.18",
    "privatePort" : 8080
  },
  {
    "ipAddress" : "10.11.12.19",
    "privatePort" : 8080
  }
]

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the list of load balancer nodes.

Update Load Balancer Pool

Updates a given shared load balancer pool. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the port, method, or persistence options for a given load balancer pool.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}/pools/{poolId}

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0/pools/40150dde098640e8b993de0e7417afc4

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer
PoolId 字符串 ID of the pool to update

Content Properties

Name Type 描述 Req.
method 字符串 The balancing method for this load balancer, either leastConnection or roundRobin. See Shared Load Balancer Overview for more information about these options.
persistence 字符串 The persistence method for this load balancer, either standard or sticky. See Shared Load Balancer Overview for more information about these options.

Examples

JSON

{
    "method": "roundRobin",
  "persistence": "standard"
}

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the load balancer pool.

Update Shared Load Balancer

Updates a given shared load balancer. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation to update the name, description, or status of a given shared load balancer.

URL

Structure

PUT https://api.ctl.io/v2/sharedLoadBalancers/{accountAlias}/{dataCenter}/{loadBalancerId}

Example

PUT https://api.ctl.io/v2/sharedLoadBalancers/ALIAS/WA1/6b66b474fce940b8b581242709b5b2f0

请求

URI Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
DataCenter 字符串 Short string representing the data center where the load balancer is. Valid codes can be retrieved from the Get Data Center List API operation.
LoadBalancerId 字符串 ID of the load balancer to update

Content Properties

Name Type 描述 Req.
用户名 字符串 Friendly name for new the load balancer
描述 字符串 Description for new the load balancer
status 字符串 Status to create the load balancer with: enabled or disabled

Examples

JSON

{
	"name":"Updated Load Balancer",
	"description":"An updated load balancer"
}

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon updating the load balancer.

Create Policy

Creates a new backup policy associated with the account. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a brand new backup policy.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

请求

Content Properties

Name Type 描述 Req.
backupIntervalHours integer The backup frequency of the Policy specified in hours -- this field is ignored if backupSchedule is defined Yes1
backupSchedule 字符串 Quartz-flavored CRON expression describing the execution schedule for backups Yes1
clcAccountAlias 字符串 The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
retentionDays integer The number of days backup data will be retained

1One of either the backupIntervalHours field OR the backupSchedule field is required. If backupSchedule is defined, it will be used and backupIntervalHours will be ignored.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "paths": [
    "/opt"
  ],
  "retentionDays": 7,
  "backupSchedule": "0 0 12 ? * TUE,SUN *"
}

响应

Entity Definition

Name Type 描述
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule 字符串 Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias 字符串 The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId 字符串 The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status 字符串 The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/opt"
  ],
  "excludedDirectoryPaths": [],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "backupSchedule": "0 0 12 ? * SUN *"
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Create Server Policies

Create multiple Server Policies under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

Note that the endpoint for this operation is the same as the standard Create Server Policy API, but an additonal header (Bulk-Operation: true) is required, and both the request and response bodies will be different than the single policy create.

When to Use It

Use this API operation when you want to create multiple Server Policies.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/193fccfc-c144-4052-98da-145eed825e0a/serverPolicies

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 The unique Id of an account policy

Headers

Name Type 描述 Req.
Bulk-Operation boolean Must be set to "true" for the multi-server-policy API

Content Properties

Name Type 描述 Req.
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored, can be "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC"

Examples

JSON

[{
  "serverId": "UC1BAADTEST01",
  "storageRegion": "US WEST"
 },{
  "serverId": "IL1BAADTEST01",
  "storageRegion": "US WEST"
}]

响应

Response List Definition

Name Type 描述
status 字符串 Aggregate status for entire server policy creation request. 'SUCCESS', 'PARTIAL', 'FAILED'
success boolean Indicates if server policy creation was successful
error 字符串 Provides details for server policy creation failure related to system or infrastructure
validationMessages 字符串 Provides details for server policy creation failure related to parameter restrictions

Server Policy Definition

Name Type 描述
serverPolicyId 字符串 Unique Id of the Server Policy
accountPolicyId 字符串 Unique Id of the Account Policy
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored
clcAccountAlias 字符串 The account alias that the Policy belongs to
status 字符串 The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId null Not currently used

Examples

JSON

{
 "status": "PARTIAL",
 "createServerPolicyResponseList": [
  {
  "success": false,
  "error": "Failed to get server information for serverId=UC1BAADTEST01",
  "validationMessages": null,
  "serverPolicy": {
    "serverPolicyId": null,
    "accountPolicyId": null,
    "serverId": "UC1BAADTEST01",
    "storageRegion": "US WEST",
    "clcAccountAlias": "BAAD",
    "status": null,
    "expirationDate": 0,
    "unsubscribedDate": 0,
    "storageAccountId": null
    }
  },
  {
  "success": true,
  "error": null,
  "validationMessages": null,
  "serverPolicy": {
    "serverPolicyId": "80448207-332c-4f95-b82b-ac1fcb87b2c6",
    "accountPolicyId": "193fccfc-c144-4052-98da-145eed825e0a",
    "serverId": "IL1BAADTEST01",
    "storageRegion": "US WEST",
    "clcAccountAlias": "BAAD",
    "status": "PROVISIONING",
    "expirationDate": 0,
    "unsubscribedDate": 0,
    "storageAccountId": null
    }
  }
 ]
}

Create Server Policy

Create a Server Policy under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to create a new Server Policy.

URL

Structure

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

POST https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 The unique Id of an account policy

Content Properties

Name Type 描述 Req.
clcAccountAlias 字符串 The account alias that the Policy belongs to
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored, can be "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC"

Examples

JSON

{
  "clcAccountAlias": "BAAD",
  "serverId": "VA1BAADTEST01",
  "storageRegion": "USEAST",
}

响应

Entity Definition

Name Type 描述
serverPolicyId 字符串 Unique Id of the Server Policy
accountPolicyId 字符串 Unique Id of the Account Policy
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored
clcAccountAlias 字符串 The account alias that the Policy belongs to
status 字符串 The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId null Not currently used

Examples

JSON

{
"serverPolicyId": "085384ce-200e-4205-8a13-ae1d0bdc71cd"
"accountPolicyId": "5fde14a2-fa9d-4376-9f01-59429d02a959"
"serverId": "VA1BAADTEST01"
"storageRegion": "US EAST"
"clcAccountAlias": "BAAD"
"status": "PROVISIONING"
"expirationDate": 0
"unsubscribedDate": 0
"storageAccountId": null
}

Delete Server Policy

Delete a Server Policy under an Account Policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete an existing Server Policy.

URL

Structure

DELETE https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

DELETE https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies/085384ce-200e-4205-8a13-ae1d0bdc71cd

请求

URI Parameters

Name Type 描述 Req.
serverPolicyId 字符串 Unique Id of the Server Policy
accountPolicyId 字符串 Unique Id of the Account Policy

响应

The response will not contain JSON content, but will return the HTTP 204 No Content response upon successful deletion of the server policy. If an invalid account policy or server policy are passed in, a HTTP 404 Not Found response will be returned.

Get All Policies Eligible For ServerId

Returns a list of the backup policies that are eligible to be applied to the specified server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve a list of policies that may be applied to a given server.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/servers/{serverId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/servers/VA1ACMEDEMO01

请求

URI Parameters

Name Type 描述 Req.
serverId 字符串 Unique server name

QueryString Parameters

Name Type 描述 Req.
limit integer Return up to this many results
offset 字符串 Return results starting from this position in the list
sortBy 字符串 Sort the results by the specified field
ascendingSort boolean Sort the sortBy field in ascending order

响应

Entity Definition

Name Type 描述
limit integer The maximum number of results requested
nextOffset integer The next position in the list of results for a subsequent call
offset integer The starting position in the list of results
results Array[Account Policy] An array of the Policies eligible for the specified server
totalCount integer The total number of Policies eligible for the specified server

Account Policy Definition

Name Type 描述
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule 字符串 Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias 字符串 The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId 字符串 The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status 字符串 The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "limit": 2,
  "offset": 0,
  "nextOffset": 2,
  "results": [
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy 1",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/root"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 15,
      "backupIntervalHours": 24,
      "policyId": "284f1801-5f2e-45e0-97d1-a7267ef7a3e8"
    },
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy 2",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/opt"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 7,
      "backupSchedule": "0 0 12 ? * SUN *",
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

Get All Regions

Retrieves a list of backup storage regions which are available in Simple Backup Service. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the list of backup storage regions which are available in Simple Backup Service.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/regions

Example

GET https://api.backup.ctl.io/clc-backup-api/api/regions

响应

Entity Definition

Name Type 描述
messages Array[string] A list of messages associated with the Storage Region
用户名 字符串 The name of the Storage Region
regionLabel 字符串 The label associated with the Storage Region

Examples

JSON

[
  {
    "name": "APAC",
    "regionLabel": "APAC (Singapore)",
    "messages": null
  },
  {
    "name": "GERMANY",
    "regionLabel": "EU (Germany)",
    "messages": null
  },
  {
    "name": "GREAT BRITAIN",
    "regionLabel": "EU (Ireland)",
    "messages": null
  },
  {
    "name": "US EAST",
    "regionLabel": "US East",
    "messages": null
  },
  {
    "name": "US WEST",
    "regionLabel": "US West",
    "messages": null
  },
  {
    "name": "CANADA",
    "regionLabel": "Canada",
    "messages": [
      "Backups stored in this region are NOT encrypted at rest"
    ]
  }
]

Get Datacenter List

Get a list of CLC Data Centers. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of CLC Data Centers.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters

响应

Entity Definition

Name Type 描述
datacenters Array[string] Array of string values corresponding to each datacenter

Examples

JSON

{
  [13]
  0:  "CA1 - Canada (Vancouver)"
  1:  "CA2 - Canada (Toronto)"
  2:  "CA3 - Canada (Toronto)"
  3:  "DE1 - Germany (Frankfurt)"
  4:  "GB1 - Great Britain (Portsmouth)"
  5:  "GB3 - Great Britain (Slough)"
  6:  "IL1 - US Central (Chicago)"
  7:  "NY1 - US East (New York)"
  8:  "SG1 - APAC (Singapore)"
  9:  "UC1 - US West (Santa Clara)"
  10:  "UT1 - US Central (Salt Lake City)"
  11:  "VA1 - US East (Sterling)"
  12:  "WA1 - US West (Seattle)"
}

Get OS Types

Returns the list of valid OS types supported by Simple Backup Service. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the list of supported OS types.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/osTypes

Example

GET https://api.backup.ctl.io/clc-backup-api/api/osTypes

响应

Entity Definition

Name Type 描述
osTypes Array[string] Array of string values corresponding to each supported OS type

Examples

JSON

[
  "Linux",
  "Windows]
]

Get Policies

Gets a list of backup policies associated with an account. Calls to this operation must include a bearer token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve a list of all policies associated with a given account.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies?limit=20&offset=0&withStatus=ACTIVE&sortBy=name&ascendingSort=true

请求

QueryString Parameters

Name Type 描述 Req.
limit integer Return up to this many results
offset 字符串 Return results starting from this position in the list
withStatus 字符串 Filter results for either 'ACTIVE' or 'INACTIVE' Policies
sortBy 字符串 Sort the results by the specified field
ascendingSort boolean Sort the sortBy field in ascending order

响应

Entity Definition

Name Type 描述
limit integer The maximum number of results requested
nextOffset integer The next position in the list of results for a subsequent call
offset integer The starting position in the list of results
results Array[Account Policy] An array of the Policies associated with the Account
totalCount integer The total number of Policies associated with the Account

Account Policy Definition

Name Type 描述
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule 字符串 Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias 字符串 The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId 字符串 The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status 字符串 The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "limit": 2,
  "offset": 0,
  "nextOffset": 2,
  "results": [
    {
      "osType": "Linux",
      "name": "Example Linux Backup Policy",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "/root"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 15,
      "backupIntervalHours": 24,
      "policyId": "284f1801-5f2e-45e0-97d1-a7267ef7a3e8"
    },
    {
      "osType": "Windows",
      "name": "Example Windows Backup Policy",
      "clcAccountAlias": "ACME",
      "status": "ACTIVE",
      "paths": [
        "C:\\backupthisup"
      ],
      "excludedDirectoryPaths": [],
      "retentionDays": 1,
      "backupSchedule": "0 0 12 ? * SUN *",
      "policyId": "18b4bdd3-cbdf-40c5-86bf-3c36b0a060f5"
    }
  ],
  "totalCount": 2
}

Get Policy Details By Server

Get policy details by server. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of policies and policy details for all policies associated with a specified server.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/serverPolicyDetails

Example

GET https://api.backup.ctl.io/clc-backup-api/api/serverPolicyDetails?serverId=VA1BAAPPRDTST01

请求

QueryString Parameters

Name Type 描述 Req.
serverId 字符串 Unique server name
withStatus Array[string] Status of the backup policy. 'ACTIVE','INACTIVE','PROVISIONING','ERROR','DELETED'

响应

Entity Definition

Name Type 描述
accountPolicyId 字符串 Unique ID of an account policy
osType 字符串 'Linux' or 'Windows'
用户名 字符串 The name of the Policy
clcAccountAlias 字符串 The account alias that the Policy belongs to
accountPolicyStatus 字符串 The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'
paths Array[string] A list of the directories that the Policy includes in each backup
backupProvider 字符串 Not currently used
retentionDays integer The number of days backup data will be retained
backupIntervalHours integer The backup frequency of the Policy specified in hours-- ignored if backupSchedule is defined
backupSchedule 字符串 Quartz-flavored CRON string describing the execution schedule for the Policy
serverPolicyId 字符串 Unique server policy identifier
serverId 字符串 Unique server identifier
storageRegion 字符串 Region where backups are stored. "US EAST", "US WEST", "CANADA", "GREAT BRITAIN", "GERMANY", "APAC"
serverPolicyStatus Array[string] Status of the backup policy. 'ACTIVE','INACTIVE','PROVISIONING','ERROR','DELETED'
eligibleForBackup boolean Indicates if the account policy or server policy are active/inactive

Examples

JSON

{
  [2]
  0:  {
  "accountPolicyId": "5323900d-1288-47c8-9cce-e29790c9afbb"
  "osType": "Windows"
  "name": "TestingPolicy_1/12/16"
  "clcAccountAlias": "BAAP"
  "accountPolicyStatus": "ACTIVE"
  "paths": [2]
  0:  "C:\BackupFolder1"
  1:  "C:\BackupFolder12"
  -
  "backupProvider": null
  "retentionDays": 2
  "backupSchedule": "0 0 12 ? * SUN *"
  "serverPolicyId": "6d05d351-9cb8-4fed-bca6-064e3034caeb"
  "serverId": "VA1BAAPPRDTST01"
  "storageRegion": "CANADA"
  "serverPolicyStatus": "ACTIVE"
  "eligibleForBackup": true
  }-
  1:  {
  "accountPolicyId": "16965823-5472-49c1-a38a-727dca9cb7a0"
  "osType": "Windows"
  "name": "C Drive"
  "clcAccountAlias": "BAAP"
  "accountPolicyStatus": "ACTIVE"
  "paths": [1]
  0:  "C:\"
  -
  "backupProvider": null
  "retentionDays": 21
  "backupIntervalHours": 2
  "serverPolicyId": "f37088d7-22ba-4704-ba61-25ecd2e8a086"
  "serverId": "VA1BAAPPRDTST01"
  "storageRegion": "US EAST"
  "serverPolicyStatus": "ACTIVE"
  "eligibleForBackup": true
  }
}

Get Policy

Gets the backup policy associated with the specified accountPolicyId. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to retrieve the details of a specific backup policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/4ca70660-f08a-407b-830d-e8e9c6c1d59a

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 The unique id associated with the backup policy to retrieve

响应

Entity Definition

Name Type 描述
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule 字符串 Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias 字符串 The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId 字符串 The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status 字符串 The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var"
  ],
  "excludedDirectoryPaths": [
    "/var/run"
  ],
  "retentionDays": 5,
  "backupSchedule": "0 0 12 ? * SUN *",
  "policyId": "4ca70660-f08a-407b-830d-e8e9c6c1d59a"
}

Get Restore Point Details

Gets a list of restore point details. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to obtain restore point details for a specific serverPolicyId.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}/restorePointDetails

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc/restorePointDetails?backupFinishedStartDate=2016-01-01&backupFinishedEndDate=2016-04-01

请求

URI Parameters

Name Type 描述 Req.
serverPolicyId 字符串 Unique Id of the Server Policy
accountPolicyId 字符串 Unique Id of the Account Policy

QueryString Parameters

Name Type 描述 Req.
limit integer Limit the number of records returned
offset integer
inRetentionOnly boolean
backupFinishedStartDate 字符串 Valid date format is 'YYYY-MM-DD'
backupFinishedEndDate 字符串 Valid date format is 'YYYY-MM-DD'
sortBy 字符串 Sort results by: [policyId, retentionDay, backupStartedDate, backupFinishedDate, retentionExpiredDate, backupStatus, filesTransferredToStorage, bytesTransferredToStorage, filesFailedTransferToStorage, bytesFailedToTransfer, unchangedFilesNotTransferred, unchangedBytesNotTransferred, filesRemovedFromDisk, bytesRemovedFromDisk]
ascendingSort boolean

响应

Entity Definition

Name Type 描述
restorePointId 字符串 Unique restore point identifier
policyId 字符串 Unique policy identifier
retentionDays integer Days of retention applied to the restore point
backupFinishedDate 字符串 Timestamp of backup completion
retentionExpiredDate 字符串 Timestamp or retention expiration
restorePointCreationStatus 字符串 'SUCCESS', 'PARTIAL_SUCCESS', 'FAILED', or 'CANCELLED'
filesTransferredToStorage integer Number of backup files transferred to storage
bytesTransferredToStorage integer Total bytes of backup data sent to storage
filesFailedTransferToStorage integer Number of backup files that failed transfer to storage
bytesFailedToTransfer integer Total bytes of backup data that failed transfer to storage
unchangedFilesNotTransferred integer Number of unchanged files not requiring retransfer to storage
unchangedBytesInStorage integer Total bytes of unchanged data not requiring retransfer to storage
filesRemovedFromDisk integer Number of files removed from local disk
bytesInStorageForItemsRemoved integer Total bytes of data removed from local disk
numberOfProtectedFiles integer Number of files currently in storage for the restore point
backupStartedDate 字符串 Timestamp of backup start

Examples

JSON

{
  "limit": 100
  "offset": 0
  "nextOffset": 0
  "results": [2]
    0:  {
        "restorePointId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc20160401225505"
        "policyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
        "retentionDays": 5
        "backupFinishedDate": "2016-04-01T22:55:10.849Z"
        "retentionExpiredDate": "2016-04-07T22:55:05.277Z"
        "restorePointCreationStatus": "SUCCESS"
        "filesTransferredToStorage": 0
        "bytesTransferredToStorage": 0
        "filesFailedTransferToStorage": 0
        "bytesFailedToTransfer": 0
        "unchangedFilesNotTransferred": 3
        "unchangedBytesInStorage": 388403200
        "filesRemovedFromDisk": 0
        "bytesInStorageForItemsRemoved": 0
        "numberOfProtectedFiles": 3
        "backupStartedDate": "2016-04-01T22:55:05.277Z"
  }
  -1:   {
        "restorePointId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc20160401214505"
        "policyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
        "retentionDays": 5
        "backupFinishedDate": "2016-04-01T21:45:10.802Z"
        "retentionExpiredDate": "2016-04-07T21:45:05.261Z"
        "restorePointCreationStatus": "SUCCESS"
        "filesTransferredToStorage": 0
        "bytesTransferredToStorage": 0
        "filesFailedTransferToStorage": 0
        "bytesFailedToTransfer": 0
        "unchangedFilesNotTransferred": 3
        "unchangedBytesInStorage": 388403200
        "filesRemovedFromDisk": 0
        "bytesInStorageForItemsRemoved": 0
        "numberOfProtectedFiles": 3
        "backupStartedDate": "2016-04-01T21:45:05.261Z"
  }
  "totalCount": 2
}

Get Server Policies

Gets a list of Server Policies associated to an Account Policy. A server policy is unique record that ties a backup (account) policy to a specific server and storage region. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of all Server Policies attached to an Account Policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/5fde14a2-fa9d-4376-9f01-59429d02a959/serverPolicies

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 Unique Id of the Account Policy

QueryString Parameters

Name Type 描述 Req.
accountPolicyId 字符串 Unique ID of an account policy
limit integer Return up to this many results
offset 字符串 Return results starting from this position in the list
withStatus 字符串 Filter results for either 'ACTIVE' or 'INACTIVE' Policies
sortBy 字符串 Sort the results by the specified field
ascendingSort boolean Sort the sortBy field in ascending order

响应

Entity Definition

Name Type 描述
limit integer The maximum number of results requested
offset integer The starting position in the list of results
nextOffset integer The next position in the list of results for a subsequent call
results Array[Server Policy] An array of the Server Policies associated with the Account Policy
totalCount integer The total number of Server Policies associated with the Account Policy

Server Policy Definition

Name Type 描述
serverPolicyId 字符串 The next position in the list of results for a subsequent call
accountPolicyId 字符串 Unique Id of the Account Policy
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored
clcAccountAlias 字符串 The account alias that the Policy belongs to
status 字符串 The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId 字符串 Not currently used

Examples

JSON

  {
  "limit": 1000
  "offset": 0
  "nextOffset": 0
  "results": [1]
      0:  {
          "serverPolicyId": "7796a750-db6a-4d6d-a9c0-93f729e9977e"
          "accountPolicyId": "5fde14a2-fa9d-4376-9f01-59429d02a959"
          "serverId": "VA1BAADTEST01"
          "storageRegion": "US EAST"
          "clcAccountAlias": "BAAD"
          "status": "ACTIVE"
          "expirationDate": 0
          "unsubscribedDate": 0
          "storageAccountId": "f5c2c756-94b6-4b74-92e9-60f648caed15"
          }
  "totalCount": 1
  }

Get Server Policy

Get details of a specific server policy associated to an account policy. A server policy is unique record that ties a backup (account) policy to a specific server and storage region. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get details for a specific server policy. Use the getServerPolicies API to obtain details for all server policies associated with an account policy.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 Unique ID of an account policy
serverPolicyId 字符串 Unique Id of the Server Policy

响应

Entity Definition

Name Type 描述
serverPolicyId 字符串 Unique Id of the Server Policy
accountPolicyId 字符串 Unique Id of the Account Policy
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored
clcAccountAlias 字符串 The account alias that the Policy belongs to
status 字符串 The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED', 'PENDING_INSTALL'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId 字符串 Not currently used

Examples

JSON

{
  "serverPolicyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
  "accountPolicyId": "c8cbf556-9ea1-4759-8d4e-c788198af26c"
  "serverId": "IL1BAAPDEMO101"
  "storageRegion": "US WEST"
  "clcAccountAlias": "BAAP"
  "status": "ACTIVE"
  "expirationDate": 0
  "unsubscribedDate": 0
  "storageAccountId": null
}

Get Servers By Datacenter

Get a list of servers based on CLC Data Center. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to get a list of servers associated with a CLC Data Center.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api//api/datacenters/{datacenter}/servers

Example

GET https://api.backup.ctl.io/clc-backup-api/api/datacenters/VA1%20-%20US%20East%20(Sterling)/servers

请求

URI Parameters

Name Type 描述 Req.
datacenter 字符串 CLC Data Center

响应

Entity Definition

Name Type 描述
list Array[string] Array of string values corresponding to each server

Examples

JSON

{
  [3]
  0:  "VA1BAAPXAMPLE01"
  1:  "VA1BAAPXAMPLE02"
  2:  "VA1BAAPXAMPLE03"
}

Get Stored Data By Server Policy

Gets the amount of stored data for a server policy on a specified date. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to determine the amount of backed up data in storage for a server on a specific day.

URL

Structure

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}/storedData

Example

GET https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc/storedData?searchDate=2016-03-29

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 Unique account policy identifier
serverPolicyId 字符串 Unique server policy identifier

QueryString Parameters

Name Type 描述 Req.
searchDate 字符串 Valid date format is 'YYYY-MM-DD'

响应

Entity Definition

Name Type 描述
gigabytesStored 字符串 Amount of stored backup data in gigabytes
bytesStored 字符串 Amount of stored backup data in bytes

Examples

JSON

{
  "gigabytesStored": "0.541"
  "bytesStored": "581560320"
}

Patch Policy

Updates specific values of a server policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Because of the business rules that apply to this product, there are limited scenarios when this operation is allowed. Specifically, you may use this API operation when you want to change the status of a server policy from 'ERROR', 'PENDING_INSTALL', or 'PROVISIONING' to 'INACTIVE'. Other attempts to modify the server policy will result in errors.

URL

Structure

PATCH https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}/serverPolicies/{serverPolicyId}

Example

PATCH https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/c8cbf556-9ea1-4759-8d4e-c788198af26c/serverPolicies/ce0eefe2-25b8-4320-ba68-eeda76aef2dc

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 Unique ID of an account policy
serverPolicyId 字符串 Unique Id of the Server Policy

Content Properties

Name Type 描述 Req.
op 字符串 The patch operation to perform: 'add', 'remove', 'replace'
path 字符串 The only change allowed currently is to the status. Valid transitions are: ERROR to INACTIVE, PENDING_INSTALL to INACTIVE, and PROVISIONING to INACTIVE
value 字符串 The new value to set path to.

Examples

JSON

{
  "op": "replace",
  "path": "/status",
  "value": "INACTIVE"
}

响应

Entity Definition

Name Type 描述
serverPolicyId 字符串 Unique Id of the Server Policy
accountPolicyId 字符串 Unique Id of the Account Policy
serverId 字符串 Unique server name
storageRegion 字符串 Region where backups are stored
clcAccountAlias 字符串 The account alias that the Policy belongs to
status 字符串 The status of the backup Policy. 'ACTIVE', 'INACTIVE', 'PROVISIONING', 'ERROR', 'DELETED'
expirationDate integer Date all data retention will elapse; unsubscribedDate+retentionDays
unsubscribedDate integer Date policy was inactivated
storageAccountId 字符串 Not currently used

Examples

JSON

{
  "serverPolicyId": "ce0eefe2-25b8-4320-ba68-eeda76aef2dc"
  "accountPolicyId": "c8cbf556-9ea1-4759-8d4e-c788198af26c"
  "serverId": "IL1BAAPDEMO101"
  "storageRegion": "US WEST"
  "clcAccountAlias": "BAAP"
  "status": "ACTIVE"
  "expirationDate": 0
  "unsubscribedDate": 0
  "storageAccountId": null
}

Update Policy

Updates a backup policy. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the settings of a backup policy. It can be used to modify the name, frequency, paths to include, and paths to exclude. Operating System and Retention may not be modified.

URL

Structure

PUT https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/{accountPolicyId}

Example

PUT https://api.backup.ctl.io/clc-backup-api/api/accountPolicies/107e6129-46b6-4b01-afcc-ea733db37214

请求

URI Parameters

Name Type 描述 Req.
accountPolicyId 字符串 The unique id associated with the backup policy to update

Content Properties

Name Type 描述 Req.
backupIntervalHours integer The backup frequency of the Policy specified in hours -- ignored if backupSchedule is defined Yes1
backupSchedule 字符串 Quartz-flavored CRON expression describing the execution schedule for backups Yes1
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId 字符串 The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status 字符串 'ACTIVE' or 'INACTIVE'

1One of either the backupIntervalHours field OR the backupSchedule field is required. If backupSchedule is defined, it will be used and backupIntervalHours will be ignored.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var",
    "/srv",
    "/etc",
    "/home",
    "/usr"
  ],
  "excludedDirectoryPaths": [
    "/var/run",
    "/var/cache",
    "/var/tmp"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "backupSchedule": "0 0 12 ? * TUE *",
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

响应

Entity Definition

Name Type 描述
backupIntervalHours integer The backup frequency of the Policy-- ignored if backupSchedule is defined
backupSchedule 字符串 Quartz-flavored CRON string describing the execution schedule for the Policy
clcAccountAlias 字符串 The account alias that the Policy belongs to
excludedDirectoryPaths Array[string] A list of the directories that the Policy excludes from backup
用户名 字符串 The name of the Policy
osType 字符串 'Linux' or 'Windows'
paths Array[string] A list of the directories that the Policy includes in each backup
policyId 字符串 The unique Id associated with the Policy
retentionDays integer The number of days backup data will be retained
status 字符串 The status of the backup Policy. Either 'ACTIVE' or 'INACTIVE'.

Examples

JSON

{
  "osType": "Linux",
  "name": "Example Backup Policy from API",
  "clcAccountAlias": "ACME",
  "status": "ACTIVE",
  "paths": [
    "/var",
    "/srv",
    "/etc",
    "/home",
    "/usr"
  ],
  "excludedDirectoryPaths": [
    "/var/run",
    "/var/cache",
    "/var/tmp"
  ],
  "retentionDays": 7,
  "backupIntervalHours": 12,
  "backupSchedule": "0 0 12 ? * TUE *",
  "policyId": "107e6129-46b6-4b01-afcc-ea733db37214"
}

Add Webhook Target Uri

Add a target uri to the webhook for a specified event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to add a uri to the collection of targetUris in a webhook.

URL

Structure

POST https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration/targetUris

Example

POST https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration/targetUris

请求

Uri Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
Event 字符串 The name of the webhook event being configured

Content Properties

Name Type 描述 Req.
targetUri 字符串 A uri that will be called when the event occurs

Examples

JSON

{ targetUri: "https://test.api/account/created" }

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

配置Webhooks和消费通知

描述

Webhooks make it possible to subscribe to key events that occur in the CenturyLink Cloud. In this article, we will walk through how to create a Webhook listener, configure a Webhook, and receive a notification. For general details on Webhooks, read the Webhook FAQ.

Prerequisites

  • Must have a CenturyLink Cloud account
  • Must be able to deploy applications to an internet-facing location that has legitimate SSL certificates

Detailed Steps

Build the Webhook Listener

Webhook Listener是一款可通过HTTP POST接收JSON消息的网络应用。 A working example application written in Node.js can be downloaded from GitHub. When designing a Webhook listener, consider the following activities:

  1. 决定订阅哪些活动。 Webhooks support Account, Alert, User, and Server events.

  2. Process HTTP POST requests. In the example Node.js application, this is done in the app.js file.

    app.post('/webhook/account', function(req, res){

    //extract the signature header
    var signatureHeader = req.get('Tier3-RsaSha1');

    //call function to send webhook data to client browser
    BroadcastAccountWebhook(req.body, signatureHeader);

    //send OK response to CenturyLink Cloud
    res.send("ok");

    })

  3. Handle the payload for each message type. In the example project, this is done in a client-side JavaScript file and the entire payload is shown to the user. A listener application that uses typed object definitions must be able to deserialize the JSON structures. Examples of each payload type can be found in the Webhooks FAQ.

Deploy the Webhook Listener

  1. Webhooks must be deployed to an internet-facing location that is reachable by the CenturyLink Cloud platform.

  2. Identify a host (public cloud IaaS, public cloud PaaS, or on-premises data center) with a valid (not self-signed) SSL certificate.

  3. Deploy the application and ensure that it's reachable. For this demonstration, the listener was deployed to a non-CenturyLink Cloud public Cloud Foundry environment hosted by Pivotal.
    Webhooks示例应用程序

Configure a Webhook in the CenturyLink Cloud

  1. Go to the CenturyLink Control Portal, log in, and select the API option from the navigation menu.
    Control Portal Menu - API

  2. Switch to the Webhooks sub-tab and review the list of available Webhooks. You can configure unique endpoints for each individual Webhook. 在下方图片中,请注意,账户Updated Webhook was set with the URL to the listener web application. A Webhook will respond to events that occur in sub-accounts if the "include sub-accounts" checkbox is selected.
    Webhooks配置

  3. Click Save when the configuration is complete.

  4. Add Webhook URLs for any other Webhooks of interest.

Test the Webhook

  1. 在平台中触发Webhook将响应的活动。 View the Webhook FAQ for a list of what platform events will trigger a Webhook notification.如要让以上配置的账户更新 Webhook启动,请更改邮寄地址等账户设置。
    更新账户信息

  2. Save the account change. Within seconds, the Webhook listener service should receive the notification message. 在示例应用程序中,此信息被推送至浏览器。 Clicking on the updated account's name reveals both the full payload and the hashed signature value.
    更新账户信息

Verifying the Webhook Signature

Each Webhook notification includes a signature attached in the Tier3-RsaSha1 header. This signature is generated by creating a SHA-1 hash from the JSON payload and encrypting it with an RSA private key. It can be verified by following these steps:

  • Generate a SHA-1 hash from the message body
  • Decrypt the signature using CenturyLink Cloud's public key (which can be found in the Webhook FAQ)
  • Compare these two values and confirm they are equal. If they're not, the message did not come from CenturyLink Cloud.

Though someone trying to be malicious may change the JSON message, they will not be able to get the correct signature to match up without the use of the private key. This confirms that the message indeed came from CenturyLink Cloud and not someone spoofing or tampering with the message in-flight.

Notice in the screenshot above that under the hashed signature value, there is a VERIFIED message in green. This is because the example application performs this verification and outputs the results. In the code above for the account Webhook handler, we retrieve the signature from the Tier3-RsaSha1 header. Later in the code, we verify the signature

function VerifySignature(data, signatureHeader) {
  var publicKey = fs.readFileSync(path.resolve(__dirname, 'public.pem')).toString();
  var key = new rsa(publicKey, 'pkcs8-public-pem', {"signingScheme":"sha1"});
  return key.verify(data, signatureHeader, 'utf8', 'base64');
}

If this verification failed because the message was tampered with or came from someone else, the following message would appear. Notice the message matches the one above, but signature does not.

更新账户信息

Delete Webhook Target Uri

Delete a target uri from a webhook. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete a single target uri from a particular webhook.

URL

Structure

DELETE https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration/targetUris?targetUri={uri}

Example

DELETE https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration/targetUris?targetUri=https%3A%2F%2Ftest.api%2Faccount%2Fcreated

请求

Uri Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
Event 字符串 The name of the event from which the target uri will be deleted
targetUri 字符串 The uri that will be removed

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Delete Webhook

Delete a webhook for an event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to delete the webhook for an event. This will delete all the targetUris for the specified event.

URL

Structure

DELETE https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration

Example

DELETE https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration

请求

Uri Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
Event 字符串 The name of the event for which the webhook will be deleted

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Get Webhooks

Gets the details on the configured webhooks. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to discover all the webhooks that have been configured for every available event and get links to operations for modifying those webhooks.

URL

Structure

GET https://api.ctl.io/v2/webhooks/{accountAlias}

Example

GET https://api.ctl.io/v2/webhooks/ALIAS

请求

Uri Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account

响应

Webhook Collection Entity Definition

Name Type 描述
items Webhook[] A list of webhooks, one per available event

Webhook Entity Definition

Name Type 描述
用户名 字符串 The name of the event that triggers the webhook
configuration 配置 Details about the webhook handling the event

Configuration Entity Definition

Name Type 描述
recursive boolean If true, the webhook will be called when the event occurs in a sub-accounts
targetUris TargetUri[] The list of targets to be called when the event occurs

TargetUri Entity Definition

Name Type 描述
targetUri 字符串 A uri that will be called when the event occurs

Examples

JSON

{
  "items": [
    {
      "name": "Account.Created",
      "configuration": {
        "recursive": false,
        "targetUris": [
          {
            "targetUri": "https://uri.test/account/created"
          },
          {
            "targetUri": "https://api.test/account/created"
          }
        ]
      },
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Account.Deleted",
      "configuration": {
        "recursive": false,
        "targetUris": [
          {
            "targetUri": "https://api.test/account/deleted"
          }
        ]
      },
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Account.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Account.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Alert.Notification",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Alert.Notification/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Created",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Deleted",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "Server.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/Server.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Created",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Created/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Deleted",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Deleted/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    },
    {
      "name": "User.Updated",
      "links": [
        {
          "rel": "configuration",
          "href": "/v2/webhooks/RJP/User.Updated/configuration",
          "verbs": [
            "DELETE",
            "PUT"
          ]
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/v2/webhooks/RJP"
    }
  ]
}

Set Webhook

Change the configuration of a webhook for a specific event. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

When to Use It

Use this API operation when you want to change the configuration of a webhook including the uris that get called when the event occurs and whether the uris are called when the event occurs in a sub-account.

URL

Structure

PUT https://api.ctl.io/v2/webhooks/{accountAlias}/{event}/configuration

Example

PUT https://api.ctl.io/v2/webhooks/ALIAS/Account.Created/configuration

请求

Uri Parameters

Name Type 描述 Req.
AccountAlias 字符串 Short code for a particular account
Event 字符串 The name of the webhook event being configured

Content Properties

Name Type 描述 Req.
recursive boolean If true, the webhook will be called when the event occurs in a sub-accounts
targetUris TargetUri[] The targets called when the event occurs

TargetUri Entity Definition

Name Type 描述 Req.
targetUri 字符串 A uri that will be called when the event occurs

Examples

JSON

{
  recursive: true,
  targetUris: [
    { targetUri: "https://test.uri/account/created" },
    { targetUri: "https://test.api" }
  ]
}

响应

The response will not contain JSON content, but should return the HTTP 204 No Content response upon making the changes successfully.

Webhooks FAQ

描述

The CenturyLink Cloud supports Webhooks which send push notifications to an HTTP endpoint specified by the customer. This FAQ addresses commonly asked questions about the service. For a walkthrough of how to use Webhooks, see Configuring Webhooks and Consuming Notifications.

Q: What exactly is a Webhook?

A: Webhooks make it possible to create push notification solutions. Platform events (e.g. "server created") are sent in real-time to a web endpoint configured for the Webhook. Whenever an event occurs, a JSON message is sent as an HTTP POST request.

Q: Did CenturyLink Cloud invent the idea of Webhooks?

A: No, but we're among the first to use it in an IaaS cloud. Webhooks are in use today for a variety of web properties including Wordpress, Trello, and Zoho. CenturyLink Cloud sees value in embracing this model for public cloud customers who want to be more responsive to changes in their cloud account.

Q: In what scenario would I use a Webhook?

A: We've identified numerous use cases where Webhooks can replace or augment the components of existing processes:

  • Replace polling-based synchronization solutions. Customers often use request-response API operations to retrieve data about their assets in the CenturyLink Cloud. However, polling is fairly inefficient as the caller is simply asking "Do you have anything for me?" over and over again. With Webhooks, there's no longer a need to poll for changes. Instead, the CenturyLink Cloud immediately tells customers whenever key events occur in the platform.
  • Perform real-time data analytics. Customers can use this data to assess their cloud usage. For resellers, Webhooks provide an opportunity to observe server provisioning and detect trends. They could use it to watch for fraudulent signup scenarios my detecting abnormal combinations of account creation and server provisioning.
  • Monitor activities with security, compliance implications. For customers who closely govern their cloud usage, Webhooks provide the opportunity to immediately see what users are doing. Whether adding public IP addresses, or creating new user accounts, customers can quickly monitor and respond to activities that are counter to company policies.

Q: What triggers a Webhook?

A: There are currently Webhooks for four major categories: Accounts, Users, Alerts, and Servers.

  • Accounts. Triggered on account creation and deletion. Triggered on account changes including account status, business name, address, telephone, fax, and time zone.
  • Users. Triggered on user creation and deletion. Triggered on user changes including user status, password, security PIN, email address, alternative email address, first name, last name, title, office number, mobile number, fax number, time zone.
  • Alerts. Triggered when a user-defined alert policy threshold is exceeded, and when the server returns to a utilization level below the alert policy threshold.
  • Servers. Triggered on server creation and deletion. Triggered on server changes including server archive, server restore, convert to template, convert from template, add/delete/edit disks, edit CPU, edit memory, assigned Group, description, add/remove IP addresses, power on/off, and shutdown.

Q: What data is sent in the Webhook event notification?

A: Some push notification systems only send a bare minimum of information and ask the user to call-back for the full data payload. CenturyLink Cloud Webhooks send a full JSON-encoded payload AND include a URL to the referenced resource.

The Account event payload:

{
  "addressLine1": "112 112th Ave NE",
  "addressLine2": "Ste 300",
  "city": "Bellevue",
  "stateProvince": "WA",
  "country": "USA",
  "postalCode": "98004",
  "telephone": "800-buy-cloud",
  "status": "Active",
  "isManaged": true,
  "links": [
    {
      "rel": "self",
      "href": "/v2/accounts/DEMO"
    },
    {
      "rel": "parentAccount",
      "href": "/v2/accounts/T3N"
    }
  ],
  "accountAlias": "DEMO",
  "businessName": "Seroter Industries",
  "parentAlias": "T3N",
  "primaryDataCenter": "WA1"
}

The User event payload:

{
  "uri": "/v2/users/demo@user.com",
  "accountUri": "/v2/accounts/DEMO",
  "accountAlias": "DEMO",
  "userName": "demo@user.com",
  "emailAddress": "demo@user.com",
  "firstName": "Richard",
  "lastName": "Seroter",
  "status": "Active"
}

The Server event payload:

{
  "id": "WA1DEMOSERVER01",
  "name": "WA1DEMOSERVER01",
  "description": "My web server",
  "groupId": "2a5c0b9662cf4fc8bf6180f139facdc0",
  "isTemplate": false,
  "locationId": "WA1",
  "osType": "Windows 2008 64-bit",
  "status": "active",
  "details": {
    "ipAddresses": [
      {
        "internal": "10.81.123.11"
      },
      {
        "public": "74.41.155.112",
        "internal": "10.81.123.14"
      }
    ],
    "alertPolicies": [
      {
        "id": "45866e6219e84ab786d07d4f570ba960",
        "name": "Production Web Servers - RAM",
        "links": [
          {
            "rel": "self",
            "href": "/v2/alertPolicies/DEMO/45866e6219e84ab786d07d4f570ba960"
          },
          {
            "rel": "alertPolicyMap",
            "href": "/v2/servers/DEMO/WA1DEMOSERVER01/alertPolicies/45866e6219e84ab786d07d4f570ba960",
            "verbs": [
              "DELETE"
            ]
          }
        ]
      }
    ],
    "cpu": 1,
    "diskCount": 1,
    "inMaintenanceMode": false,
    "memoryMB": 4096,
    "powerState": "started",
    "storageGB": 50,
    "disks": [
      {
        "id": "0:0",
        "sizeGB": 50,
        "partitionPaths": []
      }
    ],
    "partitions": [],
    "snapshots": [],
    "customFields": [
      {
        "id": 22,
        "name": "Cost Center",
        "value": "IT-DEV",
        "displayValue": "IT-DEV"
      },
      {
        "id": 237,
        "name": "CMDB ID",
        "value": "1100003",
        "displayValue": "1100003"
      }
    ]
  },
  "type": "standard",
  "storageType": "standard",
  "changeInfo": {
    "createdBy": "demo@user.com",
    "createdDate": "2012-12-17T01:17:17Z",
    "modifiedBy": "demo@user.com",
    "modifiedDate": "2014-06-18T18:28:54Z"
  },
  "links": [
    {
      "rel": "self",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01",
      "id": "WA1DEMOSERVER01",
      "verbs": [
        "GET",
        "PATCH",
        "DELETE"
      ]
    },
    {
      "rel": "group",
      "href": "/v2/groups/DEMO/2a5c0b9662cf4fc8bf6180f139facdc0",
      "id": "2a5c0b9662cf4fc8bf6180f139facdc0"
    },
    {
      "rel": "account",
      "href": "/v2/accounts/DEMO",
      "id": "demo"
    },
    {
      "rel": "billing",
      "href": "/v2/billing/DEMO/serverPricing/WA1DEMOSERVER01"
    },
    {
      "rel": "statistics",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/statistics"
    },
    {
      "rel": "scheduledActivities",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/scheduledActivities"
    },
    {
      "rel": "publicIPAddresses",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/publicIPAddresses",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "alertPolicyMappings",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/alertPolicies",
      "verbs": [
        "POST"
      ]
    },
    {
      "rel": "antiAffinityPolicyMapping",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/antiAffinityPolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "cpuAutoscalePolicyMapping",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/cpuAutoscalePolicy",
      "verbs": [
        "DELETE",
        "PUT"
      ]
    },
    {
      "rel": "capabilities",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/capabilities"
    },
    {
      "rel": "credentials",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/credentials"
    },
    {
      "rel": "publicIPAddress",
      "href": "/v2/servers/DEMO/WA1DEMOSERVER01/publicIPAddresses/74.41.155.112",
      "id": "74.41.155.112",
      "verbs": [
        "GET",
        "PUT",
        "DELETE"
      ]
    }
  ]
}

*Note that server delete events will only contain the accountAlias and name fields as the server has been deleted and any other information is no longer available.

The Alert event payload:

{
  "accountAlias": "DEMO",
  "serverName": "WA1DEMOSERVER01",
  "triggers": [
    {
      "data": {
        "cpu": 2,
        "cpuPercent": 39.34
      },
      "duration": "00:05:00",
      "metric": "cpu",
      "stateEndTime": "2014-06-18T18:23:46Z",
      "stateStartTime": "2014-06-18T18:20:00Z",
      "state": "notTriggered"
    }
  ]
}

Q: Where do I go to set a Webhook?

A: Webhooks are available at the Account-level under the API menu. There is now a sub-menu called "Webhooks." Customers can set a target URL for each Webhook event listed. Webhooks配置

Q: Can notifications be sent for events that occur within sub-accounts?

A: Yes. For each individual Webhook event, customers can specify whether they want sub-account events to ALSO be sent to the designated endpoint. If a parent account has the "include sub-accounts" checkbox selected, and a sub-account has specified their own Webhook endpoint for the same event, then a copy of the event notification is sent to both endpoints

Q: Are there any requirements for the service that receives the Webhook notification?

A: All Webhook listener services must support secure HTTP transport via HTTPS. The data transmitted in the event may be sensitive and shouldn't travel over unprotected channels. Secondly, listener services must be on the public internet in a location reachable by the CenturyLink CLoud platform. If a customer plans on consuming this data within an internal system, consider using a reverse proxy or another mechanism to forward traffic from a public-facing web service to an internal system.

Q: How can listener services be sure that it was CenturyLink Cloud that sent the message and not someone spoofing you?

A: While SSL ensures that the message cannot be read in transit, it doesn't protect you from rogue callers who target your public endpoint. Each Webhook notification includes a signature hash of the message payload. The Tier3-RsaSha1 header is signed with our private key, leveraging the JSON payload as input. This signature can be verified with the following public key and the received JSON body. Customers can use this process to ensure that the message wasn't tampered with. For more details and sample code on how to verify the signature, see Configuring Webhooks and Consuming Notifications.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnmwsVLJ22Y8lmnk+1fI/
JKkm4bM1GvggI7DN10KIoPDgBbNcePZqcFayDdmVuq/jL9MFBrqFSfVszgdq8OWF
G9lEB5vP29K/N+0kRg5V2NDXddI5AOzx6jDjkNM/jjb45UXeDcPzMMdMOl/ds6uT
p6mbfG3U8dWqM/if7mzjEbbhYkBM3OuacEFk38Tkm49IJ4jHnC0p9qWO2iaxJqRc
08M2cJ+yKcFudCVKX8ANE6g6YKK+5aSabxfHX83Vjr4I0kpqo0cfP4aSW/CPDUZ7
yR4bFiy5Wv2de2V+FOGVBQF+/viSzrtrwQjUOJViuxEnifc06xuDF0QFta9anz4d
LQIDAQAB
-----END PUBLIC KEY-----

Q: How soon after an event occurs does a Webhook notification get sent?

A: As soon as the event occurs in the CenturyLink Cloud platform, it is routed through our messaging infrastructure and sent to each Webhook endpoint. In reality, this means that messages are often received within 5 seconds of the event occurring.

Q: What happens if the destination is unreachable?

A: There is no guaranteed delivery with CenturyLink Cloud Webhooks. We make a single attempt to send a message to the designated endpoint and if it fails, it is not retried. This means two things: (1) design your endpoints to be highly available and withstand failures of any single component in the solution, and (2) rely on a combination of Webhooks and daily web service API calls to ensure that your local repositories stay in sync.

Q: Are there more Webhooks on the way?

A: Yes! We have ideas for additional Webhooks to add to the platform, but would like to hear from you. If you have suggestions for other Webhooks, send an email to features@ctl.io.