Hatena::ブログ(Diary)

TAKUYA’s CODE RECORDER このページをアンテナに追加 RSSフィード

2009-06-25

AMEE API / Creating A Profile Item

|

http://my.amee.com/developers/wiki/CreatingAProfileItem

  • Overview
    • Profilesの中のProfileItemsをメンテナンスすることは、AMEEの基本的な機能
      • ユーザーやAMEE APIの活動は、ProfileやProfileCategory、ProfileItemのエンティティとの相互連携に焦点があてられている
    • このページでは、ProfileItemの作成方法や、AMEE APIを使ってProfileへ保管する方法について述べる
  • Steps
    • 適切なDataItemを見つける
      • 適切なDataItemを見つけ、そのUIDをProfileItem生成時に利用する
      • 見つけ方は、DataCategoriesをブラウズするか、ドリルダウン機能を使う
      • 具体例が掲載されている
    • 適切なProfileCategoryを見つける
      • ProfileCategoryは、選択したDataItemが属しているDataCategoryと一致する
      • 例えば、'Lighting'というDataCategoryのURLが'/data/home/lighting'だとすると、'Lighting'のProfileCategoryは、'/profiles/CD856C3E44F5/home/lighting'になるだろう('CD856C3E44F5'はProfileを示す)
    • DataItemのUIDを使って、ProfileCategoryResourceへProfileItemをPOSTする
      • ProfileItemsは、適切なProfileCategoryResourceと連携しながら作成される
      • 'dataItemUid=CF5529D388A0'を'/profiles/6953209126F6/home/lighting'にPOSTすることで、新しいProfileItemを作成することができる
      • その時に返ってくるレスポンスの具体例が掲載されている
    • 必要ならばProfileItemValuesを更新する
      • ProfileItemResourceやProfileItemValueResourceのドキュメントを参照

2009-06-24

AMEE API / Authentication

|

http://my.amee.com/developers/wiki/Authentication

  • Overview
    • AMEE APIをインターフェイスとして使う前に、認証を得る必要がある
    • 認証を得るためには、2つの方法がある
      • HTTP Basic authentication
      • authenticated sessions
  • HTTP Basic
    • AMEEの認証を得る最もシンプルな方法は、リクエスト毎にログイン情報も送ることだ
      • HTTPの基本的なログインメソッドを使って
      • 例えば、curlを使う
      • curl http://stage.amee.com/data -H "accept:application/xml" -u username:password
    • リクエスト毎にログイン情報を送るので、この方法はHTTPSコネクションの場合のみ利用すべき
    • authenticated session methodと比べたら、APIのパフォーマンスは良くない可能性がある
  • Authenticated Sessions
    • 認証されたセッションを作った場合、the '/auth' API resourceからauthTokenを要求する必要がある
      • URL: http://{server}/auth
      • Method: POST
      • Request format: application/x-www-form-urlencoded
      • Response format: application/xml, application/json
      • Response code: 200 OK
      • Response body: Details of the authenticated user, including API version.
      • Extra data: "authToken" cookie and header, containing the authentication token that should be used for subsequent calls.
      • その他、パラメータ
    • 一度、authTokenを取得すれば、その後のリクエストでは、ログイン情報を全て送る必要はなく、そのトークンだけが必要となる
      • そのトークンを、"authToken"というcookie名称の中に入れなければならない
    • Session Duration
      • セッションが持続する時間は限られている
      • 最大時間は2時間
      • アイドル時間の最大時間は30分
      • 認証が失敗したら、再度、認証させるようなロジックを組むことが重要
      • トークンの期限切れとなったら、APIは401ステータス(UNAUTHORIZED)を返す
    • この後、参考例あり

2009-06-23

AMEE API / API Operations

|

AMEEのAPIページを読み進めていますが、いろいろと勉強しなければならない部分を見つけました。まずは、RESTfulなAPIの使い方について、その背景なんかも交えながら学んでいこうと思います。

http://my.amee.com/developers/wiki/ApiOperations

  • Overview
    • AMEEのリソース
      • AMEE API経由で利用可能
      • 親切なRESTianスタイルなURLsを使える
      • 標準的なHTTPメソッド(GET/POST/PUT/DELETE)で操作する
    • リソースのid
      • AMEEの多くのリソースはunique ID(UID)によって分類(identified)される
      • これらのUIDは、APIのレスポンスとともに返ってくる
      • 他のAPI操作において使うこともできる
  • Fetching resources (GET method)
    • 全てのリソースはHTTPのGETメソッドを使ってフェッチされる
      • RESTian規約に従って、リソースは階層的なURL構造になっている
    • GETメソッドだけでは、リソースを操作することはできない
      • 他のHTTPメソッドが、リソースの生成・編集・削除のために使われる
    • 階層情報をフェッチする方法
      • URL階層のより深いリソースをフェッチしなければならない時もある
      • 全てのリソースは、上位階層・下位階層へ移動するために必要な情報を持っている
    • 例えば
      • DataCategoryリソースは、他のDataCategoriesやDataItemsから構成されている
      • DataCategoryをフェッチした後、レスポンス情報を使って、下位のリソースへナビゲートすることが可能になる
    • URLのアーキテクチャ
  • Creating new resources (POST method)
    • リソースは、HTTPのPOSTメソッドを使って生成される
    • ほとんどのリソースは、親のリソースにPOSTingすることによってのみ生成される
      • 例えば、新しいProfileItemを追加したい場合、親となるProfileCategoryにポストする必要がある
    • POSTメソッドをサポートしているリソースは、受入可能なパラメータの定義セットを持っている
      • 例えば、nameやvalue
      • 新しいリソースをPOSTingした後は、このwikiで書かれている通り、URL規約にしたがって、新しいURLが利用可能となる
    • POSTすると、関連するHTTPのステータスコードが返ってくる
      • 制限のある(limited)XMLやJSONを返すこともある
  • Modifying resources (PUT method)
    • リソースは、HTTPのPUTメソッドで修正することができる
      • 全てのリソースが変更できるわけではない
      • 権限がある場合のみ修正することができる
    • リソースは、ユニークなURLを使えば、PUTによって直接修正される
      • 受入可能なパラメータの定義セットを持っていることもある
    • いくつかのリソースは、他のプロセスやAPIコールによって修正される
      • 例えば、コアなCO2値を表現しているDataItemが修正されたら、ProfileItemのような、それに関連するアイテムも変更されるだろう
    • PUTすると、関連するHTTPのステータスコードが返ってくる
      • 制限のある(limited)XMLやJSONを返すこともある
  • Deleting resources (DELETE method)
    • リソースは、ユニークなURLを使えば、HTTPのDELETEメソッドで削除することができる
      • 全てのリソースが削除できるわけではない
      • 権限がある場合のみ削除することができる
    • リソースを削除した時
      • 関連する全てのリソースも削除される
      • 他の関連あるリソースは変更される
      • 例えば、ProfileItemを削除したら、関連する全てのProfileItemValuesも削除される
    • DELETEすると、関連するHTTPのステータスコードが返ってくる

AMEE API / Media Types

|

http://my.amee.com/developers/wiki/MediaTypes

  • AMEEにとって、media typesは重要だ(sensitive/影響を受けやすい?)
    • クライアント側の'Accept'ヘッダーは検査され、それに適したレスポンスが生成される
    • 下記のMediaTypesがサポートされている
      • text/html
      • application/json
      • application/xml
    • jsonやxmlを使うときは、それを'Accept'ヘッダに明記する必要がある
      • デフォルトのMediaTypeはtext/html
    • 将来的には、XMLやJSONでリクエストを送れるようにするため、'Content-Type'ヘッダも重要になる

AMEE API / Calculation

|

http://my.amee.com/developers/wiki/Calculation

  • AMEEのAPIは二酸化炭素の排出量を算出する計算機として振る舞う
    • APIには、以下の3つのパーツがある
      • ProfileAPIの中にあるProfileItemResource
      • ProfileAPIの中にあるProfileCategoryResource
      • DataAPIの中にあるDataItemResource
    • それぞれのResouceページを見れば、計算機がどのように振る舞うのかを学べる
    • データの保管場所
      • 計算された二酸化炭素の量は、ProfileItemsのみに保管される
      • Profiles/ProfileCategoriesは履歴情報を持つことができるので、ここに二酸化炭素の量を保管するのは合理的ではない
    • 計算機で使われるデータ
      • ItemDefinitions/ItemValueDefinitions/DataItems/DataItemValues/ProfileItems/ProfileItemValues/Algorithms

2009-06-21

AMEE API / AMEE Concepts

|

AMEEのAPIについて調べていきたいと思います。このページの「API Manual」を一つずつ読んでいこうと考えています。今回は、先頭の「AMEE Concepts」です。詳細については理解が微妙な部分もありましたが、それらについては、詳細資料を見つつ、実際に動かしてみればわかるのではないかと感じています。

http://my.amee.com/developers/wiki/AmeeConcepts

  • Overview
    • Profileとは
      • AMEEは、CO2排出量をProfileの一部として計算し保管しているウェブアプリケーション
      • Profileは、個人やグループ、組織や他のエンティティに属している
      • ProfileとProfileItemsは、AMEEの中の重要なエンティティ
  • Profiles, Profile Items & Profile Item Values
    • Profiles
      • 様々なProfileItemsのCO2排出量をトラックする
    • ProfileItems
      • それぞれのProfileItemが車/航空機/冷蔵庫などを意味する
      • つまり、CO2排出量に影響を与える要素の全て
      • それぞれのProfileItemのCO2排出量は、AMEEによって個別に算出される
      • 使っている電球の個数などといった、付随的な情報も持てる
      • これらの値は、ProfileItemValueのレコードして保管される
    • CO2換算処理をする時
      • ProfilesやProfileItemsに関連する様々なエンティティを使う
      • DataItemsやItemDefinitions、Algorithmsがそれに当たる
  • Profile History
    • それぞれのProfileは履歴情報を持てる
      • これによって、指定した日時におけるProfileの状態を参照することができる
      • あるProfileについて、異なる時期の間で比較することが可能になる
    • 詳細はこちら : http://my.amee.com/developers/wiki/ProfileHistory
  • Data Categories, Data Items & Data Item Values
    • DataItems
      • それぞれのProfileItemは、一つのDataItemに関連づけられている
      • DataItemは、そのProfileの中で計測可能な、独立したitem
      • 例えば、移動手段(英国のタクシー)やアプライアンス(A++評価の冷蔵庫)
      • ProfileItemを作成する時に、関連させるDataItemを指定しなければならない
      • つまり、この時点で、冷蔵庫や電球のタイプを宣言するわけだ
    • DataItemValues
      • DataItemは、排出量を計算するために必要な正確な値を保持している
      • 例えば、A++評価冷蔵庫の電気使用量(KWh)
      • こららの値はDataItemValueのレコードして保管される
    • DataCategories
  • Item Definitions, Item Value Definitions, Value Definitions & Algorithms
    • defenitions
      • DataItemsやProfileItems、それらのValuesを作成し、使う前にやるべきことがある
      • それは、それらが表しているものが何かを明確にすることだ
      • これらは、ItemDefinition/ItemValueDefinition/ValueTypeのエンティティ経由で行なわれる
    • ItemDefinition
      • DataItemsやProfileItemsが保持できる情報は何かについての詳細
    • ItemValueDefinition
      • DataItemValueやProfileItemValueの中の個々の値についての詳細
    • Algorithms
      • ItemDefinitionsはいくつものAlgorithmsを持つことができる
      • 現時点でAMEEによって実装されている唯一のAlgorithmは、「perMonth」と呼ばれているもの
      • Algorithmsは、ProfileItemのCO2排出量を計算するために必要な特別な計算ロジックを保持している
  • AMEE Entity Diagram

2009-06-20

AMEE仕様・API概要

|

AMEEがどんなAPIを提供しているのかについてのページを読みました。こういったAPIを今まで使ったことがなかったので、良い勉強なりそうです。

http://my.amee.com/developers/

  • システム全体像
  • 概要
    • AMEEは、エネルギー消費量を測定するための中立でオープンなプラットフォーム
    • このプラットフォームは、XML/JSON/Atomのインターフェイスを利用するRESTfulなHTTP-basedのウェブサービス
  • Getting Started
    • 初期設定
      • 次のURLからAMEEにSignupする : http://my.amee.com/signup/
      • username/password/URLがemailで送られてくる
      • 送られてきたURLにアクセスすると、ビルドインされたUIからAMEEをブラウズすることができる
      • このURLは、コードの中に書くURLと全く同じなので、中身を知るのに役立つだろう
    • APIでできること
      • 様々なエネルギーデータを保管することができる
      • 厳格に測定された電気の使用量から、一般的な計算方法で算出されたビル全体の排出量まで
      • AMEEにデータを保管するためには、Profileにデータを追加する必要がある
      • APIは、それぞれのProfileItemを計算し、ビルドインされている排出量ファクターと提供されたデータから二酸化炭素の排出量を算出する
      • (ProfileItemについては要調査、ここに説明がありそう -> http://my.amee.com/developers/wiki/ProfileItem)
    • APIの説明
      • このページに下部にあるドキュメントで、AMEEのAPIを説明している
      • (サンプルコードとかもある)
  • Act On CO2
  • 以下、今後の調査のためのメモ

AMEE仕様・Carbon dioxide emissions

|

大気中の二酸化炭素濃度の上昇に影響を与えているのは何か、というところから始まり、何を測定して、何を減らすべきか、測定するためにはどうすればいいのか、と話が進んでいく資料です。

読んでいて感じたことは、そもそも二酸化炭素の排出量の正確な値を算出することは難しく、そんな指標をベースにして、金銭的な問題が絡む排出権取引や炭素税を導入することが可能なのかということです。やるにしてもルール作りが大切なんだろうし、やってみなければ問題点も見えてこないんだろうなとも感じました。あまり厳密に排出量の測定をやりすぎても、無駄なコストを省くどころか、かえって工数や経費がかさみ、良い結果は得られないのではないかと思いました。

このAMEEのwikiを読み進めていけば、どのような炭素の計算手法があるのかを知ることができそうなので、続けて調査を行なっていきたいと思っています。

no title

  • Intro
    • 大気中の二酸化炭素濃度の上昇に伴って、世界の平均気温は上昇傾向にある
      • 人間の活動の結果によって、二酸化炭素の濃度が上昇していると考えられている
    • AMEEデータの仮定を理解するためには
      • 直接排出と間接排出の違いを理解することが重要
      • 化石燃料を燃やすことは、二酸化炭素濃度の上昇を引き起こす大きな要因だということを認識すべき
  • Fossil fuels
    • 二酸化炭素の排出
      • 自然なことであり、回避不可能なプロセス
      • 人は二酸化炭素を吐き出す
      • 森林火災でも発生するし、植物も夜間は吐き出す
      • しかし、これらによって発生した二酸化炭素は、大気中から比較的早くなくなるので、濃度の上昇を引き起こすようなことはない
    • 森林の役割
      • 昼間は、二酸化炭素を大気から除外している
      • 木の中に、様々な炭素の分子として蓄えられる
      • もし木が燃やされたら、炭素の分子は、酸素と結合し、二酸化炭素として大気に放出される
      • 我々が食べるものの中には、それらの炭素の分子が含まれている
      • それが、呼吸とともに吐き出され、また森林が吸収する
    • 濃度の変化
      • 長い間、これらのプロセスは安定していた(吸収と排出がバランスしていた)
      • 大気中の二酸化炭素の量も変化していなかった
    • 化石燃料
      • 何百万年の時を経て、生物の死骸から構成される物質は地下に埋められ、カーボンサイクルから除外されてきた
      • これらの物質は、石油や石炭、ガスへと姿を変えていった
      • このような化石燃料を掘り出し、それらを燃やし、電力などを得ている
      • ここ最近は、排出された二酸化炭素が大気から除去されていない
      • カーボンサイクルのバランスが崩れ、それが濃度上昇を引き起こしていると考えられている
    • 重要なポイント
      • 人間の呼吸、森林火災、植物油による運転
      • これらによる二酸化炭素の排出が、問題の原因になっているわけではない
      • 問題は、化石燃料の燃焼によって引き起こされている
  • Direct vs indirect emission
    • "直接"排出
      • 化石燃料の燃焼によって、二酸化炭素が"直接"排出される
      • 部屋を暖めるために木を燃やしたり、車を動かすために植物油を燃やしても、わずかに二酸化炭素を排出するが、カーボンサイクルに影響を与えるようなことはない
      • これらは、"直接"排出はゼロと考えてもいい
      • しかし、"間接"排出している可能性はある
    • "間接"排出
      • 部屋を燃やすための木を運ぶために、化石燃料からパワーを得たトラックを使っているかもしれないし、木を伐採するときに、化石燃料によって動いている機器を使っているかもしれない
      • 例え、自分で植物油を作り、それで車を運転したとしても、その車そのものの製造で化石燃料の燃焼が関わっているかもしれない
    • AMEEの立ち位置
      • 基本的には、"間接"排出はAMEEのデータに含めない
      • 例外は、電力や個人的な所有物の利用による排出
      • 1リットルの石油を燃焼することによって排出される二酸化炭素の量の中には、タンカーによる運送で使われた"間接"的な排出量は含まれない
      • "間接"排出を除外する理由は、個々人の状況に応じて、正確に予測・算出するのが難しいからだ
  • Uncertainties in estimating carbon dioxide emissions
    • 二つの潜在的な不確実性
      • ユーザーより提供されたデータに間違いがあること
      • profileItem/dataItem/algorithmの仮定が正しいかどうか
    • どう防ぐか
      • 一つ目については、やれることは少ない
      • 二つ目については、不確実性を減らすためにできることはある
      • AMEEのデータが設定している仮定を理解すること、ユーザーへ問いかけるときの言葉に注意することが大事
    • 正確な炭素計算を行なうために必要な質問の例
      • 何KWhの電気を一ヶ月に使ったか、サプライヤーはどこか
      • 部屋を暖めるために一ヶ月にどのくらいのgas/oil/coalを使ったか
      • 車を運転するために一ヶ月に何リットルのpetrol/dieselを使ったか
    • 炭素計算機の目的
      • 個々の二酸化炭素の排出量を正確に算出することではない
      • ライフスタイルにおけるどの要素が、二酸化炭素の排出に最も大きな影響を与えているのか
      • 最も多く削減することができるアクションは何なのか
      • そんな気付きを与えることが目的
    • ユーザーへの質問の仕方
      • もし、運転するために使った燃料の量を問わず、月間の走行距離を聞いたら、もっと多くの情報をユーザーから聞き出さなければならなくなるだろう
      • 車の大きさが異なれば、燃費も異なる(小さな車なら、大きな車の半分の燃料で同じ距離を走れることもある)
      • さらに、どこを走ったか(都心か、郊外か)、どんな走り方をしたか(ゆっくりか、飛ばしたか)、といったことも聞かなければならなくなる
      • 質問の仕方によっては、質問すべき項目が多くなってしまう
      • なので、良い炭素計算機を作るためには、結果の正確性と結果を得るために必要なデータ量との間のどこかで妥協する必要がある
    • 炭素計算機を設計する際の注意点
      • 質問項目が多くなり、実装が複雑になってしまうことは、珍しいことではない
      • なので、質問項目を減らしたいという誘惑が起こるかもしれない
      • しかし、質問項目を減らすことは、仮定を増やすことになり、計算機の実装が複雑になり、結果の正確性が失われていくことになる