AMEE 简介

将环境智能嵌入您的应用程序

今天,人们对能源以及能源对环境的危害 —— 二氧化碳 —— 十分关注。为了实现一个更加可持续性的世界,个人、公司和政府都非常关注能源和能源的使用方式。理解能源(和因此导致的碳)使用的途径就是测量并分析它,理解测量结果,然后根据这些信息采取行动。AMEE 是各种能源、活动数据和相关碳模型的一个独立聚合平台。本文介绍如何在您的应用程序中使用 AMEE 平台来为您的客户提供高质量的能源管理和碳计算解决方案。

James Smith, 开发经理, AMEE

James Smith 是 AMEE 公司的开发经理。他拥有软件工程工作背景和超过 10 年的 C++ 软件开发经验,参与过的项目涉及生物测量学和飞行模拟等多个领域。在加入 AMEE 之前,James 还从事过环境软件领域的大量工作,参与了 Carbon Diet 和 Green Thing 等基于 web 的项目。



2009 年 10 月 09 日

简介

加入 My developerWorks 的绿色小组

在 My developerWorks 的 GReen IT Report 空间绿色计算小组 讨论关于能源、效率和环境的主题并分享相关资源。

AMEE 是一个基于 Web 的 API,它支持用户长期存储和检索多种形式的能源消耗数据,并应用公认的碳计算模型确定能源消耗对环境产生的影响。开发人员使用 AMEE 来提供能源跟踪和管理应用程序(包括英国政府的 Act On CO2 计算器、CNN 和 Google 的应用程序等)并支持 Carbonetworks 和 Misys OpenCarbonWorld 等碳管理应用程序。“Powered by AMEE” 标记表示您的应用程序遵守权威标准。


AMEE 平台

常用缩略词

  • API:应用程序编程接口
  • AMEE:Avoiding Mass Extinctions Engine
  • GHG:温室气体
  • HTTP:超文本传输协议
  • JSON:JavaScript 对象标记
  • REST:具象状态传输
  • SAP:标准评估流程
  • UID:用户标识符
  • URL:统一资源定位器
  • XML:可扩展标记语言

与 AMEE 平台进行交互的途径是一个 RESTful HTTP API,它支持选择 XML、JSON 或 Atom 数据格式。SOAP 和其他 API 将来会添加进来。这个 API 包含两个部分:配置文件数据。配置文件是存储能源数据的地方。通过在一段时间内存储这些数据,您可以为您的客户、业务和您自己存储一个能源使用历史。这个数据存储提供大量的标准模型,包括 GHG Protocol、SAP 构建评估、150 个国家和地区的碳排放系数,以及相关的方法。当您将能源数据存储在一个 AMEE 配置文件时,这些方法将自动应用,为您的能源使用提供一个可靠的碳 “足迹”。

如前所述,AMEE 是一个 HTTP API。为了展示一些示例,本文将包含一些 HTTP 请求的相关部分,以便您了解 AMEE 的工作方式。因此,本文假定您熟悉 HTTP 请求的工作方式并且能够阅读 XML。如果您需要这方面的帮助,请参考本文末尾的 参考资料


入门

使用 AMEE 平台的第一步是注册以获取访问密匙。您可以在 http://my.amee.com/signup 免费注册。输入您的详细信息,一两分钟之后您将收到一封电子邮件,该邮件将向您提供一个 API 密匙以及访问文档和其他相关资源的链接。

这个密匙允许您访问 AMEE 准备(stage)平台。这个平台可以免费用于开发和测试客户端应用程序,但是,平台上的数据通常会抹去。因此,如果您确定您的应用程序已准备好进行生产,您需要变更为使用 AMEE 实时平台(live platform),该平台的服务是收费的。在下面的示例中,您将使用准备平台的 URL,因为它是您的出发点。

需要注意的另一件事情是,除了使用这个 API 之外,您还可以在您的 web 浏览器中直接查看准备平台或实时平台。成功登录后,您可以在空闲时浏览这个 API,以下示例中的所有 URL 都能在您的浏览器中工作。您还可以查看 XML、JSON 和 Atom 输出,这有助于应用程序开发。


验证

获得密匙后,您就准备好和 API 本身对话了。对话的第一步是验证。这个 API 有两种验证方法:HTTP 基础验证或一个验证对话。

HTTP 基础验证非常简单,只需对每个请求使用标准的 HTTP 格式提供用户名和密码。大多数 HTTP 库都支持这个功能,清单 1 展示了使用 Ruby 语言的流程示例:

清单 1. HTTP 基础验证
http = Net::HTTP.new @host, 443
http.use_ssl = true
req = Net::HTTP::Get.new @location
req.basic_auth @username, @password
http.request(req)

或者,您也可以创建一个验证会话。这需要向 https://stage.amee.com/auth 发送一个 POST 请求,并在请求主体中以良好编码的数据形式提供用户名和密码。您还需要使用一个标准的 Accept 标头指定想要的结果格式(XML 或 JSON)。这个请求的响应包含各种信息,但最重要的是验证令牌。该令牌同时以一个 cookie 和一个自定义标头形式返回,它们都称为 authToken。存储这个 authToken 值并将它作为一个 cookie 包含在对 API 的任意后续请求中。这个 authToken 将在两小时后过期,或者如果半小时内未使用的话,也将过期。因此,如果您使用验证会话,您的应用程序应该总是准备好为任意请求重新授权,以免 authToken 过期。


AMEE 配置文件 API

经过验证后,就可以将数据存储在配置文件中了。一个配置文件可以表示个人、办公室、整个公司或者任意事物。如何分割数据完全取决于您自己,您可以随意创建多个配置文件。您的应用程序设计可能会决定最适合的分割方式,但一般来说,应该把视为一个能源使用实体的个体放在单个配置文件中。

AMEE 中的每个配置文件通过一个 16 位随机字符串(配置文件 UID)识别,将数据存储到应用程序数据库需要这个 UID 以及其他可能的用户细节;如果用户以后需要查询数据,您也需要这个配置文件 UID 来检索他们的信息。这是因为数据隐私和数据安全在今天很重要,存储在 AMEE 中的所有数据都是匿名的,因此不能根据个人信息检索配置文件数据。

要创建一个配置文件,您可以发送一个 POST 请求到 https://stage.amee.com/profiles。您还需要在请求主体中设置参数 profile=true,如 清单 2 所示。

清单 2. 创建一个配置文件
POST /profiles HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
profile=true

注意,我在这里以及后续示例中省略了验证细节。您将获得一个类似于 清单 3 的响应(同样,我省略了次要部分以便更简明)。

清单 3. 响应
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources xmlns="http://schemas.amee.cc/2.0">
  <ProfilesResource>
    <Profile uid="7C7D68C2A7CD">
      ...
    </Profile>
  </ProfilesResource>
</Resources>

这个响应中的重要部分是 Profile 标记中的 uid 属性,本例中该属性的值是 7C7D68C2A7CD。这是新创建的配置文件的 UID,也是使用该配置文件的后续请求的一部分。

配置文件类别

一个配置文件包含一个配置文件类别结构,这个结构分隔存储在上下文区域中的数据,类似于磁盘上的文件夹结构。顶级类别包含 Home、Business、Transport 等宽泛的领域,而一些类别(通常是低级类别)包含配置项目。这些类别类似于文件,是存储能源数据的地方。

首先,查看 清单 4 中的一个配置文件的描述。注意,清单 3 中的配置文件 UID 包含在请求路径中。

清单 4. 一个配置文件类别的描述
GET /profiles/7C7D68C2A7CD/home HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources xmlns="http://schemas.amee.cc/2.0">
  <ProfileCategoryResource>
    <Path>/home</Path>
    <Profile uid="7C7D68C2A7CD"/>
    ...
    <DataCategory uid="BBA3AC3E795E">
      <Name>Home</Name>
      <Path>home</Path>
    </DataCategory>
    <ProfileCategories>
      <DataCategory uid="427DFCC65E52">
        <Name>Appliances</Name>
        <Path>appliances</Path>
      </DataCategory>
      <DataCategory uid="30BA55A0C472">
        <Name>Energy</Name>
        <Path>energy</Path>
      </DataCategory>
      ...
    </ProfileCategories>
  </ProfileCategoryResource>
</Resources>

通过向 /profiles/7C7D68C2A7CD/home 发送一个 GET 请求,您将获取一个描述 Home 类别的 XML 文档。您将看到,它包含几个其他类别。如果这个类别包含配置项目(见 清单 5),那么这些项目也将包含在返回的文档中。

子类别排列在相同的 URL 结构中,因此 Appliances 子类别的路径是 /profiles/7C7D68C2A7CD/home/appliances。您可以以这种方式遍历类别结构,直到您发现要在其中存储数据的类别。但是,您很可能在开发时才需要进行这种类别浏览,而且是通过 web 界面而不是 XML 或 JSON API。类别布局并不随时间改变,因此您可以放心地将类别路径永久地存储在您的代码中。

存储数据并计算 CO2

找到想要存储能源数据的类别后,需要创建一个配置项来存储数据。为此,只需使用一组适当的参数对类别 URL 执行 POST 操作,您的数据将存储在新创建的配置项中。例如,要在 /home/energy/quantity 类别中存储一些能源数据,可以发送 清单 5 中的请求。

清单 5. 在 /home/energy/quantity 类别中存储一些能源数据
POST /profiles/7C7D68C2A7CD/home/energy/quantity HTTP/1.1
Accept: application/xml
Content-Type: application/x-www-form-urlencoded
dataItemUid=66056991EE23&energyConsumption=10

HTTP/1.1 201 CREATED
Location: https://stage.amee.com/profiles/7C7D68C2A7CD/home/energy/quantity
/F7C0580D088A

如果请求成功,您将得到一个 201 CREATED 响应,以及新创建的配置项的地址。这里有几个参数需要注意,特别是 POST 请求中的参数。第一个参数是 dataItemUid,它指定要存储在该类别中的数据的确切数据类型(本例中为 “天然气使用”)。稍后我将详细介绍这一点。第二个参数是 energyConsumption,这是特定于这个类别的配置项的值。由于每个类别都可以存储不同类型的数据,每个类别的配置项的值都不相同。稍后我将详细介绍如何确定每个类别的配置项的值。但是,在本例中,这个调用将为该项存储能源值 10 kWh/month。注意,您可以通过您的 POST 请求选择要使用的单位(参阅 “单位” 部分了解详细信息)。

还有一个选项在许多情况下都有用。如果您在 POST 请求中传递一个额外参数 representation=full,您将得到新创建的项的表示,而不只是新配置项的地址。如果您想得到刚才存储的数据的 CO2 值,您就需要传递这个参数。XML 表示看起来就像一个 GET 响应(参阅 清单 6)。

清单 6. 新创建的项的 XML 表示
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources xmlns="http://schemas.amee.cc/2.0">once you know where, 
  <ProfileCategoryResource>
    ...
    <ProfileItems>
      <ProfileItem uid="2DB26ED646AC">
        <Name/>
        <ItemValues>
          ...
          <ItemValue uid="2A0B5AD9927D">
            <Path>energyConsumption</Path>
            <Name>Energy Consumption</Name>
            <Value>10</Value>
            <Unit>kWh</Unit>
            <PerUnit>month</PerUnit>
            ...
          </ItemValue>
          ...
        </ItemValues>
        <Amount unit="kg/year">24.660000</Amount>
        <StartDate>2009-06-23T17:22:00Z</StartDate>
        <EndDate/>
        <DataItem uid="66056991EE23">
          <Label>gas</Label>
        </DataItem>
      </ProfileItem>
    </ProfileItems>
    <TotalAmount unit="kg/year">24.660000</TotalAmount>
  </ProfileCategoryResource>
</Resources>

注意 ProfileItem 标记,它包含新创建项的细节。目前最相关的值是 ItemValue 标记和 Amount 标记中的值。这些项的值(真实的响应中有多个值,为简明起见,这里只显示了一个)是来自您的 POST 请求的已存储参数的表示。本例中,这个项是 energyConsumption,它的值是 10。Unit 和 PerUnit 显示这个项值的单位,这里是 kWh/month。Amount 标记只是显示能源使用所产生的 CO2 量。如果您每年使用 10kWh/month 天然气,您将排放 24.66kg CO2。

还要注意文档末尾的 TotalAmount 标记。如果您看到一个类别包含多个项(这些项都包含在 XML 表示中),这个标记将包含该类别中的所有项的全部 CO2 排放。

通过发现适当的类别并创建正确的项,您可以将数千种不同类型的能源使用存储在 AMEE 中。通过设置各种参数,您可以在不同时间,或用不同单位存储不同的数据值。下面,我将详细介绍部分选项。


AMEE 数据 API

看起来存储数据和获取结果很简单,但是如何知道要存储什么数据,应该存储在什么地方呢?本节将讨论这个问题,揭秘您先前遇到的奇怪参数 dataItemUid

这个 AMEE API 的数据端位于 https://stage.amee.com/data(记住从 http://my.amee.com/signup 获取一个免费密匙并使用您的 AMEE 访问密匙打开 AMEE API)。如果您用一个 web 浏览器访问这个地址,您将发现它和上面的示例类似。这个数据 API 由一个类别结构组成,该结构与每个配置文件中的那些结构完全一样。实际上,这些数据类别是真实的,而配置文件中的结构则是这个结构的虚拟副本。

数据类别可以包含几个数据项,这些数据项链接到您此前创建的配置项。这些数据项包含 AMEE 系统的常量(如 CO2 排放系数),这与配置项相反,配置项存储用户提供的变量。您可以按照以下方式看待这些结构:

  • 数据类别类似于抽象基类,比如,一个类别可以表示所有的汽车型号。
  • 数据类别中的 Data Items 类似于该基类的子类,比如,一个汽车型号类别可能包含一个表示 Ford Focus 的数据项以及其他许多数据项。
  • 配置项类似那些类的实例。例如,如果您去年实际驾驶一辆 Ford Focus 行驶了 10,000 英里,您可以(在对应的配置类别中)创建一个配置项并对 Ford Focus 数据项的 UID 设置参数 dataItemUid(并设置英里数值)。

关于数据项 UID 的一个要点 — 它们并不总是保持不变。它们在 AMEE 平台的不同实例间会发生变化,比如,它们在实时平台和准备平台之间就不同。尽管在您的应用程序中持有一个常用项目 UID 的本地缓存没有问题,但不要像类别路径一样将它们硬编码。

发现数据项 UID

那么,如果您需要一个 UID 来创建一个数据项,但又不能将它硬编码到应用程序中,那该怎么办呢?这里的答案是对您感兴趣的数据类别使用钻取(drilldown)资源。如果您发送一个 GET 请求到 https://stage.amee.com/data/{data_category_path}/drill,您将得到一个可用选项列表,这将帮助您选择需要的项。例如,清单 7 展示如何选择 “home energy” 类别中的一个燃料类型。

清单 7. 选择一个汽车类型
GET /data/home/energy/quantity/drill HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Resources>
  <DrillDownResource>
    ...
    <Selections/>
    <Choices>
      <Name>type</Name>
      <Choices>
        <Choice>
          <Name>Gas</Name>
          <Value>gas</Value>
        </Choice>
        <Choice>
          <Name>Electricity</Name>
          <Value>electricity</Value>
        </Choice>
      </Choices>
    </Choices>
  </DrillDownResource>
</Resources>

这个文档给您一个 type 选项以从中选择。要选择一个类型,需要再次调用 drilldown 资源,这次在 URL 中指定类型(见 清单 8)。

清单 8. 指定燃料类型
GET /data/home/energy/quantity/drill?type=gas HTTP/1.1
Accept: application/xml

这次,您将接收一个文档,它包含针对下一个选项的不同的选择集合。经过几次迭代后,您将只获得一个称为 UID 的选择。这是对应您的选择的数据项的 UID。这对于用户从很大的数据项列表中有效选择很有用,对于较小类别中的项也是必要的。

即使您在开发应用程序时已经知道要存储哪个项目(比如 “天然气使用” 只有一个可能的项目),您仍旧需要使用钻取资源。如前所述,UID 可能变化。但是,钻取 URLs 保证不会变化,即使在不同的 AMEE 平台实例之间。您应该使用完整的钻取 URL 并临时缓存提供的 UID,而不是硬编码 UID。

应该使用什么数据?

AMEE 提供可以存储的广泛的数据类型 —— 从家用电器到工业流程,但您可能不想向用户显示整个范围。作为应用程序设计的一部分,您需要只处理可用数据的一个子集,然后您可以识别要使用的 AMEE 类别和数据项。

AMEE 数据 wiki 是实现这个目标的一个有用资源。该资源位于 //wiki.amee.com,包含关于 AMEE 中的所有数据类别的详细信息,这些信息包括每个类别中的项使用的适当参数。它还列示所有数据的来源,以便随时验证那些数据是否可靠。它还包含关于您可能要使用的常用数据子集(如针对一个家用碳计算器的数据子集)的一些建议。

更多控制

还有一些额外参数允许您控制数据的其他方面。最有用的是 times 和 units。这里不作过多介绍,AMEE 文档包含详细信息。


配置文件历史

存储单个配置项目很有用,但大多数数据随时间改变,特别是当您谈论能源用途时。AMEE 允许在存储数据的同时存储时间信息,以便根据时间构建一系列数据点。

有三个参数可用于控制时间信息:startDateendDateduration。通过在创建配置项时提供这些参数,您可以设置创建的配置项的有效期。默认情况下,startDate 是 “现在”,endDate 指无限远的未来。如果您的数据对时间不敏感,则只需使用默认设置。但是,如果您的数据表示特定时间的用途,则需要显式设置这些值。AMEE 平台的最大时间分辨度是 1 分钟,如果指定了秒数,则会四舍五入。注意,您只能在一个配置文件中设置 endDateduration

所有这些参数使用 ISO-8601 格式指定。例如,清单 9 中的参数都是有效的(当格式编码正确时)。

清单 9. 标准 ISO-8601 格式的有效参数
startDate=2009-08-01T14:30:55Z
endDate=2009-08-02T14:30:55-08:00
duration=PT30S

注意,您不是必须设置 endDateduration,即使设置了 startDate;如果您使用不同的 startDates 创建两个项,日期更早的项的 endDate 将自动设置。或者,您也可以在一个配置文件中设置 endDateduration— 一次只能设置一个。

命名配置项

如果您使用相同的数据项 UID 创建了两个配置项,而且时间重叠,那么 AMEE API 将会报错,因为它不能从该数据形成一个合理的时间时序。但是,有时候您的确需要这样做,比如相同类型的两辆车使用的能源。这时候,您可以提供一个名称参数来标识每个系列。您可以通过对每个历史使用不同的名称在相同的配置类别中构建多个历史。名称并不是必需的,但是如果您不确定是否需要存储多个时间序列,最好指定一个名称。

请求配置文件历史

构建一个时间系列后,您可能想要检索历史数据。前面,您看到了包含一列当前配置项的配置文件类别。要修改这个 “present time” 行为,在 GET 请求中提供 startDateendDate 查询参数。您可以请求特定日期之间的所有数据,某个时间之后的所有数据,或者众多其他方法。这些方法中包括一个特殊的按比例模式(pro rata mode),该模式只计算在查询期间内碳的排放量。


单位

如前所述,AMEE 包括对广泛的单位会话的内置支持。大部分单位默认使用 SI (International System of Units),但如果愿意,您也可以以 US 加仑为单位指定燃料。时间单位也可以更改。配置文件中的每个参数都关联到 UnitPerUnit 参数,它们控制数据的单位。例如,如果您想使用默认的燃料单位,您可以使用以下参数添加一个燃料采购:volume=100,这表示每月使用 100 升燃料。

但是,如果您按每周使用的加仑数计算,则需要指定以下参数: volume=100&volumeUnit=gal&volumePerUnit=week.

同样,AMEE 生成的 CO2 排放结果的默认单位是 kg/year。如果您喜欢用 “磅/周”,可以在您的 GET 请求中指定一些特殊的参数:https://stage.amee.com/profiles/7C7D68C2A7CD/home/energy/ quantity?returnUnit=lb&returnPerUnit=week

AMEE 自动处理所有单位会话计算,只需最小的工作量就能为您的应用程序提供正确的结果。


结束语

在本文中,您学习了如何使用 AMEE API 在您的应用程序中嵌入环境智能。本文讨论了 AMEE API 的工作方式,存储数据的方式和位置。如果您想进一步了解它,最好的方法是现在就开始使用它。您将发现大量免费在线文档,它们涉及使用这个 API 的所有方面,提供关于本文提到的所有主题的详细信息。我还将撰写一些文章深入介绍使用 AMEE 创建一个端对端应用程序,在此之前,请您注册 AMEE 平台并进行一些有益的尝试。

参考资料

学习

  • AMEE 主页:了解关于 AMEE 平台和碳排放测量方式的更多信息。
  • 免费 AMEE 访问密匙:注册 AMEE 平台获取访问密匙,迈出使用 AMEE 平台的第一步。
  • AMEE Developer Centre:了解使用 AMEE API 的所有方面。
  • AMEE 数据 wiki:探索 AMEE 服务中使用的数据源、方法体系(比如 Greenhouse Gas Protocol)和假设。
  • IBM Smarter Planet 主页:连接全世界运行的系统,使我们的地球更智能:交通更少、食物更健康、水更清洁、城市更安全。
  • Smart Grid:了解 IBM 如何帮助电力部门向它们的电网添加一个数字智能层。
  • City of Amsterdam Smarter Energy Project:了解 IBM 和 Cisco 如何相互协作,帮助消费者制定更合理的能源消费决策。
  • ISO-8601 on Wikipedia:阅读这个日期和时间表示的国际标准。
  • HTTP on Wikipedia:了解这个应用程序级别的协议的一些背景知识。
  • XML 入门简介(Doug Tidwell,developerWorks,2002 年 8 月):阅读 developerWorks 的这篇经典教程。
  • Ajax 和 REST,第 1 部分(Bill Higgins,developerWorks,2006 年 10 月):了解 Ajax 和 REST 在体验式 Web 应用程序中取得成功的原因。
  • REST:了解这个网络系统架构样式。
  • The GReen IT Report:发现绿色计算资源并构建您的绿色技巧。
  • IBM XML 认证:了解如何才能成为一名 IBM 认证的 XML 和相关技术的开发人员。
  • XML 技术库:访问 developerWorks XML 专区,获得广泛的技术文章和技巧、教程、标准和 IBM 红皮书。
  • developerWorks 技术活动网络广播:随时关注这些活动中的技术。
  • 技术书店:浏览关于这个主题和其他技术主题的图书。
  • developerWorks 播客:收听面向软件开发人员的有趣访谈和讨论。

获得产品和技术

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=XML
ArticleID=433880
ArticleTitle=AMEE 简介
publish-date=10092009