README

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

实际上，这些添加了一个额外的抽象层，这将使您更容易使用：使用“api”客户端方法进行的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->setVariable('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/resources/technical/reference/weather

检索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/resources/technical/reference/common/getmeasure。如果需要更轻量但稍微难以解析的 json 响应，请将优化标志设置为 true：您将仅提供起始时间戳，并将必须使用比例计算其他时间戳。最后，real_time 标志可以启用在比例高于 'max' 的情况下移除时间戳偏移。事实上，由于数据是汇总的，默认情况下时间戳偏移为 + scale/2。

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

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

检索 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
$limit = NULL;
$optimized = FALSE;
$real_time = FALSE;
$measurements = $client->getMeasure($device['_id'], $module_id, $scale, $type, $date_begin, $date_end, $limit, $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 欢迎API客户端实现 - PHP SDK

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

检索 Netatmo 欢迎数据

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

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

Netatmo 欢迎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 对象。这些对象允许您获取 Netatmo API 返回的原始数据作为 PHP 数组，或将其作为对象数组（NAHome 或 NAEvent）获取

$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的网络错误、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/resources/technical/reference获取更多信息。