Ruby>> green-button-data>> 返回
项目作者： VerdigrisTech

项目描述 ：
Fast Ruby parser and API client for Green Button data
高级语言： Ruby
项目地址: git://github.com/VerdigrisTech/green-button-data.git
创建时间： 2015-07-30T06:51:18Z
项目社区：https://github.com/VerdigrisTech/green-button-data
开源协议：Other
下载


Green Button Data

Gem Version
CI Results
Code Climate
Code Coverage

Green Button Data is a Ruby gem that can consume Green Button APIs and parse
the Green Button data XML schema very quickly. It uses an event-driven
SAX parser which parses XML data without
building an entire DOM in memory.

On a 2.3 GHz Core i7 processor, this gem is capable of parsing at a rate of
~1.7 MB/s which is fast enough to parse a 1 year 12-hour interval data in just
over a second.

You may run the benchmarks by cloning this project and running rake benchmark.

Getting Started

Add the Green Button Data gem to your Gemfile:

  1. gem 'green-button-data'

Then run Bundler:

  1. $ bundle

Unless you have a project that auto loads all gems in the Gemfile (e.g. a Rails
project), you will need to require it:

  1. require 'green-button-data'

This will expose the GreenButtonData module namespace.

Integrating GreenButtonData Into Your Application

GreenButtonData gem provides a familiar interface to consuming API endpoints.
Method names are similar to Rails’ ActiveRecord models and can be easily
integrated into existing applications.

Global Configuration

You can add configuration options like the following:

  1. GreenButtonData.configure do |config|
  2.   config.base_url = "https://api.example.com/DataCustodian/espi/1_1/resource/"
  3.   config.application_information_path = "ApplicationInformation/"
  4.   config.authorization_path = "Authorization/"
  5.   config.subscription_path = "Subscription/"
  6.   config.usage_point_path = "UsagePoint/"
  7. end

Note that each path must end with a trailing slash.

Rails Integration

IMPORTANT: Version 0.3.0 has a bug which causes Rails not to boot
correctly. Please use 0.3.1 or higher when integrating into Rails by
running bundle update green-button-data.

If you are developing a Rails app, create a file at
config/initializers/green_button_data.rb from your Rails project root and
add the configuration there.

Green Button Data API Client

Green Button Data specification states that all API endpoints be secured with
OAuth2 which means most fetch operations will require auth tokens.

Some endpoints are secured further by utilizing client SSL certificates (e.g.
Pacific Gas & Electric). You may pass in ssl options in addition to
the token option in this case.

DISCLAIMER: Green Button Data is NOT responsible for managing OAuth
tokens to make authenticated requests. There are other gems that provide mature,
production proven OAuth 2 functionalities such as OmniAuth.

Querying Data

With version 0.4.0, there are two ways to query data on a remote endpoint:

  • Using a scoped client class
  • Calling query methods directly on resource classes

Using API Client class

This is the recommended method to query data from multiple
Data Custodians.

Each instance of GreenButtonData::Client uses scoped configuration suitable
for each Data Custodians.

This allows you to make requests to different Data Custodians that have
different URL path layouts.

The example below creates two clients: one for
ESPI Green Button Data reference API and the other for Pacific Gas & Electric:

  1. espi_base_url   = "https://services.greenbuttondata.org/DataCustodian/espi/" +
  2.                   "1_1/resource/"
  3. pge_base_url    = "https://api.pge.com/GreenButtonConnect/espi/1_1/resource/"
  5. espi_client = GreenButtonData.connect base_url: "https://foo.com" do |client|
  6.   # Override base_url configuration
  7.   client.configuration.base_url = espi_base_url
  9.   # Equivalent to passing in as an argument hash in connect method:
  10.   # GreenButtonData.connect subscription_path: "Subscription/" do |client|
  11.   client.configuration.subscription_path = "Subscription/"
  13.   client.configuration.usage_point_path = "UsagePoint/"
  14.   client.configuration.usage_summary_path = "ElectricPowerUsageSummary/"
  16.   # Set OAuth 2.0 bearer token
  17.   client.token = "12345678-5672-abcd-567890abcdef"
  18. end
  20. pge_client = GreenButtonData.connect base_url: pge_base_url do |client|
  21.   client.configuration.subscription_path = "Subscription/"
  22.   client.configuration.usage_point_path = "UsagePoint/"
  23.   client.configuration.usage_summary_path = "UsageSummary/"
  25.   client.token = "098765432-abcd-ef00-12345678900"
  26. end
Querying a resource

The Client class provides query methods to query each resources:

  • GreenButtonData::Client#application_information

    Returns a collection of GreenButtonData::ApplicationInformation instances if
    id is not specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#authorization

    Returns a collection of GreenButtonData::Authorization instances if id is
    not specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#interval_block

    Returns a collection of GreenButtonData::IntervalBlock instances if id is
    not specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#local_time_parameters

    Returns a collection of GreenButtonData::LocalTimeParameters instances if id
    is not specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#meter_reading

    Returns a collection of GreenButtonData::MeterReading instances if id is not
    specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#reading_type

    Returns a collection of GreenButtonData::ReadingType instances if id is not
    specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#usage_point

    Returns a collection of GreenButtonData::UsagePoint instances if id is not
    specified. If id is specified, returns a single instance.

  • GreenButtonData::Client#usage_summary

    Returns a collection of GreenButtonData::UsageSummary instances if id is not
    specified. If id is specified, returns a single instance.

Following the example from previous section, to retrieve all entries:

  1. # Generally, Data Custodian access token is required to do this query which you
  2. # can override with `token` keyword argument
  3. # Makes a request to:
  4. # https://services.greenbuttondata.org/DataCustodian/espi/1_1/resources/UsagePoint
  5. espi_all_usage_points = espi_client.usage_point

To retrieve a specific entry, specify the resource ID:

  1. # Get a Usage Point 2
  2. # Makes a request to:
  3. # https://services.greenbuttondata.org/DataCustodian/espi/1_1/resources/UsagePoint/2
  4. espi_usage_point = espi_client.usage_point 2, token: data_custodian_access_token
  6. # Get a UsagePoint 1234 for subscription 3401
  7. # Makes a request to:
  8. # https://api.pge.com/GreenButtonConnect/espi/1_1/resources/Subscription/3401/UsagePoint/1234
  9. pge_usage_point = pge_client.usage_point 1234, subscription_id: 3401

You can query for related resources as well. There are couple ways you can do
this:

  1. # Gets all meter readings for this instance of UsagePoint
  2. meter_readings_1 = pge_usage_point.meter_readings
  4. # Same as above but requires knowledge of UsagePoint and Subscription ids
  5. meter_readings_2 = pge_client.meter_reading usage_point_id: 1234, subscription_id: 3401

Using resource classes

This method allows you to query for data using the global configuration. This
has limitations as you can only query data from one Data Custodian at a time
unless you override the global configuration per method call.

The resource classes are as follows:

  • GreenButtonData::ApplicationInformation
  • GreenButtonData::Authorization
  • GreenButtonData::IntervalBlock
  • GreenButtonData::LocalTimeParameters
  • GreenButtonData::MeterReading
  • GreenButtonData::ReadingType
  • GreenButtonData::UsagePoint
  • GreenButtonData::UsageSummary
List all entries

By default, the .all method attempts to use the URL path set by configuration:

  1. require 'green-button-data'
  3. # Ideally obtained from OmniAuth gem
  4. access_token = "12345678-1024-2048-abcdef001234"
  6. # Return all usage points; URL is specified in GreenButtonData.configuration.usage_point_url
  7. usage_points = UsagePoint.all token: access_token

You may override the global configuration by specifying the URL in the method:

  1. usage_points = UsagePoint.all "https://someotherapi.org/espi/Authorization",
  2.                               token: access_token
Find an entry by ID

If you have URL defined in configuration, the .find method appends the ID to
the URL:

  1. GreenButtonData.configure do |config|
  2.   config.base_url = "https://services.greenbuttondata.org/"
  3.   config.usage_point_path = "DataCustodian/espi/1_1/resource/UsagePoint/"
  4. end
  6. # GET request to https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/UsagePoint/2
  7. usage_point = GreenButtonData::UsagePoint.find 2, token: access_token

As with .all method, URL can be overridden per request in .find:

  1. usage_point = GreenButtonData::UsagePoint.find "https://someotherapi.org/espi/UsagePoint/1",
  2.                                                token: access_token

Parsing

Almost all of the functionality for parsing data is wrapped in the
GreenButtonData::Feed class.

To parse a Green Button Atom feed, simply call the parse method and pass in
the entire XML document:

  1. require 'green-button-data'
  3. xml_text = File.read "#{File.dirname __FILE__}/gb_example_interval_block.xml"
  4. data = GreenButtonData::Feed.parse xml_text

You can then access the data like this:

  1. # Print all the interval readings from the feed
  2. data.entries.each do |entry|
  3.   p "Entry: #{entry.title}"
  4.   entry.content.interval_block.interval_readings.each do |reading|
  5.     time_period = reading.time_period
  6.     p "[#{time_period.starts_at} - #{time_period.ends_at}]: #{reading.value}"
  7.   end
  8. end

Contributing

  1. Fork this project
  2. Create a feature branch: git checkout -b my-awesome-feature
  3. Make changes and commit: git commit -am "Add awesome feature"
  4. Push the branch: git push origin my-awesome-feature
  5. Submit a pull request

Versioning

Green Button Data gem follows Semantic Versioning 2.0. As
such, you can specify a pessimistic version constraint on this gem with two
digits of precision and be guaranteed latest features and bug fixes without
backwards breaking changes:

  1. gem 'green-button-data', '~> 0.1'

Exception to this rule as per the SemVer specification is major version zero for
initial development. This gem’s API should NOT be considered stable until 1.0
release.

License

This software is distributed AS IS WITHOUT WARRANTY under Simplified BSD
license.

Verdigris Technologies Inc. assumes NO RESPONSIBILITY OR LIABILITY
UNDER ANY CIRCUMSTANCES for usage of this software. See the LICENSE.txt
file for detailed legal information.

📣 We’re Hiring!

Do you have passion for solving challenging engineering problems? You may just be the right fit at Verdigris! We are hiring software engineers for our Mountain View, California, USA office.

Open Positions

For more information, check out our Careers page.

Copyright © 2015-2020, Verdigris Technologies Inc. All rights reserved.