562aa5c990
* Remove deprecated spring.cloud.stream.function.definition property * Restore tasklauncher-function Co-authored-by: David Turanski <dturanski@pivotal.io>
150 lines
8.3 KiB
Plaintext
150 lines
8.3 KiB
Plaintext
# Twitter Functions
|
||
|
||
This module provides couple of twitter functions that can be reused and composed in other applications.
|
||
|
||
To use those functions add the following dependency to your POM:
|
||
|
||
[source,XML]
|
||
----
|
||
<dependency>
|
||
<groupId>org.springframework.cloud.fn</groupId>
|
||
<artifactId>twitter-function</artifactId>
|
||
<version>${java-functions.version}</version>
|
||
</dependency>
|
||
----
|
||
|
||
## 1. Twitter Trend Function
|
||
|
||
Functions can return either Trends topics or the Locations of the trending topics. The `twitter.trend.trend-query-type` property allows choosing between both types.
|
||
|
||
* Trends - `twitter.trend.trend-query-type` is set to `trend`. Leverages the https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place[Trends API] to return the https://help.twitter.com/en/using-twitter/twitter-trending-faqs[trending topics] near a specific latitude, longitude location.
|
||
|
||
* Trend Locations - the `twitter.trend.trend-query-type` is set `trendLocation`. Retrieve a full or nearby locations list of trending topics by location. If the `latitude`, `longitude` parameters are NOT provided the processor performs the https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available[Trends Available API] and returns the locations that Twitter has trending topic information for.
|
||
If the `latitude`, `longitude` parameters are provided the processor performs the https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest[Trends Closest API] and returns the locations that Twitter has trending topic information for, closest to a specified location.
|
||
|
||
Response is an array of `locations` that encode the location's WOEID and some other human-readable information such as a canonical name and country the location belongs in.
|
||
|
||
### 1.1 Beans for injection
|
||
|
||
You can import the `TwitterTrendFunctionConfiguration` in a Spring Boot application and then inject the following bean.
|
||
|
||
`filterFunction`
|
||
|
||
You can use `Function<Message<?>, Message<byte[]>> twitterTrendFunction` as a qualifier when injecting.
|
||
|
||
Once injected, you can use the `apply` method of the `Function` to invoke it and get the result.
|
||
|
||
### 1.2 Configuration Options
|
||
|
||
TIP: For `SpEL` expression properties wrap the literal values in single quotes (`'`).
|
||
|
||
For more information on the various options available, please see link:../twitter-function/src/main/java/org/springframework/cloud/fn/twitter/trend/TwitterTrendFunctionProperties.java[TwitterTrendFunctionProperties.java]
|
||
|
||
### 1.3 Tests
|
||
See this link:src/test/java/org/springframework/cloud/fn/twitter/trend/TwitterTrendFunctionTests.java[test suite] for examples of how this function is used.
|
||
|
||
### 1.4 Other usage
|
||
|
||
Leveraging the Spring Cloud Function composability, you can compose the Trend function in your boot app like this:
|
||
|
||
[source,Java]
|
||
----
|
||
@SpringBootApplication
|
||
@Import(TwitterTrendFunctionConfiguration.class )
|
||
public class MyTwitterTrendBootApp {
|
||
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(MyTwitterTrendBootApp.class,
|
||
"--spring.cloud.function.definition=trend|twitterTrendFunction|managedJson");
|
||
}
|
||
}
|
||
----
|
||
|
||
## 2. Twitter Geo Function.
|
||
|
||
Function based on the https://developer.twitter.com/en/docs/geo/places-near-location/overview[Geo API] that retrieves Twitter place information based on query parameters such as (`latitude`, `longitude`) pair, an `IP` address, or a place `name`.
|
||
|
||
There are two types for geo search queries `search` and `reverse` controlled by the `twitter.geo.search.type` property.
|
||
|
||
* reverse - Given a latitude and a longitude, searches for up to 20 places that can be used as a `placeId` when updating a status.
|
||
This request is an informative call and will deliver generalized results about geography.
|
||
|
||
* search - Search for places that can be attached to statuses/update. Given a latitude and a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status.
|
||
|
||
Conceptually, a query can be made from the user’s location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location with a call to POST statuses/update.
|
||
|
||
This is the recommended method to use find places that can be attached to statuses/update. Unlike GET geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regard to the user who is authenticated. Use this approach for interactive place matching with the user.
|
||
|
||
Some parameters in this method are only required based on the existence of other parameters. For instance, “lat” is required if “long” is provided, and vice-versa. Authentication is recommended, but not required with this method.
|
||
|
||
NOTE: Limits: 15 requests / 15-min window (user auth).
|
||
|
||
### 2.1 Beans for injection
|
||
|
||
You can import the `TwitterGeoFunctionConfiguration` in a Spring Boot application and then inject the following bean.
|
||
|
||
`filterFunction`
|
||
|
||
You can use `Function<Message<?>, Message<byte[]>> twitterGeoFunction` as a qualifier when injecting.
|
||
Once injected, you can use the `apply` method of the `Function` to invoke it and get the result.
|
||
|
||
### 2.2 Configuration Options
|
||
|
||
TIP: For `SpEL` expression properties wrap the literal values in single quotes (`'`).
|
||
|
||
For more information on the various options available, please see link:../twitter-function/src/main/java/org/springframework/cloud/fn/twitter/geo/TwitterGeoFunctionProperties.java[TwitterGeoFunctionProperties.java]
|
||
|
||
### 2.3 Tests
|
||
|
||
See this link:src/test/java/org/springframework/cloud/fn/twitter/geo/TwitterGeoFunctionTest.java[test suite] for examples of how this function is used.
|
||
|
||
### 2.4 Other usage
|
||
|
||
Leveraging the Spring Cloud Function composability, you can compose the Geo function in your boot app like this:
|
||
|
||
[source,Java]
|
||
----
|
||
@SpringBootApplication
|
||
@Import(TwitterGeoFunctionConfiguration.class )
|
||
public class MyTwitterGeoProcessorBootApp {
|
||
|
||
public static void main(String[] args) {
|
||
SpringApplication.run(MyTwitterGeoProcessorBootApp.class,
|
||
"--spring.cloud.function.definition=messageToGeoQueryFunction|twitterSearchPlacesFunction|managedJson");
|
||
}
|
||
}
|
||
----
|
||
|
||
## 3. Twitter Users Function
|
||
|
||
Retrieves users either by list of use ids and/or screen-names (https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup[Users Lookup API]) or by text search query (https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search[Users Search API]).
|
||
Uses SpEL expressions to compute the query parameters from the input message.
|
||
Use the single quoted literals to set static values (e.g. user-id: '6666, 9999, 10000').
|
||
|
||
Use `twitter.users.type` property allow to select the query approaches.
|
||
|
||
* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup[Users Lookup API] - Returns fully-hydrated user objects for up to 100 users per request, as specified by comma-separated values passed to the `userId` and/or `screenName` parameters. Rate limits: (300 requests / 15-min window)
|
||
* https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search[Users Search API] - Relevance-based search interface to public user accounts on Twitter.
|
||
Querying by topical interest, full name, company name, location, or other criteria. Exact match searches are not supported. Only the first 1,000 matching results are available. Rate limits:(900 requests / 15-min window)
|
||
|
||
### 3.1 Beans for injection
|
||
|
||
You can import the `TwitterUsersFunctionConfiguration` in a Spring Boot application and then inject the following bean.
|
||
|
||
`filterFunction`
|
||
|
||
You can use `Function<Message<?>, Message<byte[]>> twitterUsersFunction` as a qualifier when injecting.
|
||
Once injected, you can use the `apply` method of the `Function` to invoke it and get the result.
|
||
|
||
|
||
### 3.2 Configuration Options
|
||
|
||
TIP: For `SpEL` expression properties wrap the literal values in single quotes (`'`).
|
||
|
||
For more information on the various options available, please see link:../twitter-function/src/main/java/org/springframework/cloud/fn/twitter/users/TwitterUsersFunctionProperties.java[TwitterUsersFunctionProperties.java]
|
||
|
||
### 3.3 Tests
|
||
See this link:src/test/java/org/springframework/cloud/fn/twitter/users/TwitterUsersFunctionTests.java[test suite] for examples of how this function is used.
|
||
|
||
### 3.4 Other usage
|