Un déclencheur https.onCall
pour Cloud Functions est un déclencheur HTTPS avec
format spécifique pour la requête 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 peut pas être atteint à l'aide des plates-formes Android et Apple, ni des SDK Web.
Format de la requête : en-têtes
La requête HTTP envoyée à un point de terminaison du déclencheur pouvant être appelé doit être un POST
avec le paramètre
les en-têtes suivants:
- Obligatoire:
Content-Type: application/json
- Un
; charset=utf-8
facultatif est autorisé.
- Un
- Facultatif:
Authorization: Bearer <token>
- Jeton d'ID utilisateur Firebase Authentication de l'utilisateur connecté qui effectue la requête. Le backend vérifie automatiquement ce jeton et le met à disposition dans le
context
du gestionnaire. Si le jeton n'est pas valide, la requête est rejetée.
- Jeton d'ID utilisateur Firebase Authentication de l'utilisateur connecté qui effectue la requête. Le backend vérifie automatiquement ce jeton et le met à disposition dans le
- Facultatif:
Firebase-Instance-ID-Token: <iid>
- Jeton d'enregistrement FCM du SDK du client Firebase. Il doit s'agir d'une chaîne. Cette information est disponible dans le fichier
context
du gestionnaire. Il est utilisé pour cibler les notifications push.
- Jeton d'enregistrement FCM du SDK du client Firebase. Il doit s'agir d'une chaîne. Cette information est disponible dans le fichier
- Facultatif:
X-Firebase-AppCheck: <token>
- Le jeton Firebase App Check fourni par l'application cliente effectuant la
requête. Le backend vérifie automatiquement
ce jeton et le décode,
en injectant
appId
dans lecontext
du gestionnaire. Si le jeton ne peut pas être validée, la demande est refusée. (Disponible pour SDK 3.14.0 ou version ultérieure)
- Le jeton Firebase App Check fourni par l'application cliente effectuant la
requête. Le backend vérifie automatiquement
ce jeton et le décode,
en injectant
Si d'autres en-têtes sont inclus, la requête est rejetée, comme décrit dans la documentation de réponse ci-dessous.
Remarque:Dans les clients JavaScript, ces requêtes déclenchent une requête préliminaire CORS OPTIONS
pour les raisons suivantes:
application/json
: non autorisé. Il doit s'agir detext/plain
ou deapplication/x-www-form-urlencoded
.- L'en-tête
Authorization
n'est pas un en-tête de requête de la liste de sécurité 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 requête
Le corps de la requête HTTP doit être un objet JSON comportant l'un des champs suivants:
- Obligatoire :
data
: argument transmis à la fonction. Il peut s'agir de n'importe quelle valeur JSON valide. Celui-ci 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 qu'elle est mal formée et la rejette.
Format de réponse: codes d'état
Il existe plusieurs cas qui peuvent entraîner des codes d'état HTTP différents et Codes d'état de chaîne correspondant aux errors dans la réponse.
Dans le cas d'une erreur HTTP avant l'appel du déclencheur
client
, la réponse n'est pas gérée en tant que fonction client. Par exemple, si un client tente d'appeler une fonction qui n'existe pas, il reçoit une réponse404 Not Found
.Si le déclencheur client est appelé, mais que la requête n'est pas au bon format (par exemple, qu'elle n'est pas au format JSON, qu'elle comporte des champs non valides ou qu'il manque le champ
data
), la requête est rejetée avec400 Bad Request
, avec un code d'erreurINVALID_ARGUMENT
.Si le jeton d'authentification fourni dans la requête n'est pas valide, celle-ci est rejetée avec
401 Unauthorized
, avec le code d'erreurUNAUTHENTICATED
.Si le jeton d'enregistrement FCM fourni dans la requête n'est pas valide, le comportement est indéfini. Le jeton 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 appelé, mais échoue avec une exception non gérée ou renvoie une promesse ayant échoué, la requête est rejetée avec
500 Internal Server Error
, avec un code d'erreurINTERNAL
. Cela évite que les erreurs de codage ne soient accidentellement divulguées aux utilisateurs finaux.Si l'appelable est appelé 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 à 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 encodés dans le corps de la réponse, comme détaillé ci-dessous. Cela signifie que si la fonction renvoie une erreur explicite avec l'état
OK
, l'état de la réponse est200 OK
, mais le champerror
est défini dans la réponse.Si le déclencheur client aboutit, l'état de la réponse est
200 OK
.
Format de réponse: en-têtes
La réponse contient les en-têtes suivants:
Content-Type: application/json
- Un
; charset=utf-8
facultatif est autorisé.
Corps de la réponse
La réponse d'un point de terminaison client est toujours un objet JSON. Elle doit au minimum
contient result
ou error
, ainsi que des champs facultatifs. Si le
n'est pas un objet JSON ou ne contient pas data
ni error
, le
le SDK client doit traiter la requête comme ayant échoué
avec le code d'erreur Google INTERNAL (13)
.
error
: si ce champ est présent, la requête est considérée comme ayant échoué, quel que soit le code d'état HTTP ou sidata
est également présent. 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 contient une valeur non valide, le client doit traiter l'état commeINTERNAL
, conformément à code.proto. Sidetails
est présent, il est inclus dans les informations utilisateur associées à l'erreur dans le SDK client, le cas échéant.
Remarque:Ici, le champdetails
est une valeur fournie par l'utilisateur. Il ne s'agit pas nécessairement d'une liste de valeurs associées par prototype comme dans le formatStatus
de Google.result
: valeur renvoyée par la fonction. Il peut s'agir de n'importe quelle valeur JSON valide. Le SDK des fonctions Firebase 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 requête et la réponse.
Pour assurer la cohérence de la plate-forme, ces valeurs sont encodées au format JSON comme s'il s'agissait de la valeur d'un champ Any
dans un tampon de protocole proto3, à l'aide du mappage JSON standard. Les valeurs de types simples tels que null
, int
, double
ou string
sont encodées directement et n'incluent pas leur type explicite. Ainsi, float
et double
sont encodés de la même manière, et vous ne savez peut-être pas quel élément est reçu à l'autre bout de l'appel. Pour les types qui ne sont pas natifs en JSON, l'encodage proto3 typé pour la valeur est utilisé. Pour en savoir plus, consultez la documentation sur l'encodage JSON.
Les types suivants sont autorisés:
- null -
null
- int (signé ou non signé, jusqu'à 32 bits), par exemple
3
ou-30
. - float (ex. :
3.14
- double (par exemple,
3.14
) - booléen :
true
oufalse
- chaîne : par exemple,
"hello world"
- map<string, any="">
- Exemple :
{"x": 3}
</string,> - liste
: par exemple, [1, 2, 3]
- long (signé ou non signé, jusqu'à 64 bits) - [voir ci-dessous pour en savoir plus]
Les valeurs NaN
et Infinity
pour float
et double
ne sont pas acceptées.
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, ces codes sont encodés comme suit:
long
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
sans signature (long)
{
'@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.
Comme le type n'est pas spécifié pour les types simples, certaines valeurs changeront de type après le passage du câble. Un float
transmis devient un double
. short
devient int
, et ainsi de suite. Dans Android, List
et JSONArray
sont compatibles avec les valeurs de liste. Dans ce cas, la transmission d'un objet JSONArray génère une erreur List
.
Si une carte dont le champ @type
est inconnu est désérialisée, elle est conservée en tant que carte. Cela permet aux développeurs d'ajouter des champs avec de nouveaux types à leurs valeurs de retour sans interrompre les anciens clients.
Exemples de code
Les exemples de cette section montrent comment encoder les éléments suivants :
- Exemple d'appel "callable.call" en Swift
- Une réponse indiquant que l'appel a réussi
- Une réponse d'échec pour l'appel
Exemple d'appel Callable.call en Swift pour l'encodage
callable.call([
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": -123456789123456 as Int64
])
En-tête de 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 à l'encodage
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 la réponse réussie :
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Réponse d'échec de 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 la réponse ayant échoué:
{
"error": {
"message": "Request had invalid credentials.",
"status": "UNAUTHENTICATED",
"details": {
"some-key": "some-value"
}
}
}