Un déclencheur https.onCall
pour Cloud Functions est un déclencheur HTTPS avec un format spécifique pour la demande et la réponse. Cette section fournit une spécification des formats de requête et de réponse HTTPS utilisés par les SDK clients pour implémenter l'API. Ces informations peuvent vous être utiles si vos besoins ne peuvent pas être satisfaits à l'aide des plates-formes Android, Apple ou des SDK Web.
Format de la demande : en-têtes
La requête HTTP adressée à un point de terminaison de déclencheur appelable doit être un POST
avec les en-têtes suivants :
- Obligatoire :
Content-Type: application/json
- Un facultatif
; charset=utf-8
est autorisé.
- Un facultatif
- Facultatif :
Authorization: Bearer <token>
- Un jeton d'ID utilisateur d'authentification Firebase pour l'utilisateur connecté effectuant la demande. Le backend vérifie automatiquement ce jeton et le rend disponible dans le
context
du gestionnaire. Si le jeton n'est pas valide, la demande est rejetée.
- Un jeton d'ID utilisateur d'authentification Firebase pour l'utilisateur connecté effectuant la demande. Le backend vérifie automatiquement ce jeton et le rend disponible dans le
- Facultatif :
Firebase-Instance-ID-Token: <iid>
- Le jeton d'enregistrement FCM du SDK du client Firebase. Cela doit être une chaîne. Ceci est disponible dans le
context
du gestionnaire. Il est utilisé pour cibler les notifications push.
- Le jeton d'enregistrement FCM du SDK du client Firebase. Cela doit être une chaîne. Ceci est disponible dans le
- Facultatif :
X-Firebase-AppCheck: <token>
- Jeton Firebase App Check fourni par l'application client qui effectue la demande. Le backend vérifie automatiquement ce jeton et le décode, en injectant l'
appId
dans lecontext
du gestionnaire. Si le jeton ne peut pas être vérifié, la demande est rejetée. (Disponible pour le SDK >=3.14.0)
- Jeton Firebase App Check fourni par l'application client qui effectue la demande. Le backend vérifie automatiquement ce jeton et le décode, en injectant l'
Si d’autres en-têtes sont inclus, la demande est rejetée, comme décrit dans la documentation de réponse ci-dessous.
Remarque : Dans les clients JavaScript, ces requêtes déclenchent un contrôle en amont CORS OPTIONS
, car :
-
application/json
n’est pas autorisé. Il doit s'agirtext/plain
ouapplication/x-www-form-urlencoded
. - L’en-tête
Authorization
n’est pas un en-tête de requête sécurisé CORS . - De même, les autres en-têtes ne sont pas autorisés.
Le déclencheur appelable gère automatiquement ces requêtes OPTIONS
.
Corps de la demande
Le corps de la requête HTTP doit être un objet JSON avec l'un des champs suivants :
- Obligatoire :
data
- L'argument passé à la fonction. Il peut s'agir de n'importe quelle valeur JSON valide. Ceci est automatiquement décodé en types JavaScript natifs selon le format de sérialisation décrit ci-dessous.
Si d'autres champs sont présents dans la requête, le backend considère la requête comme mal formée et elle est rejetée.
Format de réponse : codes d'état
Il existe plusieurs cas qui peuvent entraîner des codes d'état HTTP et des codes d'état de chaîne différents pour les erreurs dans la réponse.
Dans le cas d'une erreur HTTP avant l'appel du déclencheur
client
, la réponse n'est pas traitée comme une fonction client. Par exemple, si un client tente d'invoquer une fonction inexistante, il reçoit une réponse404 Not Found
.Si le déclencheur client est invoqué, mais que la demande est dans un format incorrect, par exemple si elle n'est pas JSON, comporte des champs non valides ou manque le champ
data
, la demande est rejetée avec400 Bad Request
, avec un code d'erreurINVALID_ARGUMENT
.Si le jeton d'authentification fourni dans la demande n'est pas valide, la demande est rejetée avec
401 Unauthorized
, avec un code d'erreurUNAUTHENTICATED
.Si le jeton d'enregistrement FCM fourni dans la demande n'est pas valide, le comportement n'est pas défini. Le token n'est pas vérifié à chaque requête, sauf lorsqu'il est utilisé pour envoyer une notification push avec FCM.
Si le déclencheur appelable est invoqué, mais échoue avec une exception non gérée ou renvoie une promesse échouée, la demande est rejetée avec
500 Internal Server Error
, avec un code d'erreurINTERNAL
. Cela évite que des erreurs de codage soient accidentellement exposées aux utilisateurs finaux.Si l'appelable est invoqué et renvoie une condition d'erreur explicite à l'aide de l'API fournie pour les fonctions appelables, la requête échoue. Le code d'état HTTP renvoyé est basé sur le mappage officiel de l'état d'erreur avec l'état HTTP, tel que défini dans code.proto . Le code d'erreur spécifique, le message et les détails renvoyés sont codés dans le corps de la réponse comme détaillé ci-dessous. Cela signifie que si la fonction renvoie une erreur explicite avec le statut
OK
, alors la réponse a le statut200 OK
, mais le champerror
est défini dans la réponse.Si le déclencheur client réussit, l'état de la réponse est
200 OK
.
Format de réponse : en-têtes
La réponse comporte les en-têtes suivants :
-
Content-Type: application/json
- Un facultatif
; charset=utf-8
est autorisé.
Corps de réponse
La réponse d'un point de terminaison client est toujours un objet JSON. Au minimum, il contient soit result
soit error
, ainsi que tous les champs facultatifs. Si la réponse n'est pas un objet JSON ou ne contient pas data
ou error
, le SDK client doit traiter la demande comme ayant échoué avec le code d'erreur Google INTERNAL (13)
.
-
error
- Si ce champ est présent, alors la demande est considérée comme ayant échoué, quel que soit le code d'état HTTP ou sidata
sont également présentes. La valeur de ce champ doit être un objet JSON au format standard de mappage HTTP Google Cloud pour les erreurs, avec des champs pourstatus
,message
et (éventuellement)details
. Le champcode
ne doit pas être inclus. Si le champstatus
n'est pas défini ou s'il s'agit d'une valeur non valide, le client doit traiter le statut commeINTERNAL
, conformément à code.proto . Sidetails
sont présents, ils sont inclus dans toutes les informations utilisateur jointes à l'erreur dans le SDK client, le cas échéant.
Remarque : Le champdetails
ici est une valeur fournie par l'utilisateur. Il ne s'agit pas nécessairement d'une liste de valeurs saisies par type de proto comme dans le format GoogleStatus
. -
result
- La valeur renvoyée par la fonction. Il peut s'agir de n'importe quelle valeur JSON valide. Le SDK Firebase-functions encode automatiquement la valeur renvoyée par l'utilisateur dans ce format JSON. Les SDK clients décodent automatiquement ces paramètres en types natifs selon le format de sérialisation décrit ci-dessous.
Si d'autres champs sont présents, ils doivent être ignorés.
Sérialisation
Le format de sérialisation des charges utiles de données arbitraires est le même pour la demande et la réponse.
Pour des raisons de cohérence sur la plate-forme, ceux-ci sont codés en JSON comme s'il s'agissait de la valeur d'un champ Any
dans un tampon de protocole proto3, en utilisant le mappage JSON standard . Les valeurs de types simples tels que null
, int
, double
ou string
sont codées directement et n'incluent pas leur type explicite. Ainsi, un float
et double
sont codés de la même manière, et vous ne savez peut-être pas lequel est reçu à l'autre bout de l'appel. Pour les types qui ne sont pas natifs de JSON, le codage proto3 typé pour la valeur est utilisé. Pour plus d'informations, consultez la documentation pour Tout encodage JSON .
Les types suivants sont autorisés :
- nul -
null
- int (signé ou non signé, jusqu'à 32 bits) - par exemple
3
ou-30
. - float - par exemple
3.14
- double - par exemple
3.14
- booléen -
true
oufalse
- chaîne - par exemple
"hello world"
- carte
- par exemple {"x": 3}
- liste
- par exemple [1, 2, 3]
- long (signé ou non signé, jusqu'à 64 bits) - [voir ci-dessous pour plus de détails]
Les valeurs NaN
et Infinity
pour float
et double
ne sont pas prises en charge.
Notez que long
est un type spécial qui n'est normalement pas autorisé dans JSON, mais qui est couvert par la spécification proto3. Par exemple, ceux-ci sont codés comme suit :
long
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
non signé depuis longtemps
{
'@type': 'type.googleapis.com/google.protobuf.UInt64Value',
'value': '123456789123456'
}
En général, la clé @type
doit être considérée comme réservée et non utilisée pour les cartes transmises.
Étant donné que le type n'est pas spécifié pour les types simples, certaines valeurs changeront de type après leur passage sur le fil. Un float
transmis devient un double
. Un short
devient un int
, et ainsi de suite. Sous Android, List
et JSONArray
sont pris en charge pour les valeurs de liste. Dans ces cas, transmettre un JSONArray donnera un List
.
Si une carte avec un champ @type
inconnu est désérialisée, elle reste sous forme de carte. Cela permet aux développeurs d'ajouter des champs avec de nouveaux types à leurs valeurs de retour sans casser les anciens clients.
Exemples de codes
Les exemples de cette section illustrent comment coder les éléments suivants :
- Un exemple callable.call dans Swift
- Une réponse positive à l’appel
- Une réponse d'échec pour l'appel
Exemple Callable.call dans Swift pour encoder
callable.call([
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": -123456789123456 as Int64
])
En-tête de la requête :
Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token
Corps de la requête :
{
"data": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": {
"@type": "type.googleapis.com/google.protobuf.Int64Value",
"value": "-123456789123456"
}
}
}
Réponse à encoder
return {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
};
En-tête de réponse réussie :
200 OK
Content-Type: application/json; charset=utf-8
Corps de réponse réussie :
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Réponse d'échec à l'encodage
throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
"some-key": "some-value"
});
En-tête de réponse ayant échoué :
401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8
Corps de réponse ayant échoué :
{
"error": {
"message": "Request had invalid credentials.",
"status": "UNAUTHENTICATED",
"details": {
"some-key": "some-value"
}
}
}