README

## 更新到 v2.x 这个版本是一个主要更新，可能破坏与旧版本的兼容性。如果您使用的是我们的 SDK 的旧版本，您将不得不停止使用 NAApiClient 类，而使用 NAThermApiClient 或 NAWSApiClient。

实际上，这些添加了一个额外的抽象层，这将使您更容易使用：现在使用 "api" 客户端方法调用被替换为针对每个产品 API 预期参数的专用方法。

您可能还需要更改 SDK 文件的包含路径，因为它们现在存储在 "src" 文件夹中（API 客户端存储在 "src/Netatmo/Clients/" 文件夹中）。

更新到 v2.1.x

这个版本引入了命名空间以避免与其他包冲突，这是一个破坏性变更，因为 Netatmo SDK 提供的类不再在全局命名空间中可用。例如，NAThermApiClient 变为 Netatmo\Clients\NAThermApiClient。有关更多信息，请参阅 https://php.ac.cn/manual/en/language.namespaces.php。

这意味着在全局命名空间中使用 Netatmo SDK 类已被弃用。到目前为止，您仍然可以使用它们，因此不会破坏现有的代码。然而，我们建议您尽快更新代码以考虑到这些更改。

它还引入了一个遵守 PSR-4 标准的自动加载器，因此您只需包含 src/Netatmo/autoload.php 文件即可。

安装和配置

要安装 SDK，将下载的文件解压到您的项目目录中。然后，只需包含 src/Netatmo/autoload.php 文件，并使用您的应用程序 client_id 和 client_secret 实例化一个新的 NAWSApiClient（或 NAThermApiClient 或 NAWelcomeApiClient）对象。

$config = array();
$config['client_id'] = "YOUR_APP_ID";
$config['client_secret'] = "YOUR_APP_SECRET";
$config['scope'] = 'read_station read_thermostat write_thermostat';
$client = new Netatmo\Clients\NAApiClient($config);

验证和授权

SDK 提供了帮助方法来验证和授权您的应用程序访问用户数据。

通过用户凭证授权获取访问令牌

$username = "YOUR_USERNAME";
$pwd = "YOUR_PWD";
$client->setVariable('username', $username);
$client->seVariable('password', $pwd);
try
{
    $tokens = $client->getAccessToken();
    $refresh_token = $tokens["refresh_token"];
    $access_token = $tokens["access_token"];
}
catch(Netatmo\Exceptions\NAClientException $ex)
{
    echo "An error occcured while trying to retrive your tokens \n";
}

请注意，您不应该存储用户的凭证（这是不安全的），并反复执行用户凭证验证，因为您的应用程序的用户将收到电子邮件以警告有人正在使用他们的凭证连接到他们的账户。相反，您应该使用在验证过程结束时发送给您的刷新令牌来获取新的访问令牌，每次它到期时。有关访问和刷新令牌的更多信息，请参阅 OAuth2 协议文档。

通过授权代码授权获取访问令牌

//test if "code" is provided in get parameters (which would mean that user has already accepted the app and has been redirected here)
if(isset($_GET['code']))
{
    try
    {
       $tokens = $client->getAccessToken();
       $refresh_token = $tokens['refresh_token'];
       $access_token = $tokens['access_token'];
    }
    catch(Netatmo\Exceptions\NAClientException $ex)
    {
       echo " An error occured while trying to retrieve your tokens \n";
    }
}
else if(isset($_GET['error']))
{
    if($_GET['error'] === 'access_denied')
        echo "You refused that this application access your Netatmo Data";
    else echo "An error occured \n";
}
else
{
    //redirect to Netatmo Authorize URL
    $redirect_url = $client->getAuthorizeUrl();
    header("HTTP/1.1 ". OAUTH2_HTTP_FOUND);
    header("Location: ". $redirect_url);
    die();
}

使用 API 方法

Netatmo 气象站 API 客户端实现 - PHP SDK

如果您需要有关 Netatmo 气象站如何工作的更多信息，请参阅 https://dev.netatmo.com/dev/resources#/technical/reference/weatherstation

检索 Netatmo 气象站的数据

一旦获取了访问令牌，就可以用它来检索用户设备数据

$data = $client->getData(NULL, TRUE);
foreach($data['devices'] as $device)
{
    echo $device['station_name'] . "\n";
    print_r($device['dashboard_data']);
    foreach($device['modules'] as $module)
    {
        echo $module['module_name'];
        print_r($module['dashboard_data']);
    }
}

$data 将是一个数组，包含设备列表及其模块及其最后存储的数据：首先是属于用户的设备，然后是用户的朋友的设备，最后是用户喜欢的设备。

要检索特定设备的数据，您必须提供其 id

$data = $client->getData("YOUR_DEVICE_ID");

如果它是用户喜欢的设备之一，您必须将 "get_favorites" 参数设置为 TRUE 才能检索它

$data = $client->getData("YOUR_FAV_DEVICE_ID", TRUE);

检索 Netatmo 气象站的测量值

您还可以检索特定设备在给定时间段内的具体测量数据。

$device = $data['devices'][0];
$module = $device['modules'][0];
$scale = "1day";
$type = $module['data_type'];
$date_begin = time() -24*3600*7; //1 week ago
$date_end = time() //now
$optimized = FALSE;
$real_time = FALSE;
$measurements = $client->getMeasure($device['_id'], $module_id, $scale, $type, $date_begin, $date_end, $optimized, $real_time);

请注意，如果不提供 module_id，则会检索主设备的测量数据。缩放参数对应于两个测量值之间的步长，类型取决于设备或模块的数据类型和缩放。有关其允许值的更多详细信息，请参阅 https://dev.netatmo.com/doc/getmeasure。如果您需要更轻量级的 JSON 响应但解析稍微复杂一些，请将优化标志设置为 true：您将只提供起始时间戳，并必须使用缩放计算其他时间戳。最后，real_time 标志可以启用以从大于 'max' 的缩放中移除时间戳偏移。实际上，由于数据是聚合的，默认情况下时间戳偏移为 + scale/2。

Netatmo 温控器 API 客户端实现 - PHP SDK

如果您需要有关 Netatmo 温控器如何工作的更多信息，请参阅 https://dev.netatmo.com/dev/resources#/technical/reference/thermostat

检索 Netatmo 温控器的数据

温控器 API 客户端与气象站 API 客户端的工作方式相同。

$client = new Netatmo\Clients\NAThermApiClient($config);

它还有自己的方法来检索用户的温控器数据，该方法返回包含设备及其数据的数组。

$data = $client->getData();

为了检索特定的温控器，您需要提供其 ID。

$data = $client->getData($device_id);

检索 Netatmo 温控器的测量数据

温控器还具有 getMeasure 方法，该方法与气象站的方法完全相同，用于检索给定时间段的具体数据。

$device = $data['devices'][0];
$module = $device['modules'][0];
$scale = "1day";
$type = "Temperature,max_temp,min_temp,date_max_temp";
$date_begin = time() -24*3600*7; //1 week ago
$date_end = time() //now
$optimized = FALSE;
$real_time = FALSE;
$measurements = $client->getMeasure($device['_id'], $module_id, $scale, $type, $date_begin, $date_end, $optimized, $real_time);

向 Netatmo 温控器发送命令

您可以轻松更改温控器的设定点。

try{
    $client->setToAwayMode($device['_id'], $module['_id']);
    $client->setToFrostGuardMode($device['_id'], $module['_id']);
    $client->setToProgramMode($device['_id'], $module['_id']);
}
catch(Netatmo\Exceptions\NAClientException $ex)
{
    "An error occured";
}

您还可以发出时间限制的命令。

$endtime = time() +2*3600;
$client->setToAwayMode($device['_id'], $module['_id'], $endtime); // away for 2 hours
$client->setToFrostGuardMode($device['_id'], $module['_id'], $endtime);

某些命令需要时间限制。

$endtime = time() + 2*3600;
$client->setToMaxMode($device['_id'], $module['_id'], $endtime);

最后，您还可以仅设置手动温度设定点。

$endtime = time() + 2*3600;
$temp = 21.5;
$client->setToManualMode($device['_id'], $module['_id'], $temp, $endtime);

您还可以关闭温控器。

$client->turnOff($device['_id'], $module['_id']);

（要重新打开，请设置另一个设定点，例如：命令温控器遵循其计划）

处理 Netatmo 温控器的周计划

Netatmo 温控器 SDK 还允许您处理温控器计划。

您可以创建一个新的计划。

$res = $client->createSchedule($device['_id'], $module['_id'], $zones, $timetable, 'new schedule');

您将在返回值中找到创建的计划 ID。

$schedule_id = $res['schedule_id'];

然后切换温控器的当前计划到另一个现有计划。

$client->switchSchedule($device['_id'], $module['_id'], $schedule_id);

然后修改您的当前计划。

$client->syncSchedule($device['_id'], $module['_id'], $zones, $timetable);

然后您可以重命名一个计划。

 $client->renameSchedule($device['_id'], $module['_id'], $schedule_id, 'new Name');

最后，您还可以删除一个计划。

$client->deleteSchedule($device['_id'], $module['_id'], $schedule_id);

Netatmo Welcome API 客户端实现 - PHP SDK

如果您需要有关 Netatmo Welcome 如何工作的更多信息，请参阅 https://dev.netatmo.com/dev/resources#/technical/reference/welcome

检索 Netatmo Welcome 数据

Netatmo Welcome SDK 的工作方式与 Netatmo 气象站和 Netatmo 温控器 SDK 略有不同。首先，实例化客户端

$client = new Netatmo\Clients\NAWelcomeApiClient($config);

Netatmo Welcome SDK 允许您检索属于用户的每个家庭（人员、摄像头、事件）的数据。

$res = $client->getData():

如果您只想检索有关特定用户家庭的详细信息，只需指定其 ID。

$res = client->getData($home_id);

请注意，您可以使用 $size 参数限制每个家庭请求的事件数量（默认值为 30）。

$res = client->getData(NULL, 10); // will retrieve every home belonging to the user and only the 10 last associated events

与气象站和温控器 SDK 的区别在于，客户端返回 NAResponseHandler 对象。这些对象允许您以 PHP 数组或对象数组（NAHome 或 NAEvent）的形式获取 Netatmo API 返回的原始数据。

$array = $res->getDecodedBody();
$objects = $res->getData();

从给定家庭检索特定事件

除了检索家庭的所有信息之外，您还可以仅获取您感兴趣的事件。为此，您可以使用以下三种方法：

• 首先，您可以从特定人员的最后一个事件开始检索每个事件。

    $res = $client->getLastEventOf($home_id, $person_id);
    $events = $res->getData();
  

  此函数还接受一个偏移参数，该参数允许检索比请求的事件更早的一定数量的事件。默认值为0。

    $res = $client->getLastEventOf($home_id, $event_id, 5);
    $events = $res->getData();
  

• 然后，您还可以检索到特定事件的所有事件。

    $res = $client->getEventsUntil($home_id, $event_id);
    $events = $res->getData();
  

• 最后，您还可以检索到发生在特定事件之前的事件。为此，您应使用$size参数指定要检索的事件数量。默认值为30。

    $res = $client->getNextEvents($home_id, $event_id, 10); // get the 10 events that happened right before event_id
    $events = $res->getData();
  

检索与事件或人物面部相关联的图片

在通过前述方法之一检索事件或人物信息后，您可能希望能够获取与事件快照或人物面部相对应的图片。为了做到这一点，如果您处理的是PHP数组中的原始数据，您将需要该事件的快照或面部信息。

$img = $client->getCameraPicture($event['snapshot']);

如果您正在使用SDK提供的对象，只需在图片上调用对象获取器，以检索其URL。

$pictureURL = $event->getSnapshot();
$faceURL = $person->getFace();

快速示例

$scope = Netatmo\Common\NAScopes::SCOPE_READ_CAMERA;

//Client configuration from Config.php
$conf = array("client_id" => $client_id,
          "client_secret" => $client_secret,
          "username" => $test_username,
          "password" => $test_password,
          "scope" => $scope);
$client = new Netatmo\Clients\NAWelcomeApiClient($conf);

//Retrieve access token
try
{
    $tokens = $client->getAccessToken();
}
catch(Netatmo\Exceptions\NAClientException $ex)
{
    echo "An error happened  while trying to retrieve your tokens \n" . $ex->getMessage() . "\n";
}

//Try to retrieve user's Welcome information
try
{
    //retrieve every user's homes and their last 10 events
    $response = $client->getData(NULL, 10);
    $homes = $response->getData();
}
catch(Netatmo\Exceptions\NASDKException $ex)
{
    echo "An error happened while trying to retrieve home information: ".$ex->getMessage() ."\n";
}

//print homes names
foreach($homes as $home)
{
    echo $home->getName() . "\n";
}

Netatmo Welcome的Webhooks

您的应用程序可以订阅Netatmo Welcome事件的Webhooks通知。有两种不同的注册方式：您可以在我们的开发者平台上填写应用程序设置中的Webhook URL（接受应用程序的每个用户都将受到webhooks通知的约束），或者您可以使用API自行管理用户的webhooks注册。

$client->subscribeToWebhook($webhook_url);

以及取消订阅用户Webhooks

$client->dropWebhook();

错误处理

###SDK错误 SDK在发生错误时抛出NASDKException。它封装了Netatmo Welcome SDK的Networking错误、API错误和SDK对象错误。

try{
    $client->getData();
}
catch(Netatmo\Exceptions\NASDKException $ex)
{
    //Handle error here
    echo $ex->getMessage();
}

API客户端错误

客户端在处理API或网络协议时遇到错误会抛出NAClientException。

try{
    $client->getData();
}
catch(Netatmo\Exceptions\NAClientException $ex)
{
    //Handle error here
    echo $ex->getMessage();
}

详细信息

请阅读https://dev.netatmo.com/dev/resources#/technical/introduction以获取更多信息。