Skip to content

docs: update README to use declarative function signatures #171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 1, 2021
Merged

docs: update README to use declarative function signatures #171

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6e128b8
docs: update README to use declarative function signatures
anniefu Nov 23, 2021
fe2771d
Fix newline
anniefu Nov 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 33 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,19 @@ pip install functions-framework
Or, for deployment, add the Functions Framework to your `requirements.txt` file:

```
functions-framework==2.3.0
functions-framework==3.*
```

## Quickstarts

### Quickstart: Hello, World on your local machine
### Quickstart: HTTP Function (Hello World)

Create an `main.py` file with the following contents:

```python
import functions_framework

@functions_framework.http
def hello(request):
return "Hello world!"
```
Expand All @@ -67,30 +70,6 @@ def hello(request):

Run the following command:

```sh
functions-framework --target=hello
```

Open http://localhost:8080/ in your browser and see *Hello world!*.


### Quickstart: Set up a new project

Create a `main.py` file with the following contents:

```python
def hello(request):
return "Hello world!"
```

Now install the Functions Framework:

```sh
pip install functions-framework
```

Use the `functions-framework` command to start the built-in local development server:

```sh
functions-framework --target hello --debug
* Serving Flask app "hello" (lazy loading)
Expand All @@ -101,17 +80,19 @@ functions-framework --target hello --debug
* Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
```

(You can also use `functions-framework-python` if you potentially have multiple
(You can also use `functions-framework-python` if you have multiple
language frameworks installed).

Send requests to this function using `curl` from another terminal window:
Open http://localhost:8080/ in your browser and see *Hello world!*.

Or send requests to this function using `curl` from another terminal window:

```sh
curl localhost:8080
# Output: Hello world!
```

### Quickstart: Register your function using decorator
### Quickstart: CloudEvent Function

Create an `main.py` file with the following contents:

Expand All @@ -120,27 +101,37 @@ import functions_framework

@functions_framework.cloud_event
def hello_cloud_event(cloud_event):
return f"Received event with ID: {cloud_event['id']} and data {cloud_event.data}"

@functions_framework.http
def hello_http(request):
return "Hello world!"

print(f"Received event with ID: {cloud_event['id']} and data {cloud_event.data}")
```

Run the following command to run `hello_http` target locally:
> Your function is passed a single [CloudEvent](https://github.com/cloudevents/sdk-python/blob/master/cloudevents/sdk/event/v1.py) parameter.

Run the following command to run `hello_cloud_event` target locally:

```sh
functions-framework --target=hello_http
functions-framework --target=hello_cloud_event
```

Open http://localhost:8080/ in your browser and see *Hello world!*.

Run the following command to run `hello_cloud_event` target locally:
In a different terminal, `curl` the Functions Framework server:

```sh
functions-framework --target=hello_cloud_event
curl -X POST localhost:8080 \
-H "Content-Type: application/cloudevents+json" \
-d '{
Comment on lines +119 to +120
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: mix of " and ' chars.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was intentional to differentiate the JSON and the beginning/end of the data blob for the terminal

"specversion" : "1.0",
"type" : "example.com.cloud.event",
"source" : "https://example.com/cloudevents/pull",
"subject" : "123",
"id" : "A234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"data" : "hello world"
}'
```

Output from the terminal running `functions-framework`:
```
Received event with ID: A234-1234-1234 and data hello world
```

More info on sending [CloudEvents](http://cloudevents.io) payloads, see [`examples/cloud_run_cloud_events`](examples/cloud_run_cloud_events/) instruction.

Expand Down Expand Up @@ -333,7 +324,7 @@ You can configure the Functions Framework using command-line flags or environmen
| `--debug` | `DEBUG` | A flag that allows to run functions-framework to run in debug mode, including live reloading. Default: `False` |
| `--dry-run` | `DRY_RUN` | A flag that allows for testing the function build from the configuration without creating a server. Default: `False` |

## Enable Google Cloud Functions Events
## Enable Google Cloud Function Events

The Functions Framework can unmarshall incoming
Google Cloud Functions [event](https://cloud.google.com/functions/docs/concepts/events-triggers#events) payloads to `event` and `context` objects.
Expand All @@ -356,19 +347,6 @@ documentation on

See the [running example](examples/cloud_run_event).

## Enable CloudEvents

The Functions framework can also unmarshall incoming [CloudEvents](http://cloudevents.io) payloads to the `cloud_event` object. This will be passed as a [CloudEvent](https://github.com/cloudevents/sdk-python) to your function when it receives a request. Note that your function must use the `CloudEvents`-style function signature:

```python
def hello(cloud_event):
print(f"Received event with ID: {cloud_event['id']}")
```

To enable automatic unmarshalling, set the function signature type to `cloudevent` using the `--signature-type` command-line flag or the `FUNCTION_SIGNATURE_TYPE` environment variable. By default, the HTTP signature type will be used and automatic event unmarshalling will be disabled.

For more details on this signature type, check out the Google Cloud Functions documentation on [background functions](https://cloud.google.com/functions/docs/writing/background#cloud_pubsub_example).

## Advanced Examples

More advanced guides can be found in the [`examples/`](examples/) directory.
Expand Down