uswitch/binj

Clojure library for accessing the Bing Ads API

binj

Clojure library to access the Bing Ads reporting API.

Example Usage

For this example to work you need:

• a developer token
• client-id
• access tokens in an edn file

Notes on how these are generated are below.

(ns example
  (:require [binj.reporting :as b]
            [clj-time.core  :as t]))

(def account-id 12345)
(def dev-token "123456789MAGIC42")
(def client-id "deadbeef-1234-5678-9009-424242424242")
(def grant (b/oauth-code-grant client-id :token-file "bing.edn"))
(def auth (b/authorization-data developer-token grant))

(def report-request (b/account-performance-report-request
    "name"
    [account-id]
    [:time-period :account-id :account-name :account-number :spend]
    :aggregation :daily
    :time-period {:start (t/date-time 2018 3 6) :end (t/date-time 2018 3 6)}))

(def results (b/submit-and-download report-request auth))

({"TimePeriod" "2018-03-06", "AccountId" "12345", "AccountName" "uSwitch Some Account", "AccountNumber" "X9876543", "Spend" 1666.66})

Getting a developer-token

Bing Developer Token docs

1. Make sure the user you will use to run the app has been at least granted "Client Viewer" permissions
2. Have a super user generate and assign that user a "Developer Token" by clicking the "request token" button in the developer portal
3. The token should now be visible to the user on the accounts page

Getting a client-id

Bing OAuth Set up docs

1. Visit the microsoft app portal
2. "Add an app" and name it
3. In the app's config page click "Add platform" and select "native"
4. Save the changes
5. Copy the "Application Id". This is the client-id

Generate Tokens

Bing OAuth SDK docs

If you're using a new client-id or developer token you'll need to generate a token file. This is best done from a repl:

$ lein repl
...
user=> (require '[binj.reporting :as b])
user=> (def client-id "deadbeef-1234-5678-9009-424242424242")
user=> (def grant (b/oauth-code-grant client-id))
user=> (b/authorization-url grant)
#object[java.net.URL 0xdeadbeef "https://login.live.com/oauth20_authorize.srf?scope=bingads.manage&response_type=code&redirect_uri=https%3A%2F%2Flogin.live.com%2Foauth20_desktop.srf&client_id=deadbeef-1234-5678-9009-424242424242"]

Visit the link generated and sign in to your BingAds account then grant your app the requested permissions. Copy the URL of the page you're redirected to

; Using the same session as before
user=> (def resp-url "https://login.live.com/oauth20_desktop.srf?code=SomeOther-UUID-THAT-OAUT-HNeedsToWork&lc=1666")
user=> (b/request-access-refresh-tokens grant resp-url)
{:access-token "some huge string", :refresh-token "some other string"}

The output of the final command should be saved so it can be used as the token-file.

Debugging

Bing Docs

If you see errors like:

AdApiFaultDetail_Exception Invalid client data. Check the SOAP fault details for more information  sun.reflect.NativeConstructorAccessorImpl.newInstance0 (NativeConstructorAccessorImpl.java:-2)

Then the API is swallowing SOAP errors. More verbose output can be gained by running:

(. System setProperty "com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump" "true")

Changelog

Version 0.5.0

• Removed support for username/password authentication (depreciated by Bing)

Version 0.4.0

• Support for v11 BingAds api
• breaking changes to report download
• Async polling for report download internalised (request-id no longer exposed)
• submit-and-download now returns a sequence of maps
• requires permission to generate a temporary file on the file system

Note: With version 0.4.0 there are some significant breaking changes to the the way reports are generated. It now uses the built in async polling mechanism provided in the SDK, so it no longer exposes the request-id. The submit-and-download now returns a sequence of maps representing the report data.

Authorisation and Report Definitions are the same, however the mechanism to download them is breaking. Please be aware when upgrading to this version.

Version 0.3,0-SNAPSHOT

• Support for v11 BingAds api
• Broken

Version 0.2,0-SNAPSHOT

• Support for v10 BingAds api

Version 0.1,2

• Support for v9 BingAds api

License

Copyright © 2018, uSwitch.

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

binj's Issues

Binj can not be used in an uberjar

This seems to be an underlying problem with the Apache Camel jars, when bundling into an uberjar.
http://camel.apache.org/how-do-i-use-a-big-uber-jar.html

Usage results in the following error:

Caused by: org.apache.cxf.service.factory.ServiceConstructionException: Could not resolve a binding for null
    at org.apache.cxf.frontend.AbstractWSDLBasedEndpointFactory.createBindingInfo(AbstractWSDLBasedEndpointFactory.java:352) 
    at org.apache.cxf.frontend.AbstractWSDLBasedEndpointFactory.createEndpointInfo(AbstractWSDLBasedEndpointFactory.java:259) 
    at org.apache.cxf.frontend.AbstractWSDLBasedEndpointFactory.createEndpoint(AbstractWSDLBasedEndpointFactory.java:144) 
    at org.apache.cxf.frontend.ClientFactoryBean.create(ClientFactoryBean.java:91) 
    at org.apache.cxf.frontend.ClientProxyFactoryBean.create(ClientProxyFactoryBean.java:157) 
    at org.apache.cxf.jaxws.JaxWsProxyFactoryBean.create(JaxWsProxyFactoryBean.java:142)
    at org.apache.cxf.jaxws.ServiceImpl.createPort(ServiceImpl.java:493) 
    at org.apache.cxf.jaxws.ServiceImpl.getPort(ServiceImpl.java:343) 
    ... 47 common frames omitted
Caused by: org.apache.cxf.BusException: No binding factory for namespace http://schemas.xmlsoap.org/soap/ registered.
    at org.apache.cxf.bus.managers.BindingFactoryManagerImpl.getBindingFactory(BindingFactoryManagerImpl.java:93) 
    at org.apache.cxf.frontend.AbstractWSDLBasedEndpointFactory.createBindingInfo(AbstractWSDLBasedEndpointFactory.java:339)

This problem is described in the following Stack Overflow posts:
http://stackoverflow.com/questions/24430342/error-on-using-camel-cxf-no-binding-factory-http-schemas-xmlsoap-org-soap
http://stackoverflow.com/questions/6831954/how-to-package-an-apache-cxf-application-into-a-monolithic-jar-with-the-maven-s

Solution seems to use Maven Shade plugin, which can be referenced in the project.clj as described here:
technomancy/leiningen#1460

I gave this a try, but it is beyond by Java/Maven powers unfortunately...