AMEE API / Creating A Profile Item
http://my.amee.com/developers/wiki/CreatingAProfileItem
- Overview
- 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のドキュメントを参照
- 適切なDataItemを見つける
AMEE API / Authentication
http://my.amee.com/developers/wiki/Authentication
- Overview
- HTTP Basic
- 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を取得すれば、その後のリクエストでは、ログイン情報を全て送る必要はなく、そのトークンだけが必要となる
- Session Duration
- この後、参考例あり
- 認証されたセッションを作った場合、the '/auth' API resourceからauthTokenを要求する必要がある
AMEE API / Calculation
http://my.amee.com/developers/wiki/Calculation
- AMEEのAPIは二酸化炭素の排出量を算出する計算機として振る舞う
- APIには、以下の3つのパーツがある
- ProfileAPIの中にあるProfileItemResource
- ProfileAPIの中にあるProfileCategoryResource
- DataAPIの中にあるDataItemResource
- それぞれのResouceページを見れば、計算機がどのように振る舞うのかを学べる
- データの保管場所
- 計算機で使われるデータ
- ItemDefinitions/ItemValueDefinitions/DataItems/DataItemValues/ProfileItems/ProfileItemValues/Algorithms
- APIには、以下の3つのパーツがある
AMEE API / API Operations
AMEEのAPIページを読み進めていますが、いろいろと勉強しなければならない部分を見つけました。まずは、RESTfulなAPIの使い方について、その背景なんかも交えながら学んでいこうと思います。
http://my.amee.com/developers/wiki/ApiOperations
- Overview
- Fetching resources (GET method)
- 全てのリソースはHTTPのGETメソッドを使ってフェッチされる
- RESTian規約に従って、リソースは階層的なURL構造になっている
- GETメソッドだけでは、リソースを操作することはできない
- 他のHTTPメソッドが、リソースの生成・編集・削除のために使われる
- 階層情報をフェッチする方法
- URL階層のより深いリソースをフェッチしなければならない時もある
- 全てのリソースは、上位階層・下位階層へ移動するために必要な情報を持っている
- 例えば
- DataCategoryリソースは、他のDataCategoriesやDataItemsから構成されている
- DataCategoryをフェッチした後、レスポンス情報を使って、下位のリソースへナビゲートすることが可能になる
- URLのアーキテクチャ
- 全てのリソースはHTTPのGETメソッドを使ってフェッチされる
- Creating new resources (POST method)
- リソースは、HTTPのPOSTメソッドを使って生成される
- ほとんどのリソースは、親のリソースにPOSTingすることによってのみ生成される
- 例えば、新しいProfileItemを追加したい場合、親となるProfileCategoryにポストする必要がある
- POSTメソッドをサポートしているリソースは、受入可能なパラメータの定義セットを持っている
- POSTすると、関連するHTTPのステータスコードが返ってくる
- Modifying resources (PUT method)
- Deleting resources (DELETE method)
- リソースは、ユニークなURLを使えば、HTTPのDELETEメソッドで削除することができる
- 全てのリソースが削除できるわけではない
- 権限がある場合のみ削除することができる
- リソースを削除した時
- 関連する全てのリソースも削除される
- 他の関連あるリソースは変更される
- 例えば、ProfileItemを削除したら、関連する全てのProfileItemValuesも削除される
- DELETEすると、関連するHTTPのステータスコードが返ってくる
- リソースは、ユニークなURLを使えば、HTTPのDELETEメソッドで削除することができる
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の中の重要なエンティティ
- Profileとは
- Profiles, Profile Items & Profile Item Values
- Profiles
- 様々なProfileItemsのCO2排出量をトラックする
- ProfileItems
- それぞれのProfileItemが車/航空機/冷蔵庫などを意味する
- つまり、CO2排出量に影響を与える要素の全て
- それぞれのProfileItemのCO2排出量は、AMEEによって個別に算出される
- 使っている電球の個数などといった、付随的な情報も持てる
- これらの値は、ProfileItemValueのレコードして保管される
- CO2換算処理をする時
- ProfilesやProfileItemsに関連する様々なエンティティを使う
- DataItemsやItemDefinitions、Algorithmsがそれに当たる
- Profiles
- Profile History
- それぞれのProfileは履歴情報を持てる
- これによって、指定した日時におけるProfileの状態を参照することができる
- あるProfileについて、異なる時期の間で比較することが可能になる
- 詳細はこちら : http://my.amee.com/developers/wiki/ProfileHistory
- それぞれのProfileは履歴情報を持てる
- Data Categories, Data Items & Data Item Values
- DataItems
- それぞれのProfileItemは、一つのDataItemに関連づけられている
- DataItemは、そのProfileの中で計測可能な、独立したitem
- 例えば、移動手段(英国のタクシー)やアプライアンス(A++評価の冷蔵庫)
- ProfileItemを作成する時に、関連させるDataItemを指定しなければならない
- つまり、この時点で、冷蔵庫や電球のタイプを宣言するわけだ
- DataItemValues
- DataItemは、排出量を計算するために必要な正確な値を保持している
- 例えば、A++評価冷蔵庫の電気使用量(KWh)
- こららの値はDataItemValueのレコードして保管される
- DataCategories
- 似たようなDataItemsはカテゴリー化される
- 例えば、車/航空機/タクシーは"Transport"カテゴリーに分類される
- これらのカテゴリーをAMEEでは、DataCategoryと表現している
- カテゴリー同士をネスト化することができる
- 詳細はこちら(URLアーキテクチャ) : http://my.amee.com/developers/wiki/UrlArchitecture
- ProfileItemsとProfileCategoriesの関係も、これと同じである
- DataItems
- 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排出量を計算するために必要な特別な計算ロジックを保持している
- defenitions
- AMEE Entity Diagram
AMEE仕様・Carbon dioxide emissions
大気中の二酸化炭素濃度の上昇に影響を与えているのは何か、というところから始まり、何を測定して、何を減らすべきか、測定するためにはどうすればいいのか、と話が進んでいく資料です。
読んでいて感じたことは、そもそも二酸化炭素の排出量の正確な値を算出することは難しく、そんな指標をベースにして、金銭的な問題が絡む排出権取引や炭素税を導入することが可能なのかということです。やるにしてもルール作りが大切なんだろうし、やってみなければ問題点も見えてこないんだろうなとも感じました。あまり厳密に排出量の測定をやりすぎても、無駄なコストを省くどころか、かえって工数や経費がかさみ、良い結果は得られないのではないかと思いました。
このAMEEのwikiを読み進めていけば、どのような炭素の計算手法があるのかを知ることができそうなので、続けて調査を行なっていきたいと思っています。
http://wiki.amee.com/index.php/Carbon_dioxide_emissions
- Intro
- Fossil fuels
- Direct vs indirect emission
- "直接"排出
- "間接"排出
- AMEEの立ち位置
- 基本的には、"間接"排出はAMEEのデータに含めない
- 例外は、電力や個人的な所有物の利用による排出
- 1リットルの石油を燃焼することによって排出される二酸化炭素の量の中には、タンカーによる運送で使われた"間接"的な排出量は含まれない
- "間接"排出を除外する理由は、個々人の状況に応じて、正確に予測・算出するのが難しいからだ
- Uncertainties in estimating carbon dioxide emissions
- 二つの潜在的な不確実性
- ユーザーより提供されたデータに間違いがあること
- profileItem/dataItem/algorithmの仮定が正しいかどうか
- どう防ぐか
- 一つ目については、やれることは少ない
- 二つ目については、不確実性を減らすためにできることはある
- AMEEのデータが設定している仮定を理解すること、ユーザーへ問いかけるときの言葉に注意することが大事
- 正確な炭素計算を行なうために必要な質問の例
- 炭素計算機の目的
- ユーザーへの質問の仕方
- もし、運転するために使った燃料の量を問わず、月間の走行距離を聞いたら、もっと多くの情報をユーザーから聞き出さなければならなくなるだろう
- 車の大きさが異なれば、燃費も異なる(小さな車なら、大きな車の半分の燃料で同じ距離を走れることもある)
- さらに、どこを走ったか(都心か、郊外か)、どんな走り方をしたか(ゆっくりか、飛ばしたか)、といったことも聞かなければならなくなる
- 質問の仕方によっては、質問すべき項目が多くなってしまう
- なので、良い炭素計算機を作るためには、結果の正確性と結果を得るために必要なデータ量との間のどこかで妥協する必要がある
- 炭素計算機を設計する際の注意点
- 質問項目が多くなり、実装が複雑になってしまうことは、珍しいことではない
- なので、質問項目を減らしたいという誘惑が起こるかもしれない
- しかし、質問項目を減らすことは、仮定を増やすことになり、計算機の実装が複雑になり、結果の正確性が失われていくことになる
- 二つの潜在的な不確実性
