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.

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.

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.

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.

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.

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_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`.

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.