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 sind möglicherweise hilfreich, 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 optionales ; 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 überprüft dieses Token automatisch und stellt es in der context des Handlers zur Verfügung. Wenn das Token nicht gültig ist, wird die Anfrage abgelehnt.
  • Optional: Firebase-Instance-ID-Token: <iid>
    • Das FCM-Registrierungstoken aus dem Firebase Client SDK. Dies muss ein String sein. Diese Funktion ist in der context des Handlers verfügbar. Sie wird für die Ausrichtung 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. Dabei wird appId in die context des Handlers eingefügt. Wenn das Token nicht überprüft 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. Muss text/plain oder application/x-www-form-urlencoded sein.
  • Der Header Authorization ist kein CORS-safelisted request-header.
  • 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. Das kann ein beliebiger gültiger JSON-Wert sein. Diese werden automatisch in native JavaScript-Typen decodiert, die dem unten beschriebenen Serialisierungsformat entsprechen.

Wenn in der Anfrage andere Felder vorhanden sind, wird sie vom Backend als fehlerhaft betrachtet und abgelehnt.

Antwortformat: Statuscodes

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

  1. Bei einem HTTP-Fehler, 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 die Antwort 404 Not Found.

  2. Wenn der Client-Trigger aufgerufen wird, die Anfrage aber das falsche Format hat, z. B. kein JSON ist, ungültige Felder enthält 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 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 geprüft, außer wenn es zum Senden einer Push-Benachrichtigung mit FCM verwendet wird.

  5. Wenn der aufrufbare Trigger aufgerufen wird, aber mit einer unbehandelten Ausnahme fehlschlägt oder ein fehlgeschlagenes Promise zurückgibt, wird die Anfrage mit 500 Internal Server Error und dem Fehlercode INTERNAL abgelehnt. So wird verhindert, dass Endnutzer versehentlich mit Codierungsfehlern konfrontiert werden.

  6. Wenn die aufrufbare Funktion aufgerufen wird und mit der für aufrufbare Funktionen bereitgestellten API eine explizite Fehlerbedingung zurückgibt, schlägt die Anfrage fehl. Der zurückgegebene HTTP-Statuscode basiert auf der offiziellen Zuordnung von Fehlerstatus zu HTTP-Status, wie in code.proto definiert. Der zurückgegebene spezifische Fehlercode, die Meldung und die Details sind wie unten beschrieben im Antworttext codiert. Wenn die Funktion 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 Client-Trigger erfolgreich ist, lautet der Antwortstatus 200 OK.

Antwortformat: Header

Die Antwort hat die folgenden Header:

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

Antworttext

Die Antwort von einem Clientendpunkt ist immer ein JSON-Objekt. Sie 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 mit dem Google-Fehlercode INTERNAL (13) behandeln.

  • error: Wenn dieses Feld vorhanden ist, gilt die Anfrage als fehlgeschlagen, unabhängig vom HTTP-Statuscode oder davon, ob data ebenfalls vorhanden ist. Der Wert dieses Felds sollte ein JSON-Objekt im Standardformat Google Cloud HTTP Mapping 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 hat, sollte der Client den Status gemäß code.proto als INTERNAL behandeln. Falls details vorhanden ist, wird es in allen Nutzerinformationen berücksichtigt, die dem Fehler im Client-SDK beigefügt sind, sofern zutreffend.
    Hinweis:Das Feld details ist ein vom Nutzer angegebener Wert. Es handelt sich nicht unbedingt um eine Liste von Werten, die nach Prototypen sortiert sind, wie im Google-Format Status.
  • result: Der von der Funktion zurückgegebene Wert. Das 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, entsprechend dem unten beschriebenen Serialisierungsformat.

Falls andere Felder vorhanden sind, sollten sie ignoriert werden.

Serialisierung

Das Serialisierungsformat für beliebige Datennutzlasten ist für Anfrage und Antwort identisch.

Aus Gründen der Plattformkonsistenz werden sie in JSON so codiert, als wären sie der Wert eines Any-Felds in einem Proto3-Pufferprotokoll, wobei die Standard-JSON-Zuordnung verwendet wird. Werte einfacher Typen wie null, int, double oder string werden direkt codiert und enthalten nicht ihren expliziten Typ. float und double werden also auf dieselbe Weise codiert und Sie wissen möglicherweise nicht, welches Zeichen am anderen Ende des Anrufs empfangen wird. 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 zur JSON-Codierung.

Die folgenden Typen sind zulässig:

  • null – null
  • int (mit oder ohne Vorzeichen, bis zu 32 Bit), z.B. 3 oder -30.
  • Gleitkommazahl, z.B. 3.14
  • double, z.B. 3.14
  • boolesch – 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) – [siehe unten für Details]

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

long ist ein spezieller Typ, der normalerweise in JSON nicht zulässig ist, aber von der Proto3-Spezifikation abgedeckt wird. Beispiel:

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 @type-Schlüssel als reserviert betrachtet und nicht für übergebene Karten verwendet werden.

Da der Typ für einfache Typen nicht angegeben wird, ändert sich der Typ einiger Werte nach der Übertragung. Ein übergebener float wird zu einem double. Ein short wird zu einem int usw. In Android werden sowohl List als auch JSONArray für Listenwerte unterstützt. In diesen Fällen führt die Übergabe eines JSONArray zu einem List.

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

Codebeispiele

Die Beispiele in diesem Abschnitt veranschaulichen, wie Sie Folgendes codieren:

  • Beispiel für callable.call in Swift
  • Eine Erfolgsantwort für den Aufruf
  • Eine Fehlermeldung für den Anruf

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

Zu codierende Antwort

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

Header einer erfolgreichen Antwort:

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

Erfolgreicher Antworttext:

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

Fehler beim Codieren 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"
        }
    }
}