Perl

SoftLayer 提供一种基于 Perl 的 API 客户端,可避免手动发出 SOAP API 调用的繁重工作量。要使用此 API 客户端,必须满足以下系统需求:

  • Perl 5.6 或更高版本
  • SOAP::Lite
  • XML::Hash::LX

从 SoftLayer 的 github 配置文件内的项目页面中,下载 SoftLayer Perl API 客户端。完成下载后,请将 Perl API 客户端解压到 Perl 项目的本地目录,或解压到 Perl 安装的 @INC 路径中。

下载 SoftLayer API Perl 客户端

发出 API 调用

下载并安装该 API 客户端后,要做的第一件事是在脚本中包含 SoftLayer::API::SOAP 模块。此文件定义 SoftLayer 的客户端对象。在包含该模块之前,您可能必须将它的父目录添加到 @INC 路径中。请使用以下代码来添加该父目录:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;

接下来,为您要使用的 SoftLayer API 服务创建客户端对象。SoftLayer::API::SOAP->new() 将为您照管这个对象,并接受四个参数:

  • 您要调用的服务的名称。
  • 您要使用的特定对象的可选 ID 号。请传递 undef 值,前提是您正在使用 SoftLayer_Account 服务,或未在使用特定的服务器、支持凭单、发票或其他对象。在您的 API 调用中,此 ID 将创建一个初始化参数
  • 您的 API 用户名。
  • 您的 API 密钥。
    以下代码片段提供了关于使用上述参数发出 API 调用的示例:
use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
# Create a client to the SoftLayer_Account API service.
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
 
# Work directly with the SoftLayer_Hardware_Server record with the hardware id 
# 1234.
#my $server_id = 1234;
#my $client = SoftLayer::API::SOAP->new('SoftLayer_Hardware_Server', $server_id, $api_username, $api_key);

准备好 API 客户端对象 ($client) 后,可调用 SoftLayer API 方法,如同它是客户端对象的本地方法一样。将 API 调用结果分配给一个变量,以获取该调用的结果。系统会将复杂类型对象作为散列值(声明为该调用的返回类型)返回。同样,如果您需要将复杂
类型参数传递至 API 调用,请使用散列值、内含散列值的散列值或内含数组的散列值。例如:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
my $domain_id = 1234;
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', $domain_id, $api_username, $api_key);
 
# Create a new A record in a domain.
my $new_record = $client->createARecord('myhost', '127.0.0.1', 86400);
 
print 'New A record id: ' . $new_record->{id}; 
 
# Create a new domain record. 
#
# This requires an API client with an undef id, and use a hash with an array to model 
# our new domain.
$client = SoftLayer::API::SOAP->new('SoftLayer_Dns_Domain', undef, $api_username, $api_key);
 
my $domain = {
    'name' => 'example.org',
    'resourceRecords' => [
        {
            'host' => '@',
            'data' => '127.0.0.1',
            'type' => 'a',
        }
    ]
};
 
my $new_domain = $client->createObject($domain);
 
print 'New domain id: ' . $new_domain->{id};
If you wish, you can declare your client object and make an API call on a single line.  The following code outlines this scenario:
use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $account = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key)->getObject();

使用对象掩码

使用嵌套散列值变量,为 API 调用创建对象掩码。定义您希望检索为散列值密钥的关系属性。如果您正在检索子属性,请为子属性定义嵌套散列值。否则,请定义空散列值作为密钥的值。通过 the setObjectMask() 方法,将对象掩码与 API 客户端绑定在一起。此示例将检索帐户的物理硬件记录、该硬件的操作系统记录、操作系统密码、网络组件、该硬件所在的数据中心,以及每个硬件中的处理器数:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
# Retrieve items related to hardware.
#
# Operating system, operating system passwords, all network components, the
# datacenter the server is located in, and the number of processors in each 
# server.
my $object_mask = {
    'hardware' => {
        'operatingSystem' => {
            'passwords' => {},
        },
        'networkComponents' => {},
        'datacenter' => {},
        'processorCount' => {},
    }
};
 
$client->setObjectMask($object_mask);
 
my $hardware = $client->getHardware();

使用结果限制

当调用数据时,尤其是查询涉及到从较大组中抽取信息片段时,使用结果限制将极大地缩短返回的等待时间。
使用客户端对象的 setResultLimit() 方法来限制 API 调用中的结果数量。此方法接受两个参数:

  • 要为调用限制的结果数量。
  • 结果集开始的可选偏移量。

以下代码提供了关于在 API 调用中使用结果限制的示例。

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'set me';
 
my $client = SoftLayer::API::SOAP->new('SoftLayer_Account', undef, $api_username, $api_key);
 
# Retrieve our first two open support tickets.
$client->setResultLimit(2);
 
$tickets = $client->getOpenTickets();

错误处理

如果 SoftLayer API 调用抛出了 SOAP 故障,那么客户端对象将填充 faultfaultstring 属性。在发出 API 调用来有效地处理错误后,检查 fault 属性。如果您的调用中发生错误,那么 faultstring 属性会包含 SoftLayer API 返回的错误。以下脚本包含此类错误的示例:

use lib '/path/to/SoftLayer/';
use SoftLayer::API::SOAP;
use strict;
 
my $api_username = 'set me';
my $api_key = 'an incorrect key';
 
$client = SoftLayer::API::SOAP->new('SoftLayer_Account', null, $api_username, $api_key);
 
# Exit the script with the message:
# "Unable to retrieve account information: Invalid API key"
my $account = $client->getObject();
 
if ($account->fault) {
    die 'Unable to retrieve account information: ' . $account->faultstring;
}

被引用的 API 组件

服务

数据类型

方法