|
| 1 | +<!--- |
| 2 | +DO NOT EDIT ! |
| 3 | +This file was generated automatically from 'src/mako/README.md.mako' |
| 4 | +DO NOT EDIT ! |
| 5 | +--> |
| 6 | +The `google-adexchangebuyer1d3` library allows access to all features of the *Google Ad Exchange Buyer* service. |
| 7 | + |
| 8 | +This documentation was generated from *Ad Exchange Buyer* crate version *0.1.0+20150218*, where *20150218* is the exact revision of the *adexchangebuyer:v1.3* schema built by the [mako](http://www.makotemplates.org/) code generator *v0.1.0*. |
| 9 | + |
| 10 | +Everything else about the *Ad Exchange Buyer* *v1d3* API can be found at the |
| 11 | +[official documentation site](https://developers.google.com/ad-exchange/buyer-rest). |
| 12 | +# Features |
| 13 | + |
| 14 | +Handle the following *Resources* with ease from the central [hub](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.AdExchangeBuyer.html) ... |
| 15 | + |
| 16 | +* [accounts](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.Account.html) |
| 17 | + * [*get*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.AccountGetCall.html), [*list*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.AccountListCall.html), [*patch*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.AccountPatchCall.html) and [*update*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.AccountUpdateCall.html) |
| 18 | +* [billing info](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.BillingInfo.html) |
| 19 | + * [*get*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.BillingInfoGetCall.html) and [*list*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.BillingInfoListCall.html) |
| 20 | +* [budget](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.Budget.html) |
| 21 | + * [*get*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.BudgetGetCall.html), [*patch*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.BudgetPatchCall.html) and [*update*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.BudgetUpdateCall.html) |
| 22 | +* [creatives](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.Creative.html) |
| 23 | + * [*get*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.CreativeGetCall.html), [*insert*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.CreativeInsertCall.html) and [*list*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.CreativeListCall.html) |
| 24 | +* [direct deals](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.DirectDeal.html) |
| 25 | + * [*get*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.DirectDealGetCall.html) and [*list*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.DirectDealListCall.html) |
| 26 | +* [performance report](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PerformanceReport.html) |
| 27 | + * [*list*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PerformanceReportListCall.html) |
| 28 | +* [pretargeting config](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfig.html) |
| 29 | + * [*delete*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfigDeleteCall.html), [*get*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfigGetCall.html), [*insert*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfigInsertCall.html), [*list*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfigListCall.html), [*patch*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfigPatchCall.html) and [*update*](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.PretargetingConfigUpdateCall.html) |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | + |
| 34 | +# Structure of this Library |
| 35 | + |
| 36 | +The API is structured into the following primary items: |
| 37 | + |
| 38 | +* **[Hub](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/struct.AdExchangeBuyer.html)** |
| 39 | + * a central object to maintain state and allow accessing all *Activities* |
| 40 | +* **[Resources](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.Resource.html)** |
| 41 | + * primary types that you can apply *Activities* to |
| 42 | + * a collection of properties and *Parts* |
| 43 | + * **[Parts](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.Part.html)** |
| 44 | + * a collection of properties |
| 45 | + * never directly used in *Activities* |
| 46 | +* **[Activities](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.CallBuilder.html)** |
| 47 | + * operations to apply to *Resources* |
| 48 | + |
| 49 | +Generally speaking, you can invoke *Activities* like this: |
| 50 | + |
| 51 | +```Rust,ignore |
| 52 | +let r = hub.resource().activity(...).doit() |
| 53 | +``` |
| 54 | + |
| 55 | +Or specifically ... |
| 56 | + |
| 57 | +```ignore |
| 58 | +let r = hub.pretargeting_config().insert(...).doit() |
| 59 | +let r = hub.pretargeting_config().patch(...).doit() |
| 60 | +let r = hub.pretargeting_config().get(...).doit() |
| 61 | +let r = hub.pretargeting_config().update(...).doit() |
| 62 | +``` |
| 63 | + |
| 64 | +The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities` |
| 65 | +supports various methods to configure the impending operation (not shown here). It is made such that all required arguments have to be |
| 66 | +specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired. |
| 67 | +The `doit()` method performs the actual communication with the server and returns the respective result. |
| 68 | + |
| 69 | +# Usage |
| 70 | + |
| 71 | +## Setting up your Project |
| 72 | + |
| 73 | +To use this library, you would put the following lines into your `Cargo.toml` file: |
| 74 | + |
| 75 | +```toml |
| 76 | +[dependencies] |
| 77 | +google-adexchangebuyer1d3 = "*" |
| 78 | +``` |
| 79 | + |
| 80 | +## A complete example |
| 81 | + |
| 82 | +```Rust |
| 83 | +extern crate hyper; |
| 84 | +extern crate "yup-oauth2" as oauth2; |
| 85 | +extern crate "google-adexchangebuyer1d3" as adexchangebuyer1d3; |
| 86 | +use adexchangebuyer1d3::PretargetingConfig; |
| 87 | +use adexchangebuyer1d3::Result; |
| 88 | +use std::default::Default; |
| 89 | +use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage}; |
| 90 | +use adexchangebuyer1d3::AdExchangeBuyer; |
| 91 | + |
| 92 | +// Get an ApplicationSecret instance by some means. It contains the `client_id` and |
| 93 | +// `client_secret`, among other things. |
| 94 | +let secret: ApplicationSecret = Default::default(); |
| 95 | +// Instantiate the authenticator. It will choose a suitable authentication flow for you, |
| 96 | +// unless you replace `None` with the desired Flow. |
| 97 | +// Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about |
| 98 | +// what's going on. You probably want to bring in your own `TokenStorage` to persist tokens and |
| 99 | +// retrieve them from storage. |
| 100 | +let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate, |
| 101 | + hyper::Client::new(), |
| 102 | + <MemoryStorage as Default>::default(), None); |
| 103 | +let mut hub = AdExchangeBuyer::new(hyper::Client::new(), auth); |
| 104 | +// As the method needs a request, you would usually fill it with the desired information |
| 105 | +// into the respective structure. Some of the parts shown here might not be applicable ! |
| 106 | +// Values shown here are possibly random and not representative ! |
| 107 | +let mut req: PretargetingConfig = Default::default(); |
| 108 | + |
| 109 | +// You can configure optional parameters by calling the respective setters at will, and |
| 110 | +// execute the final call using `doit()`. |
| 111 | +// Values shown here are possibly random and not representative ! |
| 112 | +let result = hub.pretargeting_config().patch(&req, "accountId", "configId") |
| 113 | + .doit(); |
| 114 | + |
| 115 | +match result { |
| 116 | + Result::HttpError(err) => println!("HTTPERROR: {:?}", err), |
| 117 | + Result::MissingAPIKey => println!("Auth: Missing API Key - used if there are no scopes"), |
| 118 | + Result::MissingToken => println!("OAuth2: Missing Token"), |
| 119 | + Result::Cancelled => println!("Operation cancelled by user"), |
| 120 | + Result::UploadSizeLimitExceeded(size, max_size) => println!("Upload size too big: {} of {}", size, max_size), |
| 121 | + Result::Failure(_) => println!("General Failure (hyper::client::Response doesn't print)"), |
| 122 | + Result::FieldClash(clashed_field) => println!("You added custom parameter which is part of builder: {:?}", clashed_field), |
| 123 | + Result::JsonDecodeError(err) => println!("Couldn't understand server reply - maybe API needs update: {:?}", err), |
| 124 | + Result::Success(_) => println!("Success (value doesn't print)"), |
| 125 | +} |
| 126 | + |
| 127 | +``` |
| 128 | +## Handling Errors |
| 129 | + |
| 130 | +All errors produced by the system are provided either as [Result](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/enum.Result.html) enumeration as return value of |
| 131 | +the doit() methods, or handed as possibly intermediate results to either the |
| 132 | +[Hub Delegate](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.Delegate.html), or the [Authenticator Delegate](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/../yup-oauth2/trait.AuthenticatorDelegate.html). |
| 133 | + |
| 134 | +When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This |
| 135 | +makes the system potentially resilient to all kinds of errors. |
| 136 | + |
| 137 | +## Uploads and Downlods |
| 138 | +If a method supports downloads, the response body, which is part of the [Result](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/enum.Result.html), should be |
| 139 | +read by you to obtain the media. |
| 140 | +If such a method also supports a [Response Result](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.ResponseResult.html), it will return that by default. |
| 141 | +You can see it as meta-data for the actual media. To trigger a media download, you will have to set up the builder by making |
| 142 | +this call: `.param("alt", "media")`. |
| 143 | + |
| 144 | +Methods supporting uploads can do so using up to 2 different protocols: |
| 145 | +*simple* and *resumable*. The distinctiveness of each is represented by customized |
| 146 | +`doit(...)` methods, which are then named `upload(...)` and `upload_resumable(...)` respectively. |
| 147 | + |
| 148 | +## Customization and Callbacks |
| 149 | + |
| 150 | +You may alter the way an `doit()` method is called by providing a [delegate](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.Delegate.html) to the |
| 151 | +[Method Builder](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.CallBuilder.html) before making the final `doit()` call. |
| 152 | +Respective methods will be called to provide progress information, as well as determine whether the system should |
| 153 | +retry on failure. |
| 154 | + |
| 155 | +The [delegate trait](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.Delegate.html) is default-implemented, allowing you to customize it with minimal effort. |
| 156 | + |
| 157 | +## Optional Parts in Server-Requests |
| 158 | + |
| 159 | +All structures provided by this library are made to be [enocodable](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.RequestValue.html) and |
| 160 | +[decodable](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.ResponseResult.html) via json. Optionals are used to indicate that partial requests are responses are valid. |
| 161 | +Most optionals are are considered [Parts](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.Part.html) which are identifyable by name, which will be sent to |
| 162 | +the server to indicate either the set parts of the request or the desired parts in the response. |
| 163 | + |
| 164 | +## Builder Arguments |
| 165 | + |
| 166 | +Using [method builders](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.CallBuilder.html), you are able to prepare an action call by repeatedly calling it's methods. |
| 167 | +These will always take a single argument, for which the following statements are true. |
| 168 | + |
| 169 | +* [PODs][wiki-pod] are handed by copy |
| 170 | +* strings are passed as `&str` |
| 171 | +* [request values](http://byron.github.io/google-apis-rs/google-adexchangebuyer1d3/trait.RequestValue.html) are borrowed |
| 172 | + |
| 173 | +Arguments will always be copied or cloned into the builder, to make them independent of their original life times. |
| 174 | + |
| 175 | +[wiki-pod]: http://en.wikipedia.org/wiki/Plain_old_data_structure |
| 176 | +[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern |
| 177 | +[google-go-api]: https://github.com/google/google-api-go-client |
| 178 | + |
| 179 | +# License |
| 180 | +The **adexchangebuyer1d3** library was generated by Sebastian Thiel, and is placed |
| 181 | +under the *MIT* license. |
| 182 | +You can read the full text at the repository's [license file][repo-license]. |
| 183 | + |
| 184 | +[repo-license]: https://github.com/Byron/google-apis-rs/LICENSE.md |
0 commit comments