Un activador https.onCall
para Cloud Functions es un activador HTTPS con un formato específico para la solicitud y la respuesta. Esta sección proporciona una especificación para los formatos de solicitud y respuesta HTTPS utilizados por los SDK del cliente para implementar la API. Esta información puede resultarle útil si sus requisitos no se pueden cumplir con las plataformas de Android, Apple o los SDK web.
Formato de solicitud: encabezados
La solicitud HTTP a un punto final de activación invocable debe ser una POST
con los siguientes encabezados:
- Requerido:
Content-Type: application/json
- Un opcional
; charset=utf-8
está permitido.
- Un opcional
- Opcional:
Authorization: Bearer <token>
- Un token de ID de usuario de Firebase Authentication para el usuario que inició sesión y realiza la solicitud. El backend verifica automáticamente este token y lo pone a disposición en el
context
del controlador. Si el token no es válido, se rechaza la solicitud.
- Un token de ID de usuario de Firebase Authentication para el usuario que inició sesión y realiza la solicitud. El backend verifica automáticamente este token y lo pone a disposición en el
- Opcional:
Firebase-Instance-ID-Token: <iid>
- El token de registro de FCM del SDK del cliente de Firebase. Esto debe ser una cadena. Está disponible en el
context
del controlador. Se utiliza para orientar las notificaciones push.
- El token de registro de FCM del SDK del cliente de Firebase. Esto debe ser una cadena. Está disponible en el
- Opcional:
X-Firebase-AppCheck: <token>
- El token de Firebase App Check proporcionado por la aplicación cliente que realiza la solicitud. El backend verifica automáticamente este token y lo decodifica, inyectando el
appId
en elcontext
del controlador. Si no se puede verificar el token, se rechaza la solicitud. (Disponible para SDK >=3.14.0)
- El token de Firebase App Check proporcionado por la aplicación cliente que realiza la solicitud. El backend verifica automáticamente este token y lo decodifica, inyectando el
Si se incluyen otros encabezados, la solicitud se rechaza, como se describe en la documentación de respuesta a continuación.
Nota: En los clientes de JavaScript, estas solicitudes desencadenan una verificación previa de CORS OPTIONS
porque:
-
application/json
no está permitido. Debe sertext/plain
oapplication/x-www-form-urlencoded
. - El encabezado
Authorization
no es un encabezado de solicitud incluido en la lista segura de CORS . - Tampoco se permiten otros encabezados.
El disparador invocable maneja automáticamente estas solicitudes de OPTIONS
.
cuerpo de la solicitud
El cuerpo de la solicitud HTTP debe ser un objeto JSON con cualquiera de los siguientes campos:
- Requerido:
data
- El argumento pasado a la función. Puede ser cualquier valor JSON válido. Esto se decodifica automáticamente en tipos nativos de JavaScript de acuerdo con el formato de serialización que se describe a continuación.
Si hay otros campos presentes en la solicitud, el backend considera que la solicitud tiene un formato incorrecto y se rechaza.
Formato de respuesta: códigos de estado
Hay varios casos que podrían resultar en diferentes códigos de estado HTTP y códigos de estado de cadena para errores en la respuesta.
En el caso de un error HTTP antes de que se invoque el disparador del
client
, la respuesta no se maneja como una función del cliente. Por ejemplo, si un cliente intenta invocar una función inexistente, recibe una respuesta404 Not Found
.Si se invoca el activador del cliente, pero la solicitud tiene un formato incorrecto, como no ser JSON, tener campos no válidos o falta el campo
data
, la solicitud se rechaza con400 Bad Request
, con un código de error deINVALID_ARGUMENT
.Si el token de autenticación proporcionado en la solicitud no es válido, la solicitud se rechaza con
401 Unauthorized
, con un código de error deUNAUTHENTICATED
.Si el token de registro de FCM proporcionado en la solicitud no es válido, el comportamiento no está definido. El token no se verifica en cada solicitud, excepto cuando se usa para enviar una notificación push con FCM.
Si se invoca el activador invocable, pero falla con una excepción no controlada o devuelve una promesa fallida, la solicitud se rechaza con
500 Internal Server Error
, con un código de error deINTERNAL
. Esto evita que los errores de codificación se expongan accidentalmente a los usuarios finales.Si se invoca el invocable y devuelve una condición de error explícita utilizando la API proporcionada para las funciones invocables, la solicitud falla. El código de estado HTTP devuelto se basa en la asignación oficial del estado de error al estado HTTP, como se define en code.proto . El código de error específico, el mensaje y los detalles devueltos se codifican en el cuerpo de la respuesta como se detalla a continuación. Esto significa que si la función devuelve un error explícito con el estado
OK
, entonces la respuesta tiene el estado200 OK
, pero el campo deerror
se establece en la respuesta.Si el activador del cliente tiene éxito, el estado de respuesta es
200 OK
.
Formato de respuesta: encabezados
La respuesta tiene los siguientes encabezados:
-
Content-Type: application/json
- Un opcional
; charset=utf-8
está permitido.
Cuerpo de respuesta
La respuesta de un punto final de cliente siempre es un objeto JSON. Como mínimo, contiene result
o error
, junto con cualquier campo opcional. Si la respuesta no es un objeto JSON o no contiene data
o error
, el SDK del cliente debe tratar la solicitud como fallida con el código de error de Google INTERNAL (13)
.
-
error
: si este campo está presente, la solicitud se considera fallida, independientemente del código de estado HTTP o sidata
también están presentes. El valor de este campo debe ser un objeto JSON en el formato de asignación HTTP estándar de Google Cloud para errores, con campos parastatus
,message
y (opcionalmente)details
. El campo decode
no se incluirá. Si el campo destatus
está configurado o es un valor no válido, el cliente debe tratar el estado comoINTERNAL
, de acuerdo con code.proto . Si losdetails
están presentes, se incluyen en cualquier información de usuario adjunta al error en el SDK del cliente, si corresponde.
Nota: El campo dedetails
aquí es un valor proporcionado por el usuario. No es necesariamente una lista de valores tecleados por tipo de prototipo como en el formato deStatus
de Google. -
result
: el valor devuelto por la función. Puede ser cualquier valor JSON válido. El SDK de firebase-functions codifica automáticamente el valor devuelto por el usuario en este formato JSON. Los SDK del cliente descodifican automáticamente estos parámetros en tipos nativos de acuerdo con el formato de serialización que se describe a continuación.
Si hay otros campos presentes, deben ignorarse.
Publicación por entregas
El formato de serialización para cargas útiles de datos arbitrarios es el mismo tanto para la solicitud como para la respuesta.
Para mantener la coherencia de la plataforma, estos están codificados en JSON como si fueran el valor de un campo Any
en un búfer de protocolo proto3, utilizando el mapeo JSON estándar . Los valores de tipos simples como null
, int
, double
o string
se codifican directamente y no incluyen su tipo explícito. Por lo tanto, un float
y un double
se codifican de la misma manera, y es posible que no sepa cuál se recibe en el otro extremo de la llamada. Para los tipos que no son nativos de JSON, se usa la codificación proto3 escrita para el valor. Para obtener más información, consulte la documentación de Cualquier codificación JSON .
Se permiten los siguientes tipos:
- nulo -
null
- int (con o sin signo, hasta 32 bits), por ejemplo,
3
o-30
. - flotante - por ejemplo,
3.14
- doble - por ejemplo,
3.14
- booleano -
true
ofalse
- cadena - por ejemplo,
"hello world"
- mapa
- por ejemplo {"x": 3}
- lista
- por ejemplo [1, 2, 3]
- largo (firmado o sin firmar, hasta 64 bits) - [ver más abajo para más detalles]
No se admiten los valores NaN
e Infinity
para float
y double
.
Tenga en cuenta que long
es un tipo especial que normalmente no se permite en JSON, pero está cubierto por la especificación proto3. Por ejemplo, estos se codifican como:
largo
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
largo sin firmar
{
'@type': 'type.googleapis.com/google.protobuf.UInt64Value',
'value': '123456789123456'
}
En general, la tecla @type
se debe considerar reservada y no se debe usar para mapas pasados.
Debido a que el tipo no se especifica para los tipos simples, algunos valores cambiarán de tipo después de pasar por el cable. Un float
pasado se convierte en un double
. Un short
se convierte en un int
, y así sucesivamente. En Android, tanto List
como JSONArray
son compatibles con los valores de lista. En esos casos, pasar un JSONArray producirá una List
.
Si se deserializa un mapa con un campo @type
desconocido, se deja como un mapa. Esto permite a los desarrolladores agregar campos con nuevos tipos a sus valores devueltos sin interrumpir a los clientes más antiguos.
Ejemplos de código
Los ejemplos de esta sección ilustran cómo codificar lo siguiente:
- Un ejemplo callable.call en Swift
- Una respuesta de éxito para la llamada.
- Una respuesta de falla para la llamada.
Ejemplo Callable.call en Swift para codificar
callable.call([
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": -123456789123456 as Int64
])
Encabezado de la solicitud:
Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token
Cuerpo de la solicitud:
{
"data": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": {
"@type": "type.googleapis.com/google.protobuf.Int64Value",
"value": "-123456789123456"
}
}
}
Respuesta a codificar
return {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
};
Encabezado de respuesta exitosa:
200 OK
Content-Type: application/json; charset=utf-8
Cuerpo de respuesta exitosa:
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Respuesta de falla para codificar
throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
"some-key": "some-value"
});
Encabezado de respuesta fallida:
401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8
Cuerpo de respuesta fallido:
{
"error": {
"message": "Request had invalid credentials.",
"status": "UNAUTHENTICATED",
"details": {
"some-key": "some-value"
}
}
}