Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

Request handler for a function in Python

Written by
Updated at November 2, 2024

A request handler is a method used to process each Python function call. When creating a function version, you should specify the entry point that consists of the file name and the request handler name, e.g., main.handler. The name of the handler file must not contain any . before the extension, e.g., .handler.py.

Note

At any given time, a single function instance processes only one request. This allows you to use global variables without having to provide data integrity control.

When invoking the handler, the runtime provides the following arguments:

  1. Request body (the event parameter):

    • If the request body is a JSON document, it will be converted to dict using the json.loads method.
    • If a function was invoked with the ?integration=raw request string parameter, the HTTP request body is provided to the function as is (unprocessed).

  2. Invocation context (the context parameter).

    The context contains the requred function version information. The structure of this object is described in Python function invocation context.

Handler types

A function can use both synchronous and asynchronous request handlers.

Synchronous handler

To have the execution result returned, use the return statement or throw an exception using the raise statement. A synchronous function must return a result or throw an exception.

Asynchronous handler

A handler can be an async def asynchronous function. In this case, you can use the following statements:

  • return: Returns the function response.
  • raise: Reports an error to the runtime environment.
  • await: Tracks the execution of asynchronous function invocations.

Note

Only the asyncio library is supported as a runtime environment for asynchronous functions.

For more information about the development process using async/await, see the relevant documentation section.

Examples

HTTP request structure output

The following function outputs the request structure and invocation context to both the execution log and function response:

import json


def handler(event, context):
    return {
        'statusCode': 200,
        'body': json.dumps(
            {
                'event': event,
                'context': context,
            }, 
            default=vars,
        ),
    }

Function invocation example:

curl \
  --data '{"hello": "world"}' \
  --header 'Content-Type: application/json' \
  https://functions.yandexcloud.net/<function_ID>?param=one

Result:

{
    "context": {
        "aws_request_id": "6e8356f9-489b-4c7b-8ba6-c8cd********",
        "deadline_ms": 1657713543198,
        "function_name": "d4eo2faf62**********",
        "function_version": "d4e3vrugh3**********",
        "invoked_function_arn": "d4eo2faf62**********",
        "log_group_name": "ckgjmanjlh**********",
        "log_stream_name": "d4e3vrugh3**********",
        "memory_limit_in_mb": 128,
        "request_id": "6e8356f9-489b-4c7b-8ba6-c8cd********",
        "token": {
            "access_token": "<IAM_token>",
            "expires_in": 42299,
            "token_type": "Bearer"
        }
    },
    "event": {
        "body": "{\"hello\": \"world\"}",
        "headers": {
            "Accept": "*/*",
            "Content-Length": "18",
            "Content-Type": "application/json",
            "Host": "functions.yandexcloud.net",
            "User-Agent": "curl/7.64.1",
            "X-Forwarded-For": "109.252.148.209",
            "X-Real-Remote-Address": "[109.252.148.209]:2816",
            "X-Request-Id": "6e8356f9-489b-4c7b-8ba6-c8cd********",
            "X-Trace-Id": "e9fe9b05-c1aa-4fb8-94d8-a514********"
        },
        "httpMethod": "POST",
        "isBase64Encoded": false,
        "multiValueHeaders": {
            "Accept": [
                "*/*"
            ],
            "Content-Length": [
                "18"
            ],
            "Content-Type": [
                "application/json"
            ],
            "Host": [
                "functions.yandexcloud.net"
            ],
            "User-Agent": [
                "curl/7.64.1"
            ],
            "X-Forwarded-For": [
                "109.252.148.209"
            ],
            "X-Real-Remote-Address": [
                "[109.252.148.209]:2816"
            ],
            "X-Request-Id": [
                "6e8356f9-489b-4c7b-8ba6-c8cd********"
            ],
            "X-Trace-Id": [
                "e9fe9b05-c1aa-4fb8-94d8-a514********"
            ]
        },
        "multiValueParams": {},
        "multiValueQueryStringParameters": {
            "param": [
                "one"
            ]
        },
        "params": {},
        "pathParams": {},
        "queryStringParameters": {
            "param": "one"
        },
        "requestContext": {
            "httpMethod": "POST",
            "identity": {
                "sourceIp": "109.252.148.209",
                "userAgent": "curl/7.64.1"
            },
            "requestId": "6e8356f9-489b-4c7b-8ba6-c8cd********",
            "requestTime": "13/Jul/2022:11:58:59 +0000",
            "requestTimeEpoch": 1657713539
        },
        "url": ""
    }
}
Previous
Managing dependencies
Next
Invocation context