README

Go Daddy® REST API 的 PHP 客户端。

要求

PHP 5.3 或更高版本
libcurl PHP 扩展，支持 SSL
在兼容的服务中拥有账户，例如 Cloud Servers™
您的 API 访问密钥和密钥对

入门指南

如果您还没有尝试过，请在一个浏览器中打开您想使用的 API 的基本 URL。将访问密钥作为用户名，将密钥作为密码输入。此界面将使您熟悉 API 中可用的资源类型以及您可以在这些资源上执行的操作和操作。有关更多信息，请参阅文档网站。

设置

最新稳定版本的 PHAR 存档可以在下载页面上找到。我们建议您使用此版本，而不是直接使用存储库中的源代码。

使用 PHAR 存档

下载 .phar 文件

curl -O https://github.com/downloads/godaddy/gdapi-php/gdapi.phar

创建客户端

<?php
require_once('gdapi.phar'); // Or /path/to/gdapi.phar

$url        = 'https://api.cloud.secureserver.net/v1/schemas';
$access_key = 'your-access-key';
$secret_key = 'your-secret-key';
    
$client = new \GDAPI\Client($url, $access_key, $secret_key);
?>

使用源代码

要使用源代码，请克隆它

git clone https://github.com/godaddy/gdapi-php.git

创建客户端

<?php
require_once('gdapi-php/init.php'); // Or /path/to/gdapi-php/init.php

$url        = 'https://api.cloud.secureserver.net/v1/schemas';
$access_key = 'your-access-key';
$secret_key = 'your-secret-key';
    
$client = new \GDAPI\Client($url, $access_key, $secret_key);
?>

连接问题

如果您在创建客户端时遇到错误，并显示类似以下错误，请参阅 SSL 问题部分

SSL 证书问题，请验证 CA 证书是否正确。详细信息：错误：14090086：SSL 程序：SSL3_GET_SERVER_CERTIFICATE：证书验证失败

查找资源

API 中的每种资源类型都作为客户端的一个成员可用。

列出集合中的所有资源

<?php
$machines = $client->virtualmachine->query();
echo "There are " . count($machines) . " machines:\n";
foreach ( $machines as $machine )
{
  echo $machine->getName() . "\n";
}
?>

过滤

过滤器允许您搜索满足一组条件的资源集合。

<?php
$http_balancers = $client->loadbalancers->query(array(
  'publicStartPort' => 80,
));

$privileged_portforwards = $client->portforwards->query(array(
  'publicStartPort' => array('modifier' => 'lt', 'value' => 1024)
));

$active_machines = $client->virtualmachine->query(array(
  'removed' => array('modifier' => 'null')
));

$complicated = $client->portforwards->query(array(
  'name' => 'asdf',
  'removed' => array('modifier' => 'null'),
  'publicStartPort' => array(
    array('modifier' => 'gt', 'value' => 1024)
    array('modifier' => 'lt', 'value' => 2048)
  ),
));
?>

通过 ID 获取单个资源

如果您已经知道要查找的资源 ID，您也可以直接获取它。

<?php
$machine = $client->virtualmachine->getById('your-machine-id');
?>

处理资源

访问属性

资源对每个属性都有一个获取方法，如 "get"+{属性名称}。可以更改的属性也有 "set"+{属性名称} 方法。属性名称的第一个字符可能为大写字母，以提高可读性，但名称的其余部分必须与 API 匹配。

<?php
$machine = $client->virtualmachine->getById('your-machine-id');

$privateIp = $machine->getPrivateIpv4Address(); // e.g. '10.1.1.3'
$size = $machine->getRamSizeMb(); // e.g. 1024
?>

进行更改

<?php
$machine = $client->virtualmachine->getById('your-machine-id');
$machine->setName('bigger machine');
$machine->setOffering('2gb-4cpu');

// Save the changes
$result = $machine->save();
?>

创建新资源

<?php
$network = $client->network->create(array(
  'name'     => 'My Network',
  'domain'   => 'mynetwork.local',
  'ipv4Cidr' => '192.168.0.0/24'
));
?>

删除资源

使用资源实例

<?php
$machine = $client->virtualmachine->getById('your-machine-id');
$result = $machine->remove();
?>

或静态

<?php
$result = $client->virtualmachine->remove('your-machine-id');
?>

执行操作

操作用于执行超出简单创建/读取/更新/删除之外的操作。资源对每个操作都有一个 "do"+{操作名称} 方法。操作名称的第一个字符可能为大写字母，以提高可读性，但名称的其余部分必须与 API 匹配。

<?php
$machine = $client->virtualmachine->getById('your-machine-id');
$result = $machine->doRestart();
?>

跟随链接

响应集合和资源通常有一个包含指向相关资源和集合的 URL 的 "links" 属性。例如，虚拟机属于网络，并有一个或多个卷。资源对每个链接都有一个 "fetch"+{链接名称} 方法。调用此方法将返回链接资源

<?php
$machine = $client->virtualmachine->getById('your-machine-id');
$network = $machine->fetchNetwork(); // Network resource
$volumes = $machine->fetchVolumes(); // Collection of Volume resources
?>

处理错误

默认情况下，任何错误响应都会被抛出异常。最通用的异常类型是\GDAPI\APIException，但在class/APIException.php中定义了更多具体的异常类型。

<?php
try
{
  $machine = $client->virtualmachine->getById('your-machine-id');
  echo "I found it";
}
catch ( \GDAPI\NotFoundException $e )
{
  echo "I couldn't find that machine";
}
catch ( \GDAPI\APIException $e )
{
  echo "Something else went wrong";
}
?>

您需要将最具体的类到最不具体的类的catch块顺序放置。PHP会按顺序运行您的catch语句，并且只调用第一个匹配异常的catch语句。如果您将上述两个catch语句颠倒，即使异常是NotFoundException，也会打印出“出了点问题”。

如果您不想使用异常，可以在创建Client时禁用它们。当发生错误时，返回的响应将是一个\GDAPI\Error实例的实例，而不是抛出异常。

<?php
$options = array(
  'throw_exceptions' => false
);

$client = new \GDAPI\Client($url, $access_key, $secret_key, $options);

$result = $client->virtualmachine->getById('your-machine-id');
if ( $result instanceof \GDAPI\Error )
{
  if ( $result->getStatus() == 404 )
  {
    echo "I couldn't find that machine";
  }
  else
  {
    echo "Something else went wrong: " . print_r($result,true);
  }
}
else
{
  echo "I found it";
}
?>

高级选项

将响应对象映射到您的类

默认情况下，所有响应对象都是\GDAPI\Resource、\GDAPI\Collection或\GDAPI\Error的实例。在许多情况下，将响应映射到您的类并添加自己的行为非常有用。

<?php

class MyVM extends \GDAPI\Resource
{
  function getFQDN()
  {
    $network = $this->fetchNetwork();
    return $this->getName() . "." . $network->getDomain();
  }
}

class MyLoadBalancer extends \GDAPI\Resource
{
  function getFQDN()
  {
    $network = $this->fetchNetwork();
    return $this->getName() . "." . $network->getDomain();
  }
}

$classmap = array(
  'virtualmachine' => 'MyVM',
  'loadbalancer'   => 'MyLoadBalancer'
);

$options = array(
  'classmap' => $classmap
);

$client = new \GDAPI\Client($url, $access_key, $secret_key, $options);

$machines = $client->virtualmachine->query();
echo "There are " . count($machines) . " machines:\n";
foreach ( $machines as $machine )
{
  echo $machine->getFQDN() ."\n";
}
?>

SSL问题

某些libcurl的安装没有包含任何证书颁发机构（CA）的证书。此客户端默认情况下始终验证证书，但没有CA证书意味着它将无法验证任何SSL证书。要解决这个问题，您需要一个要信任的CA证书列表。Curl提供了一个包含与Mozilla浏览器相同的CA证书的副本：cacert.pem。

如果您有权编辑您的php.ini，您可以为使用libcurl扩展的任何内容全局修复此问题

将以下行添加到您的php.ini中，然后重新启动您的Web服务器（如果适用）

curl.cainfo = /path/to/cacert.pem

如果您没有权限或不想进行全局更改，您可以仅配置GDAPI客户端使用该文件

<?php
$options = array(
  'ca_cert' => '/path/to/cacert.pem'
);

$client = new \GDAPI\Client($url, $access_key, $secret_key, $options);
?>

leolabs / gdapi-php

维护者

详细信息