archive-gh-me/serverless
1
0
Fork 0
mirror of https://github.com/serverless/serverless.git synced 2026-01-18 14:58:43 +00:00
Code Issues Projects Releases Wiki Activity

Add and update "Event sources" related documents

Browse Source
This commit is contained in:
Philipp Muens 2016-06-24 11:20:38 +02:00
parent 0fce416593
commit eb3d29eede
4 changed files with 142 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/README.md
View File

@ -41,6 +41,7 @@ You may also take a look at our [contributing guidelines](/CONTRIBUTING.md).
- [Deploying your service](guide/deploying-a-service.md)
- [Invoking your functions](guide/invoking-a-function.md)
- [Adding additional event sources](guide/event-sources.md)
- [Overview of available event source](guide/overview-of-event-sources.md)
- [Managing custom provider resources](guide/custom-provider-resources.md)
- [Removing your service](guide/removing-a-service.md)
- [Using plugins](using-plugins)

1
docs/guide/README.md
View File

@ -16,5 +16,6 @@ This guide is Amazon web service specific but can be applied to any other provid
- [Deploying a service](deploying-a-service.md)
- [Invoking a function](invoking-a-function.md)
- [Event sources](event-sources.md)
- [Overview of available event sources](overview-of-event-sources.md)
- [Custom provider resources](custom-provider-resources.md)
- [Removing a service](removing-a-service.md)

223
docs/guide/event-sources.md
View File

@ -1,54 +1,67 @@
# Event sources
Serverless is used to build event driven architecture. Basically everything a function can trigger is an event.
Events could be HTTP requests, events fired from a cloud storage, scheduled events, etc.
Serverless is used to build event driven architecture. Basically everything which can trigger a function is an event.
Events could be HTTP requests, events fired from a cloud storage (like a S3 bucket), scheduled events, etc.
This tutorial will show you how you can add event sources to your Serverless service.
Let's add a HTTP event to our services `hello` function so that the function get's called whenever a corresponding HTTP
event will come in.
We'll assume that you have Serverless v1.0 or greater installed on your machine.
## Adding a HTTP event
Our provider we use throughout the tutorial will be Amazon web services (AWS).
**Note:** This tutorial will implement a schedule event for a function which is deployed to Amazon web services.
You can re-use this tutorial to add [other event sources](/docs/guide/event-sources.md)
(even from other providers) to your functions.
## Scheduling a function
Let's pretend we want to re-run our function every 10 minutes. One solution would be to open up the cloud provider dashboard
and run the function by hand but this is of course not the best way to solve our problem.
You might be familiar with so called "Cron jobs" if you're a UNIX user. Cron jobs are a way to define reoccurring
tasks the operating system will trigger automatically (e.g. some sort of scripts that automates something for you).
AWS has introduced a similar way we can automate the way our lambda function get's called.
## Adding the schedule event source
Let's add a schedule event source to a function in our Serverless service.
Go to the Serverless service directory and open up the `serverless.yaml` file. Navigate to the function of your choice
where you want to add an event source. Add a new entry `events` inside the function. It should be on the same level as
the `handler` entry.
After that add a `- schedule: rate(10 minutes)` entry inside the `events` definition.
Not the content of your `serverless.yaml` file might look like this:
Go to the Serverless service directory and open up the `serverless.yaml` file in your favorite editor.
At first we need to add an `events` property to the function to tell Serverless that this function will have events
attached:
```yaml
functions:
greet:
handler: handler.greet
hello:
handler: handler.hello
events:
- schedule: rate(10 minutes)
```
That's it for the event addition. Next up we need to (re)deploy our service to enable our scheduled event.
This `events` property is used to store all the event definitions for the function.
Each event will be added inside this `events` section.
## (Re)deploying the Serverless service
Let's add a `http` event with a path of `greet` and a method of `get`:
Run `serverless deploy` to (re)deploy the whole service.
Your function will be scheduled to run every 10 minutes once the deployment has finished.
```yaml
functions:
hello:
handler: handler.hello
events:
- http:
path: greet
method: get
```
That's it. There's nothing more to do to setup a `http` event. Let's (re)deploy our service so that Serverless will
translate this event definition to provider specific syntax and sets it up for us.
## (Re)deploying
We can redeploy our updated service by simply running `serverless deploy` again.
Serverless will show the progress on the terminal and tell you once the service is updated.
## Calling our HTTP endpoint
Let's test our deployed HTTP endpoint.
Open up the AWS console and navigate to the `API Gateway` service section. You should see a deployed API Gateway for
the Serverless service.
Click on the API for the service and navigate to the `resources` section on the left.
You should now see the `greet` resource which is accessible through the `/greet` path and wired up to a `GET` HTTP method.
Click on `GET` to open up the API endpoint. Next up click on the lightning icon with the label `test`.
In the next window click on the blue `test` button again and see the result on the right hand side.
You've successfully executed the function through a HTTP endpoint.
## [More event sources](overview-of-event-sources.md)
Serverless provides more than just a HTTP event source. You can find the full list of all available event sources with
corresponding examples [here](overview-of-event-sources.md).
## Conclusion
@ -56,135 +69,9 @@ Event sources are a great way to extend the functionality of your functions.
They are pretty easy to setup. You simply need to add them to the corresponding function in your services `serverless.yaml`
file and (re)deploy the service.
Serverless has implementations for different provider independent and provider specific event sources you can use.
But what if you want to add custom provider specific resources to your service which are not yet available as event
sources or through plugins?
Curious what events are available? Here's a list with [all available events](/docs/guide/event-sources.md).
Let's take a look at this now.
---
# Event sources
With Serverless you write event driven architectures. An event can be e.g. a HTTP request, a schedule event or even
an event when someone uploads a file to a cloud storage.
The `serverless.yaml` file makes it easy to add events to your functions.
Events are provider specific. Your functions can have as many events as you want it to support.
Serverless will take care and translates the events into provider specific resources when you deploy your service.
## How to use event sources
Events are defined inside the function of the `serverless.yaml` file.
Here's an example of a `users` function which implements three different events (an S3 event, a http event and a
schedule event):
```yaml
functions:
users:
handler: users.handler
events:
- s3: photos
- http:
path: users/create
method: post
- schedule:
rate: rate(10 minutes)
enabled: false
```
Let's pretend that our provider is AWS and we deploy the service this function belongs to.
Serverless will create or link the `photos` S3 bucket with the `users` function so the function get's triggered each time
a new file is uploaded or modified in the S3 bucket.
Additionally a new API Gateway endpoint is created we can access via `POST` at the `users/create` endpoint.
A disabled schedule event is also created which will trigger the function every 10 minutes if we enable it.
---
## Available event sources
Here's a list of all currently supported event sources.
### AWS
Event sources for Amazon Web Services.
#### S3
##### Simple event definition
This will create a `photos` bucket which fires the `resize` when an object is added or modified inside the bucket.
```yaml
functions:
resize:
handler: resize
events:
- s3: photos
```
##### Extended event definition
This will create a bucket `photos`. The `users` function is called whenever an object is removed from the bucket.
```yaml
functions:
users:
handler: users.handler
events:
- s3:
bucket: photos
event: s3:ObjectRemoved:*
```
#### Schedule
##### Simple event definition
This will attach a schedule event and causes the function `crawl` to be called every 2 hours.
```yaml
functions:
crawl:
handler: crawl
events:
- schedule: rate(2 hours)
```
##### Extended event definition
This will create and attach a schedule event for the `aggregate` function which is disabled. If enabled it will call
the `aggregate` function every 10 minutes.
```yaml
functions:
aggregate:
handler: statistics.handler
events:
- schedule:
rate: rate(10 minutes)
enabled: false
```
#### HTTP endpoint
##### Simple event definition
*Work in progress!*
##### Extended event definition
This will create a new HTTP endpoint which is accessible at `posts/create` with the help of the HTTP `POST` method.
The function `create` is called every time someone visits this endpoint.
```yaml
functions:
create:
handler: posts.create
events:
- http:
path: posts/create
method: POST
```
[Next step > Managing custom provider resources](custom-provider-resources.md)

85
docs/guide/overview-of-event-sources.md Normal file
View File

@ -0,0 +1,85 @@
# Overview of event sources
Here's a list of all available event sources by provider.
The examples will show you how you can use the different event definitions.
## Amazon Web Services (AWS)
### S3
#### Simple event definition
This will create a `photos` bucket which fires the `resize` function when an object is added or modified inside the bucket.
```yaml
functions:
resize:
handler: resize
events:
- s3: photos
```
#### Extended event definition
This will create a bucket `photos`. The `users` function is called whenever an object is removed from the bucket.
```yaml
functions:
users:
handler: users.handler
events:
- s3:
bucket: photos
event: s3:ObjectRemoved:*
```
### Schedule
#### Simple event definition
This will attach a schedule event and causes the function `crawl` to be called every 2 hours.
```yaml
functions:
crawl:
handler: crawl
events:
- schedule: rate(2 hours)
```
#### Extended event definition
This will create and attach a schedule event for the `aggregate` function which is disabled. If enabled it will call
the `aggregate` function every 10 minutes.
```yaml
functions:
aggregate:
handler: statistics.handler
events:
- schedule:
rate: rate(10 minutes)
enabled: false
```
### HTTP endpoint
#### Simple event definition
*Work in progress!*
#### Extended event definition
This will create a new HTTP endpoint which is accessible at `posts/create` with the help of the HTTP `POST` method.
The function `create` is called every time someone visits this endpoint.
```yaml
functions:
create:
handler: posts.create
events:
- http:
path: posts/create
method: POST
```