firebase_functions.https_fn module

Module for functions that listen to HTTPS endpoints. These can be raw web requests and Callable RPCs.

Exceptions

HttpsError

exception firebase_functions.https_fn.HttpsError(code: FunctionsErrorCode, message: str, details: Any | None = None)

Bases: Exception

An explicit error that can be thrown from a handler to send an error to the client that called the function.

code: FunctionsErrorCode

A standard error code that will be returned to the client. This also determines the HTTP status code of the response.

details: Any | None = None

Extra data to be converted to JSON and included in the error response.

Classes

AppCheckData

class firebase_functions.https_fn.AppCheckData(app_id: str, token: dict[str, Any])

Bases: object

The interface for AppCheck tokens verified in Callable functions

app_id: str

The App ID corresponding to the App the App Check token belonged to. This value is not actually one of the JWT token claims. It is added as a convenience, and is set as the value of the token sub property.

token: dict[str, Any]

The token's decoded claims.

AuthData

class firebase_functions.https_fn.AuthData(uid: str | None, token: dict[str, Any])

Bases: object

The interface for Auth tokens verified in Callable functions

token: dict[str, Any]

The ID token's decoded claims.

uid: str | None

User ID of the ID token.

CallableRequest

class firebase_functions.https_fn.CallableRequest(data: T, raw_request: Request, app: AppCheckData | None = None, auth: AuthData | None = None, instance_id_token: str | None = None)

Bases: Generic[T]

The request used to call a callable function.

app: AppCheckData | None = None

The result of decoding and verifying a Firebase AppCheck token.

auth: AuthData | None = None

" The result of decoding and verifying a Firebase Auth ID token.

data: T

The parameters used by a client when calling this function.

instance_id_token: str | None = None

An unverified token for a Firebase Instance ID.

raw_request: Request

The raw request handled by the callable.

FunctionsErrorCode

class firebase_functions.https_fn.FunctionsErrorCode(value)

Bases: str, Enum

The set of Cloud Functions status codes. The codes are the same as the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md

ABORTED = 'aborted'

The operation was aborted, typically due to a concurrency issue like transaction aborts, etc.

ALREADY_EXISTS = 'already-exists'

Some document that we attempted to create already exists.

CANCELLED = 'cancelled'

The operation was cancelled (typically by the caller).

DATA_LOSS = 'data-loss'

Unrecoverable data loss or corruption.

DEADLINE_EXCEEDED = 'deadline-exceeded'

Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

FAILED_PRECONDITION = 'failed-precondition'

Operation was rejected because the system is not in a state required for the operation's execution.

INTERNAL = 'internal'

Internal errors. Means some invariants expected by the underlying system have been broken. If you see one of these errors, something is severely broken.

INVALID_ARGUMENT = 'invalid-argument'

Client specified an invalid argument. Note that this differs from failed-precondition. invalid-argument indicates arguments that are problematic regardless of the state of the system (such as an invalid field name).

NOT_FOUND = 'not-found'

Some requested document was not found.

OK = 'ok'
OUT_OF_RANGE = 'out-of-range'

Operation was attempted past the valid range.

PERMISSION_DENIED = 'permission-denied'

The caller does not have permission to execute the specified operation.

RESOURCE_EXHAUSTED = 'resource-exhausted'

Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.

UNAUTHENTICATED = 'unauthenticated'

The request does not have valid authentication credentials for the operation.

UNAVAILABLE = 'unavailable'

The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff.

UNIMPLEMENTED = 'unimplemented'

Operation is not implemented or not supported/enabled.

UNKNOWN = 'unknown'

Unknown error or an error from a different error domain.

Functions

on_call

firebase_functions.https_fn.on_call(**kwargs) Callable[[Callable[[CallableRequest[Any]], Any]], Callable[[CallableRequest[Any]], Any]]

Declares a callable method for clients to call using a Firebase SDK. Requires a function that takes a CallableRequest.

Example:

@on_call()
def example(request: CallableRequest) -> Any:
    return "Hello World"
Parameters:

**kwargs (as firebase_functions.options.HttpsOptions) -- Https options.

Return type:

typing.Callable [ [ firebase_functions.https.CallableRequest [ object ] ], object ] A function that takes a CallableRequest and returns an object.

on_request

firebase_functions.https_fn.on_request(**kwargs) Callable[[Callable[[Request], Response]], Callable[[Request], Response]]

Handler which handles HTTPS requests. Requires a function that takes a Request and Response object, the same signature as a Flask app.

Example:

@on_request()
def example(request: Request) -> Response:
    pass
Parameters:

**kwargs (as firebase_functions.options.HttpsOptions) -- Https options.

Return type:

typing.Callable [ [ flask.Request ], flask.Response ] A function that takes a flask.Request and returns a flask.Response.