Protokollspezifikation für https.onCall

Ein https.onCall-Trigger für Cloud Functions ist ein HTTPS-Trigger mit einem bestimmten Format für die Anfrage und Antwort. In diesem Abschnitt finden Sie eine Spezifikation für die HTTPS-Anfrage- und Antwortformate, die von den Client-SDKs zur Implementierung der API verwendet werden. Diese Informationen können hilfreich sein, wenn Ihre Anforderungen nicht mit den Android-, Apple-Plattformen oder Web-SDKs erfüllt werden können.

Anfrageformat: Header

Die HTTP-Anfrage an einen aufrufbaren Triggerendpunkt muss eine POST mit den folgenden Headern sein:

  • Erforderlich: Content-Type: application/json
    • Ein optionaler ; charset=utf-8 ist zulässig.
  • Optional: Authorization: Bearer <token>
    • Ein Firebase Authentication-Nutzer-ID-Token für den angemeldeten Nutzer, der die Anfrage stellt. Das Back-End überprüft dieses Token automatisch und stellt es im context des Handlers zur Verfügung. Ist das Token ungültig, wird die Anfrage abgelehnt.
  • Optional: Firebase-Instance-ID-Token: <iid>
    • Das FCM-Registrierungstoken aus dem Firebase Client SDK. Dies muss ein String sein. Diese ist im context des Handlers verfügbar. Sie wird für das Targeting von Push-Benachrichtigungen verwendet.
  • Optional: X-Firebase-AppCheck: <token>
    • Das Firebase App Check-Token, das von der Client-App bereitgestellt wird, die die Anfrage stellt. Das Backend überprüft dieses Token automatisch und decodiert es, wobei das appId in die context des Handlers eingefügt wird. Wenn das Token nicht verifiziert werden kann, wird die Anfrage abgelehnt. (Verfügbar für SDK ab Version 3.14.0)

Wenn andere Header enthalten sind, wird die Anfrage abgelehnt, wie in der Antwortdokumentation unten beschrieben.

Hinweis: In JavaScript-Clients lösen diese Anfragen einen CORS-OPTIONS-Preflight aus, weil:

  • application/json ist nicht zulässig. Es muss text/plain oder application/x-www-form-urlencoded sein.
  • Der Authorization-Header ist kein CORS-Anfrageheader auf der Zulassungsliste.
  • Andere Header sind ebenfalls nicht zulässig.

Der aufrufbare Trigger verarbeitet diese OPTIONS-Anfragen automatisch.

Anfragetext

Der Text der HTTP-Anfrage sollte ein JSON-Objekt mit einem der folgenden Felder sein:

  • Erforderlich: data – das an die Funktion übergebene Argument. Dies kann ein beliebiger gültiger JSON-Wert sein. Diese werden automatisch gemäß dem unten beschriebenen Serialization-Format in native JavaScript-Typen decodiert.

Wenn die Anfrage weitere Felder enthält, betrachtet das Back-End die Anfrage als fehlerhaft und wird abgelehnt.

Antwortformat: Statuscodes

Es gibt mehrere Fälle, die zu verschiedenen HTTP-Statuscodes und Stringstatuscodes für Fehler in der Antwort führen können.

  1. Tritt ein HTTP-Fehler auf, bevor der Trigger client aufgerufen wird, wird die Antwort nicht als Clientfunktion verarbeitet. Wenn ein Client beispielsweise versucht, eine nicht vorhandene Funktion aufzurufen, erhält er eine 404 Not Found-Antwort.

  2. Wenn der Clienttrigger aufgerufen wird, die Anfrage aber im falschen Format ist, z. B. kein JSON-Format, ungültige Felder oder das Feld data fehlt, wird die Anfrage mit 400 Bad Request und dem Fehlercode INVALID_ARGUMENT abgelehnt.

  3. Wenn das in der Anfrage angegebene Authentifizierungstoken ungültig ist, wird die Anfrage mit 401 Unauthorized abgelehnt, wobei der Fehlercode UNAUTHENTICATED lautet.

  4. Wenn das in der Anfrage angegebene FCM-Registrierungstoken ungültig ist, ist das Verhalten nicht definiert. Das Token wird nicht bei jeder Anfrage überprüft, es sei denn, es wird verwendet, um eine Push-Benachrichtigung mit FCM zu senden.

  5. Wenn der aufrufbare Trigger aufgerufen wird, aber mit einer nicht behandelten Ausnahme fehlschlägt oder ein fehlgeschlagenes Versprechen zurückgibt, wird die Anfrage mit 500 Internal Server Error und dem Fehlercode INTERNAL abgelehnt. So wird verhindert, dass Codierungsfehler versehentlich Endnutzern angezeigt werden.

  6. Wenn die aufrufbare Funktion aufgerufen wird und eine explizite Fehlerbedingung mithilfe der API für aufrufbare Funktionen zurückgibt, schlägt die Anfrage fehl. Der zurückgegebene HTTP-Statuscode basiert auf der offiziellen Zuordnung des Fehlerstatus zum HTTP-Status, wie in code.proto definiert. Der spezifische Fehlercode, die Meldung und die zurückgegebenen Details sind wie unten beschrieben im Antworttext codiert. Wenn die Funktion also einen expliziten Fehler mit dem Status OK zurückgibt, hat die Antwort den Status 200 OK, aber das Feld error ist in der Antwort festgelegt.

  7. Wenn der Clienttrigger erfolgreich ist, lautet der Antwortstatus 200 OK.

Antwortformat: Header

Die Antwort enthält die folgenden Header:

  • Content-Type: application/json
  • Ein optionaler ; charset=utf-8 ist zulässig.

Antworttext

Die Antwort eines Clientendpunkts ist immer ein JSON-Objekt. Es enthält mindestens result oder error sowie alle optionalen Felder. Wenn die Antwort kein JSON-Objekt ist oder data oder error nicht enthält, sollte das Client-SDK die Anfrage als fehlgeschlagen behandeln und den Google-Fehlercode INTERNAL (13) zurückgeben.

  • error: Wenn dieses Feld vorhanden ist, gilt die Anfrage als fehlgeschlagen, unabhängig vom HTTP-Statuscode und davon, ob data ebenfalls vorhanden ist. Der Wert dieses Felds sollte ein JSON-Objekt im standardmäßigen Google Cloud HTTP-Mapping-Format für Fehler sein, mit Feldern für status, message und (optional) details. Das Feld code darf nicht enthalten sein. Wenn das Feld status nicht festgelegt oder ungültig ist, sollte der Client den Status gemäß code.proto als INTERNAL behandeln. Wenn details vorhanden ist, ist es gegebenenfalls in allen Nutzerinformationen im Client-SDK enthalten, die an den Fehler angehängt sind.
    Hinweis: Das Feld details ist hier ein vom Nutzer angegebener Wert. Es handelt sich nicht unbedingt um eine Liste von Werten, die nach Prototyp verschlüsselt sind, wie im Status-Format von Google.
  • result: Der von der Funktion zurückgegebene Wert. Dies kann ein beliebiger gültiger JSON-Wert sein. Das Firebase-Functions SDK codiert den vom Nutzer zurückgegebenen Wert automatisch in dieses JSON-Format. Die Client-SDKs decodieren diese Parameter automatisch gemäß dem unten beschriebenen Serialisierungsformat in native Typen.

Andere Felder werden ignoriert.

Serialisierung

Das Serialisierungsformat für beliebige Datennutzlasten ist sowohl für die Anfrage als auch für die Antwort identisch.

Aus Gründen der Plattformkonsistenz werden sie in JSON codiert, als wären sie der Wert eines Any-Felds in einem Proto3-Protokollbuffer, und zwar mithilfe der Standard-JSON-Zuordnung. Werte einfacher Typen wie null, int, double oder string werden direkt codiert und enthalten keinen expliziten Typ. float und double werden also auf die gleiche Weise codiert und Sie wissen möglicherweise nicht, was am anderen Ende des Anrufs empfangen wird. Für Typen, die in JSON nicht nativ sind, wird die typisierte proto3-Codierung für den Wert verwendet. Weitere Informationen finden Sie in der Dokumentation für jede JSON-Codierung.

Folgende Typen sind zulässig:

  • null – null
  • int (vorzeichenbehaftet oder vorzeichenlos, bis zu 32 Bit) – z. B. 3 oder -30.
  • float – z. B. 3.14
  • Double – z.B. 3.14
  • boolescher Wert – true oder false
  • String – z.B. "hello world"
  • map<string, any=""> - z.B. {"x": 3}</string,>
  • list - z.B. [1, 2, 3]
  • lang (signiert oder unsigniert, bis zu 64 Bit) – [Details siehe unten]

Die Werte NaN und Infinity für float und double werden nicht unterstützt.

Hinweis: long ist ein spezieller Typ, der normalerweise in JSON nicht zulässig ist, aber von der proto3-Spezifikation abgedeckt wird. Sie werden beispielsweise so codiert:

long

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

ohne Vorzeichen – lang

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

Im Allgemeinen sollte der Schlüssel @type als reserviert betrachtet und nicht für übergebene Karten verwendet werden.

Da der Typ für einfache Typen nicht angegeben ist, ändern einige Werte ihren Typ, nachdem sie über die Verbindung gesendet wurden. Ein übergebener float wird zu einem double. Aus short wird int usw. Unter Android werden sowohl List als auch JSONArray für Listenwerte unterstützt. In diesen Fällen führt das Einreichen eines JSONArray zu einer List.

Wenn eine Map mit einem unbekannten @type-Feld deserialisiert wird, bleibt sie als Map erhalten. So können Entwickler ihren Rückgabewerten Felder mit neuen Typen hinzufügen, ohne ältere Clients zu beeinträchtigen.

Codebeispiele

In den Beispielen in diesem Abschnitt wird veranschaulicht, wie Folgendes codiert wird:

  • Beispiel für "callable.call" in Swift
  • Eine Erfolgsantwort für den Aufruf
  • Eine Fehlerantwort für den Aufruf

Beispiel für Callable.call in Swift zum Codieren

callable.call([
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23,
    "aLong": -123456789123456 as Int64
])

Anfrageheader:

Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token

Anfragetext:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23,
        "aLong": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "-123456789123456"
        }
    }
}

Antwort zum Codieren

return {
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23
};

Erfolgreicher Antwortheader:

200 OK
Content-Type: application/json; charset=utf-8

Antworttext bei Erfolg:

{
    "response": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23
    }
}

Fehler bei der Codierung der Antwort

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

Fehlgeschlagener Antwortheader:

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

Text der fehlgeschlagenen Antwort:

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