| [[Facebook-FacebookComponent]] |
| Facebook Component |
| ~~~~~~~~~~~~~~~~~~ |
| |
| *Available as of Camel 2.12* |
| |
| The Facebook component provides access to all of the Facebook APIs |
| accessible using http://facebook4j.org/en/index.html[Facebook4J]. It |
| allows producing messages to retrieve, add, and delete posts, likes, |
| comments, photos, albums, videos, photos, checkins, locations, links, |
| etc. It also supports APIs that allow polling for posts, users, |
| checkins, groups, locations, etc. |
| |
| Facebook requires the use of OAuth for all client application |
| authentication. In order to use camel-facebook with your account, you'll |
| need to create a new application within Facebook at |
| https://developers.facebook.com/apps[https://developers.facebook.com/apps] |
| and grant the application access to your account. The Facebook |
| application's id and secret will allow access to Facebook APIs which do |
| not require a current user. A user access token is required for APIs |
| that require a logged in user. More information on obtaining a user |
| access token can be found at |
| https://developers.facebook.com/docs/facebook-login/access-tokens/[https://developers.facebook.com/docs/facebook-login/access-tokens/]. |
| |
| Maven users will need to add the following dependency to their pom.xml |
| for this component: |
| |
| [source,java] |
| ----------------------------------------------- |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-facebook</artifactId> |
| <version>${camel-version}</version> |
| </dependency> |
| ----------------------------------------------- |
| |
| [[Facebook-URIformat]] |
| URI format |
| ^^^^^^^^^^ |
| |
| [source,java] |
| --------------------------------- |
| facebook://[endpoint]?[options] |
| --------------------------------- |
| |
| [[Facebook-FacebookComponent.1]] |
| FacebookComponent |
| ^^^^^^^^^^^^^^^^^ |
| |
| The facebook component can be configured with the Facebook account |
| settings below, which are mandatory. The values can be provided to the |
| component using the bean property *configuration* of type |
| *org.apache.camel.component.facebook.config.FacebookConfiguration*. The |
| *oAuthAccessToken* option may be ommited but that will only allow access |
| to application APIs. |
| |
| You can also configure these options directly in an endpoint URI. |
| |
| [width="100%",cols="20%,80%",options="header",] |
| |======================================================================= |
| |Option |Description |
| |
| |oAuthAppId |The application Id |
| |
| |oAuthAppSecret |The application Secret |
| |
| |oAuthAccessToken |The user access token |
| |======================================================================= |
| |
| In addition to the above settings, non-mandatory options below can be |
| used to configure the underlying Facebook4J runtime through either the |
| component's *configuration* property or in an endpoint URI. |
| |
| [width="100%",cols="10%,10%,80%",options="header",] |
| |======================================================================= |
| |Option |Description |Default Value |
| |
| |oAuthAuthorizationURL |OAuth authorization URL |https://www.facebook.com/dialog/oauth[https://www.facebook.com/dialog/oauth] |
| |
| |oAuthPermissions |Default OAuth permissions. Comma separeted permission names. See |
| https://developers.facebook.com/docs/reference/login/#permissions[https://developers.facebook.com/docs/reference/login/#permissions] |
| for the detail |null |
| |
| |oAuthAccessTokenURL |OAuth access token URL |https://graph.facebook.com/oauth/access_token[https://graph.facebook.com/oauth/access_token] |
| |
| |debugEnabled |Enables deubg output. Effective only with the embedded logger |false |
| |
| |gzipEnabled |Use Facebook GZIP encoding |true |
| |
| |httpConnectionTimeout |Http connection timeout in milliseconds |20000 |
| |
| |httpDefaultMaxPerRoute |HTTP maximum connections per route |2 |
| |
| |httpMaxTotalConnections |HTTP maximum total connections |20 |
| |
| |httpProxyHost |HTTP proxy server host name |null |
| |
| |httpProxyPassword |HTTP proxy server password |null |
| |
| |httpProxyPort |HTTP proxy server port |null |
| |
| |httpProxyUser |HTTP proxy server user name |null |
| |
| |httpReadTimeout |Http read timeout in milliseconds |120000 |
| |
| |httpRetryCount |Number of HTTP retries |0 |
| |
| |httpRetryIntervalSeconds |HTTP retry interval in seconds |5 |
| |
| |httpStreamingReadTimeout |HTTP streaming read timeout in milliseconds |40000 |
| |
| |jsonStoreEnabled |If set to true, raw JSON forms will be stored in DataObjectFactory |false |
| |
| |mbeanEnabled |If set to true, Facebook4J mbean will be registerd |false |
| |
| |prettyDebugEnabled |prettify JSON debug output if set to true |false |
| |
| |restBaseURL |API base URL |https://graph.facebook.com/[https://graph.facebook.com/] |
| |
| |useSSL |Use SSL |true |
| |
| |videoBaseURL |Video API base URL |https://graph-video.facebook.com/[https://graph-video.facebook.com/] |
| |
| |clientURL |Facebook4J API client URL |http://facebook4j.org/en/facebook4j-<version>.xml |
| |
| |clientVersion |Facebook4J client API version |1.1.12 |
| |======================================================================= |
| |
| [[Facebook-ProducerEndpoints:]] |
| Producer Endpoints: |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| Producer endpoints can use endpoint names and options from the table |
| below. Endpoints can also use the short name without the *get* or |
| *search* prefix, except *checkin* due to ambiguity between *getCheckin* |
| and *searchCheckin*. Endpoint options that are not mandatory are denoted |
| by []. |
| |
| Producer endpoints can also use a special option **inBody** that in turn |
| should contain the name of the endpoint option whose value will be |
| contained in the Camel Exchange In message. For example, the facebook |
| endpoint in the following route retrieves activities for the user id |
| value in the incoming message body. |
| |
| [source,java] |
| -------------------------------------------------------------------- |
| from("direct:test").to("facebook://activities?inBody=userId")... |
| -------------------------------------------------------------------- |
| |
| Any of the endpoint options can be provided in either the endpoint URI, |
| or dynamically in a message header. The message header name must be of |
| the format |
| *CamelFacebook.https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=option&linkCreation=true&fromPageId=34020899[option]*. |
| For example, the *userId* option value in the previous route could |
| alternately be provided in the message header *CamelFacebook.userId*. |
| Note that the inBody option overrides message header, e.g. the endpoint |
| option *inBody=user* would override a *CamelFacebook.userId* header. |
| |
| Endpoints that return a String return an Id for the created or modified |
| entity, e.g. *addAlbumPhoto* returns the new album Id. Endpoints that |
| return a boolean, return true for success and false otherwise. In case |
| of Facebook API errors the endpoint will throw a RuntimeCamelException |
| with a facebook4j.FacebookException cause. |
| |
| [[Facebook-ConsumerEndpoints:]] |
| Consumer Endpoints: |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| Any of the producer endpoints that take a |
| https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=reading&linkCreation=true&fromPageId=34020899[reading#reading] |
| parameter can be used as a consumer endpoint. The polling consumer uses |
| the *since* and *until* fields to get responses within the polling |
| interval. In addition to other reading fields, an initial *since* value |
| can be provided in the endpoint for the first poll. |
| |
| Rather than the endpoints returning a List (or |
| *facebook4j.ResponseList*) through a single route exchange, |
| camel-facebook creates one route exchange per returned object. As an |
| example, if *"facebook://home"* results in five posts, the route will be |
| executed five times (once for each Post). |
| |
| [[Facebook-ReadingOptions]] |
| Reading Options |
| ^^^^^^^^^^^^^^^ |
| |
| The *reading* option of type *facebook4j.Reading* adds support for |
| reading parameters, which allow selecting specific fields, limits the |
| number of results, etc. For more information see |
| https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=Graph+API&linkCreation=true&fromPageId=34020899[Graph |
| API#reading] - |
| https://developers.facebook.com/docs/reference/api/#reading[Facebook |
| Developers]. |
| |
| It is also used by consumer endpoints to poll Facebook data to avoid |
| sending duplicate messages across polls. |
| |
| The reading option can be a reference or value of type |
| *facebook4j.Reading*, or can be specified using the following reading |
| options in either the endpoint URI or exchange header with |
| *CamelFacebook.* prefix. |
| |
| [[Facebook-Messageheader]] |
| Message header |
| ^^^^^^^^^^^^^^ |
| |
| Any of the |
| https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=URI+options&linkCreation=true&fromPageId=34020899[URI |
| options#urioptions] can be provided in a message header for producer |
| endpoints with *CamelFacebook.* prefix. |
| |
| [[Facebook-Messagebody]] |
| Message body |
| ^^^^^^^^^^^^ |
| |
| All result message bodies utilize objects provided by the Facebook4J |
| API. Producer endpoints can specify the option name for incoming message |
| body in the *inBody* endpoint parameter. |
| |
| For endpoints that return an array, or *facebook4j.ResponseList*, or |
| *java.util.List*, a consumer endpoint will map every elements in the |
| list to distinct messages. |
| |
| [[Facebook-Usecases]] |
| Use cases |
| ^^^^^^^^^ |
| |
| To create a post within your Facebook profile, send this producer a |
| facebook4j.PostUpdate body. |
| |
| [source,java] |
| ---------------------------------------------------- |
| from("direct:foo") |
| .to("facebook://postFeed/inBody=postUpdate); |
| ---------------------------------------------------- |
| |
| To poll, every 5 sec (You can set the link:polling-consumer.html[polling |
| consumer] options by adding a prefix of "consumer"), all statuses on |
| your home feed: |
| |
| [source,java] |
| ----------------------------------------------- |
| from("facebook://home?consumer.delay=5000") |
| .to("bean:blah"); |
| ----------------------------------------------- |
| |
| Searching using a producer with dynamic options from header. |
| |
| In the bar header we have the Facebook search string we want to execute |
| in public posts, so we need to assign this value to the |
| CamelFacebook.query header. |
| |
| [source,java] |
| -------------------------------------------------------- |
| from("direct:foo") |
| .setHeader("CamelFacebook.query", header("bar")) |
| .to("facebook://posts"); |
| -------------------------------------------------------- |