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 Backend prüft dieses Token automatisch und stellt es in der 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. Dieser Wert 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 bestätigt werden kann, wird die Anfrage abgelehnt. (Verfügbar für SDK >=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. Er 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 ausführbare 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 Backend die Anfrage als fehlerhaft und lehnt sie ab.

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 client-Trigger 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 fehlendes Feld data), wird sie 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 und dem Fehlercode UNAUTHENTICATED abgelehnt.

  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 für Endnutzer sichtbar 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 war, 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 von einem Clientendpunkt 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, wird die Anfrage unabhängig vom HTTP-Statuscode oder davon, ob auch data vorhanden ist, als fehlgeschlagen betrachtet. 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 ist oder einen ungültigen Wert enthält, sollte der Client den Status gemäß code.proto als INTERNAL behandeln. Wenn details vorhanden ist, wird es gegebenenfalls in den Nutzerinformationen enthalten, die dem Fehler im Client-SDK zugeordnet sind.
    Hinweis:Das Feld details ist hier ein vom Nutzer angegebener Wert. Es muss sich nicht unbedingt um eine Liste von Werten handeln, die nach Prototyp sortiert sind, wie im Google-Status-Format.
  • 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 in native Typen gemäß dem unten beschriebenen Serialization-Format.

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, welche Zeichen am anderen Ende des Anrufs empfangen werden. Für Typen, die nicht nativ in JSON sind, wird die typisierte Proto3-Codierung für den Wert verwendet. Weitere Informationen finden Sie in der Dokumentation für beliebige JSON-Codierungen.

Die folgenden Typen sind zulässig:

  • null – null
  • int (vorzeichenbehaftet oder vorzeichenlos, bis zu 32 Bit) – z.B. 3 oder -30.
  • „Unverankert“ – z.B. 3.14
  • Doppelt – 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]
  • long (mit oder ohne Vorzeichen, bis zu 64 Bit) – [weitere Informationen finden Sie unten]

NaN- und Infinity-Werte 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'
}

unsigned long

{
    '@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
};

Header der erfolgreichen Antwort:

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

Erfolgreicher Antworttext:

{
    "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"
});

Fehlerhafter 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"
        }
    }
}