SoftLayer API 概述

SoftLayer 的应用程序编程接口 (API) 是开发接口,使开发人员和系统管理员能够与 SoftLayer 的后端系统直接交互。通过使用我们 API 所公开的功能,用户可以执行远程服务器管理,还可以监控和检索 SoftLayer 的各个系统(如记帐系统、库存系统和 DNS)中的信息。我们的 API 支持 SoftLayer 客户门户网站中的许多功能,这通常意味着,如果此“客户门户网站”中能够进行某种交互,那么我们的 API 中同样可以进行这种交互。

谁应该使用此 API?

SoftLayer API (SLAPI) 向所有 SoftLayer 客户提供,并且不收取额外的费用。我们鼓励那些具有面向对象程序设计基本知识的客户充分利用 SLAPI 提供的功能。虽然 SoftLayer 客户可使用 SLAPI 来完成各种任务,但是在 API 内部以编程方式与 SoftLayer 环境的所有部分进行交互的能力,使大多数使用 SLAPI 的客户能够自动完成任务。

使用 SoftLayer API

在开始之前

SLAPI 使用户能够与运行“客户门户网站”的对象直接交互。在面向 SLAPI 进行开发之前,了解一些面向对象程序设计的基本概念(如对象、属性、方法和继承)是非常有益的。SLAPI 的方法是针对后端系统中的服务对象运行的,可返回特定于
SoftLayer 的数据类型对象以及标准数据类型(如整数、布尔值和字符串)。
SLAPI 是一个远程过程调用系统。每个调用都涉及向 API 端点发送数据以及接收所返回的结构化数据。通过 SLAPI 发送和接收数据时所使用的格式将取决于您所选择的 API 实现。SLAPI 当前使用 SOAPXML-RPCREST 进行数据传输。
在发出 API 调用之前,了解一下如何在编程语言或脚本语言中使用这些协议对您非常有帮助。您可以在应用中使用任何实现。我们还提供了大量特定于服务的 API 客户端,这些客户端可使用 github 档案内支持的各种语言。

创建 API 用户

通过“客户门户网站”帐户来认证对 SLAPI 的每一个调用。“客户门户网站”上的帐户可能包含多个用户,强烈建议您创建唯一的“客户门户网站”用户来运行 API 调用。无论您是自己开发应用还是使用由他人开发的基于 API 的应用,您都必须在程序内进行认证,才能访问有关您帐户的信息并与帐户的各个方面进行交互。向 SLAPI 的认证需要“客户门户网站”用户名和 API 密钥,以及为 API 方法调用保留的专用认证令牌。API 调用中会反映出“客户门户网站”中定义的用户权限。

选择公用或专用网络

SLAPI 端点服务器存在于 SoftLayer 的公用和专用网络上。基于 API 的应用可从因特网上的任一台主机进行连接,但是,SoftLayer 的专用网络提供了额外的数据安全层。此外,SoftLayer 还提供了各种专用网络 API 端点,这些端点只能在连接到专用网络时访问。所有与 SoftLayer 帐户关联的服务器和云计算主机都可以直接连接到专用网络,而无需进行额外认证。如果您要使用另一台设备上的专用端点,那么需要与专用网络建立 VPN 连接。

基本 API 概念

服务

服务是与内部 SoftLayer 系统相关联的端点。每一个服务都是方法与可执行操作的集合。此站点的参考部分中提供了所有 SLAPI 服务的列表。
访问所需 API 的“服务”部分时,屏幕左侧会显示所有可用服务的列表。所有 SoftLayer 服务均以“SoftLayer_”开头,后跟用于定义服务所提供的通用功能的其他词汇:“Hardware”、“
Account”、“Billing”或“Network”等。每个服务都是从此处开始扩展,后跟用于定义服务专有功能(属于该特定子集)的名称。与 SoftLayer API 关联的每个服务都具有唯一的名称。虽然有些服务(如 SoftLayer_Account 和
SoftLayer_Account_Address)可能共享同一前缀,但是其交互方式不一定相似,而且名称相似的服务之间并没有直接继承关系。因此,每一个服务都应该单独处理。
要查看特定服务的详细信息,请单击此服务名称。每个服务的页面都包含可供此服务使用的方法列表,许多页面中还包含一个简介部分来说明服务。虽然每个服务会提供一组特有的方法,但是许多服务都会提供 getObject 方法。这些方法可用于从 API 检索同一类型的对象。例如,调用
SoftLayer_Network_Subnet 服务的 getObject 方法,将返回 SoftLayer_Network_Subnet 数据类型对象。

方法

方法是可对 SLAPI 服务执行的一项特定操作。每个方法都会返回标量或结构化数据类型,并可能需要特定的参数、权限或头才能运行。应当按照每种语言或每个端点的文档中所述的方式来传递方法参数。在需要多个参数的情况下,参数的传递顺序与其在“方法”页面上显示的顺序相同(从上至下)。以下截屏显示了 SoftLayer_Monitoring_Agent::getGraph 方法的必需参数。运行该方法时,请按以下顺序传递参数:configurationValues、beginDate、
endDate。
NOT FOUND: parameters.png
每个“方法”页面上都会提供参数、权限和头的完整列表。

数据类型

数据类型是包含一系列标量值及其他数据类型的结构。除了传统标量值(如字符串、布尔值或整数)外,SLAPI 还使用复杂数据类型,复杂数据类型包含一些属性来用于定义与
SLAPI 内的方法之间传递和返回的对象。每种数据类型都可能包含一些本地关系计数属性。

本地属性

本地属性是数据类型的直接子代。调用 getObject() 时,通常会返回本地属性。在调用 createObject() 期间创建此数据类型的实例时,需要使用一些(不是全部)本地属性。

关系属性

关系属性是数据类型的间接子代。关系属性是在其他数据类型或其属性中定义的。例如,SoftLayer_Account 数据类型具有一个表示硬件的关系属性。此关系属性是 SoftLayer_Hardware 数据类型的数组。点击对象掩码时,该属性将返回一个数组,此数组针对帐户上的每台硬件设备都包含一个 SoftLayer_Hardware 对象。

计数属性

计数属性是一个很有用的属性,可用于确定与属性关联的对象的总数。例如,可以通过使用对象掩码,利用所包含的 Softlayer_Hardware_Server->networkVlanCount 来检索与特定服务器相关联的 VLAN 的总数。

高级 API 概念

除了典型的创建、读取、更新和删除操作外,SLAPI 还允许开发人员定义如何使用专用的 API 调用头,从每个调用返回数据。通过这些头,可以进一步控制 API 返回的数据量。

结果限制

结果限制是一种支持方法,允许您定义要返回的对象的偏移量和数量。它支持对大数据集进行分页。

对象掩码

通过使用对象掩码,用户可以指定从某一方法返回哪些本地属性,还可以检索关系属性和计数属性中的信息。系统会创建映射或掩码来定义要包含在返回值中的特定数据。例如,通过在调用 SoftLayer_Hardware_Server::getObject 时为 networkVlans.id 指定对象掩码,可以收集 SoftLayer_Hardware_Server 上每个 VLAN 的 ID。

浏览对象掩码以获取所需的结果,是您精通 SLAPI 的一种表现。有时候,可以通过多种方式来到达特定的数据点,而且其中一些方式要比其他方式更高效一些。

从这里可通往何处

您现在已了解一些基本知识,可以开始编码了。请阅读我们的《入门指南》,了解如何创建 API 用户以及如何发出首个调用。我们还提供了多种特定语言版本的指南:

其他有用链接: