Spécification du protocole pour https.onCall

Un https.onCall déclencheur pour les fonctions Cloud est un déclencheur HTTPS avec un format spécifique pour la demande et la réponse. Cette section fournit une spécification pour les 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 SDK Android, iOS ou Web.

Format de la demande : en-têtes

La requête HTTP à un point final de déclenchement appelable doit être un POST avec les en- têtes suivants:

  • Requis: Content-Type: application/json
    • Une option ; charset=utf-8 est autorisé.
  • Facultatif: Authorization: Bearer <token>
    • Un jeton d'ID utilisateur d'authentification Firebase pour l'utilisateur connecté effectuant la demande. Le back - end automatiquement vérifie ce jeton et le rend disponible dans le gestionnaire context . Si le jeton n'est pas valide, la demande est rejetée.
  • En option: Firebase-Instance-ID-Token: <iid>
    • Le jeton d'enregistrement FCM du SDK client Firebase. Ce doit être une chaîne. Il est disponible dans le gestionnaire context . Il est utilisé pour cibler les notifications push.
  • En option: X-Firebase-AppCheck: <token>
    • Le jeton Firebase App Check fourni par l'application cliente faisant la demande. Le back - end vérifie automatiquement ce jeton et le décode, l' injection du appId dans le gestionnaire context . Si le jeton ne peut pas être vérifié, la demande est rejetée. (Disponible pour SDK >=3.14.0)

Si d'autres en-têtes sont inclus, la demande est rejetée, comme décrit dans la documentation de réponse ci-dessous.

Note: les clients en JavaScript, ces demandes déclenchent une CORS OPTIONS prévol, parce que:

  • application/json est pas autorisée. Il doit être text/plain ou application/x-www-form-urlencoded .
  • L' Authorization tête n'est pas un CORS-safelisted demande en -tête .
  • Les autres en-têtes ne sont pas non plus autorisés.

Le déclencheur appelable gère automatiquement ces OPTIONS demandes.

Corps de la demande

Le corps de la requête HTTP doit être un objet JSON avec l'un des champs suivants :

  • Requis: data - L'argument passé à 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.

S'il y a d'autres champs présents dans la demande, le backend considère que la demande est mal formée et elle est rejetée.

Format de réponse : codes d'état

Il y a plusieurs cas qui pourraient se traduire par différents codes d'état HTTP et les codes d'état de chaîne pour des erreurs dans la réponse.

  1. Dans le cas d'une erreur HTTP avant que le client déclencheur est invoquée, la réponse n'a pas été traitée comme une fonction de client. Par exemple, si un client essaie d'appeler une fonction inexistante, il reçoit un 404 Not Found réponse.

  2. Si le déclencheur client est invoqué, mais la demande est dans le mauvais format, tels que ne pas être JSON, ayant des champs invalides, ou manquant les data terrain, la demande est rejetée avec 400 Bad Request , avec un code d'erreur de INVALID_ARGUMENT .

  3. Si l'auth jeton fourni dans la demande est invalide, la demande est rejetée avec 401 Unauthorized , avec un code d'erreur de UNAUTHENTICATED .

  4. Si le jeton d'enregistrement FCM fourni dans la demande n'est pas valide, le comportement n'est pas défini. Le jeton n'est pas vérifié à chaque requête, sauf lorsqu'il est utilisé pour envoyer une notification push avec FCM.

  5. Si le déclencheur appelable est invoquée, mais échoue avec une exception non gérée ou retourne une promesse non, la demande est rejetée avec 500 Internal Server Error , avec un code d'erreur INTERNAL . Cela empêche les erreurs de codage d'être accidentellement exposées aux utilisateurs finaux.

  6. Si l'appelable est appelé et renvoie une condition d'erreur explicite à l'aide de l'API fournie pour les fonctions appelables, la demande échoue. Le code d'état HTTP renvoyé est basé sur la cartographie officielle de l' état d'erreur de statut 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 , la réponse a le statut 200 OK , mais l' error champ est défini dans la réponse.

  7. Si le déclencheur client réussit, l'état de 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
  • Une option ; 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 ou error , ainsi que tous les champs facultatifs. Si la réponse n'est pas un objet JSON, ou ne contient pas de data ou error , le SDK client doit traiter la demande comme ayant échoué avec Google code d'erreur INTERNAL (13) .

  • error - Si ce champ est présent, la demande est considéré comme ayant échoué, quel que soit le code d'état HTTP ou si des data est également présent. La valeur de ce champ doit être un objet JSON dans la norme Google Cloud HTTP Mapping format d'erreurs, avec des champs pour l' status , un message , et (éventuellement) les details . Le code de champ ne doit pas être inclus. Si l' status champ est hors service, ou est une valeur non valide, le client doit traiter le statut INTERNAL , conformément à code.proto . Si les details sont présents, il est inclus dans toute information d'utilisateur attaché à l'erreur dans le SDK client, le cas échéant.
    Note: Le details champ est une valeur fournie par l' utilisateur ici. Il est pas nécessairement une liste de valeurs calées par type proto comme dans le Google Status format.
  • result - La valeur retourné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.

Par souci de cohérence de la plate-forme, ceux - ci sont codés en JSON comme si elles correspondent à la valeur d'une Any champ dans un tampon de protocole proto3, en utilisant le mappage standard JSON . Les valeurs des types simples comme null , int , double ou string sont codées directement, et ne comprennent pas leur type explicite. Ainsi, un float et double sont codés de la même façon, et vous ne savez pas qui est reçu à l'autre bout de l'appel. Pour les types qui ne sont pas natifs de JSON, l'encodage proto3 typé pour la valeur est utilisé. Pour plus d' informations, consultez la documentation Tout codage JSON .

Les types suivants sont autorisés :

  • null - null
  • int (signé ou non signé, jusqu'à 32 bits) - par exemple 3 ou -30 .
  • flotteur - par exemple 3.14
  • double - par exemple 3.14
  • booléen - true ou false
  • string - par exemple "hello world" tout le "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]

NaN et Infinity valeurs pour float et double ne sont pas pris en charge.

Notez que de long est un type spécial normalement pas autorisé dans JSON, mais il est couvert par la spécification proto3. Par exemple, ceux-ci sont codés comme :

longue

{
    '@type': 'type.googleapis.com/google.protobuf.Int64Value',
    'value': '-123456789123456'
}

long non signé

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

En général, la @type clé doit être considérée comme réservée, et non utilisé pour les cartes transmis.

É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 passé en devient double . Un short devient un int , et ainsi de suite. Dans Android, à la fois la List et JSONArray sont pris en charge pour les valeurs de la liste. Dans ces cas, en passant dans un JSONArray donnera une List .

Si une carte avec un inconnu @type champ est désérialisée, il est laissé en plan. Cela permet aux développeurs d'ajouter des champs avec de nouveaux types à leurs valeurs de retour sans casser les clients plus anciens.

Exemples de code

Les exemples de cette section illustrent comment coder les éléments suivants :

  • Un exemple callable.call dans Swift
  • Une réponse réussie à 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
    }
}

Échec de la réponse à l'encodage

throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
  "some-key": "some-value"
});

Échec de l'en-tête de réponse :

401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8

Échec du corps de la réponse :

{
    "error": {
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": {
            "some-key": "some-value"
        }
    }
}