Protokollspezifikation für https.onCall

Ein https.onCall-Trigger für Cloud Functions ist ein HTTPS-Trigger mit einem spezifisches Format für die Anfrage und Antwort. Dieser Abschnitt enthält eine Spezifikation für die von den Client-SDKs verwendeten HTTPS-Anfrage- und -Antwortformate um die API zu implementieren. 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 den 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 weitere Header enthalten sind, wird die Anfrage abgelehnt, wie in der Antwortdokumentation unten beschrieben.

Hinweis:In JavaScript-Clients lösen diese Anfragen aus folgenden Gründen einen CORS-OPTIONS-Preflight aus:

  • application/json ist nicht zulässig. Er muss text/plain oder application/x-www-form-urlencoded sein.
  • Der Authorization-Header ist kein Anfrageheader gemäß CORS-Zulassung.
  • 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 wird automatisch gemäß dem unten beschriebenen Serialisierungsformat 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 unterschiedlichen HTTP-Statuscodes und String-Statuscodes für Fehler in der Antwort angeben.

  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 unbehandelten Ausnahme fehlschlägt oder ein fehlgeschlagenes Promise zurückgibt, wird die Anfrage mit 500 Internal Server Error mit dem Fehlercode INTERNAL abgelehnt. So wird verhindert, dass Codierungsfehler versehentlich für Endnutzer sichtbar werden.

  6. Wenn das Callable aufgerufen wird und mithilfe der für aufrufbaren Funktionen bereitgestellten API eine explizite Fehlerbedingung 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 also 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 Clienttrigger erfolgreich war, lautet der Antwortstatus 200 OK.

Antwortformat: Header

Die Antwort hat 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 sollten zumindest enthält entweder result oder error sowie alle optionalen Felder. Wenn der Parameter Antwort ist kein JSON-Objekt oder enthält nicht data oder error, die Das Client SDK sollte die Anfrage als fehlgeschlagen behandeln. mit dem Google-Fehlercode INTERNAL (13).

  • 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 Feldes sollte ein JSON-Objekt im Standardformat für Google Cloud-HTTP-Zuordnungen für Fehler mit Feldern für status, message und (optional) details sein. 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, ist sie gegebenenfalls in allen Nutzerinformationen im Client-SDK enthalten, die an den Fehler angehängt sind.
    Hinweis:Das Feld details hier ist 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.

Wenn weitere Felder vorhanden sind, sollten sie ignoriert werden.

Serialisierung

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

Aus Gründen der Plattformkonsistenz werden diese mit der JSON-Standardzuordnung so in JSON codiert, als wären sie der Wert eines Any-Felds in einem proto3-Protokollzwischenspeicher. Werte einfacher Typen wie null, int, double oder string werden direkt codiert und enthalten nicht ihren 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 die beliebige JSON-Codierung.

Folgende Typen sind zulässig:

  • null – null
  • int (vorzeichenbehaftet oder unvorzeichenlos, bis zu 32 Bit) – z.B. 3 oder -30.
  • float – 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,>
  • Liste - z.B. [1, 2, 3]
  • lang (signiert oder unsigniert, bis zu 64 Bit) – [Details siehe 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'
}

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 ein 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 Karte mit einem unbekannten @type-Feld deserialisiert wird, bleibt sie als Karte erhalten. So können Entwickler ihren Rückgabewerten Felder mit neuen Typen hinzufügen, ohne dass Probleme mit älteren Clients auftreten.

Codebeispiele

Die Beispiele in diesem Abschnitt veranschaulichen, wie die folgenden Komponenten codiert werden:

  • Beispiel für "callable.call" in Swift
  • Eine Erfolgsantwort für den Anruf
  • 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 zur Codierung

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