Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/treasure-data/td-client-ruby

Ruby Client Library for Treasure Data
https://github.com/treasure-data/td-client-ruby

Last synced: 3 months ago
JSON representation

Ruby Client Library for Treasure Data

Awesome Lists containing this project

README 

        
# Treasure Data API library for Ruby



[Coverage Status](https://coveralls.io/github/treasure-data/td-client-ruby?branch=master)



## Getting Started



    > gem install td-client



### Running Tests



    > gem install jeweler

    > gem install webmock

    > rake spec



## Configuration



The Client API library constructor supports a number of options that can

be provided as part of the optional 'opts' hash map to these methods:



- `initialize`(apikey, opts={}) (constructor)

- `Client.authenticate`(user, password, opts={}) (class method)

- `Client.server_status`(opts={}) (class method)



### Endpoint



Add the `:endpoint` key to the opts to provide an alternative endpoint to make

the API calls to. Examples are an alternate API endpoint or a static IP address

provided by Treasure Data on a case-by-case basis.



The default endpoint is:



    https://api.treasuredata.com



and configure communication using SSL encryption over HTTPS; the same happens

every time the provided endpoint is prefixed by 'https'.



E.g.



    opts.merge({:endpoint => "https://api-alternate.treasuredata.com"})



The endpoint can alternatively be provided by setting the `TD_API_SERVER`

environment variable. The `:endpoint` option takes precedence over the

`TD_API_SERVER` environment variable setting.



For communication through a Proxy, please see the Proxy option below.



### Connection, Read, and Send Timeouts



The connection, read, and send timeouts can be provided via the

`:connect_timeout`, `:read_timeout`, `:send_timeout` keys respectively.

The values for these keys is the number of seconds.



E.g.



    opts.merge({:connect_timeout => 60,

                :read_timeout    => 60,

                :send_timeout    => 60})



### SSL



The `:ssl` key specifies whether SSL communication ought to be used when

communicating with the default or custom endpoint.



This option is ignored if the endpoint (default or custom) URL specifies the

scheme (e.g. the protocol, https or http) in which case SSL enabled/disabled is

inferred directly from the URL scheme.



E.g.



    # SSL is enabled as specified by the :ssl option

    opts.merge({:endpoint => "api.treasuredata.com", :ssl => true})



    # the ssl option is ignored in this case

    opts.merge({:endpoint => "https://api.treasuredata.com", :ssl => false})



    # You can disable verification

    opts.merge({:endpoint => "https://api.treasuredata.com", :verify => false})



    # You can use your own certificate

    opts.merge({:endpoint => "https://api.treasuredata.com", :verify => "/path/to/cert"})



### Proxy



If your network requires accessing our endpoint through a proxy (anonymous or

private), the proxy settings can be specified through the `:http_proxy` option.



E.g.



    # anonymous proxies

    opts.merge({:http_proxy => "http://myproxy.com:1234"})

    opts.merge({:http_proxy => "myproxy.com:1234"})



    # private proxies

    opts.merge({:http_proxy => "https://username:[email protected]:1234"})

    opts.merge({:http_proxy => "username:[email protected]:1234"})



The proxy settings can alternatively be provided by setting the `HTTP_PROXY`

environment variable. The `:http_proxy` option takes precedence over the

`HTTP_PROXY` environment variable setting.



### Additional Header(s)



The Ruby client configures the communication with the Treasure Data REST API

endpoints using the required HTTP Headers (including authorization, Date,

User-Agent and Accept-Encoding, Content-Length, Content-Encoding where

applicable) basing on what method call is made.



The user can specify any additional HTTP Header using the `:headers` option.



E.g.



    opts.merge({:headers => "MyHeader: myheadervalue;"})



To specify a custom User-Agent please see the option below.



### Additional User-Agent(s)



Add the `:user_agent` key to the opts hash to provide an additional user agent

for all the interactions with the APIs.

The provided user agent string will be added to this default client library user

agent `TD-Client-Ruby: X.Y.Z` where X.Y.Z is the version number of this Ruby

Client library.



E.g.



    opts.merge({:user_agent => "MyApp: A.B.C"})



which sets the user agent to:



    "MyApp: A.B.C; TD-Client-Ruby: X.Y.Z"



### Retry POST Requests



Add the `:retry_post_requests` key to the opts hash to require that every

failed POST request is retried for up to 10 minutes with an exponentially

doubling backoff window just as it happens for GET requests by default.



Note that this can lead to unwanted results since POST request as not always

idempotent, that is retrying a POST request by lead to the creation of

duplicated resources, such as the submission of 2 identical jobs on failures.



As for GET requests, the retrying mechanism is triggered on 500+ HTTP error

codes or the raising of exceptions during the communication with the remote

server.



E.g.



    opts.merge({:retry_post_requests => true})



to enable retrying for POST requests.



## Testing Hooks



The client library implements several hooks to enable/disable/trigger special

behaviors. These hooks are triggered using environment variables:



- Enable debugging mode:



  `$ TD_CLIENT_DEBUG=1`



  Currently debugging mode consists of:



  - show request and response of `HTTP`/`HTTPS` `GET` REST API calls;

  - show request of `HTTP`/`HTTPS` `POST`/`PUT` REST API calls.



## More Information



- Copyright: (c) 2011-2023 Treasure Data Inc.

- License: Apache License, Version 2.0